IdePipelineStage

IdePipelineStage

Functions

Properties

gboolean active Read / Write
gboolean check-stdout Read / Write
gboolean completed Read / Write
gboolean disabled Read / Write
char * name Read / Write
char * stdout-path Read / Write
gboolean transient Read / Write

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── IdeObject
        ╰── IdePipelineStage
            ├── IdePipelineStageLauncher
            ├── IdePipelineStageMkdirs
            ╰── IdePipelineStageTransfer

Description

Functions

ide_pipeline_stage_get_active ()

gboolean
ide_pipeline_stage_get_active (IdePipelineStage *self);

Gets the "active" property, which is set to TRUE when the build stage is actively executing or cleaning.

Parameters

self

a IdePipelineStage

 

Returns

TRUE if the stage is actively executing or cleaning.

Since: 3.32


ide_pipeline_stage_set_active ()

void
ide_pipeline_stage_set_active (IdePipelineStage *self,
                               gboolean active);

ide_pipeline_stage_get_name ()

const gchar *
ide_pipeline_stage_get_name (IdePipelineStage *self);

ide_pipeline_stage_set_name ()

void
ide_pipeline_stage_set_name (IdePipelineStage *self,
                             const gchar *name);

ide_pipeline_stage_log ()

void
ide_pipeline_stage_log (IdePipelineStage *self,
                        IdeBuildLogStream stream,
                        const gchar *message,
                        gssize message_len);

ide_pipeline_stage_log_subprocess ()

void
ide_pipeline_stage_log_subprocess (IdePipelineStage *self,
                                   IdeSubprocess *subprocess);

This function will begin logging subprocess by reading from the stdout and stderr streams of the subprocess. You must have created the subprocess with G_SUBPROCESS_FLAGS_STDERR_PIPE and G_SUBPROCESS_FLAGS_STDOUT_PIPE so that the streams may be read.

Parameters

self

An IdePipelineStage

 

subprocess

An IdeSubprocess

 

Since: 3.32


ide_pipeline_stage_set_log_observer ()

void
ide_pipeline_stage_set_log_observer (IdePipelineStage *self,
                                     IdeBuildLogObserver observer,
                                     gpointer observer_data,
                                     GDestroyNotify observer_data_destroy);

Sets the log observer to handle calls to the various stage logging functions. This will be set by the pipeline to mux logs from all stages into a unified build log.

Plugins that need to handle logging from a build stage should set an observer on the pipeline so that log distribution may be fanned out to all observers.

Parameters

self

An IdePipelineStage

 

observer

The observer for the log entries.

[scope async]

observer_data

data for observer

 

observer_data_destroy

destroy callback for observer_data

 

Since: 3.32


ide_pipeline_stage_set_stdout_path ()

void
ide_pipeline_stage_set_stdout_path (IdePipelineStage *self,
                                    const gchar *path);

ide_pipeline_stage_get_stdout_path ()

const gchar *
ide_pipeline_stage_get_stdout_path (IdePipelineStage *self);

ide_pipeline_stage_get_completed ()

gboolean
ide_pipeline_stage_get_completed (IdePipelineStage *self);

ide_pipeline_stage_set_completed ()

void
ide_pipeline_stage_set_completed (IdePipelineStage *self,
                                  gboolean completed);

ide_pipeline_stage_get_disabled ()

gboolean
ide_pipeline_stage_get_disabled (IdePipelineStage *self);

ide_pipeline_stage_set_disabled ()

void
ide_pipeline_stage_set_disabled (IdePipelineStage *self,
                                 gboolean disabled);

ide_pipeline_stage_get_check_stdout ()

gboolean
ide_pipeline_stage_get_check_stdout (IdePipelineStage *self);

ide_pipeline_stage_set_check_stdout ()

void
ide_pipeline_stage_set_check_stdout (IdePipelineStage *self,
                                     gboolean check_stdout);

ide_pipeline_stage_get_transient ()

gboolean
ide_pipeline_stage_get_transient (IdePipelineStage *self);

ide_pipeline_stage_set_transient ()

void
ide_pipeline_stage_set_transient (IdePipelineStage *self,
                                  gboolean transient);

