Crate cage 

This is the internal cage API. If you’re looking for documentation about how to use the cage command-line tool, please see the cage website instead.

A note about semantic versioning and API stability

The cage library API is unstable, and it will remain so until further notice. We do provide “semver” guarantees, but only for the command-line interface and the on-disk project format, not for the library API itself.

If you would like to use cage as a library in another tool, please contact the maintainers. We may be able to stabilize parts of our API.

Where to start

Cage relies heavily on the compose_yml crate, which represents a docker-compose.yml file.

A good place to start reading through this API is the Project struct, which represents an entire project managed by cage. Most other interesting types can be reached from there.

You may also want to look the plugins module, which handles much of our code generation and YAML transformation. Essentially, cage works like a multi-pass “compiler”, where the intermediate representation is a compose_yml::v2::File object, and each transformation plugin is a analogous to a “pass” in a compiler.

Modules

args

Data structures representing arguments that we can pass to docker-compose and other command-line tools.

cmd

Various commands which can be performed on a project, corresponding to CLI entry points.

command_runner

Utilities for running and testing shell commands.

dir

Utilities for finding and working with project directories.

hook

Hooks that are run during cage execution.

plugins

Plugin support.

Macros

err

Create an error using a format string and arguments.

Structs

AllFiles

An iterator over all the dc::File objects associated with a pod, in all targets.

DefaultTags

This is typically used to incorporate image tags for specific builds generated by a continuous integration system (such as Go).

Error

The Error type.

Pod

A pod, specified by pods/$NAME.yml and zero or more pods/targets/*/*.yml targets that we can apply to it.

Pods

An iterator over the pods in a project.

Project

A cage project, which is represented as a directory containing a pods subdirectory.

ProjectConfig

Configuration information about a project, read in from PROJECT_CONFIG_PATH.

RuntimeState

Everything we know about the running application, based on querying Docker.

Source

A single source tree.

SourceIter

An iterator over all source trees associated with this project.

Sources

All the source trees associated with a project’s Docker images.

Target

A Target provides collection of extensions to a project’s basic pods. Targets are typically used to represent deployment environments: test, development and production.

TargetFiles

An iterator over this pods targets and their associated files.

Targets

An iterator over the targets in a project.

Enums

ErrorKind

The kind of an error.

PodOrService

Represents either a Pod object or a Service object.

PodType

Indicates whether a pod is a regular service or a one-shot task.

Traits

ResultExt

Additional methods for Result, for easy interaction with this crate.

Functions

err

Create an error using a string literal. (This exists mostly so that clippy doesn’t complain about err! expanding to format! with no arguments.)

version

The version of this crate.

Type Aliases

Result

Convenient wrapper around std::Result.