auxolotl/labs
26
12
Fork 16
Code Issues 6 Pull requests 10 Projects Releases Packages Wiki Activity Actions

docs: address PR feedback

Browse source
This commit is contained in:
KFears 2025-10-04 22:53:47 +04:00
parent 6293761554
commit ca5e9b303a
Signed by: KFearsoff
SSH key fingerprint: SHA256:sn39ts1xvi/KGQNlqDyrj8nNlhp9ilndgIolXKnPraw
2 changed files with 59 additions and 30 deletions
Download patch file Download diff file Expand all files Collapse all files

71
tidepool/README.md
View file

@ -31,6 +31,12 @@ in
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
```
@ -41,27 +47,41 @@ Using flakes, the difference is only in calling:
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!
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 .#packages.<package set>.<package>.<version>.packages.<build>.<host>.<target>.package
nix-build -A packages.${package-set}.${package}.${version}.packages.${build}.${host}.${target}.package
```
It allows you to specify many things! For example, you can specify the package version:
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 .#packages.foundation.bash."5.2.15-stage1".packages.x86_64-linux.x86_64-linux.x86_64-linux.package
nix-build -A packages.${package-set}.${package}.${alias}.packages.${build}.${host}.${target}.package
```
Get a package cross-compiled from `i686-linux` to `x86_64-linux`:
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` package:
Or a native `aarch64-linux` Bash:
```console
nix build .#packages.foundation.bash.latest.packages.aarch64-linux.aarch64-linux.aarch64-linux.package
@ -89,25 +109,26 @@ Tidepool exports an attribute set, which can be viewed using `nix repl`.
We can visualize it!
```console
git+file:///home/nixchad/Documents/Projects/labs?dir=tidepool
├───builders: unknown
├───extend: unknown
├───internal: unknown
├───lib: unknown
├───mirrors: unknown
├───new: unknown
tidepool
├───builders
├───lib
├───mirrors
├───packages
│ ├───aux
│ │ ├───a omitted (use '--all-systems' to show)
│ │ ├───b omitted (use '--all-systems' to show)
│ │ └───c omitted (use '--all-systems' to show)
│ │ ├───a
│ │ ├───b
│ │ └───c
│ ├───foundation
│ │ ├───bash
│ │ ├─── ...
│ │ └───zlib
│ ├───context
│ │ └───options omitted (use '--all-systems' to show)
│ └───foundation
│ ├───bash omitted (use '--all-systems' to show)
│ ├───...
│ └───zlib omitted (use '--all-systems' to show)
└───preferences: unknown
│ │ └─── ...
│ └───...
├───extend
├───internal
├───new
└───preferences
```
There are 4 outputs that share the name with folders under `src/`:
@ -140,8 +161,10 @@ in
- `internal` - this is the internal attribute set. Currently, it only brings Tidepool's
dependencies into scope: more concretely, it exposes the `foundation` namespace from
a confusingly-named [Foundation](https://git.auxolotl.org/auxolotl/foundation) repository,
which does the bootstrap chain from a 357-byte file
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

18
tidepool/src/packages/README.md
View file

@ -4,14 +4,15 @@ In this folder, the Tidepool package sets are stored.
## Foundation
`foundation` is a minimal package set to start building everything else.
It provides a comprehensive set of packages that are used
to build all other basic Linux utilities, and are often
transitive dependencies of higher-level packages.
The package set under `foundation` is a minimal set to start building everything
else. It builds upon and uses packages from [Foundation](https://git.auxolotl.org/auxolotl/foundation),
our early bootstrap chain. It provides a comprehensive set of packages that are
used to build all other basic Linux utilities, and are often transitive dependencies
of higher-level packages.
The goal of `foundation` is to build `gcc` and `glibc`,
as well as some supplementary packages, so that other packages can be built with them.
It also sets up a basic Linux environment: `coreutils`, `diffutils`, `bash`,
as well as some supplementary packages, so that other packages can be built with
them. It also sets up a basic Linux environment: `coreutils`, `diffutils`, `bash`,
and other utilities you'd expect to find on a Linux distro.
To achieve this, we need a lot of other packages built, too! Some
@ -75,6 +76,11 @@ Package `b` provides a `context` to include the necessary directory: `include` u
the Nix store path for package `b`. This Nix store path is provided as an environment
variable from a hook.
While Tidepool's architecture is subject to change, `context` already
has planned changes for it. When those changes happen - the information
about `context` will be moved to a historical design doc. But until then,
`context` is still relevant!
`hooks` provide extension points for packages. With `hooks`, you can inject arbitrary build
instructions between, before or after the default build stages. Package `b` does exactly
that: it uses a hook to add entry after `unpack` phase and before others, which exports