process/io.matthewnelson.kmp.process/Process/Builder

Builder

class Builder(val command: String) : Blocking.Builder(source)

Creates a new Process.

e.g. (Shell commands on a Unix system)

val out = Process.Builder("sh")
    .args("-c")
    .args("sleep 1; exit 5")
    .destroySignal(Signal.SIGKILL)
    .stdin(Stdio.Null)
    // Synchronous API (All platforms)
    .createOutput { timeoutMillis = 1_500 }

assertEquals(5, out.processInfo.exitCode)

e.g. (Executable file)

val b = Process.Builder(myExecutableFile)
    .args("--some-flag")
    .args("someValue")
    .args("--another-flag", "anotherValue")
    .environment {
        remove("HOME")
        // ...
    }
    .stdin(Stdio.Null)
    .stdout(Stdio.File.of("logs/myExecutable.log", append = true))
    .stderr(Stdio.File.of("logs/myExecutable.err"))

// Synchronous API (Jvm/Native)
b.createProcess().use { p ->
    // ...
}

// Asynchronous API (All platforms)
myScope.launch {
    b.createProcessAsync().use { p ->
        // ...
    }
}

Constructors

Builder

constructor(command: String)

constructor(executable: File)

An alternate constructor for an executable File. Will take the absolute & normalized path to use for command.

Properties

command

@JvmField

val command: String

The command to run, such as a program on PATH, or a file path (relative or absolute) to a program.

Functions

args

fun args(arg: String): Process.Builder

Add a single argument.

fun args(vararg args: String): Process.Builder

fun args(args: List<String>): Process.Builder

Add multiple arguments.

async

fun async(context: CoroutineContext?): Process.Builder

DEFAULT: Dispatchers.IO (Jvm/Native), Dispatchers.Default (Js/WasmJs)

changeDir

fun Process.Builder.changeDir(directory: File?): Process.Builder

Changes the working directory of the spawned process.

createOutput

fun createOutput(): Output

inline fun createOutput(block: Output.Options.Builder.() -> Unit): Output

Blocks the current thread until Process completion, Output.Options.Builder.timeoutMillis is exceeded, or Output.Options.Builder.maxBuffer is exceeded.

createOutputAsync

suspend fun createOutputAsync(): Output

inline suspend fun createOutputAsync(block: Output.Options.Builder.() -> Unit): Output

Creates the Process asynchronously using the configured async context and suspends until its completion, Output.Options.Builder.timeoutMillis is exceeded, or Output.Options.Builder.maxBuffer is exceeded.