IdeBuildStage

IdeBuildStage

Functions

Properties

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

Signals

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

Types and Values

Object Hierarchy

    GObject
    ╰── IdeObject
        ╰── IdeBuildStage
            ├── IdeBuildStageLauncher
            ├── IdeBuildStageMkdirs
            ╰── IdeBuildStageTransfer

Description

Functions

ide_build_stage_get_active ()

gboolean
ide_build_stage_get_active (IdeBuildStage *self);

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

Parameters

self

a IdeBuildStage

 

Returns

TRUE if the stage is actively executing or cleaning.

Since: 3.28


ide_build_stage_set_active ()

void
ide_build_stage_set_active (IdeBuildStage *self,
                            gboolean active);

ide_build_stage_get_name ()

const gchar *
ide_build_stage_get_name (IdeBuildStage *self);

ide_build_stage_set_name ()

void
ide_build_stage_set_name (IdeBuildStage *self,
                          const gchar *name);

ide_build_stage_log ()

void
ide_build_stage_log (IdeBuildStage *self,
                     IdeBuildLogStream stream,
                     const gchar *message,
                     gssize message_len);

ide_build_stage_log_subprocess ()

void
ide_build_stage_log_subprocess (IdeBuildStage *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 IdeBuildStage

 

subprocess

An IdeSubprocess

 

ide_build_stage_set_log_observer ()

void
ide_build_stage_set_log_observer (IdeBuildStage *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 IdeBuildStage

 

observer

The observer for the log entries.

[scope async]

observer_data

data for observer

 

observer_data_destroy

destroy callback for observer_data

 

ide_build_stage_set_stdout_path ()

void
ide_build_stage_set_stdout_path (IdeBuildStage *self,
                                 const gchar *path);

ide_build_stage_get_stdout_path ()

const gchar *
ide_build_stage_get_stdout_path (IdeBuildStage *self);

ide_build_stage_get_completed ()

gboolean
ide_build_stage_get_completed (IdeBuildStage *self);

ide_build_stage_set_completed ()

void
ide_build_stage_set_completed (IdeBuildStage *self,
                               gboolean completed);

ide_build_stage_get_disabled ()

gboolean
ide_build_stage_get_disabled (IdeBuildStage *self);

ide_build_stage_set_disabled ()

void
ide_build_stage_set_disabled (IdeBuildStage *self,
                              gboolean disabled);

ide_build_stage_get_check_stdout ()

gboolean
ide_build_stage_get_check_stdout (IdeBuildStage *self);

ide_build_stage_set_check_stdout ()

void
ide_build_stage_set_check_stdout (IdeBuildStage *self,
                                  gboolean check_stdout);

ide_build_stage_get_transient ()

gboolean
ide_build_stage_get_transient (IdeBuildStage *self);

ide_build_stage_set_transient ()

void
ide_build_stage_set_transient (IdeBuildStage *self,
                               gboolean transient);

ide_build_stage_execute_async ()

void
ide_build_stage_execute_async (IdeBuildStage *self,
                               IdeBuildPipeline *pipeline,
                               GCancellable *cancellable,
                               GAsyncReadyCallback callback,
                               gpointer user_data);

ide_build_stage_execute_finish ()

gboolean
ide_build_stage_execute_finish (IdeBuildStage *self,
                                GAsyncResult *result,
                                GError **error);

ide_build_stage_clean_async ()

void
ide_build_stage_clean_async (IdeBuildStage *self,
                             IdeBuildPipeline *pipeline,
                             GCancellable *cancellable,
                             GAsyncReadyCallback callback,
                             gpointer user_data);

ide_build_stage_clean_finish ()

gboolean
ide_build_stage_clean_finish (IdeBuildStage *self,
                              GAsyncResult *result,
                              GError **error);

ide_build_stage_chain ()

gboolean
ide_build_stage_chain (IdeBuildStage *self,
                       IdeBuildStage *next);

ide_build_stage_pause ()

void
ide_build_stage_pause (IdeBuildStage *self);

ide_build_stage_unpause ()

void
ide_build_stage_unpause (IdeBuildStage *self);

ide_build_stage_emit_reap ()

void
ide_build_stage_emit_reap (IdeBuildStage *self,
                           DzlDirectoryReaper *reaper);

Types and Values

IDE_TYPE_BUILD_STAGE

#define IDE_TYPE_BUILD_STAGE (ide_build_stage_get_type())

struct IdeBuildStageClass

struct IdeBuildStageClass {
  IdeObjectClass parent_class;

  /**
   * IdeBuildStage::execute:
   *
   * This vfunc will be run in a thread by the default
   * IdeBuildStage::execute_async() and IdeBuildStage::execute_finish()
   * vfuncs.
   *
   * Only use thread-safe API from this function.
   */
  gboolean (*execute)        (IdeBuildStage        *self,
                              IdeBuildPipeline     *pipeline,
                              GCancellable         *cancellable,
                              GError              **error);

  /**
   * IdeBuildStage::execute_async:
   *
   * Asynchronous version of the #IdeBuildStage API. This is the preferred
   * way to subclass #IdeBuildStage.
   */
  void     (*execute_async)  (IdeBuildStage        *self,
                              IdeBuildPipeline     *pipeline,
                              GCancellable         *cancellable,
                              GAsyncReadyCallback   callback,
                              gpointer              user_data);

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

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

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

  /**
   * IdeBuildStage::query:
   * @self: An #IdeBuildStage
   * @pipeline: An #IdeBuildPipeline
   * @cancellable: (nullable): a #GCancellable or %NULL
   *
   * The #IdeBuildStage::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.
   *
   * For example, in a signal handler, you may call ide_build_stage_pause()
   * and perform an external operation. Forward progress of the stage will
   * be paused until a matching number of ide_build_stage_unpause() calls
   * have been made.
   */
  void     (*query)          (IdeBuildStage        *self,
                              IdeBuildPipeline     *pipeline,
                              GCancellable         *cancellable);

  /**
   * IdeBuildStage::reap:
   * @self: An #IdeBuildStage
   * @reaper: An #DzlDirectoryReaper
   *
   * 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.
   */
  void     (*reap)           (IdeBuildStage        *self,
                              DzlDirectoryReaper   *reaper);


  /**
   * IdeBuildStage:chain:
   *
   * We might want to be able to "chain" multiple stages into a single stage
   * so that we can avoid duplicate work. For example, if we have a "make"
   * stage immediately follwed by a "make install" stage, it does not make
   * sense to perform them both individually.
   *
   * Returns: %TRUE if @next's work was chained into @self for the next
   *    execution of the pipeline.
   */
  gboolean (*chain)          (IdeBuildStage        *self,
                              IdeBuildStage        *next);
};

IdeBuildStage

typedef struct _IdeBuildStage IdeBuildStage;

Property Details

The “active” property

  “active”                   gboolean

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

Flags: Read / Write

Default value: FALSE

Since: 3.28


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.

Flags: Read / Write

Default value: FALSE


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.

Flags: Read / Write

Default value: FALSE


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-execute the pipeline.

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

Flags: Read / Write

Default value: FALSE


The “name” property

  “name”                     gchar *

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

Flags: Read / Write

Default value: NULL


The “stdout-path” property

  “stdout-path”              gchar *

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.

Flags: Read / Write

Default value: NULL


The “transient” property

  “transient”                gboolean

If the build stage is transient.

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

Flags: Read / Write

Default value: FALSE

Signal Details

The “chain” signal

gboolean
user_function (IdeBuildStage *idebuildstage,
               IdeBuildStage *arg1,
               gpointer       user_data)

Flags: Run Last


The “query” signal

void
user_function (IdeBuildStage    *self,
               IdeBuildPipeline *pipeline,
               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.

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

Parameters

self

An IdeBuildStage

 

pipeline

An IdeBuildPipeline

 

cancellable

a GCancellable or NULL.

[nullable]

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “reap” signal

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

 

reaper

An DzlDirectoryReaper

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last