OCI

OCI (Open Container Initiative) specification and builder for Zig. Build container images using the zig build system.

Quick Start

Build a container image using the zig build system:

1. Add oci as a dependency to your project.

   zig fetch --save git+https://codeberg.org/jeffective/oci.git
   

2. Import oci into your build script.

   constoci=@import("oci");

3. Create a container image.

   constimage=oci.createImage(...);

4. Add a manifest to your image.

   constmanifest=image.addManifest(...);

    An image may contain multiple target-specific manifests. Such images are "multi-platform" images and container runtimes will download the manifest that corresponds to their OS and cpu architecture.
    As part of defining the manifest, you also set a configuration that describes how to run the image, like the entrypoint.
   

5. Add a layer to your maniftest.

   constlayer=manifest.addLayer(...);

    Layers are a collection of filesystem operations: adding and deleting files.
    When container runtimes download images, they typically check which layers they already have and compare it with the registry.
    This means the way you group your files into layers can effect how quickly clients download them.
    For example, it may be advantagous to place frequently changed files in separate layers so that when those files change
    in newly published versions of your image, clients only need to download the minimum set of changed layers.
   

6. Add a file to your layer.

   layer.addFile(...);

More examples can be found in example/.

Development

zig build

References

• OpenContainers Specifications

Design

User's build graph:

1. make layers (set of filesystem operations) based on build artifacts (executables etc)
2. make manifest from layers
3. make index from manifests

API Inspiration / Prototype:

constimage=oci.createImage(b,.{});constmanifest=image.addManifest(.{.target=target,});constexe_layer=manifest.addLayer(.{.compression=.gzip_best,});exe_layer.addFile(exe.getEmittedBin(),"/bin/hello-world");constconfig_layer=manifest.addLayer(.{.compression=.gzip_best,});config_layer.addFile(b.path("etc/config.json"),"/etc/config.json");config_layer.addFile(b.path("etc/config2.json"),"/etc/config2.json");

TODO / Discussion:

• add emit docs build step
• download image to use as base image for createManifest
  • this is really hard, looks like container registeries dont provide a simple tar.gz endpoint...
• fix build steps to allow user to actually use this package, something like const dep = b.dependencyFromBuildZig(@This(), options);
• path names on windows might be wrong? see create_layer.zig, create_layout.zig etc. Need to make sure paths going into the tars are not windows paths?
• architecture variants
• reconsider current approach to file permissions