Built-in Functions

task()

This function defines a Task which will become part of the execution graph.

The task function is as follows:

task(name, requires=None, inputs=None, steps=None, outputs=None, environment=None)

Parameters:

• name (String) – Name of the task.

• requires (list[PathLike]) – A list of requirements (Task names or Locators). A string with a : will be parsed as a Task Locator. Any values which evaluate to None will be skipped.

• steps (list[Action | list[Action]]) – A list of Actions. These are actions, executables, or scripts run in sequence as part of the task.

• inputs (PathLike | list[PathLike] | dict[String, PathLike]) – A file, list of files or mapping of existing files required by this task.

• outputs (Union[PathLike, list[PathLike], dict[String, PathLike]]) – A file or list of the files this task produces. If a task produces any files that are to be consumed by any dependents of the task, they should be defined here. Defining outputs makes the Task a candidate for caching.

• environment (Mapping[str, Union[String, PathLike,Number]]) – Environment variables to set for the Task and any executables it runs. Values must be simple or immediate, and serializable to strings.

Example of creating a task named world which depends on hello:

task(
    name="world",
    requires=[
        "hello"
    ],
    steps=[
        print("World!")
    ],
)

task(
    name="hello",
    steps=[
        print("Hello")
    ],
)

Running the world task will run the hello task first (using makex run world). The printed output will be:

Hello
World!

Paths

Makex standardizes on paths with / as a separator.

Paths in Makex files may not contain the .. (double dot) marker.

Note

Any specifics or problems in the Python pathlib module will show up in Makex.

path()

To refer to arbitrary paths use the path() function to produce a Path object.

Paths may be relative to the Makex file, absolute to the Workspace (starting with two slashes //), or absolute (starting with a single slash /)

Paths in Makex files may be joined with a separator using the / operator, as a form of shorthand.

An example of using this function an operator is below:

# functional:
BASH_PATH = path("/usr/bin").join("bash")

# or, using operator:
BASH_PATH = path("/usr/bin") / "bash"

path(*path: PathLike) → Path

Return a Path object.

Parameters:

path – One or more path components.

class Path

A path object. Similar to pathlib.Path. Paths can be concatenated with separators by using the / operator.

name: String

The name of the path; typically a file name. This is the last component/part of any given path. The name of the root (/) is an empty string.

join(*parts: String)

Joins the path with one or more String components specified with the parts argument.

Return type:

Path

task_path()

The task_path() function will return the output Path for the specified task. See the Tasks and the Cache documentation for more about Task output paths.

task_path(name: String, path: PathLike = None) → Path

Returns an output path for a task with name. If the path argument is specified, returns the output path corresponding to the task with the matching name inside of a Makex file at path.

The output path of a task is typically MakexFile.folder / “_output_” / Task.identity.

Parameters:

• name – Name of a task.

• path – Optional. A folder containing a Makex file. Workspace relative paths are accepted here.

Note

If DIRECT_REFERENCES_TO_MAKEX_FILES is enabled, the path argument may be a path to a Makex file.

home()

home(*path:PathLike=None) → Path

Return a Path that evaluates to the current user’s home folder.

Parameters:

path – Optional. A subpath in the home folder.

source()

source(*path:PathLike=None) → Path

Return a Path that evaluates to the current source folder (the folder containing the makex file).

This may be used to write back files to the source folder (for example, via the copy or write actions).

Parameters:

path – Optional. A subpath in the in the source folder.

find()

find(path: PathLike, include: Pattern | Glob = None) → list[Path]

Finds files (recursively). If path is relative, it will be resolved relative to the folder of the makex file (the source folder).

This function is typically intended to arbitrarily find source files to operate on.

Note: this function is intended to be used as part of Task or its actions; find will not return/resolve otherwise.

Parameters:

• path – A path to search for files in.

• include (Union[Pattern,Glob]) – Files to include. If specified, only files matching the include will be returned.

glob()

glob(pattern: String = None) → Glob

Prepares/compiles a glob pattern.

Note: this function is intended to be used as part of Task or its actions; glob will not return/resolve otherwise.

When used alone within a task (e.g. as part of a Tasks inputs/dependencies), globs will match files within the source folder of the task (or, the same folder in which the makex file exists).

Parameters:

pattern – Patterns of files to include.

Globs support the following syntax:

• / to separate path segments.

• * to match zero or more characters in a path segment.

• ? to match on one character in a path segment.

• ** to match zero or more folders. (e.g. **.py will match python files in any directory)

• [] to declare a range of characters to match.

• {} to declare a set of patterns to match.

• [!...] to negate a range of characters to match.

Tip

Match a file with extension: *.c

Match a file with extension recursively: **.c

Match files with multiple extensions: *.{py,md,txt}