ide-build-pipeline: Builder SDK Reference

## ide-build-pipeline ide-build-pipeline |

## Functions

gboolean | ide_build_pipeline_is_ready ()
gboolean | ide_build_pipeline_get_busy ()
IdeConfiguration * | ide_build_pipeline_get_configuration ()
IdeDevice * | ide_build_pipeline_get_device ()
IdeRuntime * | ide_build_pipeline_get_runtime ()
const gchar * | ide_build_pipeline_get_builddir ()
const gchar * | ide_build_pipeline_get_srcdir ()
const gchar * | ide_build_pipeline_get_arch ()
const gchar * | ide_build_pipeline_get_kernel ()
const gchar * | ide_build_pipeline_get_system ()
const gchar * | ide_build_pipeline_get_system_type ()
gchar * | ide_build_pipeline_get_message ()
IdeBuildPhase | ide_build_pipeline_get_phase ()
gboolean | ide_build_pipeline_get_can_export ()
VtePty * | ide_build_pipeline_get_pty ()
IdeSubprocessLauncher * | ide_build_pipeline_create_launcher ()
gchar * | ide_build_pipeline_build_srcdir_path ()
gchar * | ide_build_pipeline_build_builddir_path ()
void | ide_build_pipeline_invalidate_phase ()
gboolean | ide_build_pipeline_request_phase ()
guint | ide_build_pipeline_connect ()
guint | ide_build_pipeline_connect_launcher ()
void | ide_build_pipeline_disconnect ()
IdeBuildStage * | ide_build_pipeline_get_stage_by_id ()
guint | ide_build_pipeline_add_log_observer ()
gboolean | ide_build_pipeline_remove_log_observer ()
void | ide_build_pipeline_emit_diagnostic ()
guint | ide_build_pipeline_add_error_format ()
gboolean | ide_build_pipeline_remove_error_format ()
void | ide_build_pipeline_build_async ()
gboolean | ide_build_pipeline_build_finish ()
void | ide_build_pipeline_execute_async ()
gboolean | ide_build_pipeline_execute_finish ()
void | ide_build_pipeline_foreach_stage ()
void | ide_build_pipeline_clean_async ()
gboolean | ide_build_pipeline_clean_finish ()
void | ide_build_pipeline_rebuild_async ()
gboolean | ide_build_pipeline_rebuild_finish ()
void | ide_build_pipeline_attach_pty ()
gboolean | ide_build_pipeline_has_configured ()
IdeBuildPhase | ide_build_pipeline_get_requested_phase ()
gboolean | ide_build_pipeline_is_native ()

## Properties

gboolean | busy | Read / Write
IdeConfiguration * | configuration | Read / Write / Construct Only
IdeDevice * | device | Read / Write / Construct Only
gchar * | message | Read
IdeBuildPhase | phase | Read
VtePty * | pty | Read

## Signals

void | diagnostic | Run Last
void | finished | Run Last
void | started | Run Last

## Types and Values

#define | IDE_TYPE_BUILD_PIPELINE
#define | IDE_BUILD_PHASE_MASK
#define | IDE_BUILD_PHASE_WHENCE_MASK
enum | IdeBuildPhase
| IdeBuildPipeline

## Object Hierarchy

        GFlags
        ╰── IdeBuildPhase
        GObject
        ╰── IdeObject
            ╰── IdeBuildPipeline

## Implemented Interfaces

IdeBuildPipeline implements GListModel and GInitable.

## Description

## Functions

### ide_build_pipeline_is_ready ()

    gboolean
    ide_build_pipeline_is_ready (IdeBuildPipeline *self);

Checks to see if the pipeline has been loaded. Loading may be delayed due to various initialization routines that need to complete.

#### Parameters

self | a IdeBuildPipeline |

#### Returns

`TRUE` if the pipeline has loaded, otherwise `FALSE`

Since: 3.28

### ide_build_pipeline_get_busy ()

    gboolean
    ide_build_pipeline_get_busy (IdeBuildPipeline *self);

### ide_build_pipeline_get_configuration ()

    IdeConfiguration *
    ide_build_pipeline_get_configuration (IdeBuildPipeline *self);

