IdeRunner: Builder SDK Reference

## IdeRunner IdeRunner |

## Functions

IdeRunner * | ide_runner_new ()
gboolean | ide_runner_get_failed ()
void | ide_runner_set_failed ()
IdeRuntime * | ide_runner_get_runtime ()
void | ide_runner_force_quit ()
IdeEnvironment * | ide_runner_get_environment ()
void | ide_runner_run_async ()
gboolean | ide_runner_run_finish ()
GSubprocessFlags | ide_runner_get_flags ()
void | ide_runner_set_flags ()
const gchar * | ide_runner_get_cwd ()
void | ide_runner_set_cwd ()
gboolean | ide_runner_get_clear_env ()
void | ide_runner_set_clear_env ()
void | ide_runner_prepend_argv ()
void | ide_runner_append_argv ()
void | ide_runner_push_args ()
gchar ** | ide_runner_get_argv ()
void | ide_runner_set_argv ()
gint | ide_runner_take_fd ()
GOutputStream * | ide_runner_get_stdin ()
GInputStream * | ide_runner_get_stdout ()
GInputStream * | ide_runner_get_stderr ()
gboolean | ide_runner_get_run_on_host ()
void | ide_runner_set_run_on_host ()
void | ide_runner_set_tty ()
gint | ide_runner_steal_tty ()
IdeBuildTarget * | ide_runner_get_build_target ()
void | ide_runner_set_build_target ()

## Properties

GStrv | argv | Read / Write
IdeBuildTarget * | build-target | Read / Write
gboolean | clear-env | Read / Write
gchar * | cwd | Read / Write
IdeEnvironment * | environment | Read
gboolean | failed | Read / Write
gboolean | run-on-host | Read / Write

## Signals

void | exited | Run Last
void | spawned | Run Last

## Types and Values

#define | IDE_TYPE_RUNNER
struct | IdeRunnerClass
| IdeRunner

## Object Hierarchy

        GObject
        ╰── IdeObject
            ╰── IdeRunner

## Description

## Functions

### ide_runner_new ()

    IdeRunner *
    ide_runner_new (IdeContext *context);

### ide_runner_get_failed ()

    gboolean
    ide_runner_get_failed (IdeRunner *self);

### ide_runner_set_failed ()

    void
    ide_runner_set_failed (IdeRunner *self,
                           gboolean failed);

### ide_runner_get_runtime ()

    IdeRuntime *
    ide_runner_get_runtime (IdeRunner *self);

This function will get the IdeRuntime that will be used to execute the application. Consumers may want to use this to determine if a particular program is available (such as gdb, perf, strace, etc).

#### Parameters

self | An IdeRuntime |

#### Returns

An IdeRuntime or `NULL`.

[nullable][transfer full]

### ide_runner_force_quit ()

    void
    ide_runner_force_quit (IdeRunner *self);

### ide_runner_get_environment ()

    IdeEnvironment *
    ide_runner_get_environment (IdeRunner *self);

#### Returns

The IdeEnvironment the process launched uses.

[transfer none]

### ide_runner_run_async ()

    void
    ide_runner_run_async (IdeRunner *self,
                          GCancellable *cancellable,
                          GAsyncReadyCallback callback,
                          gpointer user_data);

### ide_runner_run_finish ()

    gboolean
    ide_runner_run_finish (IdeRunner *self,
                           GAsyncResult *result,
                           GError **error);

### ide_runner_get_flags ()

    GSubprocessFlags
    ide_runner_get_flags (IdeRunner *self);

### ide_runner_set_flags ()

    void
    ide_runner_set_flags (IdeRunner *self,
                          GSubprocessFlags flags);

### ide_runner_get_cwd ()

    const gchar *
    ide_runner_get_cwd (IdeRunner *self);

#### Parameters

self | a IdeRunner |

#### Returns

The current working directory, or `NULL`.

[nullable]

Since: 3.28

### ide_runner_set_cwd ()

    void
    ide_runner_set_cwd (IdeRunner *self,
                        const gchar *cwd);

Sets the directory to use when spawning the runner.

#### Parameters

self | a IdeRunner |
cwd | The working directory or `NULL`. | [nullable]

Since: 3.28

### ide_runner_get_clear_env ()

    gboolean
    ide_runner_get_clear_env (IdeRunner *self);

### ide_runner_set_clear_env ()

    void
    ide_runner_set_clear_env (IdeRunner *self,
                              gboolean clear_env);

### ide_runner_prepend_argv ()

    void
    ide_runner_prepend_argv (IdeRunner *self,
                             const gchar *param);

### ide_runner_append_argv ()

    void
    ide_runner_append_argv (IdeRunner *self,
                            const gchar *param);

### ide_runner_push_args ()

    void
    ide_runner_push_args (IdeRunner *self,
                          const gchar * const *args);

Helper to call `ide_runner_append_argv()` for every argument contained in `args` .

#### Parameters

self | a IdeRunner |
args | the arguments. | [array zero-terminated=1][element-type utf8][nullable]

Since: 3.28

### ide_runner_get_argv ()

    gchar **
    ide_runner_get_argv (IdeRunner *self);

Gets the argument list as a newly allocated string array.

#### Returns

A newly allocated string array that should be freed with `g_strfreev()`.

[transfer full]

