305 lines
9.4 KiB
Markdown
305 lines
9.4 KiB
Markdown
```
|
|
` ______ __ __
|
|
/ ____/__ ____ ____ ____/ /__ ____ / / ____ ______
|
|
/ / __/ _ \/ __ \/ __ \/ __ / _ \/ __ \/ / / __ `/ ___/
|
|
/ /_/ / __/ / / / /_/ / /_/ / __/ /_/ / , \ /_/ (__ )
|
|
\____/\___/_/ /_/\____/\__,_/\___/ .___/_/ \_\_, /____/
|
|
/_/ /____/
|
|
```
|
|
|
|
[Genodepkgs](https://git.sr.ht/~ehmry/genodepkgs) is nexus of
|
|
[Nix](https://nixos.org/nix/) expressions related to the
|
|
[Genode OS framework](https://genode.org).
|
|
|
|
**IRC:** irc://oftc.net/#genodepkgs
|
|
|
|
**Mailing List:** https://lists.sr.ht/~ehmry/genodepkgs
|
|
|
|
**Hydra:** https://hydra7.hq.c3d2.de/project/genodepkgs
|
|
|
|
**SoTest:** https://opensource.sotest.io/userName%3Demery/1
|
|
|
|
# Contributing
|
|
|
|
At the moment every user needs to also act as distro developer, designing how
|
|
packaging works needs to be done before packages can be submitted in bulk.
|
|
Patches can be submitted and issues reported via the
|
|
[mailing list](https://lists.sr.ht/~ehmry/genodepkgs). The mailing list is the
|
|
minimum viable mechanism for community development, and may be replaced later.
|
|
|
|
The worksites at the moment are:
|
|
|
|
- Documentation
|
|
|
|
- Port tests to the NixOS test harness.
|
|
|
|
- Patching standard Nixpkgs packages via an overlay. Workflow and tooling
|
|
needs to be explored for building emulated UNIX environments.
|
|
|
|
- LLVM testing and upstreaming patches.
|
|
|
|
- Formalizing Dhall configuration types.
|
|
|
|
- Configuration validation via a service routing prover.
|
|
|
|
|
|
# Packaging
|
|
|
|
Packaging is done using standard Nixpkgs methods, a `stdenv` is available for
|
|
cross-compilation. See [Solo5](./packages/solo5/default.nix) as an example.
|
|
|
|
|
|
# System description format
|
|
|
|
The high-level interface to system building are boot descriptions. These Dhall
|
|
documents describe the configuration of an [Init](https://genode.org/documentation/genode-foundations/19.05/system_configuration/The_init_component.html)
|
|
instance and a store of ROM (Read-Only Memory) modules. These description can be
|
|
used to build firmware-like binary images or merged and nested within other
|
|
descriptions. In theory these descriptions can arrange file-systems, but those
|
|
functions are missing.
|
|
|
|
The description schema is documented as code:
|
|
https://git.sr.ht/~ehmry/dhall-genode/tree/master/Boot/package.dhall
|
|
|
|
|
|
# Nix Flakes
|
|
|
|
This repository is structured as a Nix flake, which is an experimental extension
|
|
of Nix tooling. The flakes capable Nix frontend is available from Nixpkgs as
|
|
`nixFlakes`.
|
|
|
|
## Switching to flakes
|
|
|
|
Non-NixOS users may install Nix using the following shell commands:
|
|
|
|
```sh
|
|
$ curl https://nixos.org/nix/install | sh
|
|
$ nix-env -iA nixpkgs.nixFlakes
|
|
```
|
|
|
|
Those with IPv6 will want to the following to their */etc/nix/nix.conf* file:
|
|
|
|
```
|
|
substituters = https://cache.nixos.org/ https://cache.server7.hq.c3d2.de/
|
|
trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= cache.server7.hq.c3d2.de:x8JLRG26zRZ8ysYZLEkPxuAYuK1VSJi/aMAEIs2Lv+U=
|
|
```
|
|
|
|
|
|
NixOS users may switch to flakes using the following configuration:
|
|
|
|
```nix
|
|
{ pkgs, ... }:
|
|
{
|
|
nix.package = pkgs.nixFlakes;
|
|
|
|
# The following enables the use of a binary cache (IPv6 only)
|
|
nix.binaryCaches = [ "https://cache.server7.hq.c3d2.de" ];
|
|
nix.binaryCachePublicKeys = [
|
|
"cache.server7.hq.c3d2.de:x8JLRG26zRZ8ysYZLEkPxuAYuK1VSJi/aMAEIs2Lv+U="
|
|
];
|
|
}
|
|
```
|
|
|
|
All users regardless of distro must add the following to
|
|
*~/.config/nix/nix.conf* to enable flakes:
|
|
|
|
```
|
|
experimental-features = nix-command flakes ca-references
|
|
```
|
|
|
|
## Building from flakes
|
|
|
|
### As a user
|
|
|
|
```sh
|
|
$ nix flake add genodepkgs git+https://git.sr.ht/~ehmry/genodepkgs
|
|
$ nix build genodepkgs#checks.x86_64-linux.nova-x86
|
|
|
|
# View the log if the result is already cached:
|
|
$ nix log genodepkgs#checks.x86_64-linux.nova-x86
|
|
```
|
|
|
|
### As a hacker
|
|
|
|
```sh
|
|
$ git clone https://git.sr.ht/~ehmry/genodepkgs
|
|
$ cd genodepkgs
|
|
$ nix build .#checks.x86_64-linux.nova-x86
|
|
|
|
# View the log if the result is already cached:
|
|
$ nix log .#checks.x86_64-linux.nova-x86
|
|
```
|
|
|
|
# Toolchain
|
|
|
|
The Genode Labs toolchain is available here only for Linux and in binary form.
|
|
However, an experimental LLVM cross-compiler is provided here. Bootstrapping GCC
|
|
has not been practical due to its recursive autotools build system.
|
|
|
|
# Building
|
|
|
|
Bootstrapping the build tooling can take several hours on a laptop, therefore it
|
|
is recommended enable the binary caches and to farm massive rebuilds to large
|
|
multicore machines. The Nix flake is prepared for continuous builds with a
|
|
[Hydra](https://nixos.org/hydra/), but only the experimental flakes capable
|
|
Hydra.
|
|
|
|
# Testing
|
|
|
|
Tests are performed using QEMU and a test driver similar to what is used by
|
|
NixOS (ours has not been ported to Python however). The test artifacts are built
|
|
as follows:
|
|
|
|
```shell
|
|
# Build a test log from a QEMU test run:
|
|
nix build .#checks.x86_64-linux.nova-x86
|
|
|
|
# Build an ISO of the test run:
|
|
nix build .#checks.x86_64-linux.nova-x86.iso
|
|
|
|
# Build the Dhall boot description of the test run:
|
|
nix build .#checks.x86_64-linux.nova-x86.config
|
|
```
|
|
|
|
# Tips and tricks
|
|
|
|
## How to build a Genode make target?
|
|
|
|
```nix
|
|
let flake = getFlake "genodepkgs";
|
|
in flake.packages.x86_64-linux-x86_64-genode.genodeSources.make "app/ping"
|
|
```
|
|
|
|
## How to build a Genode depot package?
|
|
|
|
```nix
|
|
let flake = getFlake "genodepkgs";
|
|
in flake.packages.x86_64-linux-x86_64-genode.genodeSources.depot "wifi_drv"
|
|
```
|
|
|
|
## How to add missing ports to a depot package?
|
|
|
|
The missing ports as indicated by a depot build failure must be added to
|
|
[targets.nix](./overlay/genode/targets.nix). To continue from the previous
|
|
example, this would be sufficient:
|
|
|
|
```nix
|
|
{
|
|
wifi_drv = { portInputs = [ dde_linux libc openssl ]; };
|
|
}
|
|
```
|
|
|
|
## How to add undefined ports?
|
|
|
|
Should a required port not be defined, it must be added to
|
|
[ports.nix](./overlay/genode/ports.nix). Initially it should be sufficient to
|
|
define the port as an empty attribute set, run the build again, and then add the
|
|
hash found in the successive build error.
|
|
|
|
To continue from the previous example:
|
|
|
|
```nix
|
|
{
|
|
dde_linux = { };
|
|
}
|
|
```
|
|
|
|
And after the reattempting the build a fixed-output hash should be produced,
|
|
this must now be added to the port definitions.
|
|
|
|
```nix
|
|
{
|
|
dde_linux = {
|
|
hash = "sha256-3G5Mprv9ZBNhDJRuVF6Nrkp3KbFaN10IKFq0OdyAY9M="; };
|
|
}
|
|
```
|
|
|
|
Should the port preparation fail do to missing utilities, these must be added to
|
|
the port definition using a `nativeBuildInputs` attribute.
|
|
|
|
Note that the hash checked into `ports.nix` is an *output hash*. The port hash
|
|
within the Genode source tree is an *explicit input hash* and the output of
|
|
the port preparation is non-deterministic.
|
|
|
|
|
|
## Render a Dhall Init configuration to XML
|
|
|
|
```shell
|
|
echo ./config.dhall | nix app genodepkgs#render-init > config.xml
|
|
```
|
|
|
|
## Build a Genode Labs Make target
|
|
|
|
```shell
|
|
nix app genodepkgs#genode-make "test/bomb"
|
|
```
|
|
|
|
## Enter an environment compatible with the Genode Labs build scripts
|
|
|
|
```shell
|
|
nix dev-shell genodepkgs
|
|
cd $GENODE_DIR
|
|
make -C build/x86_64 run/bomb
|
|
```
|
|
|
|
# Glossary
|
|
|
|
Some of terms that follow are necessary for understanding packaging methodology,
|
|
Others are simply introduced as an aid to the reader:
|
|
|
|
- *Upstream* - repositories packaged by expressions in this repository
|
|
|
|
- *Downstream* - repositories depending on this repository
|
|
|
|
- *OS ABI* - The binary interface to an operating system. In the case of Genode
|
|
this does not include kernel interfaces, as system calls are abstracted via
|
|
dynamically linked procedures.
|
|
|
|
- `localSystem` - the CPU and OS ABI pair used to evaluate and compile
|
|
packages. Genode cannot natively instantiate Nix derivations, therefore it
|
|
cannot be a `localSystem` ABI.
|
|
|
|
- `crossSystem` - the target CPU and OS ABI pair for packages. In the common
|
|
case the ABI will be Genode. In the case of tooling it may be the same as
|
|
`localSystem`. For software that runs bare-metal the CPU is significant but
|
|
ABI is irrelevant.
|
|
|
|
- `buildPlatform` - equivalent to `localSystem`.
|
|
|
|
- `hostPlatform` - the platform on which a package will execute.
|
|
|
|
- `targetPlatform` - the platform for which a package will produce artifacts.
|
|
This is only significant for software such as compilers. The respective
|
|
build, host, and target platform of a compiler that was built on a Solaris,
|
|
executes on Genode, and produces only Haiku binaries would be Solaris,
|
|
Genode, and Haiku.
|
|
|
|
- *Flake* - a code repository containing a `flake.nix` file describing
|
|
dependency repositories. The evaluation of flakes may only form ascyclic
|
|
graphs. Repositories packaged here may themselves contain a `flake.nix`
|
|
file that refers to this repository, but these repositories cannot be inputs
|
|
to the Genodepkgs flake.
|
|
|
|
- *Genode core* - Genode component of highest privilege. The core is located
|
|
conceptually at the bottom and root of the component tree. Core might be
|
|
directly above the kernel, or acting as the kernel. The role of core is a
|
|
subset of the role of the kernel in a monolithic system.
|
|
|
|
- *Lower* - lowering a subsystem is moving it closer to the Genode core
|
|
and increasing privilege.
|
|
|
|
- *Raise* - raising a subsystem is moving it further away from the Genode core
|
|
and decreasing privilege.
|
|
|
|
- *Package* - *undefined*
|
|
|
|
# Legal
|
|
|
|
This repository is for trivial packaging algebra and metadata that exists only
|
|
for the sake of richer and more meaningful code in external repositories. All
|
|
works committed to this repository, unless otherwise noted, shall be implicitly
|
|
licensed under a [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/deed)
|
|
public domain dedication.
|
|
|
|
![CC0 PUBLIC DOMAIN](.CC0-1.0.png)
|