August 2022 - Spectrum Development

[PATCH] Documentation: Architecture Decision Record
by Ville Ilvonen 06 Jan '23

06 Jan '23

* ADRs based on discussions with Alyssa * A note on ADRs to architecture.adoc Signed-off-by: Ville Ilvonen <ville.ilvonen(a)unikie.com> --- Documentation/architecture.adoc | 13 ++++++++++ ...architecture-decision-record-template.adoc | 13 ++++++++++ .../decisions/001-host-update-mechanism.adoc | 19 ++++++++++++++ .../decisions/002-install-options.adoc | 18 +++++++++++++ Documentation/decisions/003-partitioning.adoc | 25 +++++++++++++++++++ .../004-data-at-rest-encryption.adoc | 16 ++++++++++++ .../005-virtual-machine-manager.adoc | 24 ++++++++++++++++++ .../decisions/006-drivers-on-host.adoc | 17 +++++++++++++ .../decisions/007-USB-virtual-machine.adoc | 14 +++++++++++ ...008-Inter-VM-communication-mechanisms.adoc | 18 +++++++++++++ 10 files changed, 177 insertions(+) create mode 100644 Documentation/decisions/000-lightweight-architecture-decision-record-template.adoc create mode 100644 Documentation/decisions/001-host-update-mechanism.adoc create mode 100644 Documentation/decisions/002-install-options.adoc create mode 100644 Documentation/decisions/003-partitioning.adoc create mode 100644 Documentation/decisions/004-data-at-rest-encryption.adoc create mode 100644 Documentation/decisions/005-virtual-machine-manager.adoc create mode 100644 Documentation/decisions/006-drivers-on-host.adoc create mode 100644 Documentation/decisions/007-USB-virtual-machine.adoc create mode 100644 Documentation/decisions/008-Inter-VM-communication-mechanisms.adoc diff --git a/Documentation/architecture.adoc b/Documentation/architecture.adoc index 157907f..185740c 100644 --- a/Documentation/architecture.adoc +++ b/Documentation/architecture.adoc @@ -20,6 +20,19 @@ devices and provides network services to application VMs). Refer to xref:creating-vms.adoc[Creating VMs] and xref:running-vms.adoc[Running VMs] for more information about using VMs in Spectrum. +== Architecture Decision Record (ADR) + +https://adr.github.io/[Architecturally significant decisions] are +recorded as https://github.com/joelparkerhenderson/architecture-decision-record/blob/ma… ADRs] + +Status of Spectrum OS ADRs: +Accepted - Implemented and likely not to change. +Proposed - Designed and possibly partially implmented. May change. +Other - Not yet in use. + +Comments and contributions to ADRs are welcome. ADRs can be found at +Documentation/decisions + == The Spectrum host system Compartmentalization is implemented using diff --git a/Documentation/decisions/000-lightweight-architecture-decision-record-template.adoc b/Documentation/decisions/000-lightweight-architecture-decision-record-template.adoc new file mode 100644 index 0000000..087ec44 --- /dev/null +++ b/Documentation/decisions/000-lightweight-architecture-decision-record-template.adoc @@ -0,0 +1,13 @@ +# Title + +## Status +What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.? + +## Context +What is the issue that we're seeing that is motivating this decision or change? + +## Decision +What is the change that we're proposing and/or doing? + +## Consequences +What becomes easier or more difficult to do because of this change? diff --git a/Documentation/decisions/001-host-update-mechanism.adoc b/Documentation/decisions/001-host-update-mechanism.adoc new file mode 100644 index 0000000..03bbae2 --- /dev/null +++ b/Documentation/decisions/001-host-update-mechanism.adoc @@ -0,0 +1,19 @@ +# Host update mechanism + +## Status +Proposed + +## Context +Spectrum OS has no implementation for software update. The host - consisting of +Linux kernel, KVM, cloud-hypervisor and minimal user space tools - software +updates are required to support feature development and security fixes. + +## Decision +A-B partitioning created by Spectrum installer Installer sets up the system on +partition A of the block device A-B update scheme where user (or installer) +writes the update image to partition B Bootloader provides four boot options: +A, A mutable, B, B mutable + +## Consequences +Default boot selection, incremental updates (e.g. overlays), network update +postponed for later. diff --git a/Documentation/decisions/002-install-options.adoc b/Documentation/decisions/002-install-options.adoc new file mode 100644 index 0000000..f5857c5 --- /dev/null +++ b/Documentation/decisions/002-install-options.adoc @@ -0,0 +1,18 @@ +# Install options + +## Status +Proposed + +## Context +Based on identified different audiences for the Spectrum OS release it is +proposed we support three base configurations to use with Spectrum OS in the +first boot. + +## Decision +* Minimal - Spectrum OS host + system VMs: netvm, guivm, usbvm + home-directory +(optionally encrypted - see 004-disk-encryption.md) +* Common - Minimal + browser app VM + 2-3 selected app VMs +* Power - Common + NixOS VM + +## Consequences +Requires first-boot-vm (like wizard) to support user to get started. diff --git a/Documentation/decisions/003-partitioning.adoc b/Documentation/decisions/003-partitioning.adoc new file mode 100644 index 0000000..345619f --- /dev/null +++ b/Documentation/decisions/003-partitioning.adoc @@ -0,0 +1,25 @@ +# Partitioning + +## Status +Proposed + +## Context +Partitions are required to install the Spectrum OS, VMs and store user data. + +## Decision +---- +<blockdevice> # EFI system partition +<blockdevice> # XBOOTLDR +<blockdevice> # A +<blockdevice> # B +# first 32 GB are reserved for Spectrum system +# rest of the disk is reserved for user data +<blockdevice>n-1 # bootstrap user data +<blockdevice>n to the end of disk # user data +---- + +## Consequences +LVM may support resizing - both increasing and decreasing with some limitation +when there's alreay data on volume(s). Does LVM work with all disk types? We +have to implement XBOOTLDR to support EFI system partition created by Windows - +to support dual boot diff --git a/Documentation/decisions/004-data-at-rest-encryption.adoc b/Documentation/decisions/004-data-at-rest-encryption.adoc new file mode 100644 index 0000000..3ed9abb --- /dev/null +++ b/Documentation/decisions/004-data-at-rest-encryption.adoc @@ -0,0 +1,16 @@ +# Data at rest encryption + +## Status +Proposed + +## Context +To support user data and privacy protection, encryption of data at rest is +required. + +## Decision +User data is encrypted. + +## Consequences +Spectrum OS needs to come with enough SW to get the encryption key via different +methods (password, usb, fido, etc.) Can we use dm-crypt for everything instead +of LUKS? diff --git a/Documentation/decisions/005-virtual-machine-manager.adoc b/Documentation/decisions/005-virtual-machine-manager.adoc new file mode 100644 index 0000000..b4af595 --- /dev/null +++ b/Documentation/decisions/005-virtual-machine-manager.adoc @@ -0,0 +1,24 @@ +# Virtual Machine Manager + +## Status +Accepted + +## Context +rust-vmm-based VMM provides memory and concurrency safe solution. +cloud-hypervisor was chosen because firecrack does not support other +virtio-devices than net or block. crosvm was not chosen because cloud-hypervisor +has more flexible IPC mechanisms, more engaging community as LF-project. +cloud-hypervisor has more core features - such as snapshotting, live migration +and more general hot plugging. crosvm supports more devices we will also need. +It was seen easier to port devices from crosvm to cloud-hypervisor than to port +core features from cloud-hypervisor to crosvm. + +## Decision +Spectrum OS design and implementation decision is to use cloud-hypervisor as the +primary VMM. + +## Consequences +We gotta port some stuff from crosvm to cloud-hypervisor. It's easier for +Spectrum to handle virtualization dynamically with cloud-hypervisor. If the +primary VMM, cloud-hypervisor, is exchanged for trials etc. functionality is +expected to break or not supported. diff --git a/Documentation/decisions/006-drivers-on-host.adoc b/Documentation/decisions/006-drivers-on-host.adoc new file mode 100644 index 0000000..052b596 --- /dev/null +++ b/Documentation/decisions/006-drivers-on-host.adoc @@ -0,0 +1,17 @@ +# Drivers on host + +## Status +Accepted + +## Context +To harden the trusted computing base and make it more minimal, the target is to +minimize the amount of drivers on the Spectrum host kernel. + +## Decision +We are aiming to have as few drivers as possible on the host. + +## Consequences +No networking on the host. Responsibilities of the host are expected to get +smaller over time. More flexible management of devices. We need to decouple +device classes - like net, usb, bluetooth and gui - from host to their +respective VMs. diff --git a/Documentation/decisions/007-USB-virtual-machine.adoc b/Documentation/decisions/007-USB-virtual-machine.adoc new file mode 100644 index 0000000..2072427 --- /dev/null +++ b/Documentation/decisions/007-USB-virtual-machine.adoc @@ -0,0 +1,14 @@ +# USB Virtual Machine + +## Status +Proposed + +## Context +To support specific USB devices on specific VMs + +## Decision +The decision is to pass-through USB controller to a VM with authorization +controls inside the VMs to forward a specific USB device using USBIP. + +## Consequences +We need to modify the upstream USBIP daemon to support authorization. diff --git a/Documentation/decisions/008-Inter-VM-communication-mechanisms.adoc b/Documentation/decisions/008-Inter-VM-communication-mechanisms.adoc new file mode 100644 index 0000000..1007037 --- /dev/null +++ b/Documentation/decisions/008-Inter-VM-communication-mechanisms.adoc @@ -0,0 +1,18 @@ +### Inter VM communication mechanisms + +### Status +Proposed + +### Context +Guest VM software needs to communicate with software in other guest VMs + +### Decision +Spectrum provides two mechanism +- TCP/IP with virtio-net +- Wayland with virtio-gpu (nevermind the semantics) for streamed IPC protocol to + send references to shared memory + + +### Consequences +- Examples required on how to write applications which communicate over + virtio-gpu -- 2.36.0

