labs/tidepool

Aux Tidepool

Aux Tidepool is an initial package set built on top of Aux Foundation. Packages are created and managed using Aux Lib's module system to allow for highly dynamic and extensible configuration.

Installation

Packages can be imported both with and without Nix Flakes. To import them using Nix Flakes, add this repository as an input.

inputs.tidepool.url = "https://git.auxolotl.org/auxolotl/labs/archive/main.tar.gz?dir=tidepool";

To import this library without using Nix Flakes, you will need to use fetchTarball and import the library entrypoint.

let
    labs = builtins.fetchTarball {
        url = "https://git.auxolotl.org/auxolotl/labs/archive/main.tar.gz";
        sha256 = "<sha256>";
    };
    tidepool = import "${labs}/tidepool" {};
in
    # ...

Usage

To build a package, you can run the following command inside of the tidepool directory:

nix-build -A packages.foundation.bash.latest.packages.x86_64-linux.x86_64-linux.package

If you have nix-command experimental feature enabled, you can v3 CLI instead:

nix build -f . packages.foundation.bash.latest.packages.x86_64-linux.x86_64-linux.package

Using flakes, the difference is only in calling:

nix build .#packages.foundation.bash.latest.packages.x86_64-linux.x86_64-linux.package

This interface is verbose, but stable. We are still working out the details for a friendlier interface!

The full command syntax looks like this:

nix-build -A packages.${package-set}.${package}.${version}.packages.${build}.${host}.package

Tidepool packages can have multiple versions available. Tidepool also provides aliases for convenience, currently "stable" and "latest". Aliases go directly after ${package}:

nix-build -A packages.${package-set}.${package}.${alias}.packages.${build}.${host}.package

The actual available versions live one level deeper, under versions namespace:

nix-build -A packages.${package-set}.${package}.versions.${version}.packages.${build}.${host}.package

Here are a few practical examples for Tidepool. We can use a specific Bash version:

nix-build -A packages.foundation.bash.versions."5.2.15-stage1".packages.x86_64-linux.x86_64-linux.package

Get Bash cross-compiled from i686-linux to x86_64-linux:

nix build .#packages.foundation.bash.latest.packages.i686-linux.x86_64-linux.package

Or a native aarch64-linux Bash:

nix build .#packages.foundation.bash.latest.packages.aarch64-linux.aarch64-linux.package

Running this command will:

• Bootstrap i686-linux gcc using Foundation
• Incrementally bootstrap x86_64-linux gcc
• Incrementally bootstrap aarch64-linux gcc from x86_64-linux gcc
• Build the native aarch64-linux gcc
• Build the native aarch64-linux bash

It's very early in Tidepool's development, and this syntax and UX is expected to change! For now, the only syntax available is this developer-facing style. You can expect improvements to be made!

Development

Tidepool is built with Aux's portable submodules. They function similarly to submodules used by NixOS. Using the submodules, Tidepool provides a nice and easy-to-work-with API.

Tidepool can be used with flakes or without them. The solution we recommend for non-flake usage is npins. Tidepool exports an attribute set, which can be viewed using nix repl. We can visualize it!

tidepool
├───builders
├───lib
├───mirrors
├───packages
│   ├───aux
│   │   ├───a
│   │   ├───b
│   │   └───c
│   ├───foundation
│   │   ├───bash
│   │   ├─── ...
│   │   └───zlib
│   ├───context
│   │   └─── ...
│   └───...
├───extend
├───internal
├───new
└───preferences

There are 4 outputs that share the name with folders under src/:

• builders - this is a set of Tidepool builders
• lib - this is the Tidepool library. It defines some nice-to-haves for packaging
• mirrors - this is set of mirrors. Many projects, like GNU, provide many mirrors - you can change a mirror to the one your prefer
• packages - this is a set for all of the Tidepool packages

You may learn more about those attributes in their corresponding folders.

Additionally, there are several other attributes, which don't have corresponding folders:

• extend - this is a function to extend Tidepool's package set by providing additional package modules. Here's how to use it:

let
  tidepool = import ./tidepool;
in
  tidepool.extend {
    modules = [
      # Put additional modules you want to include here.
    ];
  }

• internal - this is the internal attribute set. Currently, it only brings Tidepool's dependencies into scope: more concretely, it exposes the foundation namespace from the (perhaps confusingly-named) Foundation repository, which does the bootstrap chain from a 357-byte file. It is not the same as Tidepool's foundation namespace, which makes those early-bootstrap packages integrate with Tidepool (e.g., enabling cross-compilation)
• new - this is a function that allows to create a new empty package set. It allows you to create a package set from scratch. Using this function, you will get access to Tidepool library functions and the interface for defining your own builders (but you don't get builder implementations). Here's how to use it:

let
  tidepool = import ./tidepool;

  module = { config }: {
    config = {
      # Create a new package set from scratch, no packages exist unless you define them.
    };
  };
in
  tidepool.new module;

• preferences - this is an attribute set that lists your preferences for the package sets. It has the following shape:

{
  packages = {
    allow = {
      broken = false;
      incompatible = false;
    };
    version = "latest";
  };
}