genodepkgs/README.md

```
       ______                     __           __
      / ____/__  ____  ____  ____/ /__  ____  / / ____ ______
     / / __/ _ \/ __ \/ __ \/ __  / _ \/ __ \/ / / __ `/ ___/
    / /_/ /  __/ / / / /_/ / /_/ /  __/ /_/ / , \ /_/ (__  )
    \____/\___/_/ /_/\____/\__,_/\___/ .___/_/ \_\_, /____/
                                    /_/        /____/
```

[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).

# 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

# Package manifests

Software packages are described my manifest documents, which can be used to 
build the ROM map in boot descriptions. This manifests can be automatically 
generated and made available within Nix builds and dev-shells via environmental 
variables. This may seem awkward, but consider that this is to support building 
firmware systems without a $PATH or even a file-system.

An example manifest:

```dhall
{ bin =
    { init = { mapKey = "init", mapValue = "/nix/store/.../bin/init" }
    , vfs  = { mapKey = "vfs",  mapValue = "/nix/store/.../bin/vfs" }
    }
, lib =
    { vfs =
        { mapKey = "vfs.lib.so", mapValue = "/nix/store/.../lib/vfs.lib.so" }
    }
}
```

Referenced in a boot configuration:

```dhall
let m = env:MANIFEST -- take the manifest from the shell environment

let rom = Genode.Boot.toRomPaths [ m.bin.init, m.bin.vfs, m.lib.vfs ]

in  { config = Genode.Init.default, rom = rom } : Genode.Boot.Type
```

# 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 at will. 
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:

 - Generation of documentation on internal types and functions. By generating a 
   comprehensive single document early, we should be able to refactor and prune 
   the internals faster.

 - Testing framework for simple and multi-machine tests.

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

# 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

All users regardless of distro must add the following to 
*~/.config/nix/nix.conf* to enable flakes:

```
experimental-features = nix-command flakes ca-references
```

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
  nix.binaryCaches = [ "https://cache.server7.hq.c3d2.de" ];
  nix.binaryCachePublicKeys = [
    "cache.server7.hq.c3d2.de:x8JLRG26zRZ8ysYZLEkPxuAYuK1VSJi/aMAEIs2Lv+U="
  ];
}
```

Non-NixOS users may install flakes using the following shell commands:

```sh
$ curl https://nixos.org/nix/install | sh
$ nix-env -iA nixpkgs.nixFlakes
```

Add will want to add this 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=
```


## 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-x86_64-genode.nova-pci

# View the log if the result is already cached:
$ nix log genodepkgs#checks.x86_64-linux-x86_64-genode.nova-pci
```

### As a hacker

```sh
$ git clone https://git.sr.ht/~ehmry/genodepkgs
$ cd genodepkgs
$ nix build .#checks.x86_64-linux-x86_64-genode.nova-pci

# View the log if the result is already cached:
$ nix log .#checks.x86_64-linux-x86_64-genode.nova-pci
```

# 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.

## C3D2 Hydra

A publicly available Hydra is provided by [CCC Dresden](https://c3d2.de) at 
https://server7.hq.c3d2.de/. The machine is only reachable over IPv6 and 
therefore inaccessible to SculptOS.

# 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)