Next: (maak dsl), Previous: (maak archive), Up: API
Container helpers for the two engines a Linux machine is likely to have. Podman and Docker share almost all of their command line, so a task written against one should not have to be rewritten for the other: the engine is a parameter, detected once from PATH and overridable per call or with MAAK_CONTAINER_ENGINE.
The same is true of Compose, with one extra wrinkle: Podman has both ‘podman compose‘ and the older ‘podman-compose‘, so the compose program is a parameter of its own. MAAK_COMPOSE names it, and a call can pass ‘#:program‘.
Every helper has an ‘-argv‘ builder next to it. The builder returns the list of words without running anything: that is what the procedures feed to ‘run‘, what –dry-run prints, and what a test can assert without needing a container runtime.
Nothing here starts a container as a side effect of loading the module.
Default value:
("podman-compose")
Default value:
"podman"
Return the argv that runs Compose with ARGUMENTS.
FILE is –file, PROJECT is –project-name, ENV-FILES are passed as –env-file, and PROFILES as –profile. They come before the subcommand, which is where both Docker Compose and podman-compose expect them.
Return #t when the Compose PROGRAM can be found on PATH.
PROGRAM is the list of words container-compose-command returns; its first word is what is looked for.
Build SERVICES with Compose; see ‘compose-build-argv‘.
Return the argv that builds SERVICES, or every service when it is empty.
Render the Compose configuration; see ‘compose-config-argv‘.
Return the argv that renders the resolved Compose configuration.
QUIET? asks Compose to validate without printing; SERVICES? asks for only the service definitions, and the service names are passed as arguments when given. The quiet flag is spelled -q because that is the form both Compose implementations accept.
Stop and remove SERVICES with Compose; see ‘compose-down-argv‘.
Return the argv that stops and removes SERVICES, or the whole project.
VOLUMES? also removes named volumes, which is what makes a test environment return to a clean state; it is off by default because the data is otherwise kept between runs.
Run COMMAND in SERVICE with Compose; see ‘compose-exec-argv‘.
Return the argv that runs COMMAND in SERVICE.
NO-TTY? (the default) passes -T, which both Docker Compose and podman-compose spell the same way. A task needs it: without it Compose tries to allocate a terminal, and a command run from a pipeline or a CI job does not have one. TTY? asks for a terminal instead, and wins over the default: the two flags contradict each other, so only one is ever emitted. Pass #:no-tty? #f for an interactive shell that should not be told what to do either way.
Print the logs of SERVICES with Compose; see ‘compose-logs-argv‘.
Return the argv that prints the logs of SERVICES, or of the whole project.
Run Compose with ARGUMENTS and return its output as a string.
List the containers of SERVICES with Compose; see ‘compose-ps-argv‘.
Return the argv that lists the containers of SERVICES, or of the project.
ALL? is Docker Compose’s –all; podman-compose has no equivalent flag and lists the project’s containers already, so leave it off with that program.
Pull the images of SERVICES with Compose; see ‘compose-pull-argv‘.
Return the argv that pulls the images of SERVICES.
IGNORE-PULL-FAILURES? is Docker Compose’s flag; podman-compose does not accept it, so leave it off with that program.
Restart SERVICES with Compose; see ‘compose-restart-argv‘.
Return the argv that restarts SERVICES.
Run COMMAND in a one-off container for SERVICE; see ‘compose-run-argv‘.
Return the argv that runs COMMAND in a one-off container for SERVICE.
REMOVE? (the default) passes –rm; NO-DEPS? keeps Compose from starting the service’s dependencies.
Start SERVICES with Compose; see ‘compose-up-argv‘.
Return the argv that starts SERVICES, or every service when it is empty.
DETACH? (the default) is –detach, because a task that starts a stack wants its shell back. BUILD? rebuilds images, FORCE-RECREATE? replaces the containers, REMOVE-ORPHANS? is on by default, and WAIT? waits for the services to be healthy before returning.
Run ENGINE with ARGUMENTS, a list of strings.
The escape hatch for subcommands without a wrapper, such as ‘volume ls‘. Nothing is handed to a shell, so a label or a path with a space in it stays one argument.
Return the argv that runs ENGINE with ARGUMENTS.
This is the shared shape of every helper below: the engine first, then the subcommand and its flags. It is exported because a subcommand without a wrapper is still a subcommand – pass ‘(list "volume" "ls")‘ and it works.
Return #t when ENGINE can be found on PATH.
Build the image described by CONTEXT; see ‘container-build-argv‘.
Return the argv that builds the image described by CONTEXT.
TAG is –tag, FILE is –file, TARGET is –target, and BUILD-ARGS and LABELS are lists of strings. CONTEXT is the directory sent to the engine, normally the last argument.
Run COMMAND in the container NAME; see ‘container-exec-argv‘.
Return the argv that runs COMMAND in the container NAME.
COMMAND is a list of strings. INTERACTIVE? and TTY? are the usual -i and -t; a non-interactive command needs neither, which is what a build step wants.
List images; see ‘container-images-argv‘.
Return the argv that lists images, with any extra ARGUMENTS.
Inspect NAMES; see ‘container-inspect-argv‘.
Return the argv that inspects NAMES.
FORMAT is passed as –format, which is how a task reads a field rather than the whole JSON document. TYPE is –type for engines that accept it.
Print the logs of the container NAME; see ‘container-logs-argv‘.
Return the argv that prints the logs of the container NAME.
FOLLOW? is –follow; TAIL is a number or the word all, passed as –tail; SINCE is passed as –since.
Run ENGINE with ARGUMENTS and return its output as a string.
This is the reading counterpart of ‘container‘: the output is a value a task can trim and compare rather than a line on the terminal. In dry-run mode nothing runs, the command is printed, and the empty string comes back.
List containers; see ‘container-ps-argv‘.
Return the argv that lists containers, including stopped ones with ALL?.
Pull IMAGE; see ‘container-pull-argv‘.
Return the argv that pulls IMAGE.
Push IMAGE; see ‘container-push-argv‘.
Return the argv that pushes IMAGE.
Remove the containers NAMES; see ‘container-rm-argv‘.
Return the argv that removes the containers NAMES.
FORCE? is the default because a task that removes a container means it, and a running container would otherwise fail the whole task.
Run IMAGE as a container; see ‘container-run-argv‘ for the options.
Return the argv that runs IMAGE as a container.
COMMAND is the list of arguments passed to the image, after its name. The defaults are the ones an unattended task wants: REMOVE? is #t, so a finished container leaves nothing behind, and nothing is attached to the terminal unless INTERACTIVE? or TTY? asks for it. ENV, PUBLISH, VOLUME, MOUNT and LABELS are lists of strings, each passed with its flag.
Stop the containers NAMES, a list of strings.
Return the argv that stops the containers NAMES.
Tag SOURCE as TARGET; see ‘container-tag-argv‘.
Return the argv that gives SOURCE the additional name TARGET.
Return the words that run Compose, as a list.
PREFERRED, when non-empty, is split on whitespace and used as it stands. For Podman, the standalone ‘podman-compose‘ is preferred when it is installed, and ‘podman compose‘ is used otherwise; Docker always answers ‘docker compose‘. The engine is passed in rather than read from the parameter, so the result is a pure function of its arguments.
Return the container engine maak should use.
PREFERRED, when non-empty, wins unchanged. Otherwise Podman is chosen when it is on PATH, then Docker. The fallback is Podman even when neither is installed, so a missing engine is reported as a missing program rather than silently replaced by another one.
PATH is the search path, PATH itself by default, so the choice can be tested without changing the process environment.
(detect-container-engine #:path search-path) (detect-container-engine #:preferred engine-name)
Run Compose with ARGUMENTS, a list of strings.
The escape hatch for subcommands without a wrapper, such as ‘top‘. FILE, PROJECT, ENV-FILES and PROFILES are passed before the subcommand, the way both Compose implementations expect.
Next: (maak dsl), Previous: (maak archive), Up: API