labs/tidepool/README.md

# Aux Tidepool

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

[foundation]: https://git.auxolotl.org/auxolotl/foundation
[lib]: https://git.auxolotl.org/auxolotl/lib

## Installation

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

```nix
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.

```nix
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:

```console
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:

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

Using flakes, the difference is only in calling:

```console
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:

```console
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}`:

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

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

```console
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:

```console
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`:

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

Or a native `aarch64-linux` Bash:

```console
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](https://github.com/andir/npins).
Tidepool exports an attribute set, which can be viewed using `nix repl`.
We can visualize it!

```console
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:

```nix
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](https://git.auxolotl.org/auxolotl/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:

```nix
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:

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