4 9

[PATCH] scripts/make-gpt.sh: reserve 8 MiB at start of GPT
by Alyssa Ross 26 Sep '22

26 Sep '22

In some cases (e.g. a product built on Spectrum where updates to both firmware and OS are delivered by the same vendor), it makes sense to include firmware in the same image as the OS. This firmware tends to live in the start of the image, after the GPT header. (The exact location varies by board.) The 1 MiB reserved by sfdisk by default is not enough for this. The conventional value seems to be 8 MiB. On NixOS, this is configurable with the sdImage.firmwarePartitionOffset option, but this defaults to 8 MiB and I wasn't able to find any examples in searches on DuckDuckGo and GitHub of anybody using any other value, so it looks like 8 MiB is broadly acceptable. Signed-off-by: Alyssa Ross <hi(a)alyssa.is> --- Yuriy, if you'd like to test this patch, here's some documentation about how to do that. :) https://spectrum-os.org/doc/testing-patches.html scripts/make-gpt.sh | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/scripts/make-gpt.sh b/scripts/make-gpt.sh index 56076d3..55f38d6 100755 --- a/scripts/make-gpt.sh +++ b/scripts/make-gpt.sh @@ -1,12 +1,13 @@ #!/bin/sh -eu # # SPDX-FileCopyrightText: 2021-2022 Alyssa Ross <hi(a)alyssa.is> +# SPDX-FileCopyrightText: 2022 Unikie # SPDX-License-Identifier: EUPL-1.2+ # # usage: make-gpt.sh GPT_PATH PATH:PARTTYPE[:PARTUUID]... ONE_MiB=1048576 -TWO_MiB=2097152 +NINE_MiB=9437184 # Prints the number of 1MiB blocks required to store the file named # $1. We use 1MiB blocks because that's what sfdisk uses for @@ -41,8 +42,9 @@ shift nl=$'\n' table="label: gpt" -# Keep 1MiB free at the start, and 1MiB free at the end. -gptBytes=$TWO_MiB +# Keep 8MiB free at the start (to provide space for firmware if +# required), and 1MiB free at the end. +gptBytes=$NINE_MiB for partition; do sizeMiB="$(sizeMiB "$(partitionPath "$partition")")" table="$table${nl}size=${sizeMiB}MiB,$(awk -f "$scriptsDir/sfdisk-field.awk" -v partition="$partition")" @@ -52,6 +54,7 @@ done rm -f "$out" truncate -s "$gptBytes" "$out" sfdisk "$out" <<EOF +first-lba: 16384 $table EOF -- 2.37.1

