nixide/README.md

❄️ nixide ❄️

Because Nix never held your hand. It shot off your fingers and spat out God's longest stack trace

Never have I longed for a coup de grâce more than my attempts at using the libnix APIs. C++ isn't real and it can't hurt you... Nixide is cheaper than therapy and provides a completely redesigned approach to interacting with the Nix API. These aren't just bindings to libnix, I've gone through and redesigned error handling, simplified all provided interfaces, and written custom C++ extensions to expose internal features libnix-c could only dream of!

💛💜🖤 Usage

Below is an example of how Nixide can be used to locally build a NixOS system from a flake.nix and remotely deploy it. This is not an easy thing to do with the libnix API by default.

use nixide::*;

fn main() -> Result<(), NixideError> {
    // open the default store: `/nix/store`
    let storeref = Store::default()?;

    // initialise the Nix evaluator with default settings
    let eval_state = EvalState::default(storeref)?;

    // get a flake reference to `/etc/nixos/flake.nix`
    let flakeref = FlakeRefBuilder::new("/etc/nixos", eval_state)
        .allow_dirty(true)
        .warn_dirty(true)
        .build()?;

    // lock the flake and build the system configuration
    let out_path: StorePath = flakeref
        .lock()?
        .outputs()?
        .assert_type(NixType::Attrs)?
        .get("nixosConfigurations.MY_HOSTNAME")
        .map(|system: NixThunk| {
            system
                .force_eval()?
                .assert_type(NixType::Path)?
                .into_store_path()
        })
        .expect("Flake does not provide `MY_HOSTNAME`")?;

    // copy the local build to a remote system
    // NOTE: this assumes an ssh-agent can supply a key for us, otherwise
    // NOTE: use the syntax: `ssh://dobutterfliescry.net?ssh-key=/path/to/my/key`
    let remote_storeref = Store::open("ssh://dobutterfliescry.net")?;
    
    out_path
      .copy_closure_to(remote_storeref)?;
      .as_nixos_system()?
      .set_boot_target()?
      .activate()?;
}

Credits

Thanks so much to @NotAShelf for maintaining their nix-bindings repository. And especially Robert Hensing and the nixops4 team for their nix-bindings-rust repository. Both of which I use extensively as reference when designing Nixide.