ide_pipeline_stage_build_async ()

void
ide_pipeline_stage_build_async (IdePipelineStage *self,
                                IdePipeline *pipeline,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

ide_pipeline_stage_build_finish ()

gboolean
ide_pipeline_stage_build_finish (IdePipelineStage *self,
                                 GAsyncResult *result,
                                 GError **error);

ide_pipeline_stage_clean_async ()

void
ide_pipeline_stage_clean_async (IdePipelineStage *self,
                                IdePipeline *pipeline,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

ide_pipeline_stage_clean_finish ()

gboolean
ide_pipeline_stage_clean_finish (IdePipelineStage *self,
                                 GAsyncResult *result,
                                 GError **error);

ide_pipeline_stage_chain ()

gboolean
ide_pipeline_stage_chain (IdePipelineStage *self,
                          IdePipelineStage *next);

ide_pipeline_stage_pause ()

void
ide_pipeline_stage_pause (IdePipelineStage *self);

ide_pipeline_stage_unpause ()

void
ide_pipeline_stage_unpause (IdePipelineStage *self);

ide_pipeline_stage_emit_reap ()

void
ide_pipeline_stage_emit_reap (IdePipelineStage *self,
                              DzlDirectoryReaper *reaper);

Types and Values

IDE_TYPE_PIPELINE_STAGE

#define IDE_TYPE_PIPELINE_STAGE (ide_pipeline_stage_get_type())

struct IdePipelineStageClass

struct IdePipelineStageClass {
  IdeObjectClass parent_class;

  /**
   * IdePipelineStage::build:
   *
   * This vfunc will be run in a thread by the default
   * IdePipelineStage::build_async() and IdePipelineStage::build_finish()
   * vfuncs.
   *
   * Only use thread-safe API from this function.
   *
   * Since: 3.32
   */
  gboolean (*build)          (IdePipelineStage     *self,
                              IdePipeline          *pipeline,
                              GCancellable         *cancellable,
                              GError              **error);

  /**
   * IdePipelineStage::build_async:
   *
   * Asynchronous version of the #IdePipelineStage API. This is the preferred
   * way to subclass #IdePipelineStage.
   *
   * Since: 3.32
   */
  void     (*build_async)    (IdePipelineStage     *self,
                              IdePipeline          *pipeline,
                              GCancellable         *cancellable,
                              GAsyncReadyCallback   callback,
                              gpointer              user_data);

  /**
   * IdePipelineStage::build_finish:
   *
   * Completes an asynchronous call to ide_pipeline_stage_build_async().
   *
   * Returns: %TRUE if successful; otherwise %FALSE and @error is set.
   *   Upon failure, the pipeline will be stopped.
   *
   * Since: 3.32
   */
  gboolean (*build_finish)   (IdePipelineStage     *self,
                              GAsyncResult         *result,
                              GError              **error);

  /**
   * IdePipelineStage::clean_async:
   * @self: an #IdePipelineStage
   * @pipeline: An #IdePipeline
   * @cancellable: (nullable): a #GCancellable or %NULL
   * @callback: An async callback
   * @user_data: user data for @callback
   *
   * This function will perform the clean operation.
   *
   * Since: 3.32
   */
  void     (*clean_async)    (IdePipelineStage     *self,
                              IdePipeline          *pipeline,
                              GCancellable         *cancellable,
                              GAsyncReadyCallback   callback,
                              gpointer              user_data);

  /**
   * IdePipelineStage::clean_finish:
   * @self: an #IdePipelineStage
   * @result: a #GErrorResult
   * @error: A location for a #GError or %NULL.
   *
   * Completes an async operation to ide_pipeline_stage_clean_async().
   *
   * Returns: %TRUE if successful; otherwise %FALSE and @error is set.
   *
   * Since: 3.32
   */
  gboolean (*clean_finish)   (IdePipelineStage     *self,
                              GAsyncResult         *result,
                              GError              **error);

  /* Signals */
  void     (*query)          (IdePipelineStage     *self,
                              IdePipeline          *pipeline,
                              GPtrArray            *targets,
                              GCancellable         *cancellable);
  void     (*reap)           (IdePipelineStage     *self,
                              DzlDirectoryReaper   *reaper);
  gboolean (*chain)          (IdePipelineStage     *self,
                              IdePipelineStage     *next);
};

IdePipelineStage

typedef struct _IdePipelineStage IdePipelineStage;

Property Details

The “active” property

  “active”                   gboolean

This property is set to TRUE when the build stage is actively running or cleaning.

Owner: IdePipelineStage

Flags: Read / Write

Default value: FALSE

Since: 3.32


The “check-stdout” property

  “check-stdout”             gboolean

Most build systems will preserve stderr for the processes they call, such as gcc, clang, and others. However, if your build system redirects all output to stdout, you may need to set this property to TRUE to ensure that Builder will extract errors from stdout.

One such example is Ninja.

Owner: IdePipelineStage

Flags: Read / Write

Default value: FALSE

Since: 3.32


The “completed” property

  “completed”                gboolean

The "completed" property is set to TRUE after the pipeline has completed processing the stage. When the pipeline invalidates phases, completed may be reset to FALSE.

Owner: IdePipelineStage

Flags: Read / Write

Default value: FALSE

Since: 3.32


The “disabled” property

  “disabled”                 gboolean

If the build stage is disabled. This allows you to have a stage that is attached but will not be activated during execution.

You may enable it later and then re-build the pipeline.

If the stage is both transient and disabled, it will not be removed during the transient cleanup phase.

Owner: IdePipelineStage

Flags: Read / Write

Default value: FALSE

Since: 3.32


The “name” property

  “name”                     char *

The name of the build stage. This is only used by UI to view the build pipeline.

Owner: IdePipelineStage

Flags: Read / Write

Default value: NULL

Since: 3.32


The “stdout-path” property

  “stdout-path”              char *

The "stdout-path" property allows a build stage to redirect its log messages to a stdout file. Instead of passing stdout along to the build pipeline, they will be redirected to this file.

For safety reasons, the contents are first redirected to a temporary file and will be redirected to the stdout-path location after the build stage has completed executing.

Owner: IdePipelineStage

Flags: Read / Write

Default value: NULL

Since: 3.32


The “transient” property

  “transient”                gboolean

If the build stage is transient.

A transient build stage is removed after the completion of ide_pipeline_build_async(). This can be a convenient way to add a temporary item to a build pipeline that should be immediately discarded.

Owner: IdePipelineStage

Flags: Read / Write

Default value: FALSE

Since: 3.32

Signal Details

The “chain” signal

gboolean
user_function (IdePipelineStage *idepipelinestage,
               IdePipelineStage *arg1,
               gpointer          user_data)

Flags: Run Last


The “query” signal

void
user_function (IdePipelineStage *self,
               IdePipeline      *pipeline,
               GPtrArray        *targets,
               GCancellable     *cancellable,
               gpointer          user_data)

The “query” signal is emitted to request that the build stage update its completed stage from any external resources.

This can be useful if you want to use an existing build stage instances and use a signal to pause forward progress until an external system has been checked.

The targets that the user would like to ensure are built are provided as targets . Some IdePipelineStage may use this to reduce the amount of work they perform

For example, in a signal handler, you may call ide_pipeline_stage_pause() and perform an external operation. Forward progress of the stage will be paused until a matching number of ide_pipeline_stage_unpause() calls have been made.

Parameters

self

An IdePipelineStage

 

pipeline

An IdePipeline

 

targets

an array of IdeBuildTarget or NULL.

[element-type IdeBuildTarget][nullable]

cancellable

a GCancellable or NULL.

[nullable]

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 3.32


The “reap” signal

void
user_function (IdePipelineStage   *self,
               DzlDirectoryReaper *reaper,
               gpointer            user_data)

This signal is emitted when a request to rebuild the project has occurred. This allows build stages to ensure that certain files are removed from the system. For example, an autotools build stage might request that "configure" is removed so that autogen.sh will be Executed as part of the next build.

Parameters

self

An IdePipelineStage

 

reaper

An DzlDirectoryReaper

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 3.32