docs: add basic docs on Tidepool and its package sets (#18)
This is very far from perfect, but it lays some groundwork to Tidepool documentation. This follows my (very limited) understanding, and so is very much incomplete and WIP. I would like some help with the concepts I haven't quite understood <3 Reviewed-on: #18 Reviewed-by: Jake Hamilton <jake.hamilton@hey.com> Co-authored-by: KFears <kfearsoff@gmail.com> Co-committed-by: KFears <kfearsoff@gmail.com>
This commit is contained in:
parent
b67847e7eb
commit
02a45110c9
2 changed files with 268 additions and 1 deletions
|
|
@ -4,7 +4,7 @@ Aux Tidepool is an initial package set built on top of [Aux Foundation](../found
|
|||
are created and managed using [Aux Lib](../lib)'s module system to allow for highly dynamic and
|
||||
extensible configuration.
|
||||
|
||||
## Usage
|
||||
## Installation
|
||||
|
||||
Packages can be imported both with and without Nix Flakes. To import them using Nix Flakes,
|
||||
add this repository as an input.
|
||||
|
|
@ -26,3 +26,174 @@ let
|
|||
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.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.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.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}.${target}.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}.${target}.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}.${target}.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.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.x86_64-linux.package
|
||||
```
|
||||
|
||||
Or a native `aarch64-linux` Bash:
|
||||
|
||||
```console
|
||||
nix build .#packages.foundation.bash.latest.packages.aarch64-linux.aarch64-linux.aarch64-linux.package
|
||||
```
|
||||
|
||||
Running this command will:
|
||||
|
||||
- Bootstrap `i686-linux` `gcc` as a dependency of `x86_64-linux` `gcc`
|
||||
- Incrementally bootstrap the actual `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";
|
||||
};
|
||||
}
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue