ocipkg/
lib.rs

1//! ocipkg consists of executables (`ocipkg` and `cargo-ocipkg`) and this crate for handling OCI Artifact without container runtime.
2//!
3//! See [README.md at GitHub](https://github.com/termoshtt/ocipkg) for usage of the executables.
4//! This reference describes the crate part.
5//!
6//! Layout, Manifest, and Artifact
7//! -------------------------------
8//! ocipkg defines original type of OCI Artifact, `application/vnd.ocipkg.v1.artifact` to exchange directories containing static libraries.
9//! But this crate is also a general purpose library to handle any kind of OCI Artifact which can contain any kind of data.
10//!
11//! Note that current implementation (from ocipkg 0.3.0) is based on [OCI Image specification] 1.1.0.
12//!
13//! ### Image Manifest
14//! Every contents in a container are stored as blob, and identified by its hash digest (usually SHA256 is used).
15//! [OCI Image Manifest] describes how these blobs are combined to form a container.
16//! From [OCI Image specification] 1.1.0, [OCI Image Manifest] can store OCI Artifact in addition to usual executable containers.
17//!
18//! In this crate, [oci_spec::image::ImageManifest] is used to represent [OCI Image Manifest].
19//!
20//! ### Image Layout
21//! [OCI Image Layout] specifies how blobs are stored as a directory.
22//! Blobs are stored in `blobs/sha256/` directory with its hash digest as a file name.
23//! [OCI Image Manifest] is a JSON string and also stored as a blob, thus we have to find the blob storing the manifest first.
24//! `index.json` lists the digests of manifests stored in the layout.
25//! There is also a file `oci-layout` which contains version of the layout itself.
26//!
27//! Two types of layout formats are supported. `oci-dir` format is a directory containing blobs as [OCI Image Layout] format:
28//!
29//! ```text
30//! {dirname}/
31//! ├── blobs/
32//! │   └── sha256/
33//! │       ├── 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
34//! │       └── ...
35//! ├── index.json
36//! └── oci-layout
37//! ```
38//!
39//! `oci-archive` format is a tar archive of a `oci-dir` format. Creating a new image layout takes following steps:
40//!
41//! 1. Create an empty layout
42//! 2. Add blobs, and store their digests
43//! 3. Create a manifest using blob digests, store the manifest itself as blob, and store its digest in `index.json`
44//!
45//! This process is abstracted by [image::ImageBuilder]. This yields a layout which implements [image::Image] trait.
46//!
47//! [OCI Image specification]: https://github.com/opencontainers/image-spec/blob/v1.1.0/spec.md
48//! [OCI Image Manifest]: https://github.com/opencontainers/image-spec/blob/v1.1.0/manifest.md
49//! [OCI Image Layout]: https://github.com/opencontainers/image-spec/blob/v1.1.0/image-layout.md
50
51/// Re-export since this crate exposes types in `oci_spec` crate.
52pub extern crate oci_spec;
53
54pub mod distribution;
55pub mod image;
56pub mod local;
57pub mod media_types;
58
59mod digest;
60mod image_name;
61
62pub use digest::Digest;
63pub use image_name::ImageName;
64
65use anyhow::{Context, Result};
66use std::fs;
67
68const STATIC_PREFIX: &str = if cfg!(target_os = "windows") {
69    ""
70} else {
71    "lib"
72};
73
74const STATIC_EXTENSION: &str = if cfg!(target_os = "windows") {
75    "lib"
76} else {
77    "a"
78};
79
80/// Get and link package in `build.rs` with [cargo link instructions](https://doc.rust-lang.org/cargo/reference/build-scripts.html#outputs-of-the-build-script).
81///
82/// This is aimed to use in [build script](https://doc.rust-lang.org/cargo/reference/build-scripts.html) a.k.a. `build.rs`.
83pub fn link_package(image_name: &str) -> Result<()> {
84    let image_name = ImageName::parse(image_name)?;
85    let dir = local::image_dir(&image_name)?;
86    if !dir.exists() {
87        distribution::get_image(&image_name, false)?;
88    }
89    println!("cargo:rustc-link-search={}", dir.display());
90    for path in fs::read_dir(&dir)?.filter_map(|entry| {
91        let path = entry.ok()?.path();
92        path.is_file().then_some(path)
93    }) {
94        let name = path
95            .file_stem()
96            .unwrap()
97            .to_str()
98            .context("Non UTF-8 path is not supported")?;
99        let name = if let Some(name) = name.strip_prefix(STATIC_PREFIX) {
100            name
101        } else {
102            continue;
103        };
104        if let Some(ext) = path.extension() {
105            if ext == STATIC_EXTENSION {
106                println!("cargo:rustc-link-lib=static={}", name);
107            }
108        }
109    }
110    println!("cargo:rerun-if-changed={}", dir.display());
111    println!("cargo:rerun-if-env-changed=XDG_DATA_HOME");
112    Ok(())
113}
ocipkg/lib.rs

ocipkg/
lib.rs
