https://github.com/flox/runix

A type-safe Rust interface to the Nix CLI
https://github.com/flox/runix

library nix rust

Last synced: 3 days ago
JSON representation

A type-safe Rust interface to the Nix CLI

• Host: GitHub
• URL: https://github.com/flox/runix
• Owner: flox
• License: lgpl-2.1
• Created: 2023-01-26T16:43:40.000Z (almost 2 years ago)
• Default Branch: main
• Last Pushed: 2024-11-21T17:55:33.000Z (about 2 months ago)
• Last Synced: 2025-01-08T02:04:01.901Z (10 days ago)
• Topics: library, nix, rust
• Language: Rust
• Homepage:
• Size: 287 KB
• Stars: 105
• Watchers: 8
• Forks: 3
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# runix

⚠️ runix is currently not actively maintained.

A typesafe interface to the [nix](https://github.com/nixos/nix) CLI.

*by [flox](https://github.com/flox)*

------

## Installation

Install with `cargo add` (Rust >= 1.64)

```shell

cargo add runix

```

Alternatively, manually add

```toml

runix = "{{current_version}}" # check the latest version before adding

```

to your `Cargo.toml`.

## Usage

*runix* requires an existing [nix](https://github.com/nixos/nix) installation.

runix is a library that allows you to **run** **nix** using a typed

interface.

runix converts command structures into an invocation of a `NixBackend`

implementation.

The backend currently in development is the `command_line::NixCommandLine`

backend, which uses `tokio::process::Command` to `exec` the nix CLI.

While this is the reference implmentation, other backends such as an

FFI based implementation or Mocking shims for testing are possible.

> **Warning**

> runix is still in active development!

>

> It's API is not yet deeply set in stone, more fields will be added as we

> expand the coverage of the Nix CLI and traits _may_ change if necessary.

>

> We greatly appreciate feedback and contributions.

## Examples

The easiest way to get familiar with the interface is by way of an example.

Again, mind that you'll need nix on your `PATH` to use runix

and have enabled `experimental-features='nix-command flakes'`.

```rust

// (1) initialize a backend

let cli = NixCommandLine::default();

// (2) define the command

Eval {

    source: SourceArgs {

        expr: Some(r#""Hello Rust""#.into()),

    },

    ..Default::default()

}

// (3) run the command

.run(&cli, &NixArgs::default())

.await

```

This is the runix equivalent to:

```shell

$ nix eval --expr '"Hello Rust"'

```

While certainly more wordy than its shell counterpart, it's comparable to:

```rust

tokio::process::Command::new("nix")

    .args([

        "eval".to_string(),

        "--expr".into(),

        r#""Hello Rust""#.into(),

    ])

    .status()

    .await

```

The main benefit of runix however is that it abstracts away the plain list

of arguments and guides you to correct invocations of the cli.

**Interested?** Check out the [rustdoc](https://docs.rs/runix/) for more detailed explanations.

## Future Roadmap

We plan to expand the command line backend with more commands and

a comprehensive set of flags.

Depending on the state of abstractions in Nix,

we plan to approach native bindings to Nix commands and concepts.

## License

Runix is licensed under LGPL-2.1