Gets the IdeConfiguration to use for the pipeline.

#### Returns

An IdeConfiguration.

[transfer none]

### ide_build_pipeline_get_device ()

    IdeDevice *
    ide_build_pipeline_get_device (IdeBuildPipeline *self);

Gets the device that the pipeline is building for.

#### Parameters

self | a IdeBuildPipeline |

#### Returns

an IdeDevice.

[transfer none]

Since: 3.28

### ide_build_pipeline_get_runtime ()

    IdeRuntime *
    ide_build_pipeline_get_runtime (IdeBuildPipeline *self);

A convenience function to get the runtime for a build pipeline.

#### Parameters

self | An IdeBuildPipeline |

#### Returns

An IdeRuntime or `NULL`.

[transfer none][nullable]

Since: 3.28

### ide_build_pipeline_get_builddir ()

    const gchar *
    ide_build_pipeline_get_builddir (IdeBuildPipeline *self);

Gets the "builddir" to be used for the build process. This is generally the location that build systems will use for out-of-tree builds.

#### Parameters

self | An IdeBuildPipeline |

#### Returns

the path of the build directory

### ide_build_pipeline_get_srcdir ()

    const gchar *
    ide_build_pipeline_get_srcdir (IdeBuildPipeline *self);

Gets the "srcdir" of the project. This is equivalent to the IdeVcs:working-directory property as a string.

#### Parameters

self | An IdeBuildPipeline |

#### Returns

the path of the source directory

### ide_build_pipeline_get_arch ()

    const gchar *
    ide_build_pipeline_get_arch (IdeBuildPipeline *self);

Gets the architecture that the pipeline is building for, once that has been discovered from the device.

#### Parameters

self | a IdeBuildPipeline |

#### Returns

a string describing the architecture, or `NULL`.

[nullable]

Since: 3.28

### ide_build_pipeline_get_kernel ()

    const gchar *
    ide_build_pipeline_get_kernel (IdeBuildPipeline *self);

Gets the kernel that the pipeline is building for, once that has been discovered from the device.

#### Parameters

self | a IdeBuildPipeline |

#### Returns

a string describing the kernel, or `NULL`.

[nullable]

Since: 3.28

### ide_build_pipeline_get_system ()

    const gchar *
    ide_build_pipeline_get_system (IdeBuildPipeline *self);

Gets the system portion of the host tripet that the pipeline is building for, once that has been discovered from the device.

For Linux based devices, this will generally be "gnu".

#### Parameters

self | a IdeBuildPipeline |

#### Returns

a string describing the device system, or `NULL`.

[nullable]

Since: 3.28

### ide_build_pipeline_get_system_type ()

    const gchar *
    ide_build_pipeline_get_system_type (IdeBuildPipeline *self);

Gets the combination of arch-kernel-system, sometimes referred to as the "host triplet".

For Linux based devices, this will generally be something like "x86_64-linux-gnu".

#### Parameters

self | a IdeBuildPipeline |

#### Returns

a string describing the device

Since: 3.28

### ide_build_pipeline_get_message ()

    gchar *
    ide_build_pipeline_get_message (IdeBuildPipeline *self);

Gets the current message for the build pipeline. This can be shown to users in UI elements to signify progress in the build.

#### Parameters

self | An IdeBuildPipeline |

#### Returns

A string representing the current stage of the build, or `NULL`.

[nullable][transfer full]

### ide_build_pipeline_get_phase ()

    IdeBuildPhase
    ide_build_pipeline_get_phase (IdeBuildPipeline *self);

Gets the current phase that is executing. This is only useful during execution of the pipeline.

### ide_build_pipeline_get_can_export ()

    gboolean
    ide_build_pipeline_get_can_export (IdeBuildPipeline *self);

This function is useful to discover if there are any pipeline addins which implement the export phase. UI or GAction implementations may want to use this value to set the enabled state of the action or sensitivity of a button.

#### Parameters

self | a IdeBuildPipeline |

#### Returns

`TRUE` if there are export pipeline stages.

### ide_build_pipeline_get_pty ()

    VtePty *
    ide_build_pipeline_get_pty (IdeBuildPipeline *self);

