From fefed4c5e86a3900faa0515c7c4dc6bd7dc7b1f8 Mon Sep 17 00:00:00 2001 From: Emery Hemingway Date: Fri, 24 Jan 2020 14:45:31 +0100 Subject: [PATCH] Write a decent README --- README.md | 189 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 169 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index b35140f..933c1f0 100644 --- a/README.md +++ b/README.md @@ -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 +`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.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 + +```sh +$ 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 +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 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)