IdePipelineStage: Builder SDK Reference

## IdePipelineStage IdePipelineStage |

## Functions

gboolean | ide_pipeline_stage_get_active ()
void | ide_pipeline_stage_set_active ()
const gchar * | ide_pipeline_stage_get_name ()
void | ide_pipeline_stage_set_name ()
void | ide_pipeline_stage_log ()
void | ide_pipeline_stage_log_subprocess ()
void | ide_pipeline_stage_set_log_observer ()
void | ide_pipeline_stage_set_stdout_path ()
const gchar * | ide_pipeline_stage_get_stdout_path ()
gboolean | ide_pipeline_stage_get_completed ()
void | ide_pipeline_stage_set_completed ()
gboolean | ide_pipeline_stage_get_disabled ()
void | ide_pipeline_stage_set_disabled ()
gboolean | ide_pipeline_stage_get_check_stdout ()
void | ide_pipeline_stage_set_check_stdout ()
gboolean | ide_pipeline_stage_get_transient ()
void | ide_pipeline_stage_set_transient ()
void | ide_pipeline_stage_build_async ()
gboolean | ide_pipeline_stage_build_finish ()
void | ide_pipeline_stage_clean_async ()
gboolean | ide_pipeline_stage_clean_finish ()
gboolean | ide_pipeline_stage_chain ()
void | ide_pipeline_stage_pause ()
void | ide_pipeline_stage_unpause ()
void | ide_pipeline_stage_emit_reap ()

## 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

gboolean | chain | Run Last
void | query | Run Last
void | reap | Run Last

## Types and Values

#define | IDE_TYPE_PIPELINE_STAGE
struct | IdePipelineStageClass
| IdePipelineStage

## 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