Gets the VtePty for the pipeline, if set.

This will not be set until the pipeline has been initialized. That is not guaranteed to happen at object creation time.

#### Parameters

self | a IdeBuildPipeline |

#### Returns

a VtePty or `NULL`.

[transfer none][nullable]

Since: 3.28

### ide_build_pipeline_create_launcher ()

    IdeSubprocessLauncher *
    ide_build_pipeline_create_launcher (IdeBuildPipeline *self,
                                        GError **error);

This is a convenience function to create a new IdeSubprocessLauncher using the configuration and runtime associated with the pipeline.

#### Parameters

self | An IdeBuildPipeline |

#### Returns

An IdeSubprocessLauncher.

[transfer full]

### ide_build_pipeline_build_srcdir_path ()

    gchar *
    ide_build_pipeline_build_srcdir_path (IdeBuildPipeline *self,
                                          const gchar *first_part,
                                          ...);

This is a convenience function to create a new path that starts with the source directory of the project.

This is functionally equivalent to calling `g_build_filename()` with the working directory of the source tree.

#### Returns

A newly allocated string.

[transfer full]

### ide_build_pipeline_build_builddir_path ()

    gchar *
    ide_build_pipeline_build_builddir_path
                                   (IdeBuildPipeline *self,
                                    const gchar *first_part,
                                    ...);

This is a convenience function to create a new path that starts with the build directory for this build configuration.

This is functionally equivalent to calling `g_build_filename()` with the result of `ide_build_pipeline_get_builddir()` as the first parameter.

#### Returns

A newly allocated string.

[transfer full]

### ide_build_pipeline_invalidate_phase ()

    void
    ide_build_pipeline_invalidate_phase (IdeBuildPipeline *self,
                                         IdeBuildPhase phases);

Invalidates the phases matching `phases` flags.

If the requested phases include the phases invalidated here, the next execution of the pipeline will execute thse phases.

This should be used by plugins to ensure a particular phase is re-executed upon discovering its state is no longer valid. Such an example might be invalidating the `IDE_BUILD_PHASE_AUTOGEN` phase when the an autotools projects autogen.sh file has been changed.

#### Parameters

self | An IdeBuildPipeline |
phases | The phases to invalidate |

### ide_build_pipeline_request_phase ()

    gboolean
    ide_build_pipeline_request_phase (IdeBuildPipeline *self,
                                      IdeBuildPhase phase);

Requests that the next execution of the pipeline will build up to `phase` including all stages that were previously invalidated.

#### Parameters

self | An IdeBuildPipeline |
phase | An IdeBuildPhase |

#### Returns

`TRUE` if a stage is known to require execution.

### ide_build_pipeline_connect ()

    guint
    ide_build_pipeline_connect (IdeBuildPipeline *self,
                                IdeBuildPhase phase,
                                gint priority,
                                IdeBuildStage *stage);

Insert `stage` into the pipeline as part of the phase denoted by `phase` .

If priority is non-zero, it will be used to sort the stage among other stages that are part of the same phase.

#### Parameters

self | an IdeBuildPipeline |
phase | An IdeBuildPhase |
priority | an optional priority for sorting within the phase |
stage | An IdeBuildStage |

#### Returns

A stage_id that may be passed to `ide_build_pipeline_disconnect()`.

### ide_build_pipeline_connect_launcher ()

    guint
    ide_build_pipeline_connect_launcher (IdeBuildPipeline *self,
                                         IdeBuildPhase phase,
                                         gint priority,
                                         IdeSubprocessLauncher *launcher);

This creates a new stage that will spawn a process using `launcher` and log the output of stdin/stdout.

It is a programmer error to modify `launcher` after passing it to this function.

#### Parameters

self | an IdeBuildPipeline |
phase | An IdeBuildPhase |
priority | an optional priority for sorting within the phase |
launcher | An IdeSubprocessLauncher |

#### Returns

A stage_id that may be passed to `ide_build_pipeline_remove()`.

### ide_build_pipeline_disconnect ()

    void
    ide_build_pipeline_disconnect (IdeBuildPipeline *self,
                                   guint stage_id);

