1.2.1 Macros

Macro: get-module-var x ¶

Get a variable from the currently loaded maak file module.

1.2.2 Procedures

Procedure: $ cmd-parts KEY: #:verbose? #:join ¶

Executes a shell command constructed from a list of strings.

($ '("echo -n" "hello-world"))

ARGUMENTS:

• cmd-parts (list): A list of strings that will be joined to form the command.
• #:verbose? (boolean, default #f): If #t, logs the generated command before executing it.
• #:join (boolean, default " "): A string to use as a separator when joining the command parts.

RETURNS: The result of the syscall function, which is #t if the command completes with an exit code of 0.

Procedure: bold-output x ¶

Undocumented procedure.

Procedure: cat file KEY: #:verbose? ¶

Undocumented procedure.

Procedure: cp x y KEY: #:recursive? #:force? #:verbose? #:verbose-copy? ¶

Copy a file or directory from X to Y.

ARGUMENTS: x: Source file or directory. y: Destination path.

recursive?: If #t, copy directories recursively (‘-r‘). Defaults to #t. force?: If #t, overwrite existing files without prompting (‘-f‘). Defaults to #f. verbose?: If #t, logs the final shell command before execution. Defaults to #f. verbose-copy?: If #t, enables verbose output from ‘cp‘ (‘-v‘). Defaults to #t.

Constructs and executes a command of the form:

cp [OPTIONS] X Y

using the ‘$‘ wrapper, ensuring errors are caught and logged.

RETURNS: #t if the copy succeeds.

ERRORS: Signals an error if the underlying ‘cp‘ command exits with a non-zero status.

Procedure: delete-file-recursively dir KEY: #:verbose? ¶

Delete a directory and all its contents recursively. Runs ‘rm -rfv DIR‘ using the ‘$‘ command wrapper. This means: The deletion is recursive.It forces removal without prompting (‘-f‘).It prints removed files (‘-v‘).

ARGUMENTS:

• dir (string): The path of the directory (or file) to delete.
• #:verbose? (boolean, default #f): If #t, logs the generated command before executing it.

RETURNS: #t if the command succeeded.

ERRORS: Signals an error if the underlying shell command exits with a non-zero status.

Procedure: list-tasks ¶

List documentation for all maak tasks defined in the currently loaded module.

Procedure: log-error msg . args ¶

Undocumented procedure.

Procedure: log-info msg . args ¶

Undocumented procedure.

Procedure: log-message msg ¶

Undocumented procedure.

Procedure: log-separator ¶

Undocumented procedure.

Procedure: maak-proc? x ¶

Predicate that indicates whether a procedure is a valid maak proc.

Procedure: maak-task? x ¶

Predicate that indicates whether it is a valid maak task.

Procedure: manifest-shell cmd-parts KEY: #:verbose? #:join #:manifest ¶

Execute a command inside a Guix shell defined by a manifest file.

ARGUMENTS:

cmd-parts: A list of strings representing the command to run inside the Guix shell environment.

#:verbose?: If #t, logs the fully constructed command before execution. Defaults to #f. #:join: The string separator used when joining command segments. Defaults to a single space. #:manifest: Path to the manifest file (in Scheme) describing the package environment. Defaults to "manifest.scm".

Constructs and executes a command of the form:

    guix shell -m MANIFEST -- <cmd ...>

using the ‘$‘ wrapper to enforce proper execution and error handling.

RETURNS: #t if the command succeeds.

ERRORS: Signals an error if the underlying shell command exits with a non-zero status.

Procedure: mkdir-p dir KEY: #:verbose? ¶

Create a directory and all necessary parent directories. Executes ‘mkdir -pv DIR‘ using the ‘$‘ wrapper. This means: Parent directories are created as needed (‘-p‘). The operation prints each created directory (‘-v‘).

ARGUMENTS:

• dir: The path of the directory to create.
• #:verbose? (boolean, default #f): If #t, logs the generated command before executing it.

RETURNS: #t if the command completed successfully.

ERRORS: Signals an error if the underlying shell command exits with a non-zero code.

Procedure: mv x y KEY: #:verbose? ¶

Move or rename a file or directory. Executes ‘mv -v X Y‘ using the ‘$‘ wrapper. The ‘-v‘ flag prints each move operation performed.

ARGUMENTS:

• x (string): The source file or directory.
• y (string): The destination path.
• #:verbose? (boolean, default #f): If #t, logs the generated command before executing it.

RETURNS: #t if the command succeeds.

ERRORS: Signals an error if the underlying shell command returns a non-zero exit code.

Procedure: program-shell cmd-parts KEY: #:verbose? #:join #:file ¶

Execute a command inside a Guix shell defined by a program file.

ARGUMENTS: cmd-parts: A list of strings representing the command to run inside the Guix shell environment.

#:verbose?: If #t, logs the full constructed command before execution. Defaults to #f. #:join: String used to join command segments. Defaults to a single space. #:file: Path to the Guix program or manifest file defining the shell environment. Defaults to "guix.scm".

Constructs and executes a command of the form:

    guix shell -f FILE -- <cmd ...>

using the ‘$‘ wrapper to safely run the command and check for errors.

RETURNS: #t if the command succeeds.

ERRORS: Signals an error if the underlying shell command exits with a non-zero status.

Procedure: remkdir-p dir KEY: #:verbose? ¶

Remove a directory if it exists, then recreate it. This results in an empty directory, regardless of its previous state. Calls ‘delete-file-recursively‘ then ‘mkdir-p‘ on DIR.

ARGUMENTS:

• dir: The path of the directory to recreate.
• #:verbose? (boolean, default #f): If #t, logs the generated command before executing it.

RETURNS: #t if the operations succeed.

ERRORS: Signals an error if any underlying shell command fails.

Procedure: resolve-maak-tasks KEY: #:module-name ¶

Undocumented procedure.

Procedure: run-task task ¶

Runs a given task if it is a valid maak task (a no-argument procedure). Logs information about the task and its documentation before execution. Args: task: A symbol representing the name of the task to be executed. Returns: The result of calling the task procedure. Errors: Signals an error if the task is not a valid thunk (no-argument function) as determined by ‘maak-task?‘.

Procedure: run-tasks tasks ¶

Runs a list of tasks sequentially.

Procedure: syscall cmd ¶

Executes a shell command and checks its exit code.

ARGUMENTS:

• cmd (string): The shell command to be executed.

RETURNS: #t if the command completes with an exit code of 0.

ERRORS: Signals an error if the command returns a non-zero exit code, providing the command and the exit code in the error message.

Procedure: time-machine cmd-parts KEY: #:verbose? #:join #:channels ¶

Execute a command using a pinned Guix revision via ‘guix time-machine‘.

ARGUMENTS: cmd-parts: A list of strings representing the command to run after the ‘guix time-machine‘ invocation.

#:verbose?: If #t, logs the final constructed command before running it. Defaults to #f. #:join: The string used to join command segments when constructing the final command. Defaults to a single space. #:channels: Path to the channels file used to pin the Guix revision. Defaults to "channels.scm".

Constructs and executes a command of the form:

    guix time-machine --channels=CHANNELS -- <cmd ...>

using the ‘$‘ wrapper to run the resulting shell command safely.

RETURNS: #t if the command succeeds.

ERRORS: Signals an error if the underlying command exits with a non-zero status.

Procedure: time-machine-manifest-shell cmd-parts KEY: #:verbose? #:join #:channels #:manifest ¶

Execute a command inside a Guix shell defined by a manifest file, using a pinned Guix revision via ‘guix time-machine‘.

ARGUMENTS: cmd-parts: A list of strings representing the command to run inside the pinned Guix shell environment.

verbose?: If #t, logs the composed command before execution. Defaults to #f. join: String used to join command segments. Defaults to a single space. channels: Path to the channels file used to pin the Guix revision. Defaults to "channels.scm". manifest: Path to the manifest file describing the package environment. Defaults to "manifest.scm".

Constructs and executes a command of the form:

    guix time-machine --channels=CHANNELS -- shell -m MANIFEST -- <cmd ...>

This provides a reproducible shell environment defined by the manifest file and pinned to the Guix revision specified in the channels file.

RETURNS: #t if the command succeeds.

ERRORS: Signals an error if any underlying shell command exits with a non-zero status.

Procedure: time-machine-program-shell cmd-parts KEY: #:verbose? #:join #:channels #:file ¶

Execute a command inside a Guix shell defined by a program file, using a pinned Guix revision via ‘guix time-machine‘.

ARGUMENTS: cmd-parts: A list of strings representing the command to run inside the pinned Guix shell environment.

#:verbose?: If #t, logs the composed command before execution. Defaults to #f. #:join: String used to join command segments. Defaults to a single space. #:channels: Path to the channels file used to pin the Guix revision. Defaults to "channels.scm". #:file: Path to the Guix program file (e.g. guix.scm) defining the environment. Defaults to "guix.scm".

Constructs and executes a command of the form:

    guix time-machine --channels=CHANNELS -- shell -f FILE -- <cmd ...>

This provides a reproducible development environment defined by the program file and pinned to the Guix revision specified in the channels file.

RETURNS: #t if the command succeeds.

ERRORS: Signals an error if any underlying shell command exits with a non-zero status.

Procedure: ~ . args ¶

A utility function to format a string (interpolation). Alias for (apply format #f ARGS).

(~ "Hello world, my name is ~a and I am ~a years old"
    "Joe"
    30)

ARGUMENTS:

• args (list): A list of arguments where the first element is the format string and the subsequent elements are the values to be substituted.

RETURNS: A newly allocated string resulting from the formatting operation.