2 2

[PATCH 1/4] Introduce a build configuration file
by Alyssa Ross 14 Sep '22

14 Sep '22

By default, a file called "config.nix" in the root of the Spectrum repository will be read if it exists. That file should contain an attribute set. Currently, only a "pkgs" key is supported, which allows specifying a custom package set that will be used throughout the Spectrum Nix files. This will allow us to provide configuartion options for people who want to build Spectrum in ways that are probably not suitable for upstreaming. For example, using the "pkgs" config option I'm introducing here, it would be possible to use an overlay to patch individual components, like so: { pkgs = import <nixpkgs> { overlays = [ (final: super: { weston = super.weston.overrideAttrs ({ patches ? [], ... }: { patches = patches ++ [ path/to/weston.patch ]; }); }) ]; }; } Signed-off-by: Alyssa Ross <hi(a)alyssa.is> --- José, Ivan, if you'd like to review these patches, there's some documentation on how to do so here: :) https://spectrum-os.org/doc/reviewing-patches.html .gitignore | 1 + Documentation/default.nix | 4 ++-- Documentation/jekyll.nix | 2 +- host/initramfs/default.nix | 7 +++---- host/initramfs/extfs.nix | 8 ++++---- host/initramfs/shell.nix | 9 +++++---- host/rootfs/default.nix | 7 +++++-- host/rootfs/shell.nix | 8 ++++---- host/start-vm/default.nix | 2 +- host/start-vm/shell.nix | 6 +++--- img/combined/default.nix | 6 +++--- img/combined/eosimages.nix | 4 ++-- img/combined/run-vm.nix | 4 ++-- img/installer/default.nix | 3 ++- img/installer/run-vm.nix | 7 ++++--- img/live/default.nix | 11 ++++++----- img/live/shell.nix | 15 +++++++++------ nix/eval-config.nix | 10 ++++++++++ release.nix | 10 +++++++--- scripts/default.nix | 4 ++-- shell.nix | 2 +- vm/app/catgirl/default.nix | 6 +++--- vm/app/catgirl/shell.nix | 6 +++--- vm/app/lynx/default.nix | 6 +++--- vm/app/lynx/shell.nix | 6 +++--- vm/sys/net/default.nix | 6 +++--- vm/sys/net/shell.nix | 6 +++--- 27 files changed, 95 insertions(+), 71 deletions(-) create mode 100644 nix/eval-config.nix diff --git a/.gitignore b/.gitignore index 8b965e2..a97f309 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ # SPDX-License-Identifier: CC0-1.0 # SPDX-FileCopyrightText: 2021 Alyssa Ross <hi(a)alyssa.is> +/config.nix build/ result result-* diff --git a/Documentation/default.nix b/Documentation/default.nix index d94a8cd..9edfbe8 100644 --- a/Documentation/default.nix +++ b/Documentation/default.nix @@ -2,7 +2,7 @@ # SPDX-FileCopyrightText: 2022 Unikie # SPDX-License-Identifier: MIT -{ pkgs ? import <nixpkgs> {} }: pkgs.callPackage ( +{ config ? import ../nix/eval-config.nix {} }: config.pkgs.callPackage ( { lib, stdenvNoCC, jekyll, drawio-headless }: @@ -31,5 +31,5 @@ stdenvNoCC.mkDerivation { passthru = { inherit jekyll; }; } ) { - jekyll = import ./jekyll.nix { inherit pkgs; }; + jekyll = import ./jekyll.nix { inherit config; }; } diff --git a/Documentation/jekyll.nix b/Documentation/jekyll.nix index bc804b1..6f2866f 100644 --- a/Documentation/jekyll.nix +++ b/Documentation/jekyll.nix @@ -1,7 +1,7 @@ # SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> # SPDX-License-Identifier: MIT -{ pkgs ? import <nixpkgs> {} }: pkgs.callPackage ( +{ config ? import ../nix/eval-config.nix {} }: config.pkgs.callPackage ( { bundlerApp }: diff --git a/host/initramfs/default.nix b/host/initramfs/default.nix index a4f7330..68deb5e 100644 --- a/host/initramfs/default.nix +++ b/host/initramfs/default.nix @@ -1,11 +1,10 @@ # SPDX-FileCopyrightText: 2021-2022 Alyssa Ross <hi(a)alyssa.is> # SPDX-License-Identifier: MIT -{ pkgs ? import <nixpkgs> {} -, rootfs ? import ../rootfs { inherit pkgs; } +{ config ? import ../../nix/eval-config.nix {} +, rootfs ? import ../rootfs { inherit config; } }: - -pkgs.callPackage ( +let inherit (config) pkgs; in pkgs.callPackage ( { lib, stdenvNoCC, makeModulesClosure, runCommand, writeReferencesToFile , pkgsStatic, busybox, cpio, cryptsetup, lvm2, microcodeAmd, microcodeIntel }: diff --git a/host/initramfs/extfs.nix b/host/initramfs/extfs.nix index 9fdbd9a..63f436a 100644 --- a/host/initramfs/extfs.nix +++ b/host/initramfs/extfs.nix @@ -1,21 +1,21 @@ # SPDX-FileCopyrightText: 2021-2022 Alyssa Ross <hi(a)alyssa.is> # SPDX-License-Identifier: MIT -{ pkgs, runCommand, tar2ext4 }: +{ config, runCommand, tar2ext4 }: let netvm = import ../../vm/sys/net { - inherit pkgs; + inherit config; # inherit (foot) terminfo; }; appvm-catgirl = import ../../vm/app/catgirl { - inherit pkgs; + inherit config; # inherit (foot) terminfo; }; appvm-lynx = import ../../vm/app/lynx { - inherit pkgs; + inherit config; # inherit (foot) terminfo; }; in diff --git a/host/initramfs/shell.nix b/host/initramfs/shell.nix index 42da6a4..cbd2c60 100644 --- a/host/initramfs/shell.nix +++ b/host/initramfs/shell.nix @@ -1,16 +1,17 @@ # SPDX-License-Identifier: MIT # SPDX-FileCopyrightText: 2021-2022 Alyssa Ross <hi(a)alyssa.is> -{ pkgs ? import <nixpkgs> {} }: +{ config ? import ../../nix/eval-config.nix {} }: let + inherit (config) pkgs; inherit (pkgs.lib) cleanSource cleanSourceWith; extfs = pkgs.pkgsStatic.callPackage ./extfs.nix { - inherit pkgs; + inherit config; }; - rootfs = import ../rootfs { inherit pkgs; }; - initramfs = import ./. { inherit pkgs rootfs; }; + rootfs = import ../rootfs { inherit config; }; + initramfs = import ./. { inherit config rootfs; }; in with pkgs; diff --git a/host/rootfs/default.nix b/host/rootfs/default.nix index e5f316f..44e910b 100644 --- a/host/rootfs/default.nix +++ b/host/rootfs/default.nix @@ -2,7 +2,8 @@ # SPDX-FileCopyrightText: 2021-2022 Alyssa Ross <hi(a)alyssa.is> # SPDX-FileCopyrightText: 2022 Unikie -{ pkgs ? import <nixpkgs> {} }: pkgs.pkgsStatic.callPackage ( +{ config ? import ../../nix/eval-config.nix {} }: let inherit (config) pkgs; in +pkgs.pkgsStatic.callPackage ( { lib, stdenvNoCC, nixos, runCommand, writeReferencesToFile, s6-rc, tar2ext4 , busybox, cloud-hypervisor, cryptsetup, execline, jq, kmod @@ -13,7 +14,9 @@ let inherit (lib) cleanSource cleanSourceWith concatMapStringsSep hasSuffix; inherit (nixosAllHardware.config.hardware) firmware; - start-vm = import ../start-vm { pkgs = pkgs.pkgsStatic; }; + start-vm = import ../start-vm { + config = config // { pkgs = pkgs.pkgsStatic; }; + }; pkgsGui = pkgs.pkgsMusl.extend (final: super: { systemd = final.libudev-zero; diff --git a/host/rootfs/shell.nix b/host/rootfs/shell.nix index 3b2310f..8c30f68 100644 --- a/host/rootfs/shell.nix +++ b/host/rootfs/shell.nix @@ -1,11 +1,11 @@ # SPDX-License-Identifier: MIT # SPDX-FileCopyrightText: 2021 Alyssa Ross <hi(a)alyssa.is> -{ pkgs ? import <nixpkgs> {} }: +{ config ? import ../../nix/eval-config.nix {} }: -with pkgs; +with config.pkgs; -(import ./. { inherit pkgs; }).overrideAttrs ( +(import ./. { inherit config; }).overrideAttrs ( { passthru ? {}, nativeBuildInputs ? [], ... }: { @@ -13,6 +13,6 @@ with pkgs; jq netcat qemu_kvm reuse util-linux ]; - EXT_FS = pkgsStatic.callPackage ../initramfs/extfs.nix { inherit pkgs; }; + EXT_FS = pkgsStatic.callPackage ../initramfs/extfs.nix { inherit config; }; KERNEL = "${passthru.kernel}/${stdenv.hostPlatform.linux-kernel.target}"; }) diff --git a/host/start-vm/default.nix b/host/start-vm/default.nix index 56be882..fcce495 100644 --- a/host/start-vm/default.nix +++ b/host/start-vm/default.nix @@ -1,7 +1,7 @@ # SPDX-License-Identifier: MIT # SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> -{ pkgs ? import <nixpkgs> {} }: pkgs.callPackage ( +{ config ? import ../../nix/eval-config.nix {} }: config.pkgs.callPackage ( { lib, stdenv, fetchpatch, meson, ninja, rustc }: let diff --git a/host/start-vm/shell.nix b/host/start-vm/shell.nix index c7f6365..5192b76 100644 --- a/host/start-vm/shell.nix +++ b/host/start-vm/shell.nix @@ -1,11 +1,11 @@ # SPDX-License-Identifier: MIT # SPDX-FileCopyrightText: 2021 Alyssa Ross <hi(a)alyssa.is> -{ pkgs ? import <nixpkgs> {} }: +{ config ? import ../../nix/eval-config.nix {} }: -with pkgs; +with config.pkgs; -(import ./. { inherit pkgs; }).overrideAttrs ( +(import ./. { inherit config; }).overrideAttrs ( { nativeBuildInputs ? [], ... }: { diff --git a/img/combined/default.nix b/img/combined/default.nix index 16cd506..3989d55 100644 --- a/img/combined/default.nix +++ b/img/combined/default.nix @@ -2,17 +2,17 @@ # SPDX-FileCopyrightText: 2021-2022 Alyssa Ross <hi(a)alyssa.is> # SPDX-FileCopyrightText: 2021 Yureka <yuka(a)yuka.dev> -{ pkgs ? import <nixpkgs> {} }: with pkgs; +{ config ? import ../../nix/eval-config.nix {} }: with config.pkgs; let inherit (builtins) storeDir; inherit (pkgs.lib) removePrefix; - eosimages = import ./eosimages.nix { inherit pkgs; }; + eosimages = import ./eosimages.nix { inherit config; }; installerPartUuid = "6e23b026-9f1e-479d-8a58-a0cda382e1ce"; installer = import ../installer { - inherit pkgs; + inherit config; extraConfig = { boot.initrd.availableKernelModules = [ "squashfs" ]; diff --git a/img/combined/eosimages.nix b/img/combined/eosimages.nix index 4ec28e5..9f2ab10 100644 --- a/img/combined/eosimages.nix +++ b/img/combined/eosimages.nix @@ -1,12 +1,12 @@ # SPDX-License-Identifier: MIT # SPDX-FileCopyrightText: 2021-2022 Alyssa Ross <hi(a)alyssa.is> -{ pkgs ? import <nixpkgs> {} }: with pkgs; +{ config ? import ../../nix/eval-config.nix {} }: with config.pkgs; runCommand "eosimages.img" { nativeBuildInputs = [ e2fsprogs tar2ext4 ]; imageName = "Spectrum-0.0-x86_64-generic.0.Live.img"; - image = import ../live { inherit pkgs; }; + image = import ../live { inherit config; }; } '' mkdir dir cd dir diff --git a/img/combined/run-vm.nix b/img/combined/run-vm.nix index 893bc7d..40eacc4 100644 --- a/img/combined/run-vm.nix +++ b/img/combined/run-vm.nix @@ -1,10 +1,10 @@ # SPDX-License-Identifier: MIT # SPDX-FileCopyrightText: 2021 Alyssa Ross <hi(a)alyssa.is> -{ pkgs ? import <nixpkgs> {} }: with pkgs; +{ config ? import ../../nix/eval-config.nix {} }: with config.pkgs; let - image = import ./. { inherit pkgs; }; + image = import ./. { inherit config; }; in writeShellScript "run-spectrum-installer-vm.sh" '' diff --git a/img/installer/default.nix b/img/installer/default.nix index ba97a53..0c57704 100644 --- a/img/installer/default.nix +++ b/img/installer/default.nix @@ -1,7 +1,8 @@ # SPDX-License-Identifier: MIT # SPDX-FileCopyrightText: 2021-2022 Alyssa Ross <hi(a)alyssa.is> -{ pkgs ? import <nixpkgs> {}, extraConfig ? {} }: with pkgs; +{ config ? import ../../nix/eval-config.nix {}, extraConfig ? {} }: +with config.pkgs; let inherit (builtins) head match storeDir; diff --git a/img/installer/run-vm.nix b/img/installer/run-vm.nix index 4a6c849..4efbf1a 100644 --- a/img/installer/run-vm.nix +++ b/img/installer/run-vm.nix @@ -1,17 +1,18 @@ # SPDX-License-Identifier: MIT # SPDX-FileCopyrightText: 2021-2022 Alyssa Ross <hi(a)alyssa.is> -{ pkgs ? import <nixpkgs> {} }: +{ config ? import ../../nix/eval-config.nix {} }: let inherit (builtins) storeDir; + inherit (config) pkgs; inherit (pkgs) coreutils qemu_kvm stdenv writeShellScript; inherit (pkgs.lib) makeBinPath escapeShellArg; - eosimages = import ../combined/eosimages.nix { inherit pkgs; }; + eosimages = import ../combined/eosimages.nix { inherit config; }; installer = import ./. { - inherit pkgs; + inherit config; extraConfig = { boot.initrd.availableKernelModules = [ "9p" "9pnet_virtio" ]; diff --git a/img/live/default.nix b/img/live/default.nix index 88f0ee4..65ad058 100644 --- a/img/live/default.nix +++ b/img/live/default.nix @@ -1,17 +1,18 @@ # SPDX-License-Identifier: MIT # SPDX-FileCopyrightText: 2021-2022 Alyssa Ross <hi(a)alyssa.is> -{ pkgs ? import <nixpkgs> {} }: +{ config ? import ../../nix/eval-config.nix {} }: let + inherit (config) pkgs; inherit (pkgs.lib) cleanSource cleanSourceWith hasSuffix; extfs = pkgs.pkgsStatic.callPackage ../../host/initramfs/extfs.nix { - inherit pkgs; + inherit config; }; - rootfs = import ../../host/rootfs { inherit pkgs; }; - scripts = import ../../scripts { inherit pkgs; }; - initramfs = import ../../host/initramfs { inherit pkgs rootfs; }; + rootfs = import ../../host/rootfs { inherit config; }; + scripts = import ../../scripts { inherit config; }; + initramfs = import ../../host/initramfs { inherit config rootfs; }; in with pkgs; diff --git a/img/live/shell.nix b/img/live/shell.nix index b9f0246..dcf2059 100644 --- a/img/live/shell.nix +++ b/img/live/shell.nix @@ -1,12 +1,15 @@ # SPDX-License-Identifier: MIT # SPDX-FileCopyrightText: 2021-2022 Alyssa Ross <hi(a)alyssa.is> -{ pkgs ? import <nixpkgs> {} }: +{ config ? import ../../nix/eval-config.nix {} }: -with pkgs; +with config.pkgs; -(import ./. { inherit pkgs; }).overrideAttrs ({ nativeBuildInputs ? [], ... }: { - nativeBuildInputs = nativeBuildInputs ++ [ qemu_kvm ]; +(import ./. { inherit config; }).overrideAttrs ( + { nativeBuildInputs ? [], ... }: + { + nativeBuildInputs = nativeBuildInputs ++ [ qemu_kvm ]; - OVMF_CODE = "${qemu_kvm}/share/qemu/edk2-${stdenv.hostPlatform.qemuArch}-code.fd"; -}) + OVMF_CODE = "${qemu_kvm}/share/qemu/edk2-${stdenv.hostPlatform.qemuArch}-code.fd"; + } +) diff --git a/nix/eval-config.nix b/nix/eval-config.nix new file mode 100644 index 0000000..9265df7 --- /dev/null +++ b/nix/eval-config.nix @@ -0,0 +1,10 @@ +# SPDX-License-Identifier: MIT +# SPDX-FileCopyrightText: 2022 Unikie + +{ config ? + if builtins.pathExists ../config.nix then import ../config.nix else {} +}: + +({ pkgs ? import <nixpkgs> {} }: { + inherit pkgs; +}) config diff --git a/release.nix b/release.nix index da7123f..91a843b 100644 --- a/release.nix +++ b/release.nix @@ -3,10 +3,14 @@ # This file is built to populate the binary cache. -{ pkgs ? import <nixpkgs> {} }: +# Set config = {} to disable implicitly reading config.nix, since +# we'll want the result to be the same as on the binary cache. If it +# turns out there is a compelling reason to read the default config +# here, we can reconsider this. +{ config ? import nix/eval-config.nix { config = {}; } }: { - doc = import ./Documentation { inherit pkgs; }; + doc = import ./Documentation { inherit config; }; - combined = import img/combined/run-vm.nix { inherit pkgs; }; + combined = import img/combined/run-vm.nix { inherit config; }; } diff --git a/scripts/default.nix b/scripts/default.nix index 7995723..2237cb5 100644 --- a/scripts/default.nix +++ b/scripts/default.nix @@ -1,10 +1,10 @@ # SPDX-License-Identifier: MIT # SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> -{ pkgs ? import <nixpkgs> {} }: +{ config ? import ../nix/eval-config.nix {} }: let - inherit (pkgs.lib) cleanSource cleanSourceWith hasSuffix; + inherit (config.pkgs.lib) cleanSource cleanSourceWith hasSuffix; in cleanSourceWith { diff --git a/shell.nix b/shell.nix index 41d0865..4dc8558 100644 --- a/shell.nix +++ b/shell.nix @@ -1,7 +1,7 @@ # SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> # SPDX-License-Identifier: MIT -{ pkgs ? import <nixpkgs> {} }: with pkgs; +{ config ? import nix/eval-config.nix {} }: with config.pkgs; mkShell { nativeBuildInputs = [ reuse rustfmt ]; diff --git a/vm/app/catgirl/default.nix b/vm/app/catgirl/default.nix index 738a603..61f1462 100644 --- a/vm/app/catgirl/default.nix +++ b/vm/app/catgirl/default.nix @@ -1,11 +1,11 @@ # SPDX-License-Identifier: MIT # SPDX-FileCopyrightText: 2021 Alyssa Ross <hi(a)alyssa.is> -{ pkgs ? import <nixpkgs> {} -, terminfo ? pkgs.foot.terminfo +{ config ? import ../../../nix/eval-config.nix {} +, terminfo ? config.pkgs.foot.terminfo }: -pkgs.pkgsStatic.callPackage ( +config.pkgs.pkgsStatic.callPackage ( { lib, stdenvNoCC, runCommand, writeReferencesToFile, buildPackages , s6-rc, tar2ext4 diff --git a/vm/app/catgirl/shell.nix b/vm/app/catgirl/shell.nix index 87c4f6e..852b246 100644 --- a/vm/app/catgirl/shell.nix +++ b/vm/app/catgirl/shell.nix @@ -1,11 +1,11 @@ # SPDX-License-Identifier: MIT # SPDX-FileCopyrightText: 2021 Alyssa Ross <hi(a)alyssa.is> -{ pkgs ? import <nixpkgs> {} }: +{ config ? import ../../../nix/eval-config.nix {} }: -with pkgs; +with config.pkgs; -(import ./. { inherit pkgs; }).overrideAttrs ( +(import ./. { inherit config; }).overrideAttrs ( { passthru ? {}, nativeBuildInputs ? [], ... }: { diff --git a/vm/app/lynx/default.nix b/vm/app/lynx/default.nix index 50fd760..ba715ec 100644 --- a/vm/app/lynx/default.nix +++ b/vm/app/lynx/default.nix @@ -1,11 +1,11 @@ # SPDX-License-Identifier: MIT # SPDX-FileCopyrightText: 2021 Alyssa Ross <hi(a)alyssa.is> -{ pkgs ? import <nixpkgs> {} -, terminfo ? pkgs.foot.terminfo +{ config ? import ../../../nix/eval-config.nix {} +, terminfo ? config.pkgs.foot.terminfo }: -pkgs.pkgsStatic.callPackage ( +config.pkgs.pkgsStatic.callPackage ( { lib, stdenvNoCC, runCommand, writeReferencesToFile, buildPackages , s6-rc, tar2ext4 diff --git a/vm/app/lynx/shell.nix b/vm/app/lynx/shell.nix index 87c4f6e..852b246 100644 --- a/vm/app/lynx/shell.nix +++ b/vm/app/lynx/shell.nix @@ -1,11 +1,11 @@ # SPDX-License-Identifier: MIT # SPDX-FileCopyrightText: 2021 Alyssa Ross <hi(a)alyssa.is> -{ pkgs ? import <nixpkgs> {} }: +{ config ? import ../../../nix/eval-config.nix {} }: -with pkgs; +with config.pkgs; -(import ./. { inherit pkgs; }).overrideAttrs ( +(import ./. { inherit config; }).overrideAttrs ( { passthru ? {}, nativeBuildInputs ? [], ... }: { diff --git a/vm/sys/net/default.nix b/vm/sys/net/default.nix index 0ce72fc..dfc7c35 100644 --- a/vm/sys/net/default.nix +++ b/vm/sys/net/default.nix @@ -1,11 +1,11 @@ # SPDX-License-Identifier: MIT # SPDX-FileCopyrightText: 2021 Alyssa Ross <hi(a)alyssa.is> -{ pkgs ? import <nixpkgs> {} -, terminfo ? pkgs.foot.terminfo +{ config ? import ../../../nix/eval-config.nix {} +, terminfo ? config.pkgs.foot.terminfo }: -pkgs.pkgsStatic.callPackage ( +config.pkgs.pkgsStatic.callPackage ( { lib, stdenvNoCC, runCommand, writeReferencesToFile, buildPackages , s6-rc, tar2ext4, xorg diff --git a/vm/sys/net/shell.nix b/vm/sys/net/shell.nix index bc4de67..849920d 100644 --- a/vm/sys/net/shell.nix +++ b/vm/sys/net/shell.nix @@ -1,11 +1,11 @@ # SPDX-License-Identifier: MIT # SPDX-FileCopyrightText: 2021 Alyssa Ross <hi(a)alyssa.is> -{ pkgs ? import <nixpkgs> {} }: +{ config ? import ../../../nix/eval-config.nix {} }: -with pkgs; +with config.pkgs; -(import ./. { inherit pkgs; }).overrideAttrs ( +(import ./. { inherit config; }).overrideAttrs ( { passthru ? {}, nativeBuildInputs ? [], ... }: { -- 2.37.1