### ide_runner_set_argv ()

    void
    ide_runner_set_argv (IdeRunner *self,
                         const gchar * const *argv);

### ide_runner_take_fd ()

    gint
    ide_runner_take_fd (IdeRunner *self,
                        gint source_fd,
                        gint dest_fd);

This will ensure that `source_fd` is mapped into the new process as `dest_fd` . If `dest_fd` is -1, then the next fd will be used and that value will be returned. Note that this is not a valid fd in the calling process, only within the destination process.

#### Parameters

self | An IdeRunner |
source_fd | the fd to map, this will be closed by IdeRunner |
dest_fd | the target FD in the spawned process, or -1 for next available |

#### Returns

`dest_fd` or the FD or the next available dest_fd.

### ide_runner_get_stdin ()

    GOutputStream *
    ide_runner_get_stdin (IdeRunner *self);

#### Returns

An GOutputStream or `NULL`.

[nullable][transfer full]

### ide_runner_get_stdout ()

    GInputStream *
    ide_runner_get_stdout (IdeRunner *self);

#### Returns

An GOutputStream or `NULL`.

[nullable][transfer full]

### ide_runner_get_stderr ()

    GInputStream *
    ide_runner_get_stderr (IdeRunner *self);

#### Returns

An GOutputStream or `NULL`.

[nullable][transfer full]

### ide_runner_get_run_on_host ()

    gboolean
    ide_runner_get_run_on_host (IdeRunner *self);

### ide_runner_set_run_on_host ()

    void
    ide_runner_set_run_on_host (IdeRunner *self,
                                gboolean run_on_host);

### ide_runner_set_tty ()

    void
    ide_runner_set_tty (IdeRunner *self,
                        int tty_fd);

### ide_runner_steal_tty ()

    gint
    ide_runner_steal_tty (IdeRunner *self);

### ide_runner_get_build_target ()

    IdeBuildTarget *
    ide_runner_get_build_target (IdeRunner *self);

#### Parameters

self | a IdeRunner |

#### Returns

The `IdeBuildTarget` associated with this `IdeRunner`, or `NULL`. See “build-target” for details.

[nullable][transfer none]

Since: 3.28

### ide_runner_set_build_target ()

    void
    ide_runner_set_build_target (IdeRunner *self,
                                 IdeBuildTarget *build_target);

Sets the build target associated with this runner.

#### Parameters

self | a IdeRunner |
build_target | The build target, or `NULL`. | [nullable]

Since: 3.28

## Types and Values

### IDE_TYPE_RUNNER

    #define IDE_TYPE_RUNNER (ide_runner_get_type())

### struct IdeRunnerClass

    struct IdeRunnerClass {
      IdeObjectClass parent;

      void                   (*force_quit)      (IdeRunner             *self);
      GOutputStream         *(*get_stdin)       (IdeRunner             *self);
      GInputStream          *(*get_stdout)      (IdeRunner             *self);
      GInputStream          *(*get_stderr)      (IdeRunner             *self);
      void                   (*run_async)       (IdeRunner             *self,
                                                 GCancellable          *cancellable,
                                                 GAsyncReadyCallback    callback,
                                                 gpointer               user_data);
      gboolean               (*run_finish)      (IdeRunner             *self,
                                                 GAsyncResult          *result,
                                                 GError               **error);
      void                   (*set_tty)         (IdeRunner             *self,
                                                 int                    tty_fd);
      IdeSubprocessLauncher *(*create_launcher) (IdeRunner             *self);
      void                   (*fixup_launcher)  (IdeRunner             *self,
                                                 IdeSubprocessLauncher *launcher);
      IdeRuntime            *(*get_runtime)     (IdeRunner             *self);
    };

### IdeRunner

    typedef struct _IdeRunner IdeRunner;

## Property Details

### The `“argv”` property

      “argv”                     GStrv

The argument list for the command.

Flags: Read / Write

### The `“build-target”` property

      “build-target”             IdeBuildTarget *

The `IdeBuildTarget` from which this `IdeRunner` was constructed.

This is useful to retrieve various properties related to the program that will be launched, such as what programming language it uses, or whether it's a graphical application, a command line tool or a test program.

Flags: Read / Write

Since: 3.28

### The `“clear-env”` property

      “clear-env”                gboolean

If the environment should be cleared before applying overrides.

Flags: Read / Write

Default value: FALSE

### The `“cwd”` property

      “cwd”                      gchar *

The directory to use as the working directory for the process.

Flags: Read / Write

Default value: NULL

### The `“environment”` property

      “environment”              IdeEnvironment *

The environment variables for the command.

Flags: Read

### The `“failed”` property

      “failed”                   gboolean

If the runner has "failed". This should be set if a plugin can determine that the runner cannot be executed due to an external issue. One such example might be a debugger plugin that cannot locate a suitable debugger to run the program.

Flags: Read / Write

Default value: FALSE

### The `“run-on-host”` property

      “run-on-host”              gboolean

The "run-on-host" property indicates the program should be run on the host machine rather than inside the application sandbox.

Flags: Read / Write

Default value: FALSE

## Signal Details

### The `“exited”` signal

    void
    user_function (IdeRunner *iderunner,
                   gpointer   user_data)

Flags: Run Last

### The `“spawned”` signal

    void
    user_function (IdeRunner *iderunner,
                   gchar     *arg1,
                   gpointer   user_data)

Flags: Run Last