crun-sys 0.1.1

# crun-sys

Low-level Rust FFI bindings for [libcrun](https://github.com/containers/crun), the OCI container runtime library.

## Overview

This crate provides raw C bindings generated by [bindgen](https://github.com/rust-lang/rust-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

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

### Fedora/RHEL

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

### Arch Linux

```bash
pacman -S crun libseccomp libcap
```

## Usage

Add to your `Cargo.toml`:

```toml
[dependencies]
crun-sys = "0.1"
```

### Example (Linux)

```rust
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

```bash
# 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:

```bash
# 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

- libcrun: https://github.com/containers/crun
- Minimum supported version: 1.8