4 11

[PATCH] Documentation: add "Sending your First Patch"
by Alyssa Ross 11 Aug '22

11 Aug '22

I think having this written down in tutorial style is important, so people can follow through some step by step instructions. We already have some similar documentation on <https://spectrum-os.org/contributing.html>, but it doesn't really go into any detail, and I think this belongs in the main documentation. Signed-off-by: Alyssa Ross <hi(a)alyssa.is> --- Ville, I'm CCing you in case you'd like to review, since we talked about documenting the patch workflow a bit better before. We also have this small document about reviewing patches on the list now, at <https://spectrum-os.org/doc/reviewing-patches.html>. :) Documentation/first-patch.adoc | 96 ++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 Documentation/first-patch.adoc diff --git a/Documentation/first-patch.adoc b/Documentation/first-patch.adoc new file mode 100644 index 0000000..22140e4 --- /dev/null +++ b/Documentation/first-patch.adoc @@ -0,0 +1,96 @@ += Sending Your First Patch +:page-parent: Tutorials + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +== Prerequisites + +This tutorial assumes that you already have basic +https://git-scm.com/[git] experience. + +Before beginning, you'll need to have a local git checkout of the +https://spectrum-os.org/git/[Spectrum source tree]. You'll also need +to have configured `git send-email` — a guide for this can be found at +https://git-send-email.io/. + +== Making your changes + +If you've worked on any git repository before, the process for making +your changes will probably be very familiar. + +1. Create a branch for your changes: ++ +---- +git checkout -b fix-docs # for example +---- +2. Make changes in your editor. +3. Stage and commit your changes: ++ +---- +git add Documentation/first-patch.adoc # for example +git commit -s +---- ++ +TIP: The `-s` option adds a `Signed-off-by` line to the commit. This +indicates your acceptance of the +https://spectrum-os.org/git/spectrum/tree/DCO-1.1.txt[Developer's +Certificate of Origin], which is mandatory for Spectrum patches. + +== Submitting changes + +Once you're happy with how the commits on your branch look, run: + +---- +git send-email --to devel(a)spectrum-os.org --confirm=always origin/main +---- + +For each message, you will be prompted for confirmation, and then the +change will be submitted to the Spectrum development mailing list. +They will appear shortly on the +https://spectrum-os.org/lists/hyperkitty/list/devel@spectrum-os.org/[web +interface]. + +[#cover-letter] +TIP: If you're submitting multiple changes, and you'd like to provide +an overall description for the whole series, you can add the +`--compose` option, which will prompt you to compose a "cover letter" +message that will be sent before all of your patches. + +== Feedback + +Once your patch has been submitted, wait for it to be reviewed. +Feedback, if any, will be sent as email replies to your submitted +patch. You can respond to feedback in your mail client. Please use +the Reply All button to ensure that your messages are sent to the +mailing list as well as to the person who sent the feedback. + +If you need to make changes to your patch, and submit a new version, +use https://git-rebase.io/[`git rebase`] to create a new version of +your patch(es), and submit it like this: + +---- +git send-email -v2 --to devel(a)spectrum-os.org --confirm=always origin/main +---- + +The added `-v2` flag indicates that this is version two of your +patch set. If your patches require more rounds of changes, submit +subsequent rounds with `-v3`, `-v4`, etc. as appropriate. + +If you'd like to describe what has changed from the previous version +of your patches, you can do so in a xref:cover-letter[cover letter] +as described above. + +== Acceptance + +Once your patch has been accepted, it will be applied to the upstream +Spectrum git repository. You will receive an automated email +confirmation when this happens. + +== Questions + +If you have any questions about the patch submission process, you can +ask them either on the +https://spectrum-os.org/participating.html#spectrum-devel[development +mailing list], or in the +https://spectrum-os.org/participating.html#irc[IRC/Matrix channel]. -- 2.35.1

2 1