Write a decent README

This commit is contained in:
Emery Hemingway 2020-01-24 14:45:31 +01:00
parent c5da3100c4
commit fefed4c5e8
1 changed files with 169 additions and 20 deletions

View File

@ -1,26 +1,175 @@
# Genode Packages
______ __ __
/ ____/__ ____ ____ ____/ /__ ____ / / ____ ______
/ / __/ _ \/ __ \/ __ \/ __ / _ \/ __ \/ / / __ `/ ___/
/ /_/ / __/ / / / /_/ / /_/ / __/ /_/ / , \ /_/ (__ )
\____/\___/_/ /_/\____/\__,_/\___/ .___/_/ \_\_, /____/
/_/ /____/
This repo contains Nix expressions for building Genode with Nixpkgs and building
Nixpkgs for Genode. At the moment the former is experimental and broken in many
cases, the later is probably broken for all cases.
[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).
Furthermore, this repository is structured as a Nix flake, with is in itself an
experimental extension of the Nix utility. The flakes capable `nix` frontend is
available from Nixpkgs as `nixFlakes`. It is possible to bootstrap to flakes by
installing Nix on a standard Linux distro, followed by `nix-env -i nixFlakes`.
Flakes are available from NixOS using the following expression:
`{ pkgs, ... }: { nix.package = pkgs.nixFlakes; }`
# Contributing
## Toolchain
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 LLVM cross-compiler may useful already, Clang apparently builds trivial
Genode componenents without serious problems. Bootstrapping GCC is not practical
due to the recursive autotools build system.
The worksites at the moment are:
The compiler environment for x86_64 should be accessible from the `stdenv` at
the path `.#packages.x86_64-linux-x86_64-genode.stdenv`. There is currently no
recommendations for integrating the compiler within external build systems.
- 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.
Bootstrapping the LLVM toolchain on a laptop can take hours, so personally I
farm out the builds. If you interested in binaries please contact me and we can
setup a cache.
- 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
## 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:
{ pkgs, ... }:
nix.package = pkgs.nixFlakes;
# The following enables the use of a binary cache
nix.binaryCaches = [ "https://cache.server7.hq.c3d2.de" ];
nix.binaryCachePublicKeys = [
Non-NixOS users may install flakes using the following shell commands:
$ 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
$ nix flake add genodepkgs git+https://git.sr.ht/~ehmry/genodepkgs
$ nix build genodepkgs#checks.x86_64-linux-x86_64-genode.checks.nova-pci
# View the log if the result is already cached:
$ nix log genodepkgs#checks.x86_64-linux-x86_64-genode.checks.nova-pci
### As a hacker
$ git clone https://git.sr.ht/~ehmry/genodepkgs
$ cd genodepkgs
$ nix build .#checks.x86_64-linux-x86_64-genode.checks.nova-pci
# View the log if the result is already cached:
$ nix log .#checks.x86_64-linux-x86_64-genode.checks.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 continous builds with a
[Hydra](https://nixos.org/hydra/), but only the experimental flakes capable
## 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 baremetal the CPU is signficant but ABI
is irrelevant.
- `buildPlatform` - equilavent 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 evaulation of flakes may only form directed
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.
- *Package* - *undefined*
# Legal
This repository is for trivial packaging aljebra 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)