⛩️ Yae

Yae is a powerful yet minimal dependency manager intended for use with Nix, which functions similar to niv and npins.

How does Yae differ from niv and npins?

1. Yae needs no helper Nix expressions.

   niv and npins generate Nix expressions that you keep in sync with their mainline sources. A Yae environment is a single JSON file that can be placed anywhere and read with builtins.fromJSON.

2. Yae has a small, coherent source tree focused on fetching sources and updating their versions and hashes.

3. If you need a niche feature that niv or npins has, use them; if not, Yae is here for you.

Introduction

You can try out Yae without installing anything permanently on your system by running nix run github:Fuwn/yae.

Check out Tsutsumi to see an example of Yae running in a production environment. Tsutsumi fully leverages the power of Yae to manage and automagically update the sources of the Nix packages it provides using a simple GitHub Actions CRON workflow.

Usage

View the installations instructions below to set up Yae after running yae init.

Example Environment Setup

# Initialises a Yae environment in the current directory by creating an empty `yae.json`
# file
yae init

# Adds a Yae dependency named `zen-browser-twilight-bin` using a floating tag
# (tag always remain `twilight`, but may receive frequent hash changes)
yae add \
  --type binary \
  --version twilight \
  --unpack \
  zen-browser-twilight-bin \
  'https://github.com/zen-browser/desktop/releases/download/{version}/zen.linux-specific.tar.bz2'

# This command adds a Yae dependency named `zen-browser-bin` starting at tag `1.0.1-a.7`.
yae add \
  --type git \
  --version 1.0.1-a.7 \
  --unpack \
  zen-browser-bin \
  'https://github.com/zen-browser/desktop/releases/download/{version}/zen.linux-specific.tar.bz2'

# This command adds a Yae dependency named `yaak` starting at tag `2024.10.1` with tag
# trimming for updates.
yae add \
  --type git \
  --unpack=false \
  --version 2024.10.1 \
  --trim-tag-prefix v \
  yaak \
  'https://github.com/yaakapp/app/releases/download/v{version}/yaak_{version}_amd64.AppImage.tar.gz'

# Updates all dependencies, e.g., updates the hash of `zen-browser-twilight-bin`
# and bumps the version of `zen-browser-bin` to `1.0.1-a.8`, handling URL and
# hash recalculations, etc.
yae update

# Only updates `zen-browser-twilight-bin`
yae update zen-browser-twilight-bin

Use --pin when adding a source to prevent version and content updates.

git sources follow remote tags. To follow a branch, add a binary source whose URL names the branch (for example, --version main with an archive/{version}.tar.gz URL); every yae update then recomputes its hashes.

Installation

You can either install Yae through the flake that this repository exposes or through Tsutsumi.

Tsutsumi provides both flake and flake-less installation options, while this repository only provides installation support through flakes using the exported inputs.yae.packages.${system}.yae package.

Click here to see a minimal Nix flake that exposes a development shell with Yae bundled.

# Enter the development shell using `nix develop --impure` (impure is used here because `nixpkgs` internally
# assigns `builtins.currentSystem` to `nixpkgs.system` for the sake of simplicity in this example)
{
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";

  inputs.tsutsumi = {
    url = "github:Fuwn/tsutsumi";
    inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = { nixpkgs, tsutsumi, ... }:
    let
      pkgs = import nixpkgs { };
      inherit (pkgs.stdenv.hostPlatform) system;
    in
    {
      devShells.${system}.default = pkgs.mkShell {
        packages = [ tsutsumi.packages.${system}.yae ];
      };
    };
}

Integrating with Nix

To add Yae support to your Nix expression after running yae init, just read from the Yae environment file. See the example below for more details.

Examples

Check out the examples/ directory for a couple of great examples of Yae managing different sources including Nixpkgs!

Real-world Example

Tsutsumi reads its yae.json once in its flake.nix and passes each source's fields straight to the standard fetchers.

Expand this!

# flake.nix (simplified excerpt)
yae = builtins.fromJSON (builtins.readFile "${self}/yae.json");

# Every Yae source carries a URL and an SRI hash, which is exactly what
# `fetchzip` needs.
yaePackage =
  name:
  let
    archive = pkgs.fetchzip {
      inherit (yae.${name}) url hash;
    };
  in
  ((import "${archive}/flake.nix").outputs { inherit nixpkgs; self = archive; })
  .packages.${system}.default;

A scheduled GitHub Actions workflow runs yae --silent update --output-formatted-updated-list and uses the printed list, such as maple, rui, & yae, as its commit message.

Licence

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.