Write a decent README
This commit is contained in:
parent
c5da3100c4
commit
fefed4c5e8
189
README.md
189
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.
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue