ide-pipeline

ide-pipeline

Functions

GQuark ide_build_error_quark ()
gchar * ide_pipeline_get_arch ()
gboolean ide_pipeline_is_native ()
gboolean ide_pipeline_is_ready ()
gboolean ide_pipeline_get_busy ()
IdeConfig * ide_pipeline_get_config ()
IdeDevice * ide_pipeline_get_device ()
IdeDeviceInfo * ide_pipeline_get_device_info ()
IdeTriplet * ide_pipeline_get_host_triplet ()
IdeRuntime * ide_pipeline_get_runtime ()
IdeToolchain * ide_pipeline_get_toolchain ()
IdeToolchain * ide_pipeline_ref_toolchain ()
const gchar * ide_pipeline_get_builddir ()
const gchar * ide_pipeline_get_srcdir ()
gchar * ide_pipeline_get_message ()
IdePipelinePhase ide_pipeline_get_phase ()
gboolean ide_pipeline_get_can_export ()
VtePty * ide_pipeline_get_pty ()
IdeSubprocessLauncher * ide_pipeline_create_launcher ()
gchar * ide_pipeline_build_srcdir_path ()
gchar * ide_pipeline_build_builddir_path ()
void ide_pipeline_invalidate_phase ()
gboolean ide_pipeline_request_phase ()
guint ide_pipeline_attach ()
guint ide_pipeline_attach_launcher ()
void ide_pipeline_detach ()
IdePipelineStage * ide_pipeline_get_stage_by_id ()
guint ide_pipeline_add_log_observer ()
gboolean ide_pipeline_remove_log_observer ()
void ide_pipeline_emit_diagnostic ()
guint ide_pipeline_add_error_format ()
gboolean ide_pipeline_remove_error_format ()
void ide_pipeline_build_async ()
gboolean ide_pipeline_build_finish ()
void ide_pipeline_build_targets_async ()
gboolean ide_pipeline_build_targets_finish ()
void ide_pipeline_foreach_stage ()
void ide_pipeline_clean_async ()
gboolean ide_pipeline_clean_finish ()
void ide_pipeline_rebuild_async ()
gboolean ide_pipeline_rebuild_finish ()
void ide_pipeline_attach_pty ()
gboolean ide_pipeline_has_configured ()
IdePipelinePhase ide_pipeline_get_requested_phase ()

Properties

gboolean busy Read / Write
IdeConfig * config Read / Write / Construct Only
IdeDevice * device Read / Write / Construct Only
gchar * message Read
IdePipelinePhase phase Read
VtePty * pty Read

Signals

Types and Values

Object Hierarchy

    GEnum
    ╰── IdeBuildError
    GFlags
    ╰── IdePipelinePhase
    GObject
    ╰── IdeObject
        ╰── IdePipeline

Implemented Interfaces

IdePipeline implements GListModel and GInitable.

Description

Functions

ide_build_error_quark ()

GQuark
ide_build_error_quark (void);

ide_pipeline_get_arch ()

gchar *
ide_pipeline_get_arch (IdePipeline *self);

ide_pipeline_is_native ()

gboolean
ide_pipeline_is_native (IdePipeline *self);

This is a helper to check if the triplet that we are compiling for matches the host system. That allows some plugins to do less work by avoiding some cross-compiling work.

Parameters

self

a IdePipeline

 

Returns

FALSE if we're possibly cross-compiling, otherwise TRUE

Since: 3.32


ide_pipeline_is_ready ()

gboolean
ide_pipeline_is_ready (IdePipeline *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 IdePipeline

 

Returns

TRUE if the pipeline has loaded, otherwise FALSE

Since: 3.32


ide_pipeline_get_busy ()

gboolean
ide_pipeline_get_busy (IdePipeline *self);

ide_pipeline_get_config ()

IdeConfig *
ide_pipeline_get_config (IdePipeline *self);

Gets the IdeConfig to use for the pipeline.

Returns

An IdeConfig.

[transfer none]

Since: 3.32


ide_pipeline_get_device ()

IdeDevice *
ide_pipeline_get_device (IdePipeline *self);

Gets the device that the pipeline is building for.

Parameters

self

a IdePipeline

 

Returns

an IdeDevice.

[transfer none]

Since: 3.32


ide_pipeline_get_device_info ()

IdeDeviceInfo *
ide_pipeline_get_device_info (IdePipeline *self);

Gets the device info for the current device.

Parameters

self

a IdePipeline

 

Returns

an IdeDeviceInfo or NULL.

[nullable][transfer none]

Since: 3.32


ide_pipeline_get_host_triplet ()

IdeTriplet *
ide_pipeline_get_host_triplet (IdePipeline *self);

Gets the "host" triplet which specifies where the build results will run.

This is a convenience wrapper around getting the triplet from the device set for the build pipeline.

Parameters

self

a IdePipeline

 

Returns

an IdeTriplet.

[transfer none]

Since: 3.32


ide_pipeline_get_runtime ()

IdeRuntime *
ide_pipeline_get_runtime (IdePipeline *self);

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

Parameters

self

An IdePipeline

 

Returns

An IdeRuntime or NULL.

[transfer none][nullable]

Since: 3.32


ide_pipeline_get_toolchain ()

IdeToolchain *
ide_pipeline_get_toolchain (IdePipeline *self);

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

Parameters

self

An IdePipeline

 

Returns

An IdeToolchain.

[transfer none]

Since: 3.32


ide_pipeline_ref_toolchain ()

IdeToolchain *
ide_pipeline_ref_toolchain (IdePipeline *self);

Thread-safe variant of ide_pipeline_get_toolchain().

Parameters

self

a IdePipeline

 

Returns

an IdeToolchain or NULL.

[transfer full][nullable]

Since: 3.32


ide_pipeline_get_builddir ()

const gchar *
ide_pipeline_get_builddir (IdePipeline *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 IdePipeline

 

Returns

the path of the build directory

Since: 3.32


ide_pipeline_get_srcdir ()

const gchar *
ide_pipeline_get_srcdir (IdePipeline *self);

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

Parameters

self

An IdePipeline

 

Returns

the path of the source directory

Since: 3.32


ide_pipeline_get_message ()

gchar *
ide_pipeline_get_message (IdePipeline *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 IdePipeline

 

Returns

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

[nullable][transfer full]

Since: 3.32


ide_pipeline_get_phase ()

IdePipelinePhase
ide_pipeline_get_phase (IdePipeline *self);

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

Since: 3.32


ide_pipeline_get_can_export ()

gboolean
ide_pipeline_get_can_export (IdePipeline *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 IdePipeline

 

Returns

TRUE if there are export pipeline stages.

Since: 3.32


ide_pipeline_get_pty ()

VtePty *
ide_pipeline_get_pty (IdePipeline *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 IdePipeline

 

Returns

a VtePty or NULL.

[transfer none][nullable]

Since: 3.32


ide_pipeline_create_launcher ()

IdeSubprocessLauncher *
ide_pipeline_create_launcher (IdePipeline *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 IdePipeline

 

Returns

An IdeSubprocessLauncher.

[transfer full]

Since: 3.32


ide_pipeline_build_srcdir_path ()

gchar *
ide_pipeline_build_srcdir_path (IdePipeline *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]

Since: 3.32


ide_pipeline_build_builddir_path ()

gchar *
ide_pipeline_build_builddir_path (IdePipeline *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_pipeline_get_builddir() as the first parameter.

Returns

A newly allocated string.

[transfer full]

Since: 3.32


ide_pipeline_invalidate_phase ()

void
ide_pipeline_invalidate_phase (IdePipeline *self,
                               IdePipelinePhase phases);

Invalidates the phases matching phases flags.

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

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

Parameters

self

An IdePipeline

 

phases

The phases to invalidate

 

Since: 3.32


ide_pipeline_request_phase ()

gboolean
ide_pipeline_request_phase (IdePipeline *self,
                            IdePipelinePhase phase);

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

Parameters

self

An IdePipeline

 

phase

An IdePipelinePhase

 

Returns

TRUE if a stage is known to require execution.

Since: 3.32


ide_pipeline_attach ()

guint
ide_pipeline_attach (IdePipeline *self,
                     IdePipelinePhase phase,
                     gint priority,
                     IdePipelineStage *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 IdePipeline

 

phase

An IdePipelinePhase

 

priority

an optional priority for sorting within the phase

 

stage

An IdePipelineStage

 

Returns

A stage_id that may be passed to ide_pipeline_detach().

Since: 3.32


ide_pipeline_attach_launcher ()

guint
ide_pipeline_attach_launcher (IdePipeline *self,
                              IdePipelinePhase 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 IdePipeline

 

phase

An IdePipelinePhase

 

priority

an optional priority for sorting within the phase

 

launcher

An IdeSubprocessLauncher

 

Returns

A stage_id that may be passed to ide_pipeline_remove().

Since: 3.32


ide_pipeline_detach ()

void
ide_pipeline_detach (IdePipeline *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_pipeline_attach() or ide_pipeline_attach_launcher().

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

Parameters

self

An IdePipeline

 

stage_id

An identifier returned from adding a stage

 

Since: 3.32


ide_pipeline_get_stage_by_id ()

IdePipelineStage *
ide_pipeline_get_stage_by_id (IdePipeline *self,
                              guint stage_id);

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

Parameters

self

An IdePipeline

 

stage_id

the identfier of the stage

 

Returns

An IdePipelineStage or NULL if the stage could not be found.

[transfer none][nullable]

Since: 3.32


ide_pipeline_add_log_observer ()

guint
ide_pipeline_add_log_observer (IdePipeline *self,
                               IdeBuildLogObserver observer,
                               gpointer observer_data,
                               GDestroyNotify observer_data_destroy);

ide_pipeline_remove_log_observer ()

gboolean
ide_pipeline_remove_log_observer (IdePipeline *self,
                                  guint observer_id);

ide_pipeline_emit_diagnostic ()

void
ide_pipeline_emit_diagnostic (IdePipeline *self,
                              IdeDiagnostic *diagnostic);

ide_pipeline_add_error_format ()

guint
ide_pipeline_add_error_format (IdePipeline *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_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 IdePipeline

 

regex

A regex to be compiled

 

Returns

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

Since: 3.32


ide_pipeline_remove_error_format ()

gboolean
ide_pipeline_remove_error_format (IdePipeline *self,
                                  guint error_format_id);

Removes an error format that was registered with ide_pipeline_add_error_format().

Parameters

self

An IdePipeline

 

error_format_id

an identifier for the error format.

 

Returns

TRUE if the error format was removed.

Since: 3.32


ide_pipeline_build_async ()

void
ide_pipeline_build_async (IdePipeline *self,
                          IdePipelinePhase phase,
                          GCancellable *cancellable,
                          GAsyncReadyCallback callback,
                          gpointer user_data);

Asynchronously starts the build pipeline.

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

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

Upon completion, callback will be buildd and should call ide_pipeline_build_finish() to get the status of the operation.

Parameters

self

A IdePipeline

 

phase

the requested build phase

 

cancellable

a GCancellable or NULL.

[nullable]

callback

a callback to build upon completion

 

user_data

data for callback

 

Since: 3.32


ide_pipeline_build_finish ()

gboolean
ide_pipeline_build_finish (IdePipeline *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 IdePipeline

 

result

a GAsyncResult provided to callback

 

error

A location for a GError, or NULL

 

Returns

TRUE if the build stages were buildd successfully up to the requested build phase provided to ide_pipeline_build_async().

Since: 3.32


ide_pipeline_build_targets_async ()

void
ide_pipeline_build_targets_async (IdePipeline *self,
                                  IdePipelinePhase phase,
                                  GPtrArray *targets,
                                  GCancellable *cancellable,
                                  GAsyncReadyCallback callback,
                                  gpointer user_data);

Asynchronously starts the build pipeline.

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

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

Upon completion, callback will be buildd and should call ide_pipeline_build_finish() to get the status of the operation.

Parameters

self

A IdePipeline

 

phase

the requested build phase

 

targets

an optional array of IdeBuildTarget for the pipeline to build.

[nullable][element-type IdeBuildTarget]

cancellable

a GCancellable or NULL.

[nullable]

callback

a callback to build upon completion

 

user_data

data for callback

 

Since: 3.32


ide_pipeline_build_targets_finish ()

gboolean
ide_pipeline_build_targets_finish (IdePipeline *self,
                                   GAsyncResult *result,
                                   GError **error);

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

Parameters

self

An IdePipeline

 

result

a GAsyncResult provided to callback

 

error

A location for a GError, or NULL

 

Returns

TRUE if the build stages were buildd successfully up to the requested build phase provided to ide_pipeline_build_targets_async().

Since: 3.32


ide_pipeline_foreach_stage ()

void
ide_pipeline_foreach_stage (IdePipeline *self,
                            GFunc stage_callback,
                            gpointer user_data);

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

Parameters

self

An IdePipeline

 

stage_callback

A callback for each IdePipelineStage.

[scope call]

user_data

user data for stage_callback

 

Since: 3.32


ide_pipeline_clean_async ()

void
ide_pipeline_clean_async (IdePipeline *self,
                          IdePipelinePhase phase,
                          GCancellable *cancellable,
                          GAsyncReadyCallback callback,
                          gpointer user_data);

ide_pipeline_clean_finish ()

gboolean
ide_pipeline_clean_finish (IdePipeline *self,
                           GAsyncResult *result,
                           GError **error);

ide_pipeline_rebuild_async ()

void
ide_pipeline_rebuild_async (IdePipeline *self,
                            IdePipelinePhase phase,
                            GPtrArray *targets,
                            GCancellable *cancellable,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

Asynchronously starts the build pipeline after cleaning any existing build artifacts.

Parameters

self

A IdePipeline

 

phase

the requested build phase

 

targets

an array of IdeBuildTarget or NULL.

[element-type IdeBuildTarget][nullable]

cancellable

a GCancellable or NULL.

[nullable]

callback

a callback to build upon completion

 

user_data

data for callback

 

Since: 3.32


ide_pipeline_rebuild_finish ()

gboolean
ide_pipeline_rebuild_finish (IdePipeline *self,
                             GAsyncResult *result,
                             GError **error);

ide_pipeline_attach_pty ()

void
ide_pipeline_attach_pty (IdePipeline *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 IdePipeline

 

launcher

an IdeSubprocessLauncher

 

Since: 3.32


ide_pipeline_has_configured ()

gboolean
ide_pipeline_has_configured (IdePipeline *self);

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

Parameters

self

a IdePipeline

 

Returns

TRUE if IDE_PIPELINE_PHASE_CONFIGURE has been reached.

Since: 3.32


ide_pipeline_get_requested_phase ()

IdePipelinePhase
ide_pipeline_get_requested_phase (IdePipeline *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 IdePipeline

 

Returns

an IdePipelinePhase

Since: 3.32

Types and Values

IDE_TYPE_PIPELINE

#define IDE_TYPE_PIPELINE              (ide_pipeline_get_type())

IDE_PIPELINE_PHASE_MASK

#define IDE_PIPELINE_PHASE_MASK        (0xFFFFFF)

IDE_PIPELINE_PHASE_WHENCE_MASK

#define IDE_PIPELINE_PHASE_WHENCE_MASK (IDE_PIPELINE_PHASE_BEFORE | IDE_PIPELINE_PHASE_AFTER)

IDE_BUILD_ERROR

#define IDE_BUILD_ERROR                (ide_build_error_quark())

enum IdePipelinePhase

Members

IDE_PIPELINE_PHASE_NONE

   

IDE_PIPELINE_PHASE_PREPARE

   

IDE_PIPELINE_PHASE_DOWNLOADS

   

IDE_PIPELINE_PHASE_DEPENDENCIES

   

IDE_PIPELINE_PHASE_AUTOGEN

   

IDE_PIPELINE_PHASE_CONFIGURE

   

IDE_PIPELINE_PHASE_BUILD

   

IDE_PIPELINE_PHASE_INSTALL

   

IDE_PIPELINE_PHASE_COMMIT

   

IDE_PIPELINE_PHASE_EXPORT

   

IDE_PIPELINE_PHASE_FINAL

   

IDE_PIPELINE_PHASE_BEFORE

   

IDE_PIPELINE_PHASE_AFTER

   

IDE_PIPELINE_PHASE_FINISHED

   

IDE_PIPELINE_PHASE_FAILED

   

enum IdeBuildError

Members

IDE_BUILD_ERROR_UNKNOWN

   

IDE_BUILD_ERROR_BROKEN

   

IDE_BUILD_ERROR_NOT_LOADED

   

IDE_BUILD_ERROR_NEEDS_REBUILD

   

IdePipeline

typedef struct _IdePipeline IdePipeline;

Property Details

The “busy” property

  “busy”                     gboolean

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

Flags: Read / Write

Default value: FALSE

Since: 3.32


The “config” property

  “config”                   IdeConfig *

Configuration.

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.32


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.32


The “phase” property

  “phase”                    IdePipelinePhase

The current build phase during execution of the pipeline.

Flags: Read

Since: 3.32


The “pty” property

  “pty”                      VtePty *

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

Flags: Read

Since: 3.32

Signal Details

The “diagnostic” signal

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

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

Parameters

self

An IdePipeline

 

diagnostic

The newly created diagnostic

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 3.32


The “finished” signal

void
user_function (IdePipeline *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 IdePipeline

 

failed

If the build was a failure

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 3.32


The “loaded” signal

void
user_function (IdePipeline *idepipeline,
               gpointer     user_data)

The "loaded" signal is emitted after the pipeline has finished loading addins.

Parameters

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 3.32


The “started” signal

void
user_function (IdePipeline     *self,
               IdePipelinePhase phase,
               gpointer         user_data)

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

Parameters

self

An IdePipeline

 

phase

the IdePipelinePhase for which we are advancing

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 3.32