crun-sys 0.1.0

Rust FFI bindings for libcrun (OCI container runtime, Linux only)
docs.rs failed to build crun-sys-0.1.0
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Visit the last successful build: crun-sys-0.1.1

crun-sys

Low-level Rust FFI bindings for libcrun, the OCI container runtime library.

Overview

This crate provides raw C bindings generated by bindgen. It exposes the libcrun API for creating, running, and managing OCI containers.

Platform Support

Platform Status
Linux ✅ Full support
macOS ⚠️ Stub module (compiles, no functionality)
Windows ⚠️ Stub module (compiles, no functionality)

libcrun is Linux-only — it relies on Linux-specific features:

  • cgroups (v1 and v2)
  • namespaces (user, pid, network, mount, etc.)
  • seccomp (syscall filtering)
  • capabilities

On non-Linux platforms, this crate provides a stub module that allows dependent code to compile but provides no runtime functionality.

Requirements (Linux)

  • libcrun >= 1.8
  • pkg-config (for library discovery)
  • Development headers for libcrun and dependencies

Debian/Ubuntu

apt-get install libcrun-dev libyajl-dev libseccomp-dev libcap-dev pkg-config

Fedora/RHEL

dnf install crun-devel yajl-devel libseccomp-devel libcap-devel pkgconf-pkg-config

Arch Linux

pacman -S crun libseccomp libcap

Usage

Add to your Cargo.toml:

[dependencies]
crun-sys = "0.1"

Example (Linux)

use crun_sys::*;
use std::ffi::CString;
use std::ptr;

fn main() {
    // All FFI functions are unsafe
    unsafe {
        let mut err: libcrun_error_t = ptr::null_mut();
        
        // Load container from OCI config JSON
        let config = CString::new(r#"{"ociVersion": "1.0.0", ...}"#).unwrap();
        let container = libcrun_container_load_from_memory(
            config.as_ptr(),
            &mut err,
        );
        
        if container.is_null() {
            // Handle error, then release
            crun_error_release(&mut err);
            return;
        }
        
        // ... use container ...
        
        libcrun_container_free(container);
    }
}

Safety

All functions in this crate are unsafe as they are direct C FFI bindings. The caller must ensure:

Requirement Description
Pointer validity All pointers must be valid and properly aligned
Null-termination All C strings must be null-terminated (CString)
Lifetime management Contexts and containers must be properly freed
Error handling libcrun_error_t must be released via crun_error_release()
Thread safety libcrun contexts are NOT thread-safe

Building from Source

# Clone the repository
git clone https://github.com/magikrun/magik.git
cd magik/crun-sys

# Build (Linux)
cargo build

# Build (non-Linux) - produces stub module
cargo build  # Warning: libcrun is Linux-only, building stub module

# Run tests
cargo test

Static Builds with musl

For fully portable static binaries that run on any Linux distribution:

# On Alpine Linux (native musl)
apk add rust cargo libcrun-static libseccomp-static libcap-static yajl-static
cargo build --release

# On other distros - build libcrun from source with musl
# See .github/workflows/ci.yml for the full build process

The resulting binary will have zero runtime dependencies.

Related Crates

  • crun-sys (this crate) — Raw FFI bindings
  • machineplane — High-level safe Rust wrapper with CrunEngine

License

Apache-2.0

Upstream