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	An 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 Definitions

Result

Convenient wrapper around std::Result.