From f7a0a448254e7b70d99d94ccf33667c35b6fdc1b Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Fri, 20 Sep 2024 15:01:47 -0400 Subject: [PATCH 1/3] Move main lib docs into README.md So our repository landing page has more useful information. Signed-off-by: Colin Walters --- README.md | 33 +++++++++++++++++++++++++++++++-- src/lib.rs | 37 +------------------------------------ 2 files changed, 32 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 2ba1630..b8ea90e 100644 --- a/README.md +++ b/README.md @@ -5,5 +5,34 @@ [crates-badge]: https://img.shields.io/crates/v/ocidir.svg [crates-url]: https://crates.io/crates/ocidir -A low level Rust library for reading and writing -[OCI directories](https://github.com/opencontainers/image-spec/). +# Read and write to OCI image layout directories + +This library contains medium and low-level APIs for working with +[OCI images], which are basically a directory with blobs and JSON files +for metadata. + +## Dependency on cap-std + +This library makes use of [cap-std] to operate in a capability-oriented +fashion. In practice, the code in this project is well tested and would +not traverse outside its own path root. However, using capabilities +is a generally good idea when operating in the container ecosystem, +in particular when actively processing tar streams. + +## Examples + +To access an existing OCI directory: + +```rust,no_run +# use ocidir::cap_std; +# use anyhow::{anyhow, Result}; +# fn main() -> anyhow::Result<()> { +let d = cap_std::fs::Dir::open_ambient_dir("/path/to/ocidir", cap_std::ambient_authority())?; +let d = ocidir::OciDir::open(&d)?; +println!("{:?}", d.read_index()?.ok_or_else(|| anyhow!("missing Image Index"))?); +# Ok(()) +# } +``` + +[cap-std]: https://docs.rs/cap-std/ +[OCI images]: https://github.com/opencontainers/image-spec diff --git a/src/lib.rs b/src/lib.rs index e8b0756..3245ae3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,39 +1,4 @@ -//! # Read and write to OCI image layout directories -//! -//! This library contains medium and low-level APIs for working with -//! [OCI images], which are basically a directory with blobs and JSON files -//! for metadata. -//! -//! ## Dependency on cap-std -//! -//! This library makes use of [cap-std] to operate in a capability-oriented -//! fashion. In practice, the code in this project is well tested and would -//! not traverse outside its own path root. However, using capabilities -//! is a generally good idea when operating in the container ecosystem, -//! in particular when actively processing tar streams. -//! -//! ## Getting started -//! -//! To access an existing OCI directory: -//! -//! ```rust,no_run -//! # use ocidir::cap_std; -//! # use anyhow::{anyhow, Result}; -//! # fn main() -> anyhow::Result<()> { -//! let d = cap_std::fs::Dir::open_ambient_dir("/path/to/ocidir", cap_std::ambient_authority())?; -//! let d = ocidir::OciDir::open(&d)?; -//! println!("{:?}", d.read_index()?.ok_or_else(|| anyhow!("missing Image Index"))?); -//! # Ok(()) -//! # } -//! ``` -//! -//! Users of this crate are likely to want to perform low-level manipulations -//! such as synthesizing tar layers; [`OciDir::push_layer`] for example can -//! be used for this. -//! -//! [cap-std]: https://docs.rs/cap-std/ -//! [OCI images]: https://github.com/opencontainers/image-spec -//! +#![doc = include_str!("../README.md")] use cap_std::fs::{Dir, DirBuilderExt}; use cap_std_ext::cap_tempfile; From f13e9f85d7a650f1c55514041afea6edb6292345 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Fri, 20 Sep 2024 15:02:47 -0400 Subject: [PATCH 2/3] README.md: Add docs.rs shield Signed-off-by: Colin Walters --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index b8ea90e..759565c 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ [crates-badge]: https://img.shields.io/crates/v/ocidir.svg [crates-url]: https://crates.io/crates/ocidir +[![docs.rs](https://docs.rs/ocidir/badge.svg)](https://docs.rs/ocidir) # Read and write to OCI image layout directories From 6c0813923d5da331d54a5a912e487cd544406fa1 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Fri, 20 Sep 2024 15:03:08 -0400 Subject: [PATCH 3/3] Release 0.3.1 Signed-off-by: Colin Walters --- Cargo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Cargo.toml b/Cargo.toml index fc7dcd3..1cd88fa 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "ocidir" description = "A Rust library for reading and writing OCI (opencontainers) layout directories" -version = "0.3.0" +version = "0.3.1" edition = "2021" license = "MIT OR Apache-2.0" repository = "https://github.com/containers/ocidir-rs"