Actions

Each task can accept a list of “Actions” that are run when the task is executed.

For example:

task(
    name="example",
    steps=[
        copy(...),
        execute(...),
        print(...),
    ]
)

execute()

execute(*executable: str | PathLike | list[str | PathLike])

Execute an executable.

Executables are run from the task’s source folder (the input root).

The first value in executable is the executable to run. This may be a relative path (to a source folder), an absolute path, the name of an executable, or the reference/output of another task. If it’s a name (without any slashes), it will be searched for in the folders defined inside the PATH environment variable.

Followed by the executable is a variable number of arguments passed to the executable.

List values in any arguments are “flattened”.

Any arguments which evaluate to None will not be included when running the executable.

To execute the output of another Task, you must specify the task name and path of the Task (for example, execute(“//path:task_name”, …)). See {ref}`Tasks as executables<tasks-as-executables>` for more information.

Note

Arguments should be quoted and separated as required by the executable. Typically, this means passing each argument and value as a separate string.

Note

Arguments are passed to the executable as is, with no shell expansion. If you use ~ to denote a home directory, you will need to expand it, or use the home() or shell() functions.

Note

When the executable is a reference to the output of another task, currently, the first declared unnamed output of the referred Task is used as the executable. The referenced Task should be included in executing task’s requirements, though it may be automatically added (implicitly, by configuration). For more on this, see Executing the Output of a Task from another Task.

copy()

copy(paths, destination=None, /)

Copy paths (files or folders) to the Task’s output folder, or the specified folder destination. paths may be a list of paths or a single path.

If destination is a relative path, it will be resolved relative to the Task’s output path; this may be used to prefix items in the output. Any directories specified in destination (by using a directory separator) will be created before copying.

If the destination is empty, the specified paths will be copied directly into the Task’s output path.

If the destination doesn’t exist, it will be created.

An Execution error will be raised if the destination exists, and it is not a folder.

The contents of folders will be copied as-is. Symbolic links shall remain unchanged.

Parameters:

  • paths (Union[PathLike,list[PathLike]]) – Paths to the file(s) or folder(s) to copy. Relative paths are resolved relative to the makex file (or source folder).

  • destination (PathLike) – The destination. May be a path relative to the task output path, or an absolute path.

Note

Makex uses file cloning/copy-on-write/reflinks for lightweight copies of files on supporting filesystems (bcachefs, btrfs, XFS, OCFS2, ZFS (unstable), APFS and ReFSv2).

The copy function has 7 valid forms:

# copy a file to the Task output
copy(file)

# copy a folder to the Task output
copy(folder)

# copy folder to the specified Folder (relative to the task output)
copy(folder, folder)

# list forms:

# copy a list of files to the Task output
copy(files)

# copies a set of files to the specified folder (relative to the task output).
copy(files, folder)

# copy a list of folders to the Task output
copy(folders) 

# copies a set of folders to the specified folder (relative to the task output).
copy(folders, folder)

print()

print(message)

Print a message to standard output.

Parameters:

message (String) – The message to print.

shell()

shell(*script)

Run script in a system shell.

Warning

You should seriously avoid use of this function. Shells may introduce unexpected behavior in Makex.

For example, the line shell(f”rm {SOME_VARIABLE}/bin”)) will attempt to remove your /bin directory if SOME_VARIABLE is defined as an empty string.

shell() is there if you really need it, and additional mechanisms will be employed in the future to increase safety. Keep your scripts simple.

Makex may a adopt a “strict” mode where all shell scripting is disabled.

By default, Makex will use the detected/system shell (usually, sh, or the Bourne Shell bash). A shell can be specified in configuration, but it’s recommened to leave it to autodetect based on platform.

The passed script is prefixed with a preamble by default:

set -Eeuo pipefail
Parameters:

script (Union[String,list[String]]) – The script/command line to run. If a list of strings, the strings will concatenated with new line separators and run in one process/shell.

Note

The syntax of the script depends on the system’s shell. Variables are expanded according the specified shell’s rules.

write()

write(file: PathLike, data: str | list[str], executable: bool = False)

Writes data to file.

Any intermediate folders specified in the file path will be created as necessary.

Parameters:

  • file (PathLike) – The destination file. May be a Workspace path, an absolute path (if allowed), or relative path within the Task’s output path.

  • data (Union[str,list[str]]) – The data to write, may be a list of strings which will be concatenated.

  • executable (bool) – Ensure the file is executable.