This removes the stage matching `stage_id` . You are returned a `stage_id` when inserting a stage with functions such as `ide_build_pipeline_connect()` or `ide_build_pipeline_connect_launcher()`.

Plugins should use this function to remove their stages when the plugin is unloading.

#### Parameters

self | An IdeBuildPipeline |
stage_id | An identifier returned from adding a stage |

### ide_build_pipeline_get_stage_by_id ()

    IdeBuildStage *
    ide_build_pipeline_get_stage_by_id (IdeBuildPipeline *self,
                                        guint stage_id);

Gets the stage matching the identifier `stage_id` as returned from `ide_build_pipeline_connect()`.

#### Parameters

self | An IdeBuildPipeline |
stage_id | the identfier of the stage |

#### Returns

An IdeBuildStage or `NULL` if the stage could not be found.

[transfer none][nullable]

### ide_build_pipeline_add_log_observer ()

    guint
    ide_build_pipeline_add_log_observer (IdeBuildPipeline *self,
                                         IdeBuildLogObserver observer,
                                         gpointer observer_data,
                                         GDestroyNotify observer_data_destroy);

### ide_build_pipeline_remove_log_observer ()

    gboolean
    ide_build_pipeline_remove_log_observer
                                   (IdeBuildPipeline *self,
                                    guint observer_id);

### ide_build_pipeline_emit_diagnostic ()

    void
    ide_build_pipeline_emit_diagnostic (IdeBuildPipeline *self,
                                        IdeDiagnostic *diagnostic);

### ide_build_pipeline_add_error_format ()

    guint
    ide_build_pipeline_add_error_format (IdeBuildPipeline *self,
                                         const gchar *regex,
                                         GRegexCompileFlags flags);

This can be used to add a regex that will extract errors from standard output. This is similar to the "errorformat" feature of vim to extract warnings from standard output.

The regex should used named capture groups to pass information to the extraction process.

Supported group names are:

• filename (a string path) • line (an integer) • column (an integer) • level (a string) • message (a string)

For example, to extract warnings from GCC you might do something like the following:

"(?<filename>[a-zA-Z0-9\-\.\/_]+):" "(?<line>\d+):" "(?<column>\d+): " "(?<level>[\w\s]+): " "(?<message>.*)"

To remove the regex, use the `ide_build_pipeline_remove_error_format()` function with the resulting format id returned from this function.

The resulting format id will be > 0 if successful.

#### Parameters

self | an IdeBuildPipeline |
regex | A regex to be compiled |

#### Returns

an error format id that may be passed to `ide_build_pipeline_remove_error_format()`.

### ide_build_pipeline_remove_error_format ()

    gboolean
    ide_build_pipeline_remove_error_format
                                   (IdeBuildPipeline *self,
                                    guint error_format_id);

Removes an error format that was registered with `ide_build_pipeline_add_error_format()`.

#### Parameters

self | An IdeBuildPipeline |
error_format_id | an identifier for the error format. |

#### Returns

`TRUE` if the error format was removed.

