A reusable, copyable description of an image to BUILD from a Dockerfile and a build context.
More...
|
| | GenericBuildableImage (std::string_view name, std::string_view tag="latest") |
| | Construct a buildable image with the given name and tag.
|
| GenericBuildableImage & | with_dockerfile (std::filesystem::path source_path) |
| | Add a Dockerfile from the host filesystem, placed at Dockerfile in the build context.
|
| GenericBuildableImage & | with_dockerfile_string (std::string content) |
| | Add a Dockerfile from an inline string, placed at Dockerfile in the build context.
|
| GenericBuildableImage & | with_file (std::filesystem::path source_path, std::string target) |
| | Add a host file or directory to the build context at target (a directory is added recursively, each regular file under target/<relpath>; empty directories are not shipped).
|
| GenericBuildableImage & | with_data (std::string data, std::string target) |
| | Add in-memory bytes to the build context at target. data may be binary.
|
| GenericBuildableImage & | with_build_arg (std::string key, std::string value) |
| | Add a build argument (buildargs=), e.g. with_build_arg("VERSION", "1.2").
|
| GenericBuildableImage & | with_target (std::string stage) |
| | Build only up to a named stage of a multi-stage Dockerfile (target=).
|
| GenericBuildableImage & | with_no_cache (bool no_cache=true) |
| | Disable the build cache (nocache=).
|
| GenericBuildableImage & | with_pull (bool pull=true) |
| | Always attempt to pull a newer version of the base image (pull=).
|
| GenericBuildableImage & | with_build_log_consumer (docker::BuildLogConsumer consumer) |
| | Stream the build output live: consumer is called from build() with each decoded output line (step banners and the steps' own stdout/stderr) as the daemon emits it, instead of the output staying invisible until the build ends.
|
| const std::string & | name () const noexcept |
| const std::string & | tag () const noexcept |
| std::string | descriptor () const |
| | The image reference the build produces (<name>:<tag>).
|
| const std::vector< CopyToContainer > & | build_context () const noexcept |
| const std::vector< std::pair< std::string, std::string > > & | build_args () const noexcept |
| const std::string & | target () const noexcept |
| bool | no_cache () const noexcept |
| bool | pull () const noexcept |
| const docker::BuildLogConsumer & | build_log_consumer () const noexcept |
| GenericImage | build () const |
| | Build the image (tagged <name>:<tag>) from the configured Dockerfile and build context, and return a runnable GenericImage for it.
|
A reusable, copyable description of an image to BUILD from a Dockerfile and a build context.
Construct it with a name and tag, add the Dockerfile (from a host path or an inline string) plus any context files/data, then call build() to build the image (tagged <name>:<tag>) and get back a runnable GenericImage:
.with_dockerfile_string("FROM alpine:3.20\n...")
.with_data("hi", "/hello.txt")
.build();
A RAII handle to a running container, normally obtained from GenericImage::start().
Definition Container.hpp:44
GenericBuildableImage(std::string_view name, std::string_view tag="latest")
Construct a buildable image with the given name and tag.
Definition GenericBuildableImage.hpp:44
A reusable, copyable description of a container to run: image reference, exposed ports,...
Definition GenericImage.hpp:48
Container start() const
Create, start, and wait for a container from this image, returning a RAII handle that removes the con...
GenericImage & with_wait(WaitFor w)
Definition GenericImage.hpp:184
WaitFor exit()
Wait until the container stops (with any exit code).
Definition WaitFor.hpp:109
The build context is a list of CopyToContainer entries (the same value type used for copy-to-container): each is either a host file/dir (host_file) or in-memory bytes (content), placed at a target path within the context. The Dockerfile is simply the entry targeting Dockerfile (Docker's default).
The with_* builders mutate in place and return *this by reference, so a named config can be configured incrementally — no consume-self, no use-after-move (mirrors GenericImage).
Public on purpose: the header pulls in only std + value types. The filesystem walk and tar packing happen in the .cpp so no libarchive/Boost leaks here.
| GenericBuildableImage & testcontainers::GenericBuildableImage::with_file |
( |
std::filesystem::path | source_path, |
|
|
std::string | target ) |
|
inline |
Add a host file or directory to the build context at target (a directory is added recursively, each regular file under target/<relpath>; empty directories are not shipped).
A .dockerignore at the directory's root filters the walk with docker build semantics; for a directory mapped to the context root (target empty) the .dockerignore itself always ships, and so does its Dockerfile — unless one was added via with_dockerfile* or with_data, which always takes precedence. File bytes are read only while the build uploads, so large contexts are never held in memory. The Dockerfile must be named Dockerfile unless added via with_dockerfile*.
| GenericImage testcontainers::GenericBuildableImage::build |
( |
| ) |
const |
Build the image (tagged <name>:<tag>) from the configured Dockerfile and build context, and return a runnable GenericImage for it.
Throws DockerError on failure (including a build error embedded in the daemon's streamed output, which Docker reports with an HTTP 200).
The built image is session-scoped, like every testcontainers resource: it carries the testcontainers labels, and the Ryuk reaper removes it shortly after this process exits (the base image and pulled layers are untouched). build() starts that reaper on first use, so it can also throw for a reaper-startup failure, before any build work. For an image that must outlive the test run, disable the reaper (TESTCONTAINERS_RYUK_DISABLED=1).
1.16.1