Command Reference

Execute Program

exec(cargo build)
exec("./some/local/executable" arg)

---

Spawns a process and waits for it to complete.

Arguments can be either a string literal or identifier. Note that the lexical definition of an identifier is loosened for this command to provide better ergonomics.

Metadata

meta(
    @attr_name "attr_value"
    @desc "attr_value"
)

---

Adds metadata to the current unit which can be viewed with august inspect.

This command is a no op at runtime.

Depends On

depends_on(Test)
depends_on(A, B, C)

---

Makes a unit a dependency of the current unit.

This command is a no op at runtime.

Do Unit

do(A)
do(A, B)

---

Runs a unit sequentially.

Example

do(A, B)

Is equivalent to:

do(A)
do(B)

Concurrency Block

0.6

Warning

This language feature is only useable on the async runtime as it would be incredibly expensive on threads.

concurrent {
    do(A)
    ~(cargo build)
    ~(npm run build)
}

---

Runs multiple commands at the same time. Works best for long running operations like executing CLI tools.

August runs the commands in a unit sequentially and a unit's dependencies in parallel. The concurrency block is useful for running multiple independent commands inline rather than creating new units.

The example above can be written without the concurrency block like so:

unit ConcurrencyBlock {
    depends_on(__command_a, __command_b, __command_c)
}

unit __command_a {
    do(A)
}

unit __command_b {
    ~(cargo build)
}

unit __command_c {
    ~(npm run build)
}

Module: fs

Create File

fs::create("path")

---

Creates an empty file.

Create Directory

fs::create_dir("path\of\dir")

---

Recursively creates an empty directory.

Remove File/Directory

fs::remove("path")
fs::remove("path\to\dir")

---

Removes a file or recursively removes a directory.

Copy File/Directory

fs::copy("src", "dst")
fs::copy("path\to\src\dir", "path\to\dst\dir")

---

Copies a file or directory to a different location.

Move File/Directory

fs::move("src", "dst")
fs::move("path\to\src\dir", "path\to\dst\dir")

---

Moves a file or directory to a different location.

Example

move("src", "dst")

Is equivalent to the following:

copy("src", "dst")
remove("src")

Copy and Move Expansions

0.6

fs::copy_to("dst", [
    "src",
    "src" => "dst"
])

fs::move_to("dst", [
    "src",
    "src" => "dst"
])

---

Expands to several copy/move calls to a common destination directory.

Example

fs::copy_to("dst", [
    "src",
    "src" => "dst"
])

Is equivalent to the following:

copy("src", "dst/src")
copy("src", "dst/dst")

Print/EPrint File

fs::print_file("path")
fs::eprint_file("path")

---

Print the contents of a file to stdout or stderr

Module: io

Print

io::print("Hello, World!")
io::println("Hello, World!")
io::eprint("Hello, World!")
io::eprintln("Hello, World!")

---

Prints text to stdout or stderr

Module: env

Set Environment Variable

env::set_var("VAR_NAME", "var_content")

---

Sets the value of an environment variable for the august process, which is inherited by child processes spawned by exec.

Remove Environment Variable

env::remove_var("VAR_NAME")

---

Clears the value of an environment variable for the august process, which is inherited by child processes spawned by exec.

Add to PATH

env::path_push("path\to\dir")

---

Adds a directory to the PATH environment variable for the august process, which is inherited by child processes spawned by exec.

Directory path is canonicalised before it is added.

Remove from PATH

env::path_remove("path\to\dir")

---

Remove a directory to the PATH environment variable for the august process, which is inherited by child processes spawned by exec.

Directory path is canonicalised during comparison for removal.