### ide_build_pipeline_build_async ()

    void
    ide_build_pipeline_build_async (IdeBuildPipeline *self,
                                    IdeBuildPhase phase,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Asynchronously starts the build pipeline.

The `phase` parameter should contain the IdeBuildPhase that is necessary to complete. If you simply want to trigger a generic build, you probably want `IDE_BUILD_PHASE_BUILD`. If you only need to configure the project (and necessarily the dependencies up to that phase) you might want `IDE_BUILD_PHASE_CONFIGURE`.

You may not specify `IDE_BUILD_PHASE_AFTER` or `IDE_BUILD_PHASE_BEFORE` flags as those must always be processed with the underlying phase they are attached to.

Upon completion, `callback` will be executed and should call `ide_build_pipeline_execute_finish()` to get the status of the operation.

#### Parameters

self | A `IdeBuildPipeline` |
phase | the requested build phase |
cancellable | a GCancellable or `NULL`. | [nullable]
callback | a callback to execute upon completion |
user_data | data for `callback` |

Since: 3.28

### ide_build_pipeline_build_finish ()

    gboolean
    ide_build_pipeline_build_finish (IdeBuildPipeline *self,
                                     GAsyncResult *result,
                                     GError **error);

This function completes the asynchronous request to build up to a particular phase of the build pipeline.

#### Parameters

self | An IdeBuildPipeline |
result | a GAsyncResult provided to callback |
error | A location for a GError, or `NULL` |

#### Returns

`TRUE` if the build stages were executed successfully up to the requested build phase provided to `ide_build_pipeline_build_async()`.

Since: 3.28

### ide_build_pipeline_execute_async ()

    void
    ide_build_pipeline_execute_async (IdeBuildPipeline *self,
                                      GCancellable *cancellable,
                                      GAsyncReadyCallback callback,
                                      gpointer user_data);

Asynchronously starts the build pipeline.

Any phase that has been invalidated up to the requested phase will be executed until a stage has failed.

Upon completion, `callback` will be executed and should call `ide_build_pipeline_execute_finish()` to get the status of the operation.

#### Parameters

self | A `IdeBuildPipeline` |
cancellable | a GCancellable or `NULL`. | [nullable]
callback | a callback to execute upon completion |
user_data | data for `callback` |

Since: 3.24

### ide_build_pipeline_execute_finish ()

    gboolean
    ide_build_pipeline_execute_finish (IdeBuildPipeline *self,
                                       GAsyncResult *result,
                                       GError **error);

#### Returns

`TRUE` if successful; otherwise `FALSE` and `error` is set.

### ide_build_pipeline_foreach_stage ()

    void
    ide_build_pipeline_foreach_stage (IdeBuildPipeline *self,
                                      GFunc stage_callback,
                                      gpointer user_data);

This function will call `stage_callback` for every IdeBuildStage registered in the pipeline.

#### Parameters

self | An IdeBuildPipeline |
stage_callback | A callback for each IdePipelineStage. | [scope call]
user_data | user data for `stage_callback` |

### ide_build_pipeline_clean_async ()

    void
    ide_build_pipeline_clean_async (IdeBuildPipeline *self,
                                    IdeBuildPhase phase,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

### ide_build_pipeline_clean_finish ()

    gboolean
    ide_build_pipeline_clean_finish (IdeBuildPipeline *self,
                                     GAsyncResult *result,
                                     GError **error);

### ide_build_pipeline_rebuild_async ()

    void
    ide_build_pipeline_rebuild_async (IdeBuildPipeline *self,
                                      IdeBuildPhase phase,
                                      GCancellable *cancellable,
                                      GAsyncReadyCallback callback,
                                      gpointer user_data);

### ide_build_pipeline_rebuild_finish ()

    gboolean
    ide_build_pipeline_rebuild_finish (IdeBuildPipeline *self,
                                       GAsyncResult *result,
                                       GError **error);

### ide_build_pipeline_attach_pty ()

    void
    ide_build_pipeline_attach_pty (IdeBuildPipeline *self,
                                   IdeSubprocessLauncher *launcher);

Attaches a PTY to stdin/stdout/stderr of the IdeSubprocessLauncher. This is useful if the application can take advantage of a PTY for features like colors and other escape sequences.

#### Parameters

self | an IdeBuildPipeline |
launcher | an IdeSubprocessLauncher |

Since: 3.28

### ide_build_pipeline_has_configured ()

    gboolean
    ide_build_pipeline_has_configured (IdeBuildPipeline *self);

Checks to see if the pipeline has advanced far enough to ensure that the configure stage has been reached.

#### Parameters

self | a IdeBuildPipeline |

#### Returns

`TRUE` if `IDE_BUILD_PHASE_CONFIGURE` has been reached.

Since: 3.28

### ide_build_pipeline_get_requested_phase ()

    IdeBuildPhase
    ide_build_pipeline_get_requested_phase
                                   (IdeBuildPipeline *self);

Gets the phase that has been requested. This can be useful when you want to get an idea of where the build pipeline will attempt to advance.

#### Parameters

self | a IdeBuildPipeline |

#### Returns

an IdeBuildPhase

Since: 3.28

### ide_build_pipeline_is_native ()

    gboolean
    ide_build_pipeline_is_native (IdeBuildPipeline *self);

Checks to see if the pipeline is building for the native architecture, kernel, and system of the host.

This is equivalent to checking if `ide_get_system_type()` matches the host triplet (arch, kernel, system) properties of the pipeline.

#### Parameters

self | a IdeBuildPipeline |

#### Returns

`TRUE` if this is a native build, otherwise `FALSE`.

## Types and Values

### IDE_TYPE_BUILD_PIPELINE

    #define IDE_TYPE_BUILD_PIPELINE     (ide_build_pipeline_get_type())

### IDE_BUILD_PHASE_MASK

    #define IDE_BUILD_PHASE_MASK        (0xFFFFFF)

### IDE_BUILD_PHASE_WHENCE_MASK

    #define IDE_BUILD_PHASE_WHENCE_MASK (IDE_BUILD_PHASE_BEFORE | IDE_BUILD_PHASE_AFTER)

### enum IdeBuildPhase

#### Members

IDE_BUILD_PHASE_NONE |  |
IDE_BUILD_PHASE_PREPARE |  |
IDE_BUILD_PHASE_DOWNLOADS |  |
IDE_BUILD_PHASE_DEPENDENCIES |  |
IDE_BUILD_PHASE_AUTOGEN |  |
IDE_BUILD_PHASE_CONFIGURE |  |
IDE_BUILD_PHASE_BUILD |  |
IDE_BUILD_PHASE_INSTALL |  |
IDE_BUILD_PHASE_COMMIT |  |
IDE_BUILD_PHASE_EXPORT |  |
IDE_BUILD_PHASE_FINAL |  |
IDE_BUILD_PHASE_BEFORE |  |
IDE_BUILD_PHASE_AFTER |  |
IDE_BUILD_PHASE_FINISHED |  |
IDE_BUILD_PHASE_FAILED |  |

### IdeBuildPipeline

    typedef struct _IdeBuildPipeline IdeBuildPipeline;

## Property Details

### The `“busy”` property

      “busy”                     gboolean

Gets the "busy" property. If `TRUE`, the pipeline is busy executing.

Flags: Read / Write

Default value: FALSE

### The `“configuration”` property

      “configuration”            IdeConfiguration *

The configuration to use for the build pipeline.

Flags: Read / Write / Construct Only

### The `“device”` property

      “device”                   IdeDevice *

The "device" property is the device we are compiling for.

Flags: Read / Write / Construct Only

Since: 3.28

### The `“message”` property

      “message”                  gchar *

The "message" property is descriptive text about what the the pipeline is doing or it's readiness status.

Flags: Read

Default value: NULL

Since: 3.28

### The `“phase”` property

      “phase”                    IdeBuildPhase

The current build phase during execution of the pipeline.

Flags: Read

### The `“pty”` property

      “pty”                      VtePty *

The "pty" property is the VtePty that is used by build stages that execute subprocesses with a pseudo terminal.

Flags: Read

Since: 3.28

## Signal Details

### The `“diagnostic”` signal

    void
    user_function (IdeBuildPipeline *self,
                   IdeDiagnostic    *diagnostic,
                   gpointer          user_data)

This signal is emitted when a plugin has detected a diagnostic while building the pipeline.

#### Parameters

self | An IdeBuildPipeline |
diagnostic | The newly created diagnostic |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“finished”` signal

    void
    user_function (IdeBuildPipeline *self,
                   gboolean          failed,
                   gpointer          user_data)

This signal is emitted when the build process has finished executing. If the build failed to complete all requested stages, then `failed` will be set to `TRUE`, otherwise `FALSE`.

#### Parameters

self | An IdeBuildPipeline |
failed | If the build was a failure |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“started”` signal

    void
    user_function (IdeBuildPipeline *self,
                   IdeBuildPhase     phase,
                   gpointer          user_data)

This signal is emitted when the pipeline has started executing in response to `ide_build_pipeline_execute_async()` being called.

#### Parameters

self | An IdeBuildPipeline |
phase | the IdeBuildPhase for which we are advancing |
user_data | user data set when the signal handler was connected. |

Flags: Run Last