Spectrum Development

Download

devel@spectrum-os.org

388 discussions

[PATCH 0/2] IOMMU fixes
by Alyssa Ross 14 Nov '22

14 Nov '22

Vadim found that it was not possible to test networking in the live image's make run target. This turned out to be for two separate reasons. One was that we didn't have an IOMMU on that QEMU machine, but even adding that wasn't enough, because Intel IOMMUs also just didn't work at all on the live image, due to a missing kernel command line parameter. Alyssa Ross (2): Set intel_iommu=on in kernel command line Add IOMMU to other host test targets host/initramfs/Makefile | 4 +++- img/combined/run-vm.nix | 3 ++- img/live/Makefile | 4 +++- 3 files changed, 8 insertions(+), 3 deletions(-) base-commit: 3aa2f8aa7423cdf36c797943ad7d5a9756290909 -- 2.37.1

2 4

[PATCH 1/2] scripts: fix shellcheck warnings
by Alyssa Ross 11 Nov '22

11 Nov '22

Signed-off-by: Alyssa Ross <alyssa.ross(a)unikie.com> --- Henri, I've CCed you on this series, in case you'd like to review. We have some documentation on reviewing patches here: https://spectrum-os.org/doc/development/reviewing-patches.html scripts/format-uuid.sh | 12 ++++++------ scripts/make-gpt.sh | 6 +++--- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/scripts/format-uuid.sh b/scripts/format-uuid.sh index 6758088..441ed64 100755 --- a/scripts/format-uuid.sh +++ b/scripts/format-uuid.sh @@ -8,12 +8,12 @@ substr () { str=$1 beg=$2 end=$3 - echo $str | cut -c $beg-$end + echo "$str" | cut -c "$beg-$end" } -u1=$(substr $1 1 8) -u2=$(substr $1 9 12) -u3=$(substr $1 13 16) -u4=$(substr $1 17 20) -u5=$(substr $1 21 32) +u1=$(substr "$1" 1 8) +u2=$(substr "$1" 9 12) +u3=$(substr "$1" 13 16) +u4=$(substr "$1" 17 20) +u5=$(substr "$1" 21 32) printf "%s\n" "$u1-$u2-$u3-$u4-$u5" diff --git a/scripts/make-gpt.sh b/scripts/make-gpt.sh index 3215edb..554182f 100755 --- a/scripts/make-gpt.sh +++ b/scripts/make-gpt.sh @@ -23,7 +23,7 @@ sizeMiB() { fillPartition() { sfdisk -J "$1" | jq -r --argjson index "$2" \ '.partitiontable.partitions[$index] | "\(.start) \(.size)"' | - (read start size; + (read -r start size; dd if="$3" of="$1" seek="$start" count="$size" conv=notrunc) } @@ -48,7 +48,7 @@ gptBytes=$TWO_MiB for partition; do sizeMiB="$(sizeMiB "$(partitionPath "$partition")")" table="$table${nl}size=${sizeMiB}MiB,$(awk -f "$scriptsDir/sfdisk-field.awk" -v partition="$partition")" - gptBytes="$(expr "$gptBytes" + "$sizeMiB" \* $ONE_MiB)" + gptBytes="$((gptBytes + sizeMiB * ONE_MiB))" done rm -f "$out" @@ -60,5 +60,5 @@ EOF n=0 for partition; do fillPartition "$out" "$n" "$(partitionPath "$partition")" - n="$(expr "$n" + 1)" + n="$((n + 1))" done -- 2.35.1

3 5

[PATCH v3] Remove bashisms from spectrum shell scripts
by Henri Rosten 10 Nov '22

10 Nov '22

This commit removes bashisms from spectrum shell scripts. This change is needed to be able to use the scripts from POSIX-compliant shells which are not bash compatible - such as dash. Signed-off-by: Henri Rosten <henri.rosten(a)unikie.com> --- Documentation/scripts/undocumented-uuids.sh | 9 +++++++-- scripts/format-uuid.sh | 15 ++++++++++++++- scripts/make-gpt.sh | 4 +++- 3 files changed, 24 insertions(+), 4 deletions(-) diff --git a/Documentation/scripts/undocumented-uuids.sh b/Documentation/scripts/undocumented-uuids.sh index 34c2d22..c75bfd2 100755 --- a/Documentation/scripts/undocumented-uuids.sh +++ b/Documentation/scripts/undocumented-uuids.sh @@ -1,14 +1,19 @@ #!/bin/sh -eu # SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> +# SPDX-FileCopyrightText: 2022 Unikie # SPDX-License-Identifier: EUPL-1.2+ cd "$(dirname "$0")/../.." PATTERN='\b[A-F0-9]{8}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{12}\b' -UUID_REFERENCE_PATH=Documentation/uuid-reference.adoc +UUID_REFERENCE_PATH=Documentation/appendices/uuid-reference.adoc +documented_uuids=$(mktemp) +trap 'rm -f -- "$documented_uuids"' EXIT + +grep -Eio "$PATTERN" "$UUID_REFERENCE_PATH" | sort -u >"$documented_uuids" git ls-files -coz --exclude-standard | grep -Fxvz "$UUID_REFERENCE_PATH" | xargs -0 git grep -Ehio --no-index --no-line-number "$PATTERN" -- | sort -u | - comm -23 - <(grep -Eio "$PATTERN" "$UUID_REFERENCE_PATH" | sort -u) + comm -23 - "$documented_uuids" diff --git a/scripts/format-uuid.sh b/scripts/format-uuid.sh index fa07eb9..6758088 100755 --- a/scripts/format-uuid.sh +++ b/scripts/format-uuid.sh @@ -1,6 +1,19 @@ #!/bin/sh -eu # # SPDX-FileCopyrightText: 2021-2022 Alyssa Ross <hi(a)alyssa.is> +# SPDX-FileCopyrightText: 2022 Unikie # SPDX-License-Identifier: EUPL-1.2+ -printf "%s\n" "${1:0:8}-${1:8:4}-${1:12:4}-${1:16:4}-${1:20}" +substr () { + str=$1 + beg=$2 + end=$3 + echo $str | cut -c $beg-$end +} + +u1=$(substr $1 1 8) +u2=$(substr $1 9 12) +u3=$(substr $1 13 16) +u4=$(substr $1 17 20) +u5=$(substr $1 21 32) +printf "%s\n" "$u1-$u2-$u3-$u4-$u5" diff --git a/scripts/make-gpt.sh b/scripts/make-gpt.sh index 56076d3..3215edb 100755 --- a/scripts/make-gpt.sh +++ b/scripts/make-gpt.sh @@ -1,6 +1,7 @@ #!/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]... @@ -38,7 +39,8 @@ scriptsDir="$(dirname "$0")" out="$1" shift -nl=$'\n' +nl=' +' table="label: gpt" # Keep 1MiB free at the start, and 1MiB free at the end. -- 2.25.1

2 1

[PATCH v2] Remove bashisms from spectrum shell scripts
by Henri Rosten 09 Nov '22

09 Nov '22

This commit removes bashisms from spectrum shell scripts. This change is needed to be able to use the scripts from POSIX-compliant shells which are not bash compatible - such as dash. Signed-off-by: Henri Rosten <henri.rosten(a)unikie.com> --- Documentation/scripts/undocumented-uuids.sh | 7 ++++++- scripts/format-uuid.sh | 15 ++++++++++++++- scripts/make-gpt.sh | 7 +++---- 3 files changed, 23 insertions(+), 6 deletions(-) diff --git a/Documentation/scripts/undocumented-uuids.sh b/Documentation/scripts/undocumented-uuids.sh index 34c2d22..fa21366 100755 --- a/Documentation/scripts/undocumented-uuids.sh +++ b/Documentation/scripts/undocumented-uuids.sh @@ -1,14 +1,19 @@ #!/bin/sh -eu # SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> +# SPDX-FileCopyrightText: 2022 Unikie # SPDX-License-Identifier: EUPL-1.2+ +trap 'rm -f -- "$documented_uuids"' EXIT + cd "$(dirname "$0")/../.." PATTERN='\b[A-F0-9]{8}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{12}\b' UUID_REFERENCE_PATH=Documentation/uuid-reference.adoc +documented_uuids=$(mktemp) +grep -Eio "$PATTERN" "$UUID_REFERENCE_PATH" | sort -u >$documented_uuids git ls-files -coz --exclude-standard | grep -Fxvz "$UUID_REFERENCE_PATH" | xargs -0 git grep -Ehio --no-index --no-line-number "$PATTERN" -- | sort -u | - comm -23 - <(grep -Eio "$PATTERN" "$UUID_REFERENCE_PATH" | sort -u) + comm -23 - $documented_uuids diff --git a/scripts/format-uuid.sh b/scripts/format-uuid.sh index fa07eb9..6758088 100755 --- a/scripts/format-uuid.sh +++ b/scripts/format-uuid.sh @@ -1,6 +1,19 @@ #!/bin/sh -eu # # SPDX-FileCopyrightText: 2021-2022 Alyssa Ross <hi(a)alyssa.is> +# SPDX-FileCopyrightText: 2022 Unikie # SPDX-License-Identifier: EUPL-1.2+ -printf "%s\n" "${1:0:8}-${1:8:4}-${1:12:4}-${1:16:4}-${1:20}" +substr () { + str=$1 + beg=$2 + end=$3 + echo $str | cut -c $beg-$end +} + +u1=$(substr $1 1 8) +u2=$(substr $1 9 12) +u3=$(substr $1 13 16) +u4=$(substr $1 17 20) +u5=$(substr $1 21 32) +printf "%s\n" "$u1-$u2-$u3-$u4-$u5" diff --git a/scripts/make-gpt.sh b/scripts/make-gpt.sh index 56076d3..351aa69 100755 --- a/scripts/make-gpt.sh +++ b/scripts/make-gpt.sh @@ -1,6 +1,7 @@ #!/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]... @@ -38,7 +39,7 @@ scriptsDir="$(dirname "$0")" out="$1" shift -nl=$'\n' +nl='\n' table="label: gpt" # Keep 1MiB free at the start, and 1MiB free at the end. @@ -51,9 +52,7 @@ done rm -f "$out" truncate -s "$gptBytes" "$out" -sfdisk "$out" <<EOF -$table -EOF +printf "$table" | sfdisk "$out" n=0 for partition; do -- 2.25.1

2 2

[PATCH] Remove bashisms from spectrum shell scripts
by Henri Rosten 09 Nov '22

09 Nov '22

This commit removes bashisms from spectrum shell scripts. This change is needed to be able to use the scripts from POSIX-compliant shells which are not bash compatible - such as dash. Signed-off-by: Henri Rosten <henri.rosten(a)unikie.com> --- Documentation/scripts/undocumented-uuids.sh | 6 +++++- scripts/format-uuid.sh | 15 ++++++++++++++- scripts/make-gpt.sh | 7 +++---- 3 files changed, 22 insertions(+), 6 deletions(-) diff --git a/Documentation/scripts/undocumented-uuids.sh b/Documentation/scripts/undocumented-uuids.sh index 34c2d22..0434407 100755 --- a/Documentation/scripts/undocumented-uuids.sh +++ b/Documentation/scripts/undocumented-uuids.sh @@ -1,5 +1,6 @@ #!/bin/sh -eu # SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> +# SPDX-FileCopyrightText: 2022 Unikie # SPDX-License-Identifier: EUPL-1.2+ cd "$(dirname "$0")/../.." @@ -7,8 +8,11 @@ cd "$(dirname "$0")/../.." PATTERN='\b[A-F0-9]{8}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{12}\b' UUID_REFERENCE_PATH=Documentation/uuid-reference.adoc +tmp=$(mktemp) +grep -Eio "$PATTERN" "$UUID_REFERENCE_PATH" | sort -u >$tmp git ls-files -coz --exclude-standard | grep -Fxvz "$UUID_REFERENCE_PATH" | xargs -0 git grep -Ehio --no-index --no-line-number "$PATTERN" -- | sort -u | - comm -23 - <(grep -Eio "$PATTERN" "$UUID_REFERENCE_PATH" | sort -u) + comm -23 - $tmp +rm -f $tmp diff --git a/scripts/format-uuid.sh b/scripts/format-uuid.sh index fa07eb9..c7b94da 100755 --- a/scripts/format-uuid.sh +++ b/scripts/format-uuid.sh @@ -1,6 +1,19 @@ #!/bin/sh -eu # # SPDX-FileCopyrightText: 2021-2022 Alyssa Ross <hi(a)alyssa.is> +# SPDX-FileCopyrightText: 2022 Unikie # SPDX-License-Identifier: EUPL-1.2+ -printf "%s\n" "${1:0:8}-${1:8:4}-${1:12:4}-${1:16:4}-${1:20}" +substr () { + str=$1 + beg=$2 + end=$3 + echo $(echo $str | cut -c $beg-$end) +} + +u1=$(substr $1 1 8) +u2=$(substr $1 9 12) +u3=$(substr $1 13 16) +u4=$(substr $1 17 20) +u5=$(substr $1 21 32) +printf "%s\n" "$u1-$u2-$u3-$u4-$u5" diff --git a/scripts/make-gpt.sh b/scripts/make-gpt.sh index 56076d3..351aa69 100755 --- a/scripts/make-gpt.sh +++ b/scripts/make-gpt.sh @@ -1,6 +1,7 @@ #!/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]... @@ -38,7 +39,7 @@ scriptsDir="$(dirname "$0")" out="$1" shift -nl=$'\n' +nl='\n' table="label: gpt" # Keep 1MiB free at the start, and 1MiB free at the end. @@ -51,9 +52,7 @@ done rm -f "$out" truncate -s "$gptBytes" "$out" -sfdisk "$out" <<EOF -$table -EOF +printf "$table" | sfdisk "$out" n=0 for partition; do -- 2.25.1

2 4

[PATCH v4] Docs: new structure
by Jenni Nikolaenko 08 Nov '22

08 Nov '22

Create separate folders for new parent pages, update Introduction page, remove a and the articles from titles, quick check text for simple english Signed-off-by: Jenni Nikolaenko <evgeniia.nikolaenko(a)unikie.com> --- Documentation/{ => about}/architecture.adoc | 51 +++++++++--------- Documentation/about/index.adoc | 32 ++++++++++++ Documentation/appendices/index.adoc | 13 +++++ Documentation/appendices/user-partition.adoc | 17 ++++++ .../{ => appendices}/uuid-reference.adoc | 8 +-- Documentation/building-documentation.adoc | 52 ------------------- .../decisions/001-host-update-mechanism.adoc | 4 +- .../decisions/002-install-options.adoc | 4 +- Documentation/decisions/003-partitioning.adoc | 2 +- .../004-data-at-rest-encryption.adoc | 4 +- .../005-virtual-machine-monitor.adoc | 2 +- .../decisions/006-drivers-on-host.adoc | 2 +- .../decisions/007-usb-virtual-machines.adoc | 2 +- ...008-inter-vm-communication-mechanisms.adoc | 2 +- Documentation/decisions/index.adoc | 2 +- Documentation/{ => development}/b4.adoc | 6 ++- .../build-configuration.adoc | 13 +++-- .../development/building-documentation.adoc | 52 +++++++++++++++++++ .../{ => development}/debugging.adoc | 12 ++--- .../{ => development}/first-patch.adoc | 32 ++++++------ Documentation/development/index.adoc | 27 ++++++++++ Documentation/{ => development}/replying.adoc | 13 ++--- .../{ => development}/reviewing-patches.adoc | 4 +- .../{ => development}/testing-patches.adoc | 28 +++++----- .../development/working-with-patches.adoc | 12 +++++ Documentation/explanation.adoc | 6 --- .../{ => getting-started}/creating-vms.adoc | 3 +- Documentation/getting-started/index.adoc | 13 +++++ .../{ => getting-started}/running-vms.adoc | 3 +- Documentation/how-to.adoc | 6 --- Documentation/index.adoc | 29 +++++++++-- .../{ => installation}/binary-cache.adoc | 22 +++++--- .../{ => installation}/getting-spectrum.adoc | 16 +++--- Documentation/installation/index.adoc | 23 ++++++++ Documentation/reference.adoc | 6 --- Documentation/tutorials.adoc | 6 --- Documentation/user-partition.adoc | 12 ----- 37 files changed, 341 insertions(+), 200 deletions(-) rename Documentation/{ => about}/architecture.adoc (56%) create mode 100644 Documentation/about/index.adoc create mode 100644 Documentation/appendices/index.adoc create mode 100644 Documentation/appendices/user-partition.adoc rename Documentation/{ => appendices}/uuid-reference.adoc (96%) delete mode 100644 Documentation/building-documentation.adoc rename Documentation/{ => development}/b4.adoc (91%) rename Documentation/{ => development}/build-configuration.adoc (73%) create mode 100644 Documentation/development/building-documentation.adoc rename Documentation/{ => development}/debugging.adoc (79%) rename Documentation/{ => development}/first-patch.adoc (80%) create mode 100644 Documentation/development/index.adoc rename Documentation/{ => development}/replying.adoc (68%) rename Documentation/{ => development}/reviewing-patches.adoc (88%) rename Documentation/{ => development}/testing-patches.adoc (82%) create mode 100644 Documentation/development/working-with-patches.adoc delete mode 100644 Documentation/explanation.adoc rename Documentation/{ => getting-started}/creating-vms.adoc (98%) create mode 100644 Documentation/getting-started/index.adoc rename Documentation/{ => getting-started}/running-vms.adoc (90%) delete mode 100644 Documentation/how-to.adoc rename Documentation/{ => installation}/binary-cache.adoc (74%) rename Documentation/{ => installation}/getting-spectrum.adoc (79%) create mode 100644 Documentation/installation/index.adoc delete mode 100644 Documentation/reference.adoc delete mode 100644 Documentation/tutorials.adoc delete mode 100644 Documentation/user-partition.adoc diff --git a/Documentation/architecture.adoc b/Documentation/about/architecture.adoc similarity index 56% rename from Documentation/architecture.adoc rename to Documentation/about/architecture.adoc index 1c4307b..b311e77 100644 --- a/Documentation/architecture.adoc +++ b/Documentation/about/architecture.adoc @@ -1,32 +1,31 @@ = Architecture -:page-parent: Explanation +:page-parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 -== Introduction +Spectrum is based on the principle of security by compartmentalization. -Spectrum is based on the principle of security by -compartmentalization. The high level stack is illustrated in the -following diagram: +The high level stack is illustrated in the following diagram: -image::diagrams/stack.svg[] +image::../diagrams/stack.svg[] The default set of virtual machines includes two application VMs, _appvm-catgirl_ (an IRC client) and _appvm-lynx_ (a text-based web browser); and a system VM, _netvm_ (which handles hardware network -devices and provides network services to application VMs). Refer to -xref:creating-vms.adoc[Creating VMs] and xref:running-vms.adoc[Running +devices and provides network services to application VMs). +Refer to xref:../getting-started/creating-vms.adoc[Creating VMs] and +xref:../getting-started/running-vms.adoc[Running VMs] for more information about using VMs in Spectrum. == Architecture Decision Records (ADRs) https://en.wikipedia.org/wiki/Architectural_decision[Architecturally significant -decisions] are xref:decisions/index.adoc[recorded] as lightweight -https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions/[ADRs]. +decisions] are xref:../decisions/index.adoc[recorded] as lightweight +https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions[ADRs]. -== The Spectrum host system +== Spectrum Host System Compartmentalization is implemented using https://cloud-hypervisor.org/[cloud-hypervisor] virtual machines. @@ -35,8 +34,8 @@ https://en.wikipedia.org/wiki/Kernel-based_Virtual_Machine[Kernel-based Virtual Machine] (KVM) to provide lightweight, hardware-accelerated VMs. While Linux (including KVM) is portable between many hardware architectures, -cloud-hypervisor supports only x86_64 and aarch64. Spectrum currently only -works on x86_64, but aarch64 support is in development. +cloud-hypervisor supports only x86_64 and aarch64. +Spectrum currently only works on x86_64, but aarch64 support is in development. https://skarnet.org/software/s6-rc/overview.html[s6-rc] is used for service management. Utilities like kmod, util-linux and busybox are installed for boot @@ -44,20 +43,22 @@ and service scripts. https://wayland.freedesktop.org/[Wayland] is used for window management and display. The Wayland architecture is well documented -https://wayland.freedesktop.org/architecture.html[here]. The host provides only -a Wayland terminal client, https://codeberg.org/dnkl/foot/[foot], which is used -for interacting with VM consoles. In future it will be possible for application -VMs to display windows on the single Wayland compositor on the host system, -using Wayland virtio-gpu contexts. X11 applications are not currently -supported, but could be in future. +https://wayland.freedesktop.org/architecture.html[here]. +The host provides onlya Wayland terminal client, +https://codeberg.org/dnkl/foot/[foot], which is used for interacting with VM +consoles. +In future it will be possible for application VMs to display windows on the +single Wayland compositor on the host system, using Wayland virtio-gpu +contexts. X11 applications are not currently supported, but could be in future. All host user space components are built with the https://musl.libc.org/[musl C -library]. In comparison to other libc implementations, musl has +library]. +In comparison to other libc implementations, musl has https://www.etalabs.net/compare_libcs.html[added safety on resource exhaustion -and security hardening on memory allocation]. Kernel hardening will be -investigated in future. +and security hardening on memory allocation]. +Kernel hardening will be investigated in future. -== Exploring the Spectrum dependency tree +== Spectrum Dependency Tree For a detailed, interactive view of dependencies, use https://github.com/utdemir/nix-tree[nix-tree] in the Spectrum repository: @@ -66,5 +67,5 @@ https://github.com/utdemir/nix-tree[nix-tree] in the Spectrum repository: [listing] nix-build img/live -I nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz --no-out-link | xargs -o nix-tree -https://diode.zone/w/8DBDQ6HQUe5UUdLkpDuL35[See video of Spectrum live image -interactive analysis with nix-tree] +See the https://diode.zone/w/8DBDQ6HQUe5UUdLkpDuL35[video] of Spectrum live +image interactive analysis with nix-tree. diff --git a/Documentation/about/index.adoc b/Documentation/about/index.adoc new file mode 100644 index 0000000..6961b6a --- /dev/null +++ b/Documentation/about/index.adoc @@ -0,0 +1,32 @@ += About Spectrum +:description: Some words about Spectrum as the operating system, not a project. Highlights the differences between common Linux distributions and Spectrum. +:page-nav_order: 1 +:page-has_children: true + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Spectrum is a Linux-based system that uses the +https://github.com/NixOS/nix[Nix package manager] and +the https://github.com/NixOS/nixpkgs[Nix Packages collection] (Nixpkgs). + +This gives an actively-developed base with good +hardware support, powerful and optimised compartmentalization primitives in +https://www.linux-kvm.org/page/Main_Page[KVM], and the reproducible packaging +and configuration system that is important +for a maintainable compartmentalized system. + +== Why Spectrum + +* User data and applications are managed centrally while remaining isolated. +That means that the system can be backed up and managed as a whole, rather than +mixed up in several dozen VMs. + +* The host system and isolated environments are managed declaratively and +reproducibly using the Nix package manager. +This can save the user the burden of maintaining many different virtual +computers, allowing finer-grained resource access controls and making it +possible to verify the software running across all environments. + +TIP: If you are interested in why we do something _this_ way instead of _that_ +way, see xref:../decisions/index.adoc[Architecture Decision Records]. diff --git a/Documentation/appendices/index.adoc b/Documentation/appendices/index.adoc new file mode 100644 index 0000000..ebacda7 --- /dev/null +++ b/Documentation/appendices/index.adoc @@ -0,0 +1,13 @@ += Appendices +:description: Additional information. +:page-nav_order: 5 +:page-has_children: true +:page-has_toc: false + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +This section provides additional information on how to work with: + +* xref:../appendices/user-partition.adoc[user partition] +* xref:../appendices/uuid-reference.adoc[universally unique identifier (UUID)]. diff --git a/Documentation/appendices/user-partition.adoc b/Documentation/appendices/user-partition.adoc new file mode 100644 index 0000000..4121340 --- /dev/null +++ b/Documentation/appendices/user-partition.adoc @@ -0,0 +1,17 @@ += Appendix A. User Partition +:page-parent: Appendices +:page-nav_order: 1 + +// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +The Spectrum host system is immutable, so configuration and user data +lives on a separate partition. + +The host system discovers the user +partition by looking for the special partition type +`9293e1ff-cee4-4658-88be-898ec863944f`. + +This behavior can be overridden with the `ext` parameter on the host's kernel +command line, which works in a similar way to the standard Linux `root` +parameter. diff --git a/Documentation/uuid-reference.adoc b/Documentation/appendices/uuid-reference.adoc similarity index 96% rename from Documentation/uuid-reference.adoc rename to Documentation/appendices/uuid-reference.adoc index 4b0b481..146c068 100644 --- a/Documentation/uuid-reference.adoc +++ b/Documentation/appendices/uuid-reference.adoc @@ -1,7 +1,7 @@ -= UUID Reference -:page-parent: Reference -:toc: preamble += Appendix B. UUID +:page-parent: Appendices :toclevels: 1 +:page-nav_order: 2 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -40,7 +40,7 @@ xref:user-partition.adoc[Spectrum user partition]. === `56a3bbc3-aefa-43d9-a64d-7b3fd59bbc4e` -https://github.com/endlessm/eos-installer["eosimages"] partition on the +https://github.com/endlessm/eos-installer["eosimages"] partition on the Spectrum combined live system / installer image. == Combined Image Partition IDs diff --git a/Documentation/building-documentation.adoc b/Documentation/building-documentation.adoc deleted file mode 100644 index b491105..0000000 --- a/Documentation/building-documentation.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= Building the Documentation -:page-parent: Tutorials - -// SPDX-FileCopyrightText: 2022 Unikie -// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 - -This tutorial assumes that you have https://nixos.org/[Nix] installed. -You may also want to xref:binary-cache.adoc[configure the Spectrum -binary cache], to avoid having to wait for dependencies to compile on -your local system. - -1. Get a copy of the Spectrum source code: -+ -[source,shell] ----- -git clone https://spectrum-os.org/git/spectrum ----- -2. Enter the documentation directory: -+ -[source,shell] ----- -cd spectrum/Documentation ----- -3. Enter the development environment: -+ -[source,shell] ----- -nix-shell -I nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz ----- -4. In the development shell, do an initial build of the documentation -site: -+ -[source,shell] ----- -scripts/build.sh ----- -5. Run a development server for previewing changes locally: -+ -[source,shell] ----- -jekyll serve ----- -+ -This will serve a local copy of the documentation at http://localhost:4000/. -+ -IMPORTANT: Jekyll doesn't handle rendering of the draw.io diagrams, so -if you modify any of those, or add new ones, you'll have to run -`scripts/build.sh` again to do a full rebuild of the site. - -Once you've made your changes to the documentation, see -xref:first-patch.adoc[Sending Your First Patch] for information -about how to submit them for review. diff --git a/Documentation/decisions/001-host-update-mechanism.adoc b/Documentation/decisions/001-host-update-mechanism.adoc index 574deb4..39f9f28 100644 --- a/Documentation/decisions/001-host-update-mechanism.adoc +++ b/Documentation/decisions/001-host-update-mechanism.adoc @@ -1,6 +1,6 @@ = 001 Host Update Mechanism :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -11,7 +11,7 @@ Proposed == Context -Spectrum currently has no implementation for software update. The host -- +Spectrum currently has no implementation for software update. The host -- consisting of the Linux kernel, KVM, cloud-hypervisor and minimal user space tools -- will require software updates to support feature development and security fixes. diff --git a/Documentation/decisions/002-install-options.adoc b/Documentation/decisions/002-install-options.adoc index 4412b53..4a745eb 100644 --- a/Documentation/decisions/002-install-options.adoc +++ b/Documentation/decisions/002-install-options.adoc @@ -1,6 +1,6 @@ -= 002 Install options += 002 Install Options :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/003-partitioning.adoc b/Documentation/decisions/003-partitioning.adoc index 8494ea4..a13b8cc 100644 --- a/Documentation/decisions/003-partitioning.adoc +++ b/Documentation/decisions/003-partitioning.adoc @@ -1,6 +1,6 @@ = 003 Partitioning :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/004-data-at-rest-encryption.adoc b/Documentation/decisions/004-data-at-rest-encryption.adoc index 26fe273..5b0f518 100644 --- a/Documentation/decisions/004-data-at-rest-encryption.adoc +++ b/Documentation/decisions/004-data-at-rest-encryption.adoc @@ -1,6 +1,6 @@ = 004 Data at Rest Encryption :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -20,5 +20,5 @@ User data is encrypted. == Consequences Spectrum needs to come with enough software to get the encryption key -via different methods (password, usb, fido, etc.) Can we use dm-crypt +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-monitor.adoc b/Documentation/decisions/005-virtual-machine-monitor.adoc index db81c72..df1b501 100644 --- a/Documentation/decisions/005-virtual-machine-monitor.adoc +++ b/Documentation/decisions/005-virtual-machine-monitor.adoc @@ -1,6 +1,6 @@ = 005 Virtual Machine Monitor :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/006-drivers-on-host.adoc b/Documentation/decisions/006-drivers-on-host.adoc index 872044e..b92d863 100644 --- a/Documentation/decisions/006-drivers-on-host.adoc +++ b/Documentation/decisions/006-drivers-on-host.adoc @@ -1,6 +1,6 @@ = 006 Drivers on Host :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/007-usb-virtual-machines.adoc b/Documentation/decisions/007-usb-virtual-machines.adoc index 3bdf78b..d832691 100644 --- a/Documentation/decisions/007-usb-virtual-machines.adoc +++ b/Documentation/decisions/007-usb-virtual-machines.adoc @@ -1,6 +1,6 @@ = 007 USB Virtual Machine :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc b/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc index a1b7d49..c1e5b87 100644 --- a/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc +++ b/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc @@ -1,6 +1,6 @@ = 008 Inter-VM Communication Mechanisms :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/index.adoc b/Documentation/decisions/index.adoc index 772f382..a022239 100644 --- a/Documentation/decisions/index.adoc +++ b/Documentation/decisions/index.adoc @@ -1,6 +1,6 @@ = Architecture Decision Records :page-has_children: true -:page-parent: Explanation +:page-parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/b4.adoc b/Documentation/development/b4.adoc similarity index 91% rename from Documentation/b4.adoc rename to Documentation/development/b4.adoc index 489ced4..5f141e9 100644 --- a/Documentation/b4.adoc +++ b/Documentation/development/b4.adoc @@ -1,5 +1,7 @@ = Installing and Configuring b4 -:page-parent: Tutorials +:page-parent: Working with Patches +:page-grand_parent: Development +:page-nav_order: 1 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-FileCopyrightText: 2022 Unikie @@ -19,7 +21,7 @@ of the Spectrum root's nix-shell. You should be able to install b4 from your package manager. -Using Nix, you can start a shell with b4 available by running +Using Nix, you can start a shell with b4 available by running: [listing] [source,shell] diff --git a/Documentation/build-configuration.adoc b/Documentation/development/build-configuration.adoc similarity index 73% rename from Documentation/build-configuration.adoc rename to Documentation/development/build-configuration.adoc index b89575f..c9a8c99 100644 --- a/Documentation/build-configuration.adoc +++ b/Documentation/development/build-configuration.adoc @@ -1,19 +1,22 @@ = Configuring the Build -:page-parent: How-to Guides +:page-parent: Development +:page-nav_order: 1 :example-caption: Test // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 Some aspects of a Spectrum build can be customised using a build -configuration file. By default, this configuration file should be -called config.nix and located in the root of the Spectrum source tree, -but this can be overridden by setting `spectrum-config` in the +configuration file. + +By default, this configuration file should be called config.nix and located in +the root of the Spectrum source tree, but this can be overridden by setting +`spectrum-config` in the https://nixos.org/manual/nix/stable/command-ref/env-common.html#env-NIX_PAT… to the path of the configuration file. The configuration file should contain an attribute set. The only -currently allowed attribute name is `pkgs`, which allows using a +currently allowed attribute name is `pkgs`. It allows using a custom Nixpkgs to evaluate Spectrum. .config.nix to build Spectrum with a https://nixos.org/manual/nixpkgs/unstable/#sec-overlays-definition[Nixpkgs overlay] diff --git a/Documentation/development/building-documentation.adoc b/Documentation/development/building-documentation.adoc new file mode 100644 index 0000000..4f464f5 --- /dev/null +++ b/Documentation/development/building-documentation.adoc @@ -0,0 +1,52 @@ += Building Documentation +:page-parent: Development +:page-nav_order: 5 + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Make sure you have https://nixos.org/download.html[Nix] installed. +You may also want to xref:../installation/binary-cache.adoc[configure the Spectrum +binary cache], to avoid having to wait for dependencies to compile on +your local system. + +. Get a copy of the Spectrum source code: ++ +[source,shell] +---- +git clone https://spectrum-os.org/git/spectrum +---- +. Enter the documentation directory: ++ +[source,shell] +---- +cd spectrum/Documentation +---- +. Enter the development environment: ++ +[source,shell] +---- +nix-shell -I nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz +---- +. In the development shell, do an initial build of the documentation +site: ++ +[source,shell] +---- +scripts/build.sh +---- +. Run a development server for previewing changes locally: ++ +[source,shell] +---- +jekyll serve +---- ++ +This will serve a local copy of the documentation at http://localhost:4000/. ++ +IMPORTANT: Jekyll does not handle rendering of the draw.io diagrams. If you +modify any of those, or add new ones, run `scripts/build.sh` again to do a full +rebuild of the site. + +After making changes to the documentation, see how to +xref:first-patch.adoc[send your patch] and submit the changes for review. diff --git a/Documentation/debugging.adoc b/Documentation/development/debugging.adoc similarity index 79% rename from Documentation/debugging.adoc rename to Documentation/development/debugging.adoc index 3871a7c..f1bbf01 100644 --- a/Documentation/debugging.adoc +++ b/Documentation/development/debugging.adoc @@ -1,7 +1,6 @@ -= Debugging Spectrum -:page-parent: Explanation -:toc: -:toclevels: 1 += Debugging +:page-parent: Development +:page-nav_order: 4 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -9,8 +8,9 @@ == Extracting core dumps when running Spectrum in a VM When using a VM to run the Spectrum host system, a special mechanism -is available to enable easy introspection of core files. When a -program on the Spectrum host system dumps core, the system will +is available to enable easy introspection of core files. + +When a program on the Spectrum host system dumps core, the system will attempt to upload the core file to _its_ host (i.e. the system running Spectrum in a VM) using the vsock(7) protocol, on port 1129271877. diff --git a/Documentation/first-patch.adoc b/Documentation/development/first-patch.adoc similarity index 80% rename from Documentation/first-patch.adoc rename to Documentation/development/first-patch.adoc index 30672b9..aa6ebee 100644 --- a/Documentation/first-patch.adoc +++ b/Documentation/development/first-patch.adoc @@ -1,11 +1,11 @@ -= Sending Your First Patch -:page-parent: Tutorials += Sending Your Patch +:page-parent: Working with Patches +:page-grand_parent: Development +:page-nav_order: 1 // 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. @@ -14,19 +14,18 @@ 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 +== Making Changes -If you've worked on any git repository before, the process for making -your changes will probably be very familiar. +The process of making changes is similar to working on any git repository. -1. Create a branch for your changes: +. Create a branch for your changes: + [source,shell] ---- git checkout -b fix-docs # for example ---- -2. Make changes in your editor. -3. Stage and commit your changes: +. Make changes in your editor. +. Stage and commit your changes: + [source,shell] ---- @@ -39,7 +38,7 @@ 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 +== Submitting Changes Once you're happy with how the commits on your branch look, run: @@ -64,13 +63,14 @@ message that will be sent before all of your patches. 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 +patch. You can respond to feedback in your mail client. + +Use the *Reply All* button to sent your messages 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, +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: +your patch(es) and then submit it like this: [source,shell] ---- @@ -81,7 +81,7 @@ 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 +If you would 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. diff --git a/Documentation/development/index.adoc b/Documentation/development/index.adoc new file mode 100644 index 0000000..1fccdd5 --- /dev/null +++ b/Documentation/development/index.adoc @@ -0,0 +1,27 @@ += Development +:description: Development progress, general development practices +:page-nav_order: 4 +:page-has_children: true + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Spectrum is free software, currently under active development. + + +== Developer Setup + +* https://git.kernel.org/pub/scm/utils/b4/b4.git/about/[b4] +* https://nixos.org/manual/nix/stable/introduction.html[Nix package manager] +* https://docs.asciidoctor.org/[AsciiDoc] for writing the documentation + + +== Mailing Lists + +The Spectrum project runs several +https://spectrum-os.org/participating.html#mailing-lists[mailing lists] on +which you can ask your questions or help other people with the questions they +have. All the Spectrum developers as well as many long time Linux and Spectrum users are on the lists. + +For real-time feedback, use +https://spectrum-os.org/participating.html#irc[IRC/Matrix channel]. diff --git a/Documentation/replying.adoc b/Documentation/development/replying.adoc similarity index 68% rename from Documentation/replying.adoc rename to Documentation/development/replying.adoc index bb8e31a..a1ad394 100644 --- a/Documentation/replying.adoc +++ b/Documentation/development/replying.adoc @@ -1,5 +1,7 @@ = Replying to Messages in the Mailing List Archives -:page-parent: Tutorials +:page-parent: Working with Patches +:page-grand_parent: Development +:page-nav_order: 3 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -9,14 +11,13 @@ https://spectrum-os.org/participating.html#mailing-lists[mailing lists]. Make sure to Reply All when replying to messages, so that the message -is sent to the mailing list and not just to the person you're -replying to. +is sent to the mailing list and not just to the person you reply to. == Getting a copy of a message -You may want to reply to a mailing list message that you don't have a -copy of in your mail client, because you aren't subscribed to the -list, or because you subscribed after the message was sent. +You may want to reply to a mailing list message that you do not have a +copy of in your mail client, because you are not subscribed to the +list or because you subscribed after the message was sent. To do this, find the message you want to reply to in the https://spectrum-os.org/lists/archives[public-inbox list archives], diff --git a/Documentation/reviewing-patches.adoc b/Documentation/development/reviewing-patches.adoc similarity index 88% rename from Documentation/reviewing-patches.adoc rename to Documentation/development/reviewing-patches.adoc index 63ff24e..ba47f25 100644 --- a/Documentation/reviewing-patches.adoc +++ b/Documentation/development/reviewing-patches.adoc @@ -1,5 +1,7 @@ = Reviewing Patches -:page-parent: How-to Guides +:page-parent: Working with Patches +:page-grand_parent: Development +:page-nav_order: 2 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/testing-patches.adoc b/Documentation/development/testing-patches.adoc similarity index 82% rename from Documentation/testing-patches.adoc rename to Documentation/development/testing-patches.adoc index 743cd6e..0c72c93 100644 --- a/Documentation/testing-patches.adoc +++ b/Documentation/development/testing-patches.adoc @@ -1,5 +1,7 @@ = Testing Patches -:page-parent: How-to Guides +:page-parent: Working with Patches +:page-grand_parent: Development +:page-nav_order: 2 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-FileCopyrightText: 2022 Unikie @@ -9,7 +11,7 @@ Potential changes to Spectrum are posted to and discussed on the https://spectrum-os.org/participating.html#spectrum-devel[devel@spectrum-os… mailing list. -== Apply the patch +== Apply Patch . Find the patch series you want to test on https://spectrum-os.org/lists/archives/spectrum-devel/[public-inbox]. @@ -33,15 +35,15 @@ of the Spectrum root's nix-shell, which allows you to skip this step. ---- b4 am 20220511092352.70E54C980(a)atuin.qyliss.net ---- - -. b4 will indicate the file name it has downloaded the patches into - with a line like: +b4 will indicate the file name it has downloaded the patches into with a line +like: + [example] [listing] +---- Writing ./20220424_hi_host_rootfs_fix_weston_hotplugging.mbx -+ -Run `git am` on that file to apply the patches, for example: +---- +. Run `git am` on that file to apply the patches. For example: + [example] [source,shell] @@ -49,14 +51,12 @@ Run `git am` on that file to apply the patches, for example: git am 20220424_hi_host_rootfs_fix_weston_hotplugging.mbx ---- -== Post your test results +== Post Your Results -When you've tested a patch, it's really helpful to +When you tested a patch, it is helpful to xref:replying.adoc[reply] with your test results. -If the patch worked for you, please reply to it and include a line -like the following, separated from any reply text: - +If the patch worked for you, please reply to it and include a line like the following, separated from any reply text: ---- Tested-by: John Smith <john(a)example.com> ---- @@ -66,10 +66,10 @@ patch replies will be automatically included in the commit message when a patch is applied. It's also helpful to explain in your reply how you tested the patch, -but you don't have to if it's obvious. (For example, if a patch is +but you don't have to if it's obvious. For example, if a patch is supposed to fix a bug, and you verified that after applying the patch the bug is fixed, just the Tested-by line on its own is enough to -indicate that.) +indicate that. If you found an issue with the patch, do not include a Tested-by line, and instead reply to the patch explaining what you tested, what you diff --git a/Documentation/development/working-with-patches.adoc b/Documentation/development/working-with-patches.adoc new file mode 100644 index 0000000..a2694ed --- /dev/null +++ b/Documentation/development/working-with-patches.adoc @@ -0,0 +1,12 @@ += Working with Patches +:page-parent: Development +:page-nav_order: 3 +:page-has_children: true + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Patches are the way for contributors to submit code to the Spectrum project. + +Make sure to xref:../development/b4.adoc[install and configure the b4 utility] +for applying and testing other people's patches. diff --git a/Documentation/explanation.adoc b/Documentation/explanation.adoc deleted file mode 100644 index b39cc6d..0000000 --- a/Documentation/explanation.adoc +++ /dev/null @@ -1,6 +0,0 @@ -= Explanation -:page-has_children: true -:page-nav_order: 4 - -// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> -// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/creating-vms.adoc b/Documentation/getting-started/creating-vms.adoc similarity index 98% rename from Documentation/creating-vms.adoc rename to Documentation/getting-started/creating-vms.adoc index d967098..725316c 100644 --- a/Documentation/creating-vms.adoc +++ b/Documentation/getting-started/creating-vms.adoc @@ -1,5 +1,6 @@ = Creating VMs -:page-parent: Reference +:page-parent: Getting Started +:page-nav_order: 1 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/getting-started/index.adoc b/Documentation/getting-started/index.adoc new file mode 100644 index 0000000..10dde7f --- /dev/null +++ b/Documentation/getting-started/index.adoc @@ -0,0 +1,13 @@ += Getting Started +:description: Exploring Spectrum OS. Using (=How-To-Guides), Configuring (adding smth). +:page-nav_order: 3 +:page-has_children: true +:page-has_toc: false + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Ready to get started with Spectrum? Here is what you can do next: + +* xref:../getting-started/creating-vms.adoc[Create your own VM] to use others applications. +* xref:../getting-started/running-vms.adoc[Start some applications]. diff --git a/Documentation/running-vms.adoc b/Documentation/getting-started/running-vms.adoc similarity index 90% rename from Documentation/running-vms.adoc rename to Documentation/getting-started/running-vms.adoc index d0d3f99..ca70835 100644 --- a/Documentation/running-vms.adoc +++ b/Documentation/getting-started/running-vms.adoc @@ -1,5 +1,6 @@ = Running VMs -:page-parent: Reference +:page-parent: Getting Started +:page-nav_order: 2 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/how-to.adoc b/Documentation/how-to.adoc deleted file mode 100644 index f43fa13..0000000 --- a/Documentation/how-to.adoc +++ /dev/null @@ -1,6 +0,0 @@ -= How-to Guides -:page-has_children: true -:page-nav_order: 2 - -// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> -// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/index.adoc b/Documentation/index.adoc index 3079847..e0a45c7 100644 --- a/Documentation/index.adoc +++ b/Documentation/index.adoc @@ -1,13 +1,32 @@ -= Spectrum Docs += Spectrum Documentation :page-nav_exclude: true // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> +// SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 -Spectrum is a compartmentalized operating system. -If you'd like to try Spectrum, see xref:getting-spectrum.adoc[Getting -Spectrum]. +Spectrum is an open-source project that aims to create a computer operating +system, based on the principle of security by compartmentalization, that has a +lower barrier to entry and is easy to use and maintain. + +== Using Spectrum To learn about what Spectrum is and how it's implemented, start with -the xref:architecture.adoc[architecture overview]. +the xref:about/architecture.adoc[architecture overview]. + +If you want to try Spectrum, see xref:../installation/index.adoc[Build and Run] + to setup a development environment. + + +== Developing and Contributing + +Spectrum is made of free and open-source software. It is free for anyone to + use, modify, and distribute. + +Once you are up and running, see + xref:../development/index.adoc[Development] to understand how to work with + Spectrum's code and participate in the collaborative development process. + +If you are thinking of contributing to Spectrum docs, see + xref:../development/building-documentation.adoc[Building Documentation]. diff --git a/Documentation/binary-cache.adoc b/Documentation/installation/binary-cache.adoc similarity index 74% rename from Documentation/binary-cache.adoc rename to Documentation/installation/binary-cache.adoc index 6e69b39..ab53666 100644 --- a/Documentation/binary-cache.adoc +++ b/Documentation/installation/binary-cache.adoc @@ -1,5 +1,6 @@ -= Setting Up the Binary Cache -:page-parent: How-to Guides += Setting Up Binary Cache +:page-parent: Build and Run +:page-nav_order: 1 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -20,10 +21,9 @@ encounter any trouble with it. The binary cache is currently not able to provide logs, due to a https://github.com/NixOS/nix/pull/6051[Nix bug]. -== On NixOS +== For NixOS -The following configuration adds the Spectrum binary cache as a -substituter, and tells Nix to trust builds signed with its public key. +Add the following configuration to /etc/nixos/configuration.nix: [source,nix] ---- @@ -38,7 +38,13 @@ substituter, and tells Nix to trust builds signed with its public key. } ---- -== On Non-NixOS systems +This configuration adds the Spectrum binary cache as a substituter and makes +Nix trust builds signed with its public key. + +To apply changes, rebuild your system with the https://nixos.wiki/wiki/Nixos-rebuild[nixos-rebuild] command. + + +== For Non-NixOS Systems Add the following configuration to /etc/nix/nix.conf: @@ -48,6 +54,10 @@ substituters = https://cache.dataaturservice.se/spectrum/ https://cache.nixos.or trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= spectrum-os.org-1:rnnSumz3+Dbs5uewPlwZSTP0k3g/5SRG4hD7Wbr9YuQ= ---- +Run `systemctl restart nix-daemon.service` after making any changes in the Nix +configuration. After that the binary cache will be used automatically when +`nix-build` is run. + If you have other binary caches configured besides cache.nixos.org, make sure to add the Spectrum cache URL and public key to the existing configuration lines in your nix.conf file. diff --git a/Documentation/getting-spectrum.adoc b/Documentation/installation/getting-spectrum.adoc similarity index 79% rename from Documentation/getting-spectrum.adoc rename to Documentation/installation/getting-spectrum.adoc index b422a94..392cab5 100644 --- a/Documentation/getting-spectrum.adoc +++ b/Documentation/installation/getting-spectrum.adoc @@ -1,5 +1,6 @@ = Getting Spectrum -:page-parent: Tutorials +:page-parent: Build and Run +:page-nav_order: 2 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -8,7 +9,7 @@ To get Spectrum, you need to build it from source. As long as you're running Linuxfootnote:[Building from other operating systems might work, but hasn't been tested. Patches are welcome to support building from other operating systems, as long as they're not too invasive.] -and have https://nixos.org/[Nix] and https://git-scm.com/[git] +and have https://nixos.org/download.html[Nix] and https://git-scm.com/[git] installed, it's very easy to do. TIP: Before you start, consider setting up the @@ -34,7 +35,7 @@ nix-shell -I nixpkgs=../../../nixpkgs-spectrum --run 'make run' This builds just enough of Spectrum to try it out in a VM, but it will still take a very long time. -== Building an installer +== Building Installer [source,shell] ---- @@ -47,8 +48,7 @@ If you haven't set up the xref:binary-cache.adoc[binary cache], this will take a very long time. When it's done, a symbolic link named "result" will appear, pointing to a Spectrum USB installer image. -CAUTION: Spectrum is not yet suitable for real-world use. Do not use -your Spectrum system for anything important or sensitive. Spectrum is -currently missing many important security properties, and there is no -procedure for updating to new versions of Spectrum -- you have to -reinstall. +CAUTION: Do not use Spectrum for anything important or sensitive as it is not +yet suitable for real-world use. Many important security properties are +currently missing, and there is no procedure for updating to +new versions—you have to reinstall the OS. diff --git a/Documentation/installation/index.adoc b/Documentation/installation/index.adoc new file mode 100644 index 0000000..d67c88d --- /dev/null +++ b/Documentation/installation/index.adoc @@ -0,0 +1,23 @@ += Build and Run +:description: How to download and install Spectrum OS. +:page-nav_order: 2 +:page-has_children: true +:page-has_toc: false + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + + +To start working with Spectrum, you need: + +* xref:../installation/binary-cache.adoc[Set up the binary cache] to speed up the build process. +* xref:../installation/getting-spectrum.adoc[Build Spectrum] from the source. + +TIP: At this stage, Spectrum works only on x86-64. AArch64 support is in +development. + +== Uninstalling and Updating + +Currently, there is no implementation for a software update. + +You can replace Spectrum by installing another OS. diff --git a/Documentation/reference.adoc b/Documentation/reference.adoc deleted file mode 100644 index 44b359d..0000000 --- a/Documentation/reference.adoc +++ /dev/null @@ -1,6 +0,0 @@ -= Reference -:page-has_children: true -:page-nav_order: 3 - -// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> -// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/tutorials.adoc b/Documentation/tutorials.adoc deleted file mode 100644 index cd1fb12..0000000 --- a/Documentation/tutorials.adoc +++ /dev/null @@ -1,6 +0,0 @@ -= Tutorials -:page-nav_order: 1 -:page-has_children: true - -// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> -// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/user-partition.adoc b/Documentation/user-partition.adoc deleted file mode 100644 index 73bc0d0..0000000 --- a/Documentation/user-partition.adoc +++ /dev/null @@ -1,12 +0,0 @@ -= The User Partition -:page-parent: Explanation - -// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> -// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 - -The Spectrum host system is immutable, so configuration and user data -lives on a separate partition. The host system discovers the user -partition by looking for the special partition type -`9293e1ff-cee4-4658-88be-898ec863944f`. This behavior can be -overridden with the `ext` parameter on the host's kernel command line, -which works in a similar way to the standard Linux `root` parameter. -- 2.34.1

2 2

[PATCH] Docs: new structure
by Jenni Nikolaenko 08 Nov '22

08 Nov '22

Create separate folders for new parent pages, update Introduction page, remove a and the articles from titles, quick check text for simple english Signed-off-by: Jenni Nikolaenko <evgeniia.nikolaenko(a)unikie.com> --- Documentation/{ => about}/architecture.adoc | 20 ++++--- Documentation/about/index.adoc | 30 +++++++++++ Documentation/building-documentation.adoc | 52 ------------------ .../decisions/001-host-update-mechanism.adoc | 4 +- .../decisions/002-install-options.adoc | 4 +- Documentation/decisions/003-partitioning.adoc | 2 +- .../004-data-at-rest-encryption.adoc | 4 +- .../005-virtual-machine-monitor.adoc | 2 +- .../decisions/006-drivers-on-host.adoc | 2 +- .../decisions/007-usb-virtual-machines.adoc | 2 +- ...008-inter-vm-communication-mechanisms.adoc | 2 +- Documentation/decisions/index.adoc | 2 +- .../build-configuration.adoc | 13 +++-- .../development/building-documentation.adoc | 53 +++++++++++++++++++ .../{ => development}/debugging.adoc | 12 ++--- .../{ => development}/first-patch.adoc | 32 +++++------ Documentation/development/index.adoc | 31 +++++++++++ Documentation/{ => development}/replying.adoc | 13 ++--- .../{ => development}/reviewing-patches.adoc | 4 +- .../{ => development}/testing-patches.adoc | 34 ++++++------ .../{ => development}/uuid-reference.adoc | 5 +- Documentation/explanation.adoc | 3 +- .../{ => getting-started}/creating-vms.adoc | 2 +- Documentation/getting-started/index.adoc | 14 +++++ .../{ => getting-started}/running-vms.adoc | 2 +- .../getting-started/user-partition.adoc | 16 ++++++ Documentation/how-to.adoc | 1 + Documentation/index.adoc | 29 ++++++++-- Documentation/{ => installation}/b4.adoc | 5 +- .../{ => installation}/binary-cache.adoc | 18 ++++--- .../{ => installation}/getting-spectrum.adoc | 14 ++--- Documentation/installation/index.adoc | 26 +++++++++ Documentation/reference.adoc | 3 +- Documentation/tutorials.adoc | 3 +- Documentation/user-partition.adoc | 12 ----- 35 files changed, 302 insertions(+), 169 deletions(-) rename Documentation/{ => about}/architecture.adoc (84%) create mode 100644 Documentation/about/index.adoc delete mode 100644 Documentation/building-documentation.adoc rename Documentation/{ => development}/build-configuration.adoc (73%) create mode 100644 Documentation/development/building-documentation.adoc rename Documentation/{ => development}/debugging.adoc (79%) rename Documentation/{ => development}/first-patch.adoc (80%) create mode 100644 Documentation/development/index.adoc rename Documentation/{ => development}/replying.adoc (68%) rename Documentation/{ => development}/reviewing-patches.adoc (88%) rename Documentation/{ => development}/testing-patches.adoc (81%) rename Documentation/{ => development}/uuid-reference.adoc (97%) rename Documentation/{ => getting-started}/creating-vms.adoc (98%) create mode 100644 Documentation/getting-started/index.adoc rename Documentation/{ => getting-started}/running-vms.adoc (93%) create mode 100644 Documentation/getting-started/user-partition.adoc rename Documentation/{ => installation}/b4.adoc (93%) rename Documentation/{ => installation}/binary-cache.adoc (80%) rename Documentation/{ => installation}/getting-spectrum.adoc (82%) create mode 100644 Documentation/installation/index.adoc delete mode 100644 Documentation/user-partition.adoc diff --git a/Documentation/architecture.adoc b/Documentation/about/architecture.adoc similarity index 84% rename from Documentation/architecture.adoc rename to Documentation/about/architecture.adoc index 1c4307b..c1af320 100644 --- a/Documentation/architecture.adoc +++ b/Documentation/about/architecture.adoc @@ -1,17 +1,15 @@ = Architecture -:page-parent: Explanation +:page-parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 -== Introduction +Spectrum is based on the principle of security by compartmentalization. -Spectrum is based on the principle of security by -compartmentalization. The high level stack is illustrated in the -following diagram: +The high level stack is illustrated in the following diagram: -image::diagrams/stack.svg[] +image::../diagrams/stack.svg[] The default set of virtual machines includes two application VMs, _appvm-catgirl_ (an IRC client) and _appvm-lynx_ (a text-based web @@ -26,7 +24,7 @@ https://en.wikipedia.org/wiki/Architectural_decision[Architecturally significant decisions] are xref:decisions/index.adoc[recorded] as lightweight https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions/[A…. -== The Spectrum host system +== Spectrum Host System Compartmentalization is implemented using https://cloud-hypervisor.org/[cloud-hypervisor] virtual machines. @@ -35,7 +33,7 @@ https://en.wikipedia.org/wiki/Kernel-based_Virtual_Machine[Kernel-based Virtual Machine] (KVM) to provide lightweight, hardware-accelerated VMs. While Linux (including KVM) is portable between many hardware architectures, -cloud-hypervisor supports only x86_64 and aarch64. Spectrum currently only +cloud-hypervisor supports only x86_64 and aarch64. Spectrum currently only works on x86_64, but aarch64 support is in development. https://skarnet.org/software/s6-rc/overview.html[s6-rc] is used for service @@ -44,7 +42,7 @@ and service scripts. https://wayland.freedesktop.org/[Wayland] is used for window management and display. The Wayland architecture is well documented -https://wayland.freedesktop.org/architecture.html[here]. The host provides only +https://wayland.freedesktop.org/architecture.html[here]. The host provides only a Wayland terminal client, https://codeberg.org/dnkl/foot/[foot], which is used for interacting with VM consoles. In future it will be possible for application VMs to display windows on the single Wayland compositor on the host system, @@ -57,7 +55,7 @@ https://www.etalabs.net/compare_libcs.html[added safety on resource exhaustion and security hardening on memory allocation]. Kernel hardening will be investigated in future. -== Exploring the Spectrum dependency tree +== Spectrum Dependency Tree For a detailed, interactive view of dependencies, use https://github.com/utdemir/nix-tree[nix-tree] in the Spectrum repository: @@ -67,4 +65,4 @@ https://github.com/utdemir/nix-tree[nix-tree] in the Spectrum repository: nix-build img/live -I nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz --no-out-link | xargs -o nix-tree https://diode.zone/w/8DBDQ6HQUe5UUdLkpDuL35[See video of Spectrum live image -interactive analysis with nix-tree] +interactive analysis with nix-tree]. diff --git a/Documentation/about/index.adoc b/Documentation/about/index.adoc new file mode 100644 index 0000000..9e2a47e --- /dev/null +++ b/Documentation/about/index.adoc @@ -0,0 +1,30 @@ += About Spectrum +:description: Some words about Spectrum as the operating system, not a project. Highlights the differences between common Linux distributions and Spectrum. +:page-nav_order: 1 +:page-has_children: true + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Spectrum is a Linux-based system that uses Nix package manager and Nixpkgs +collection of packages. + +This gives an actively-developed base with good +hardware support, powerful and optimised compartmentalization primitives in +KVM, and the reproducible packaging and configuration system that is important +for a maintainable compartmentalized system. + +== Why Spectrum + +* User data and applications are managed centrally while remaining isolated. +That means that the system can be backed up and managed as a whole, rather than +mixed up in several dozen VMs. + +* The host system and isolated environments are managed declaratively and +reproducibly using the Nix package manager. +This can save the user the burden of maintaining many different virtual +computers, allowing finer-grained resource access controls and making it +possible to verify the software running across all environments. + +TIP: If you are interested in why we do something _this_ way instead of _that_ +way, see xref:../decisions/index.adoc[Architecture Decision Records]. diff --git a/Documentation/building-documentation.adoc b/Documentation/building-documentation.adoc deleted file mode 100644 index b491105..0000000 --- a/Documentation/building-documentation.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= Building the Documentation -:page-parent: Tutorials - -// SPDX-FileCopyrightText: 2022 Unikie -// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 - -This tutorial assumes that you have https://nixos.org/[Nix] installed. -You may also want to xref:binary-cache.adoc[configure the Spectrum -binary cache], to avoid having to wait for dependencies to compile on -your local system. - -1. Get a copy of the Spectrum source code: -+ -[source,shell] ----- -git clone https://spectrum-os.org/git/spectrum ----- -2. Enter the documentation directory: -+ -[source,shell] ----- -cd spectrum/Documentation ----- -3. Enter the development environment: -+ -[source,shell] ----- -nix-shell -I nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz ----- -4. In the development shell, do an initial build of the documentation -site: -+ -[source,shell] ----- -scripts/build.sh ----- -5. Run a development server for previewing changes locally: -+ -[source,shell] ----- -jekyll serve ----- -+ -This will serve a local copy of the documentation at http://localhost:4000/. -+ -IMPORTANT: Jekyll doesn't handle rendering of the draw.io diagrams, so -if you modify any of those, or add new ones, you'll have to run -`scripts/build.sh` again to do a full rebuild of the site. - -Once you've made your changes to the documentation, see -xref:first-patch.adoc[Sending Your First Patch] for information -about how to submit them for review. diff --git a/Documentation/decisions/001-host-update-mechanism.adoc b/Documentation/decisions/001-host-update-mechanism.adoc index 574deb4..39f9f28 100644 --- a/Documentation/decisions/001-host-update-mechanism.adoc +++ b/Documentation/decisions/001-host-update-mechanism.adoc @@ -1,6 +1,6 @@ = 001 Host Update Mechanism :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -11,7 +11,7 @@ Proposed == Context -Spectrum currently has no implementation for software update. The host -- +Spectrum currently has no implementation for software update. The host -- consisting of the Linux kernel, KVM, cloud-hypervisor and minimal user space tools -- will require software updates to support feature development and security fixes. diff --git a/Documentation/decisions/002-install-options.adoc b/Documentation/decisions/002-install-options.adoc index 4412b53..4a745eb 100644 --- a/Documentation/decisions/002-install-options.adoc +++ b/Documentation/decisions/002-install-options.adoc @@ -1,6 +1,6 @@ -= 002 Install options += 002 Install Options :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/003-partitioning.adoc b/Documentation/decisions/003-partitioning.adoc index 8494ea4..a13b8cc 100644 --- a/Documentation/decisions/003-partitioning.adoc +++ b/Documentation/decisions/003-partitioning.adoc @@ -1,6 +1,6 @@ = 003 Partitioning :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/004-data-at-rest-encryption.adoc b/Documentation/decisions/004-data-at-rest-encryption.adoc index 26fe273..5b0f518 100644 --- a/Documentation/decisions/004-data-at-rest-encryption.adoc +++ b/Documentation/decisions/004-data-at-rest-encryption.adoc @@ -1,6 +1,6 @@ = 004 Data at Rest Encryption :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -20,5 +20,5 @@ User data is encrypted. == Consequences Spectrum needs to come with enough software to get the encryption key -via different methods (password, usb, fido, etc.) Can we use dm-crypt +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-monitor.adoc b/Documentation/decisions/005-virtual-machine-monitor.adoc index db81c72..df1b501 100644 --- a/Documentation/decisions/005-virtual-machine-monitor.adoc +++ b/Documentation/decisions/005-virtual-machine-monitor.adoc @@ -1,6 +1,6 @@ = 005 Virtual Machine Monitor :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/006-drivers-on-host.adoc b/Documentation/decisions/006-drivers-on-host.adoc index 872044e..b92d863 100644 --- a/Documentation/decisions/006-drivers-on-host.adoc +++ b/Documentation/decisions/006-drivers-on-host.adoc @@ -1,6 +1,6 @@ = 006 Drivers on Host :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/007-usb-virtual-machines.adoc b/Documentation/decisions/007-usb-virtual-machines.adoc index 3bdf78b..d832691 100644 --- a/Documentation/decisions/007-usb-virtual-machines.adoc +++ b/Documentation/decisions/007-usb-virtual-machines.adoc @@ -1,6 +1,6 @@ = 007 USB Virtual Machine :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc b/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc index a1b7d49..c1e5b87 100644 --- a/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc +++ b/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc @@ -1,6 +1,6 @@ = 008 Inter-VM Communication Mechanisms :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/index.adoc b/Documentation/decisions/index.adoc index 772f382..a022239 100644 --- a/Documentation/decisions/index.adoc +++ b/Documentation/decisions/index.adoc @@ -1,6 +1,6 @@ = Architecture Decision Records :page-has_children: true -:page-parent: Explanation +:page-parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/build-configuration.adoc b/Documentation/development/build-configuration.adoc similarity index 73% rename from Documentation/build-configuration.adoc rename to Documentation/development/build-configuration.adoc index b89575f..c9a8c99 100644 --- a/Documentation/build-configuration.adoc +++ b/Documentation/development/build-configuration.adoc @@ -1,19 +1,22 @@ = Configuring the Build -:page-parent: How-to Guides +:page-parent: Development +:page-nav_order: 1 :example-caption: Test // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 Some aspects of a Spectrum build can be customised using a build -configuration file. By default, this configuration file should be -called config.nix and located in the root of the Spectrum source tree, -but this can be overridden by setting `spectrum-config` in the +configuration file. + +By default, this configuration file should be called config.nix and located in +the root of the Spectrum source tree, but this can be overridden by setting +`spectrum-config` in the https://nixos.org/manual/nix/stable/command-ref/env-common.html#env-NIX_PAT… to the path of the configuration file. The configuration file should contain an attribute set. The only -currently allowed attribute name is `pkgs`, which allows using a +currently allowed attribute name is `pkgs`. It allows using a custom Nixpkgs to evaluate Spectrum. .config.nix to build Spectrum with a https://nixos.org/manual/nixpkgs/unstable/#sec-overlays-definition[Nixpkgs overlay] diff --git a/Documentation/development/building-documentation.adoc b/Documentation/development/building-documentation.adoc new file mode 100644 index 0000000..d83c343 --- /dev/null +++ b/Documentation/development/building-documentation.adoc @@ -0,0 +1,53 @@ += Building Documentation +:page-parent: Development +:page-nav_order: 4 + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Make sure you have https://nixos.org/[Nix] installed. +You may also want to xref:binary-cache.adoc[configure the Spectrum +binary cache], to avoid having to wait for dependencies to compile on +your local system. + +. Get a copy of the Spectrum source code: ++ +[source,shell] +---- +git clone https://spectrum-os.org/git/spectrum +---- +. Enter the documentation directory: ++ +[source,shell] +---- +cd spectrum/Documentation +---- +. Enter the development environment: ++ +[source,shell] +---- +nix-shell -I nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz +---- +. In the development shell, do an initial build of the documentation +site: ++ +[source,shell] +---- +scripts/build.sh +---- +. Run a development server for previewing changes locally: ++ +[source,shell] +---- +jekyll serve +---- ++ +This will serve a local copy of the documentation at http://localhost:4000/. ++ +IMPORTANT: Jekyll does not handle rendering of the draw.io diagrams. If you +modify any of those, or add new ones, run `scripts/build.sh` again to do a full +rebuild of the site. + +After making changes to the documentation, see +xref:first-patch.adoc[Working with Patches] for information +on how to submit your changes for review. diff --git a/Documentation/debugging.adoc b/Documentation/development/debugging.adoc similarity index 79% rename from Documentation/debugging.adoc rename to Documentation/development/debugging.adoc index 3871a7c..d342294 100644 --- a/Documentation/debugging.adoc +++ b/Documentation/development/debugging.adoc @@ -1,7 +1,6 @@ -= Debugging Spectrum -:page-parent: Explanation -:toc: -:toclevels: 1 += Debugging +:page-parent: Development +:page-nav_order: 3 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -9,8 +8,9 @@ == Extracting core dumps when running Spectrum in a VM When using a VM to run the Spectrum host system, a special mechanism -is available to enable easy introspection of core files. When a -program on the Spectrum host system dumps core, the system will +is available to enable easy introspection of core files. + +When a program on the Spectrum host system dumps core, the system will attempt to upload the core file to _its_ host (i.e. the system running Spectrum in a VM) using the vsock(7) protocol, on port 1129271877. diff --git a/Documentation/first-patch.adoc b/Documentation/development/first-patch.adoc similarity index 80% rename from Documentation/first-patch.adoc rename to Documentation/development/first-patch.adoc index 30672b9..cf19b37 100644 --- a/Documentation/first-patch.adoc +++ b/Documentation/development/first-patch.adoc @@ -1,11 +1,11 @@ -= Sending Your First Patch -:page-parent: Tutorials += Working with Patches +:page-parent: Development +:page-nav_order: 1 +:page-has_children: true // 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. @@ -14,19 +14,18 @@ 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 +== Making Changes -If you've worked on any git repository before, the process for making -your changes will probably be very familiar. +The process of making changes is similar to working on any git repository. -1. Create a branch for your changes: +. Create a branch for your changes: + [source,shell] ---- git checkout -b fix-docs # for example ---- -2. Make changes in your editor. -3. Stage and commit your changes: +. Make changes in your editor. +. Stage and commit your changes: + [source,shell] ---- @@ -39,7 +38,7 @@ 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 +== Submitting Changes Once you're happy with how the commits on your branch look, run: @@ -64,13 +63,14 @@ message that will be sent before all of your patches. 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 +patch. You can respond to feedback in your mail client. + +Use the *Reply All* button to sent your messages 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, +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: +your patch(es) and then submit it like this: [source,shell] ---- @@ -81,7 +81,7 @@ 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 +If you would 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. diff --git a/Documentation/development/index.adoc b/Documentation/development/index.adoc new file mode 100644 index 0000000..1fe4d8b --- /dev/null +++ b/Documentation/development/index.adoc @@ -0,0 +1,31 @@ += Development +:description: Development progress, general development practices +:page-nav_order: 4 +:page-has_children: true + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Spectrum is free software, currently under active development. + +If you made changes in a source code, +https://spectrum-os.org/installation/getting-spectrum.html#building-an-installer[rebuild Spectrum], +xref:../development/testing-patches.adoc[test your patch] and +then https://spectrum-os.org/development/first-patch.html#submitting-changes[sub… your changes for review]. + +== Developer Setup + +Before starting, make sure you are familiar with +https://git.kernel.org/pub/scm/utils/b4/b4.git/about/[b4] and the +https://nixos.org/manual/nix/stable/introduction.html[Nix package manager]. + +== Mailing Lists + +The Spectrum project runs several +https://spectrum-os.org/mailman3/lists/?all-lists[mailing lists] on which you +can ask your questions or help other people with the questions they have. All +the Spectrum developers as well as many long time Linux and Spectrum users are +on the lists. + +For real-time feedback, use +https://spectrum-os.org/participating.html#irc[IRC/Matrix channel]. diff --git a/Documentation/replying.adoc b/Documentation/development/replying.adoc similarity index 68% rename from Documentation/replying.adoc rename to Documentation/development/replying.adoc index bb8e31a..a1ad394 100644 --- a/Documentation/replying.adoc +++ b/Documentation/development/replying.adoc @@ -1,5 +1,7 @@ = Replying to Messages in the Mailing List Archives -:page-parent: Tutorials +:page-parent: Working with Patches +:page-grand_parent: Development +:page-nav_order: 3 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -9,14 +11,13 @@ https://spectrum-os.org/participating.html#mailing-lists[mailing lists]. Make sure to Reply All when replying to messages, so that the message -is sent to the mailing list and not just to the person you're -replying to. +is sent to the mailing list and not just to the person you reply to. == Getting a copy of a message -You may want to reply to a mailing list message that you don't have a -copy of in your mail client, because you aren't subscribed to the -list, or because you subscribed after the message was sent. +You may want to reply to a mailing list message that you do not have a +copy of in your mail client, because you are not subscribed to the +list or because you subscribed after the message was sent. To do this, find the message you want to reply to in the https://spectrum-os.org/lists/archives[public-inbox list archives], diff --git a/Documentation/reviewing-patches.adoc b/Documentation/development/reviewing-patches.adoc similarity index 88% rename from Documentation/reviewing-patches.adoc rename to Documentation/development/reviewing-patches.adoc index 63ff24e..ba47f25 100644 --- a/Documentation/reviewing-patches.adoc +++ b/Documentation/development/reviewing-patches.adoc @@ -1,5 +1,7 @@ = Reviewing Patches -:page-parent: How-to Guides +:page-parent: Working with Patches +:page-grand_parent: Development +:page-nav_order: 2 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/testing-patches.adoc b/Documentation/development/testing-patches.adoc similarity index 81% rename from Documentation/testing-patches.adoc rename to Documentation/development/testing-patches.adoc index 743cd6e..600cf0f 100644 --- a/Documentation/testing-patches.adoc +++ b/Documentation/development/testing-patches.adoc @@ -1,5 +1,7 @@ = Testing Patches -:page-parent: How-to Guides +:page-parent: Working with Patches +:page-grand_parent: Development +:page-nav_order: 2 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-FileCopyrightText: 2022 Unikie @@ -9,7 +11,7 @@ Potential changes to Spectrum are posted to and discussed on the https://spectrum-os.org/participating.html#spectrum-devel[devel@spectrum-os… mailing list. -== Apply the patch +== Apply Patch . Find the patch series you want to test on https://spectrum-os.org/lists/archives/spectrum-devel/[public-inbox]. @@ -28,35 +30,31 @@ of the Spectrum root's nix-shell, which allows you to skip this step. with the patch's Message-Id to download all the patches in the series into a file. + -[example] [source,shell] ---- b4 am 20220511092352.70E54C980(a)atuin.qyliss.net ---- - -. b4 will indicate the file name it has downloaded the patches into - with a line like: +b4 will indicate the file name it has downloaded the patches into with a line +like: + -[example] -[listing] +[source,shell] +---- Writing ./20220424_hi_host_rootfs_fix_weston_hotplugging.mbx +---- +. Run `git am` on that file to apply the patches. For example: + -Run `git am` on that file to apply the patches, for example: -+ -[example] [source,shell] ---- git am 20220424_hi_host_rootfs_fix_weston_hotplugging.mbx ---- -== Post your test results +== Post Your Results -When you've tested a patch, it's really helpful to +When you tested a patch, it is helpful to xref:replying.adoc[reply] with your test results. -If the patch worked for you, please reply to it and include a line -like the following, separated from any reply text: - +If the patch worked for you, please reply to it and include a line like the following, separated from any reply text: +[source,shell] ---- Tested-by: John Smith <john(a)example.com> ---- @@ -66,10 +64,10 @@ patch replies will be automatically included in the commit message when a patch is applied. It's also helpful to explain in your reply how you tested the patch, -but you don't have to if it's obvious. (For example, if a patch is +but you don't have to if it's obvious. For example, if a patch is supposed to fix a bug, and you verified that after applying the patch the bug is fixed, just the Tested-by line on its own is enough to -indicate that.) +indicate that. If you found an issue with the patch, do not include a Tested-by line, and instead reply to the patch explaining what you tested, what you diff --git a/Documentation/uuid-reference.adoc b/Documentation/development/uuid-reference.adoc similarity index 97% rename from Documentation/uuid-reference.adoc rename to Documentation/development/uuid-reference.adoc index 4b0b481..61c602f 100644 --- a/Documentation/uuid-reference.adoc +++ b/Documentation/development/uuid-reference.adoc @@ -1,7 +1,8 @@ = UUID Reference -:page-parent: Reference +:page-parent: Development :toc: preamble :toclevels: 1 +:page-nav_order: 5 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -40,7 +41,7 @@ xref:user-partition.adoc[Spectrum user partition]. === `56a3bbc3-aefa-43d9-a64d-7b3fd59bbc4e` -https://github.com/endlessm/eos-installer["eosimages"] partition on the +https://github.com/endlessm/eos-installer["eosimages"] partition on the Spectrum combined live system / installer image. == Combined Image Partition IDs diff --git a/Documentation/explanation.adoc b/Documentation/explanation.adoc index b39cc6d..f682129 100644 --- a/Documentation/explanation.adoc +++ b/Documentation/explanation.adoc @@ -1,6 +1,5 @@ = Explanation -:page-has_children: true -:page-nav_order: 4 +:page-nav_exclude: true // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/creating-vms.adoc b/Documentation/getting-started/creating-vms.adoc similarity index 98% rename from Documentation/creating-vms.adoc rename to Documentation/getting-started/creating-vms.adoc index d967098..e06be85 100644 --- a/Documentation/creating-vms.adoc +++ b/Documentation/getting-started/creating-vms.adoc @@ -1,5 +1,5 @@ = Creating VMs -:page-parent: Reference +:page-parent: Getting Started // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/getting-started/index.adoc b/Documentation/getting-started/index.adoc new file mode 100644 index 0000000..639e0a6 --- /dev/null +++ b/Documentation/getting-started/index.adoc @@ -0,0 +1,14 @@ += Getting Started +:description: Exploring Spectrum OS. Using (=How-To-Guides), Configuring (adding smth). Ready to get started with Spectrum OS? After installing you can create VMs and then configure each one. +:page-nav_order: 3 +:page-has_children: true +:page-has_toc: false + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Ready to get started with Spectrum? Here is what you can do next: + +* xref:../getting-started/creating-vms.adoc[Create your own VM] to use others applications. +* xref:../getting-started/running-vms.adoc[Start some applications]. +* If needed, xref:../getting-started/user-partition.adoc[change the user partition type]. diff --git a/Documentation/running-vms.adoc b/Documentation/getting-started/running-vms.adoc similarity index 93% rename from Documentation/running-vms.adoc rename to Documentation/getting-started/running-vms.adoc index d0d3f99..9073e3c 100644 --- a/Documentation/running-vms.adoc +++ b/Documentation/getting-started/running-vms.adoc @@ -1,5 +1,5 @@ = Running VMs -:page-parent: Reference +:page-parent: Getting Started // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/getting-started/user-partition.adoc b/Documentation/getting-started/user-partition.adoc new file mode 100644 index 0000000..7c142b8 --- /dev/null +++ b/Documentation/getting-started/user-partition.adoc @@ -0,0 +1,16 @@ += User Partition +:page-parent: Getting Started + +// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +The Spectrum host system is immutable, so configuration and user data +lives on a separate partition. + +The host system discovers the user +partition by looking for the special partition type +`9293e1ff-cee4-4658-88be-898ec863944f`. + +This behavior can be overridden with the `ext` parameter on the host's kernel +command line, which works in a similar way to the standard Linux `root` +parameter. diff --git a/Documentation/how-to.adoc b/Documentation/how-to.adoc index f43fa13..98cc842 100644 --- a/Documentation/how-to.adoc +++ b/Documentation/how-to.adoc @@ -1,4 +1,5 @@ = How-to Guides +:page-nav_exclude: true :page-has_children: true :page-nav_order: 2 diff --git a/Documentation/index.adoc b/Documentation/index.adoc index 3079847..ea28533 100644 --- a/Documentation/index.adoc +++ b/Documentation/index.adoc @@ -1,13 +1,32 @@ -= Spectrum Docs += Spectrum Documentation :page-nav_exclude: true // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> +// SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 -Spectrum is a compartmentalized operating system. -If you'd like to try Spectrum, see xref:getting-spectrum.adoc[Getting -Spectrum]. +Spectrum is an open-source project that aims to create a computer operating +system, based on the principle of security by compartmentalization, that has a +lower barrier to entry and is easy to use and maintain. + +== Using Spectrum To learn about what Spectrum is and how it's implemented, start with -the xref:architecture.adoc[architecture overview]. +the xref:about/architecture.adoc[architecture overview]. + +If you want to try Spectrum, see xref:../installation/index.adoc[Build and Run] + to setup a development environment. + + +== Developing and Contributing + +Spectrum is made of free and open-source software. It is free for anyone to + use, modify, and distribute. + +Once you are up and rinning, see + xref:../development/index.adoc[Development] to understand how to work with + patches, debug the system or build the documentation. + +If you are thinking of contributing to Spectrum docs, see + xref:../development/building-documentation.adoc[Building Documentation]. diff --git a/Documentation/b4.adoc b/Documentation/installation/b4.adoc similarity index 93% rename from Documentation/b4.adoc rename to Documentation/installation/b4.adoc index 489ced4..58efd0e 100644 --- a/Documentation/b4.adoc +++ b/Documentation/installation/b4.adoc @@ -1,5 +1,6 @@ = Installing and Configuring b4 -:page-parent: Tutorials +:page-parent: Build and Run +:page-nav_order: 3 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-FileCopyrightText: 2022 Unikie @@ -19,7 +20,7 @@ of the Spectrum root's nix-shell. You should be able to install b4 from your package manager. -Using Nix, you can start a shell with b4 available by running +Using Nix, you can start a shell with b4 available by running: [listing] [source,shell] diff --git a/Documentation/binary-cache.adoc b/Documentation/installation/binary-cache.adoc similarity index 80% rename from Documentation/binary-cache.adoc rename to Documentation/installation/binary-cache.adoc index 6e69b39..dff12e1 100644 --- a/Documentation/binary-cache.adoc +++ b/Documentation/installation/binary-cache.adoc @@ -1,5 +1,6 @@ -= Setting Up the Binary Cache -:page-parent: How-to Guides += Setting Up Binary Cache +:page-parent: Build and Run +:page-nav_order: 1 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -20,10 +21,9 @@ encounter any trouble with it. The binary cache is currently not able to provide logs, due to a https://github.com/NixOS/nix/pull/6051[Nix bug]. -== On NixOS +== For NixOS -The following configuration adds the Spectrum binary cache as a -substituter, and tells Nix to trust builds signed with its public key. +Add the following configuration to /etc/nixos/configuration.nix: [source,nix] ---- @@ -38,7 +38,13 @@ substituter, and tells Nix to trust builds signed with its public key. } ---- -== On Non-NixOS systems +This configuration adds the Spectrum binary cache as a substituter and makes +Nix to trust builds signed with its public key. + +To apply changes, rebuild your system with the https://nixos.wiki/wiki/Nixos-rebuild[nixos-rebuild] command. + + +== For Non-NixOS Systems Add the following configuration to /etc/nix/nix.conf: diff --git a/Documentation/getting-spectrum.adoc b/Documentation/installation/getting-spectrum.adoc similarity index 82% rename from Documentation/getting-spectrum.adoc rename to Documentation/installation/getting-spectrum.adoc index b3fa1ef..c365a93 100644 --- a/Documentation/getting-spectrum.adoc +++ b/Documentation/installation/getting-spectrum.adoc @@ -1,5 +1,6 @@ = Getting Spectrum -:page-parent: Tutorials +:page-parent: Build and Run +:page-nav_order: 2 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -34,7 +35,7 @@ nix-shell -I nixpkgs=../../../nixpkgs-spectrum --run 'make run' This builds just enough of Spectrum to try it out in a VM, but it will still take a very long time. -== Building an installer +== Building Installer [source,shell] ---- @@ -47,8 +48,7 @@ This will take a very long time, but when it's done, a symbolic link named "result" will appear, pointing to a Spectrum USB installer image. -CAUTION: Spectrum is not yet suitable for real-world use. Do not use -your Spectrum system for anything important or sensitive. Spectrum is -currently missing many important security properties, and there is no -procedure for updating to new versions of Spectrum -- you have to -reinstall. +CAUTION: Do not use Spectrum for anything important or sensitive as it is not +yet suitable for real-world use. Many important security properties are +currently missing, and there is no procedure for updating to +new versions—you have to reinstall the OS. diff --git a/Documentation/installation/index.adoc b/Documentation/installation/index.adoc new file mode 100644 index 0000000..2c4e9c7 --- /dev/null +++ b/Documentation/installation/index.adoc @@ -0,0 +1,26 @@ += Build and Run +:description: How to download and install Spectrum OS. +:page-nav_order: 2 +:page-has_children: true +:page-has_toc: false + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + + +To start working with Spectrum, you need: + +* xref:../installation/binary-cache.adoc[Set up the binary cache] to speed up the build process. +* xref:../installation/getting-spectrum.adoc[Build Spectrum] from the source. +* xref:../installation/b4.adoc[Install and configure the b4 utility] to be able to work with patches. + +TIP: Currently, Spectrum works only on x86-64. AAarch64 support is in +development. If you have the configuration layer, you can +xref:../development/build-configuration.adoc[configure the build] to be able to +work with specific devices. + +== Uninstalling and Updating + +Currently, there is no implementation for a software update. + +You can replace Spectrum by installing another OS. diff --git a/Documentation/reference.adoc b/Documentation/reference.adoc index 44b359d..55259ea 100644 --- a/Documentation/reference.adoc +++ b/Documentation/reference.adoc @@ -1,6 +1,5 @@ = Reference -:page-has_children: true -:page-nav_order: 3 +:page-nav_exclude: true // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/tutorials.adoc b/Documentation/tutorials.adoc index cd1fb12..fcef31b 100644 --- a/Documentation/tutorials.adoc +++ b/Documentation/tutorials.adoc @@ -1,6 +1,5 @@ = Tutorials -:page-nav_order: 1 -:page-has_children: true +:page-nav_exclude: true // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/user-partition.adoc b/Documentation/user-partition.adoc deleted file mode 100644 index 73bc0d0..0000000 --- a/Documentation/user-partition.adoc +++ /dev/null @@ -1,12 +0,0 @@ -= The User Partition -:page-parent: Explanation - -// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> -// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 - -The Spectrum host system is immutable, so configuration and user data -lives on a separate partition. The host system discovers the user -partition by looking for the special partition type -`9293e1ff-cee4-4658-88be-898ec863944f`. This behavior can be -overridden with the `ext` parameter on the host's kernel command line, -which works in a similar way to the standard Linux `root` parameter. -- 2.34.1

3 6

[PATCH v3] Docs: new structure
by Jenni Nikolaenko 08 Nov '22

08 Nov '22

Create separate folders for new parent pages, update Introduction page, remove a and the articles from titles, quick check text for simple english Signed-off-by: Jenni Nikolaenko <evgeniia.nikolaenko(a)unikie.com> --- Documentation/{ => about}/architecture.adoc | 27 ++++----- Documentation/about/index.adoc | 32 ++++++++++ Documentation/building-documentation.adoc | 52 ---------------- .../decisions/001-host-update-mechanism.adoc | 4 +- .../decisions/002-install-options.adoc | 4 +- Documentation/decisions/003-partitioning.adoc | 2 +- .../004-data-at-rest-encryption.adoc | 4 +- .../005-virtual-machine-monitor.adoc | 2 +- .../decisions/006-drivers-on-host.adoc | 2 +- .../decisions/007-usb-virtual-machines.adoc | 2 +- ...008-inter-vm-communication-mechanisms.adoc | 2 +- Documentation/decisions/index.adoc | 2 +- Documentation/{ => development}/b4.adoc | 6 +- .../build-configuration.adoc | 13 ++-- .../development/building-documentation.adoc | 52 ++++++++++++++++ .../{ => development}/creating-vms.adoc | 4 +- .../{ => development}/debugging.adoc | 12 ++-- .../{ => development}/first-patch.adoc | 32 +++++----- Documentation/development/index.adoc | 59 +++++++++++++++++++ Documentation/development/managing-vms.adoc | 14 +++++ Documentation/{ => development}/replying.adoc | 13 ++-- .../{ => development}/reviewing-patches.adoc | 4 +- .../{ => development}/running-vms.adoc | 4 +- .../{ => development}/testing-patches.adoc | 28 ++++----- Documentation/development/user-partition.adoc | 18 ++++++ .../{ => development}/uuid-reference.adoc | 5 +- .../development/working-with-patces.adoc | 12 ++++ Documentation/explanation.adoc | 6 -- Documentation/how-to.adoc | 6 -- Documentation/index.adoc | 29 +++++++-- .../{ => installation}/binary-cache.adoc | 22 +++++-- .../{ => installation}/getting-spectrum.adoc | 16 ++--- Documentation/installation/index.adoc | 23 ++++++++ Documentation/reference.adoc | 6 -- Documentation/tutorials.adoc | 6 -- Documentation/user-partition.adoc | 12 ---- 36 files changed, 350 insertions(+), 187 deletions(-) rename Documentation/{ => about}/architecture.adoc (79%) create mode 100644 Documentation/about/index.adoc delete mode 100644 Documentation/building-documentation.adoc rename Documentation/{ => development}/b4.adoc (91%) rename Documentation/{ => development}/build-configuration.adoc (73%) create mode 100644 Documentation/development/building-documentation.adoc rename Documentation/{ => development}/creating-vms.adoc (97%) rename Documentation/{ => development}/debugging.adoc (79%) rename Documentation/{ => development}/first-patch.adoc (80%) create mode 100644 Documentation/development/index.adoc create mode 100644 Documentation/development/managing-vms.adoc rename Documentation/{ => development}/replying.adoc (68%) rename Documentation/{ => development}/reviewing-patches.adoc (88%) rename Documentation/{ => development}/running-vms.adoc (85%) rename Documentation/{ => development}/testing-patches.adoc (82%) create mode 100644 Documentation/development/user-partition.adoc rename Documentation/{ => development}/uuid-reference.adoc (97%) create mode 100644 Documentation/development/working-with-patces.adoc delete mode 100644 Documentation/explanation.adoc delete mode 100644 Documentation/how-to.adoc rename Documentation/{ => installation}/binary-cache.adoc (74%) rename Documentation/{ => installation}/getting-spectrum.adoc (79%) create mode 100644 Documentation/installation/index.adoc delete mode 100644 Documentation/reference.adoc delete mode 100644 Documentation/tutorials.adoc delete mode 100644 Documentation/user-partition.adoc diff --git a/Documentation/architecture.adoc b/Documentation/about/architecture.adoc similarity index 79% rename from Documentation/architecture.adoc rename to Documentation/about/architecture.adoc index 1c4307b..1237577 100644 --- a/Documentation/architecture.adoc +++ b/Documentation/about/architecture.adoc @@ -1,32 +1,31 @@ = Architecture -:page-parent: Explanation +:page-parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 -== Introduction +Spectrum is based on the principle of security by compartmentalization. -Spectrum is based on the principle of security by -compartmentalization. The high level stack is illustrated in the -following diagram: +The high level stack is illustrated in the following diagram: -image::diagrams/stack.svg[] +image::../diagrams/stack.svg[] The default set of virtual machines includes two application VMs, _appvm-catgirl_ (an IRC client) and _appvm-lynx_ (a text-based web browser); and a system VM, _netvm_ (which handles hardware network devices and provides network services to application VMs). Refer to -xref:creating-vms.adoc[Creating VMs] and xref:running-vms.adoc[Running +xref:../development/creating-vms.adoc[Creating VMs] and +xref:../development/running-vms.adoc[Running VMs] for more information about using VMs in Spectrum. == Architecture Decision Records (ADRs) https://en.wikipedia.org/wiki/Architectural_decision[Architecturally significant -decisions] are xref:decisions/index.adoc[recorded] as lightweight -https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions/[ADRs]. +decisions] are xref:../decisions/index.adoc[recorded] as lightweight +https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions[ADRs]. -== The Spectrum host system +== Spectrum Host System Compartmentalization is implemented using https://cloud-hypervisor.org/[cloud-hypervisor] virtual machines. @@ -44,7 +43,7 @@ and service scripts. https://wayland.freedesktop.org/[Wayland] is used for window management and display. The Wayland architecture is well documented -https://wayland.freedesktop.org/architecture.html[here]. The host provides only +https://wayland.freedesktop.org/architecture.html[here]. The host provides only a Wayland terminal client, https://codeberg.org/dnkl/foot/[foot], which is used for interacting with VM consoles. In future it will be possible for application VMs to display windows on the single Wayland compositor on the host system, @@ -57,7 +56,7 @@ https://www.etalabs.net/compare_libcs.html[added safety on resource exhaustion and security hardening on memory allocation]. Kernel hardening will be investigated in future. -== Exploring the Spectrum dependency tree +== Spectrum Dependency Tree For a detailed, interactive view of dependencies, use https://github.com/utdemir/nix-tree[nix-tree] in the Spectrum repository: @@ -66,5 +65,5 @@ https://github.com/utdemir/nix-tree[nix-tree] in the Spectrum repository: [listing] nix-build img/live -I nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz --no-out-link | xargs -o nix-tree -https://diode.zone/w/8DBDQ6HQUe5UUdLkpDuL35[See video of Spectrum live image -interactive analysis with nix-tree] +See the https://diode.zone/w/8DBDQ6HQUe5UUdLkpDuL35[video] of Spectrum live +image interactive analysis with nix-tree. diff --git a/Documentation/about/index.adoc b/Documentation/about/index.adoc new file mode 100644 index 0000000..6961b6a --- /dev/null +++ b/Documentation/about/index.adoc @@ -0,0 +1,32 @@ += About Spectrum +:description: Some words about Spectrum as the operating system, not a project. Highlights the differences between common Linux distributions and Spectrum. +:page-nav_order: 1 +:page-has_children: true + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Spectrum is a Linux-based system that uses the +https://github.com/NixOS/nix[Nix package manager] and +the https://github.com/NixOS/nixpkgs[Nix Packages collection] (Nixpkgs). + +This gives an actively-developed base with good +hardware support, powerful and optimised compartmentalization primitives in +https://www.linux-kvm.org/page/Main_Page[KVM], and the reproducible packaging +and configuration system that is important +for a maintainable compartmentalized system. + +== Why Spectrum + +* User data and applications are managed centrally while remaining isolated. +That means that the system can be backed up and managed as a whole, rather than +mixed up in several dozen VMs. + +* The host system and isolated environments are managed declaratively and +reproducibly using the Nix package manager. +This can save the user the burden of maintaining many different virtual +computers, allowing finer-grained resource access controls and making it +possible to verify the software running across all environments. + +TIP: If you are interested in why we do something _this_ way instead of _that_ +way, see xref:../decisions/index.adoc[Architecture Decision Records]. diff --git a/Documentation/building-documentation.adoc b/Documentation/building-documentation.adoc deleted file mode 100644 index b491105..0000000 --- a/Documentation/building-documentation.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= Building the Documentation -:page-parent: Tutorials - -// SPDX-FileCopyrightText: 2022 Unikie -// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 - -This tutorial assumes that you have https://nixos.org/[Nix] installed. -You may also want to xref:binary-cache.adoc[configure the Spectrum -binary cache], to avoid having to wait for dependencies to compile on -your local system. - -1. Get a copy of the Spectrum source code: -+ -[source,shell] ----- -git clone https://spectrum-os.org/git/spectrum ----- -2. Enter the documentation directory: -+ -[source,shell] ----- -cd spectrum/Documentation ----- -3. Enter the development environment: -+ -[source,shell] ----- -nix-shell -I nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz ----- -4. In the development shell, do an initial build of the documentation -site: -+ -[source,shell] ----- -scripts/build.sh ----- -5. Run a development server for previewing changes locally: -+ -[source,shell] ----- -jekyll serve ----- -+ -This will serve a local copy of the documentation at http://localhost:4000/. -+ -IMPORTANT: Jekyll doesn't handle rendering of the draw.io diagrams, so -if you modify any of those, or add new ones, you'll have to run -`scripts/build.sh` again to do a full rebuild of the site. - -Once you've made your changes to the documentation, see -xref:first-patch.adoc[Sending Your First Patch] for information -about how to submit them for review. diff --git a/Documentation/decisions/001-host-update-mechanism.adoc b/Documentation/decisions/001-host-update-mechanism.adoc index 574deb4..39f9f28 100644 --- a/Documentation/decisions/001-host-update-mechanism.adoc +++ b/Documentation/decisions/001-host-update-mechanism.adoc @@ -1,6 +1,6 @@ = 001 Host Update Mechanism :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -11,7 +11,7 @@ Proposed == Context -Spectrum currently has no implementation for software update. The host -- +Spectrum currently has no implementation for software update. The host -- consisting of the Linux kernel, KVM, cloud-hypervisor and minimal user space tools -- will require software updates to support feature development and security fixes. diff --git a/Documentation/decisions/002-install-options.adoc b/Documentation/decisions/002-install-options.adoc index 4412b53..4a745eb 100644 --- a/Documentation/decisions/002-install-options.adoc +++ b/Documentation/decisions/002-install-options.adoc @@ -1,6 +1,6 @@ -= 002 Install options += 002 Install Options :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/003-partitioning.adoc b/Documentation/decisions/003-partitioning.adoc index 8494ea4..a13b8cc 100644 --- a/Documentation/decisions/003-partitioning.adoc +++ b/Documentation/decisions/003-partitioning.adoc @@ -1,6 +1,6 @@ = 003 Partitioning :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/004-data-at-rest-encryption.adoc b/Documentation/decisions/004-data-at-rest-encryption.adoc index 26fe273..5b0f518 100644 --- a/Documentation/decisions/004-data-at-rest-encryption.adoc +++ b/Documentation/decisions/004-data-at-rest-encryption.adoc @@ -1,6 +1,6 @@ = 004 Data at Rest Encryption :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -20,5 +20,5 @@ User data is encrypted. == Consequences Spectrum needs to come with enough software to get the encryption key -via different methods (password, usb, fido, etc.) Can we use dm-crypt +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-monitor.adoc b/Documentation/decisions/005-virtual-machine-monitor.adoc index db81c72..df1b501 100644 --- a/Documentation/decisions/005-virtual-machine-monitor.adoc +++ b/Documentation/decisions/005-virtual-machine-monitor.adoc @@ -1,6 +1,6 @@ = 005 Virtual Machine Monitor :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/006-drivers-on-host.adoc b/Documentation/decisions/006-drivers-on-host.adoc index 872044e..b92d863 100644 --- a/Documentation/decisions/006-drivers-on-host.adoc +++ b/Documentation/decisions/006-drivers-on-host.adoc @@ -1,6 +1,6 @@ = 006 Drivers on Host :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/007-usb-virtual-machines.adoc b/Documentation/decisions/007-usb-virtual-machines.adoc index 3bdf78b..d832691 100644 --- a/Documentation/decisions/007-usb-virtual-machines.adoc +++ b/Documentation/decisions/007-usb-virtual-machines.adoc @@ -1,6 +1,6 @@ = 007 USB Virtual Machine :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc b/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc index a1b7d49..c1e5b87 100644 --- a/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc +++ b/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc @@ -1,6 +1,6 @@ = 008 Inter-VM Communication Mechanisms :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/index.adoc b/Documentation/decisions/index.adoc index 772f382..a022239 100644 --- a/Documentation/decisions/index.adoc +++ b/Documentation/decisions/index.adoc @@ -1,6 +1,6 @@ = Architecture Decision Records :page-has_children: true -:page-parent: Explanation +:page-parent: About Spectrum // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/b4.adoc b/Documentation/development/b4.adoc similarity index 91% rename from Documentation/b4.adoc rename to Documentation/development/b4.adoc index 489ced4..5f141e9 100644 --- a/Documentation/b4.adoc +++ b/Documentation/development/b4.adoc @@ -1,5 +1,7 @@ = Installing and Configuring b4 -:page-parent: Tutorials +:page-parent: Working with Patches +:page-grand_parent: Development +:page-nav_order: 1 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-FileCopyrightText: 2022 Unikie @@ -19,7 +21,7 @@ of the Spectrum root's nix-shell. You should be able to install b4 from your package manager. -Using Nix, you can start a shell with b4 available by running +Using Nix, you can start a shell with b4 available by running: [listing] [source,shell] diff --git a/Documentation/build-configuration.adoc b/Documentation/development/build-configuration.adoc similarity index 73% rename from Documentation/build-configuration.adoc rename to Documentation/development/build-configuration.adoc index b89575f..c9a8c99 100644 --- a/Documentation/build-configuration.adoc +++ b/Documentation/development/build-configuration.adoc @@ -1,19 +1,22 @@ = Configuring the Build -:page-parent: How-to Guides +:page-parent: Development +:page-nav_order: 1 :example-caption: Test // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 Some aspects of a Spectrum build can be customised using a build -configuration file. By default, this configuration file should be -called config.nix and located in the root of the Spectrum source tree, -but this can be overridden by setting `spectrum-config` in the +configuration file. + +By default, this configuration file should be called config.nix and located in +the root of the Spectrum source tree, but this can be overridden by setting +`spectrum-config` in the https://nixos.org/manual/nix/stable/command-ref/env-common.html#env-NIX_PAT… to the path of the configuration file. The configuration file should contain an attribute set. The only -currently allowed attribute name is `pkgs`, which allows using a +currently allowed attribute name is `pkgs`. It allows using a custom Nixpkgs to evaluate Spectrum. .config.nix to build Spectrum with a https://nixos.org/manual/nixpkgs/unstable/#sec-overlays-definition[Nixpkgs overlay] diff --git a/Documentation/development/building-documentation.adoc b/Documentation/development/building-documentation.adoc new file mode 100644 index 0000000..4f464f5 --- /dev/null +++ b/Documentation/development/building-documentation.adoc @@ -0,0 +1,52 @@ += Building Documentation +:page-parent: Development +:page-nav_order: 5 + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Make sure you have https://nixos.org/download.html[Nix] installed. +You may also want to xref:../installation/binary-cache.adoc[configure the Spectrum +binary cache], to avoid having to wait for dependencies to compile on +your local system. + +. Get a copy of the Spectrum source code: ++ +[source,shell] +---- +git clone https://spectrum-os.org/git/spectrum +---- +. Enter the documentation directory: ++ +[source,shell] +---- +cd spectrum/Documentation +---- +. Enter the development environment: ++ +[source,shell] +---- +nix-shell -I nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz +---- +. In the development shell, do an initial build of the documentation +site: ++ +[source,shell] +---- +scripts/build.sh +---- +. Run a development server for previewing changes locally: ++ +[source,shell] +---- +jekyll serve +---- ++ +This will serve a local copy of the documentation at http://localhost:4000/. ++ +IMPORTANT: Jekyll does not handle rendering of the draw.io diagrams. If you +modify any of those, or add new ones, run `scripts/build.sh` again to do a full +rebuild of the site. + +After making changes to the documentation, see how to +xref:first-patch.adoc[send your patch] and submit the changes for review. diff --git a/Documentation/creating-vms.adoc b/Documentation/development/creating-vms.adoc similarity index 97% rename from Documentation/creating-vms.adoc rename to Documentation/development/creating-vms.adoc index d967098..8785190 100644 --- a/Documentation/creating-vms.adoc +++ b/Documentation/development/creating-vms.adoc @@ -1,5 +1,7 @@ = Creating VMs -:page-parent: Reference +:page-parent: Managing VMs +:page-grand_parent: Development +:page-nav_order: 1 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/debugging.adoc b/Documentation/development/debugging.adoc similarity index 79% rename from Documentation/debugging.adoc rename to Documentation/development/debugging.adoc index 3871a7c..f1bbf01 100644 --- a/Documentation/debugging.adoc +++ b/Documentation/development/debugging.adoc @@ -1,7 +1,6 @@ -= Debugging Spectrum -:page-parent: Explanation -:toc: -:toclevels: 1 += Debugging +:page-parent: Development +:page-nav_order: 4 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -9,8 +8,9 @@ == Extracting core dumps when running Spectrum in a VM When using a VM to run the Spectrum host system, a special mechanism -is available to enable easy introspection of core files. When a -program on the Spectrum host system dumps core, the system will +is available to enable easy introspection of core files. + +When a program on the Spectrum host system dumps core, the system will attempt to upload the core file to _its_ host (i.e. the system running Spectrum in a VM) using the vsock(7) protocol, on port 1129271877. diff --git a/Documentation/first-patch.adoc b/Documentation/development/first-patch.adoc similarity index 80% rename from Documentation/first-patch.adoc rename to Documentation/development/first-patch.adoc index 30672b9..aa6ebee 100644 --- a/Documentation/first-patch.adoc +++ b/Documentation/development/first-patch.adoc @@ -1,11 +1,11 @@ -= Sending Your First Patch -:page-parent: Tutorials += Sending Your Patch +:page-parent: Working with Patches +:page-grand_parent: Development +:page-nav_order: 1 // 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. @@ -14,19 +14,18 @@ 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 +== Making Changes -If you've worked on any git repository before, the process for making -your changes will probably be very familiar. +The process of making changes is similar to working on any git repository. -1. Create a branch for your changes: +. Create a branch for your changes: + [source,shell] ---- git checkout -b fix-docs # for example ---- -2. Make changes in your editor. -3. Stage and commit your changes: +. Make changes in your editor. +. Stage and commit your changes: + [source,shell] ---- @@ -39,7 +38,7 @@ 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 +== Submitting Changes Once you're happy with how the commits on your branch look, run: @@ -64,13 +63,14 @@ message that will be sent before all of your patches. 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 +patch. You can respond to feedback in your mail client. + +Use the *Reply All* button to sent your messages 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, +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: +your patch(es) and then submit it like this: [source,shell] ---- @@ -81,7 +81,7 @@ 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 +If you would 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. diff --git a/Documentation/development/index.adoc b/Documentation/development/index.adoc new file mode 100644 index 0000000..4925570 --- /dev/null +++ b/Documentation/development/index.adoc @@ -0,0 +1,59 @@ += Development +:description: Development progress, general development practices +:page-nav_order: 4 +:page-has_children: true + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Spectrum is free software, currently under active development. + + +== General Workflow + +Spectrum is a very small and not changeable sort of Linux distro. It does +not have a package manager for users. If you faced a missing feature or a bug, or you want to suggest some improvements, please consider the following: + +* Get the latest version of the +https://spectrum-os.org/git/spectrum[source code] and make sure your problem +was not fixed. +* xref:../installation/getting-spectrum.adoc[Build Spectrum] and make changes +in the source code. In addition: +** If you need to customize the build to be able to use a +vendor kernel, you can +xref:../development/build-configuration.adoc[configure the build]. +** You can xref:../development/testing-patches.adoc[test patches] +subbmited by others. +* If you would like to share your code with the community, +you can send the changes to the maintainers for possible inclusion in +the Spectrum source code as a new patch. +** xref:../development/b4.adoc[Install and configure the b4 utility] to be able +to work with patches. +** xref:../development/first-patch.adoc[Submit the changes for review]. +Keep your git commits clean and make sure they meet general guidelines. +** Wait for approval from the maintainers' side. Detailed updates are posted in +Spectrum Development +https://spectrum-os.org/lists/hyperkitty/list/devel@spectrum-os.org/[threads]. +** Update documentation with the code. For more information, see +xref:../development/building-documentation.adoc[Building Documentation]. + +For additional information, see +https://spectrum-os.org/contributing.html[Contributing to Spectrum]. + + +== Developer Setup + +* https://git.kernel.org/pub/scm/utils/b4/b4.git/about/[b4] +* https://nixos.org/manual/nix/stable/introduction.html[Nix package manager] +* https://docs.asciidoctor.org/[AsciiDoc] for writing the documentation + + +== Mailing Lists + +The Spectrum project runs several +https://spectrum-os.org/participating.html#mailing-lists[mailing lists] on +which you can ask your questions or help other people with the questions they +have. All the Spectrum developers as well as many long time Linux and Spectrum users are on the lists. + +For real-time feedback, use +https://spectrum-os.org/participating.html#irc[IRC/Matrix channel]. diff --git a/Documentation/development/managing-vms.adoc b/Documentation/development/managing-vms.adoc new file mode 100644 index 0000000..d0a3f09 --- /dev/null +++ b/Documentation/development/managing-vms.adoc @@ -0,0 +1,14 @@ += Managing VMs +:page-parent: Development +:page-nav_order: 2 +:page-has_children: true +:page-has_toc: false + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Ready to get started with Spectrum? Here is what you can do next: + +* xref:../development/creating-vms.adoc[Create your own VM] to use others applications. +* xref:../development/running-vms.adoc[Start some applications]. +* If needed, xref:../development/user-partition.adoc[change the user partition type]. diff --git a/Documentation/replying.adoc b/Documentation/development/replying.adoc similarity index 68% rename from Documentation/replying.adoc rename to Documentation/development/replying.adoc index bb8e31a..a1ad394 100644 --- a/Documentation/replying.adoc +++ b/Documentation/development/replying.adoc @@ -1,5 +1,7 @@ = Replying to Messages in the Mailing List Archives -:page-parent: Tutorials +:page-parent: Working with Patches +:page-grand_parent: Development +:page-nav_order: 3 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -9,14 +11,13 @@ https://spectrum-os.org/participating.html#mailing-lists[mailing lists]. Make sure to Reply All when replying to messages, so that the message -is sent to the mailing list and not just to the person you're -replying to. +is sent to the mailing list and not just to the person you reply to. == Getting a copy of a message -You may want to reply to a mailing list message that you don't have a -copy of in your mail client, because you aren't subscribed to the -list, or because you subscribed after the message was sent. +You may want to reply to a mailing list message that you do not have a +copy of in your mail client, because you are not subscribed to the +list or because you subscribed after the message was sent. To do this, find the message you want to reply to in the https://spectrum-os.org/lists/archives[public-inbox list archives], diff --git a/Documentation/reviewing-patches.adoc b/Documentation/development/reviewing-patches.adoc similarity index 88% rename from Documentation/reviewing-patches.adoc rename to Documentation/development/reviewing-patches.adoc index 63ff24e..ba47f25 100644 --- a/Documentation/reviewing-patches.adoc +++ b/Documentation/development/reviewing-patches.adoc @@ -1,5 +1,7 @@ = Reviewing Patches -:page-parent: How-to Guides +:page-parent: Working with Patches +:page-grand_parent: Development +:page-nav_order: 2 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/running-vms.adoc b/Documentation/development/running-vms.adoc similarity index 85% rename from Documentation/running-vms.adoc rename to Documentation/development/running-vms.adoc index d0d3f99..7c474d5 100644 --- a/Documentation/running-vms.adoc +++ b/Documentation/development/running-vms.adoc @@ -1,5 +1,7 @@ = Running VMs -:page-parent: Reference +:page-parent: Managing VMs +:page-grand_parent: Development +:page-nav_order: 2 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/testing-patches.adoc b/Documentation/development/testing-patches.adoc similarity index 82% rename from Documentation/testing-patches.adoc rename to Documentation/development/testing-patches.adoc index 743cd6e..0c72c93 100644 --- a/Documentation/testing-patches.adoc +++ b/Documentation/development/testing-patches.adoc @@ -1,5 +1,7 @@ = Testing Patches -:page-parent: How-to Guides +:page-parent: Working with Patches +:page-grand_parent: Development +:page-nav_order: 2 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-FileCopyrightText: 2022 Unikie @@ -9,7 +11,7 @@ Potential changes to Spectrum are posted to and discussed on the https://spectrum-os.org/participating.html#spectrum-devel[devel@spectrum-os… mailing list. -== Apply the patch +== Apply Patch . Find the patch series you want to test on https://spectrum-os.org/lists/archives/spectrum-devel/[public-inbox]. @@ -33,15 +35,15 @@ of the Spectrum root's nix-shell, which allows you to skip this step. ---- b4 am 20220511092352.70E54C980(a)atuin.qyliss.net ---- - -. b4 will indicate the file name it has downloaded the patches into - with a line like: +b4 will indicate the file name it has downloaded the patches into with a line +like: + [example] [listing] +---- Writing ./20220424_hi_host_rootfs_fix_weston_hotplugging.mbx -+ -Run `git am` on that file to apply the patches, for example: +---- +. Run `git am` on that file to apply the patches. For example: + [example] [source,shell] @@ -49,14 +51,12 @@ Run `git am` on that file to apply the patches, for example: git am 20220424_hi_host_rootfs_fix_weston_hotplugging.mbx ---- -== Post your test results +== Post Your Results -When you've tested a patch, it's really helpful to +When you tested a patch, it is helpful to xref:replying.adoc[reply] with your test results. -If the patch worked for you, please reply to it and include a line -like the following, separated from any reply text: - +If the patch worked for you, please reply to it and include a line like the following, separated from any reply text: ---- Tested-by: John Smith <john(a)example.com> ---- @@ -66,10 +66,10 @@ patch replies will be automatically included in the commit message when a patch is applied. It's also helpful to explain in your reply how you tested the patch, -but you don't have to if it's obvious. (For example, if a patch is +but you don't have to if it's obvious. For example, if a patch is supposed to fix a bug, and you verified that after applying the patch the bug is fixed, just the Tested-by line on its own is enough to -indicate that.) +indicate that. If you found an issue with the patch, do not include a Tested-by line, and instead reply to the patch explaining what you tested, what you diff --git a/Documentation/development/user-partition.adoc b/Documentation/development/user-partition.adoc new file mode 100644 index 0000000..3fa6d01 --- /dev/null +++ b/Documentation/development/user-partition.adoc @@ -0,0 +1,18 @@ += User Partition +:page-parent: Managing VMs +:page-grand_parent: Development +:page-nav_order: 3 + +// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +The Spectrum host system is immutable, so configuration and user data +lives on a separate partition. + +The host system discovers the user +partition by looking for the special partition type +`9293e1ff-cee4-4658-88be-898ec863944f`. + +This behavior can be overridden with the `ext` parameter on the host's kernel +command line, which works in a similar way to the standard Linux `root` +parameter. diff --git a/Documentation/uuid-reference.adoc b/Documentation/development/uuid-reference.adoc similarity index 97% rename from Documentation/uuid-reference.adoc rename to Documentation/development/uuid-reference.adoc index 4b0b481..0bbded5 100644 --- a/Documentation/uuid-reference.adoc +++ b/Documentation/development/uuid-reference.adoc @@ -1,7 +1,8 @@ = UUID Reference -:page-parent: Reference +:page-parent: Development :toc: preamble :toclevels: 1 +:page-nav_order: 6 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -40,7 +41,7 @@ xref:user-partition.adoc[Spectrum user partition]. === `56a3bbc3-aefa-43d9-a64d-7b3fd59bbc4e` -https://github.com/endlessm/eos-installer["eosimages"] partition on the +https://github.com/endlessm/eos-installer["eosimages"] partition on the Spectrum combined live system / installer image. == Combined Image Partition IDs diff --git a/Documentation/development/working-with-patces.adoc b/Documentation/development/working-with-patces.adoc new file mode 100644 index 0000000..f73734f --- /dev/null +++ b/Documentation/development/working-with-patces.adoc @@ -0,0 +1,12 @@ += Working with Patches +:page-parent: Development +:page-nav_order: 3 +:page-has_children: true + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Patches are the way for contributors to submit code to the Spectrum project. + +Make sure to xref:../development/b4.adoc[install and configure the b4 utility] +before starting. diff --git a/Documentation/explanation.adoc b/Documentation/explanation.adoc deleted file mode 100644 index b39cc6d..0000000 --- a/Documentation/explanation.adoc +++ /dev/null @@ -1,6 +0,0 @@ -= Explanation -:page-has_children: true -:page-nav_order: 4 - -// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> -// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/how-to.adoc b/Documentation/how-to.adoc deleted file mode 100644 index f43fa13..0000000 --- a/Documentation/how-to.adoc +++ /dev/null @@ -1,6 +0,0 @@ -= How-to Guides -:page-has_children: true -:page-nav_order: 2 - -// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> -// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/index.adoc b/Documentation/index.adoc index 3079847..e0a45c7 100644 --- a/Documentation/index.adoc +++ b/Documentation/index.adoc @@ -1,13 +1,32 @@ -= Spectrum Docs += Spectrum Documentation :page-nav_exclude: true // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> +// SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 -Spectrum is a compartmentalized operating system. -If you'd like to try Spectrum, see xref:getting-spectrum.adoc[Getting -Spectrum]. +Spectrum is an open-source project that aims to create a computer operating +system, based on the principle of security by compartmentalization, that has a +lower barrier to entry and is easy to use and maintain. + +== Using Spectrum To learn about what Spectrum is and how it's implemented, start with -the xref:architecture.adoc[architecture overview]. +the xref:about/architecture.adoc[architecture overview]. + +If you want to try Spectrum, see xref:../installation/index.adoc[Build and Run] + to setup a development environment. + + +== Developing and Contributing + +Spectrum is made of free and open-source software. It is free for anyone to + use, modify, and distribute. + +Once you are up and running, see + xref:../development/index.adoc[Development] to understand how to work with + Spectrum's code and participate in the collaborative development process. + +If you are thinking of contributing to Spectrum docs, see + xref:../development/building-documentation.adoc[Building Documentation]. diff --git a/Documentation/binary-cache.adoc b/Documentation/installation/binary-cache.adoc similarity index 74% rename from Documentation/binary-cache.adoc rename to Documentation/installation/binary-cache.adoc index 6e69b39..ab53666 100644 --- a/Documentation/binary-cache.adoc +++ b/Documentation/installation/binary-cache.adoc @@ -1,5 +1,6 @@ -= Setting Up the Binary Cache -:page-parent: How-to Guides += Setting Up Binary Cache +:page-parent: Build and Run +:page-nav_order: 1 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -20,10 +21,9 @@ encounter any trouble with it. The binary cache is currently not able to provide logs, due to a https://github.com/NixOS/nix/pull/6051[Nix bug]. -== On NixOS +== For NixOS -The following configuration adds the Spectrum binary cache as a -substituter, and tells Nix to trust builds signed with its public key. +Add the following configuration to /etc/nixos/configuration.nix: [source,nix] ---- @@ -38,7 +38,13 @@ substituter, and tells Nix to trust builds signed with its public key. } ---- -== On Non-NixOS systems +This configuration adds the Spectrum binary cache as a substituter and makes +Nix trust builds signed with its public key. + +To apply changes, rebuild your system with the https://nixos.wiki/wiki/Nixos-rebuild[nixos-rebuild] command. + + +== For Non-NixOS Systems Add the following configuration to /etc/nix/nix.conf: @@ -48,6 +54,10 @@ substituters = https://cache.dataaturservice.se/spectrum/ https://cache.nixos.or trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= spectrum-os.org-1:rnnSumz3+Dbs5uewPlwZSTP0k3g/5SRG4hD7Wbr9YuQ= ---- +Run `systemctl restart nix-daemon.service` after making any changes in the Nix +configuration. After that the binary cache will be used automatically when +`nix-build` is run. + If you have other binary caches configured besides cache.nixos.org, make sure to add the Spectrum cache URL and public key to the existing configuration lines in your nix.conf file. diff --git a/Documentation/getting-spectrum.adoc b/Documentation/installation/getting-spectrum.adoc similarity index 79% rename from Documentation/getting-spectrum.adoc rename to Documentation/installation/getting-spectrum.adoc index b422a94..392cab5 100644 --- a/Documentation/getting-spectrum.adoc +++ b/Documentation/installation/getting-spectrum.adoc @@ -1,5 +1,6 @@ = Getting Spectrum -:page-parent: Tutorials +:page-parent: Build and Run +:page-nav_order: 2 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -8,7 +9,7 @@ To get Spectrum, you need to build it from source. As long as you're running Linuxfootnote:[Building from other operating systems might work, but hasn't been tested. Patches are welcome to support building from other operating systems, as long as they're not too invasive.] -and have https://nixos.org/[Nix] and https://git-scm.com/[git] +and have https://nixos.org/download.html[Nix] and https://git-scm.com/[git] installed, it's very easy to do. TIP: Before you start, consider setting up the @@ -34,7 +35,7 @@ nix-shell -I nixpkgs=../../../nixpkgs-spectrum --run 'make run' This builds just enough of Spectrum to try it out in a VM, but it will still take a very long time. -== Building an installer +== Building Installer [source,shell] ---- @@ -47,8 +48,7 @@ If you haven't set up the xref:binary-cache.adoc[binary cache], this will take a very long time. When it's done, a symbolic link named "result" will appear, pointing to a Spectrum USB installer image. -CAUTION: Spectrum is not yet suitable for real-world use. Do not use -your Spectrum system for anything important or sensitive. Spectrum is -currently missing many important security properties, and there is no -procedure for updating to new versions of Spectrum -- you have to -reinstall. +CAUTION: Do not use Spectrum for anything important or sensitive as it is not +yet suitable for real-world use. Many important security properties are +currently missing, and there is no procedure for updating to +new versions—you have to reinstall the OS. diff --git a/Documentation/installation/index.adoc b/Documentation/installation/index.adoc new file mode 100644 index 0000000..d67c88d --- /dev/null +++ b/Documentation/installation/index.adoc @@ -0,0 +1,23 @@ += Build and Run +:description: How to download and install Spectrum OS. +:page-nav_order: 2 +:page-has_children: true +:page-has_toc: false + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + + +To start working with Spectrum, you need: + +* xref:../installation/binary-cache.adoc[Set up the binary cache] to speed up the build process. +* xref:../installation/getting-spectrum.adoc[Build Spectrum] from the source. + +TIP: At this stage, Spectrum works only on x86-64. AArch64 support is in +development. + +== Uninstalling and Updating + +Currently, there is no implementation for a software update. + +You can replace Spectrum by installing another OS. diff --git a/Documentation/reference.adoc b/Documentation/reference.adoc deleted file mode 100644 index 44b359d..0000000 --- a/Documentation/reference.adoc +++ /dev/null @@ -1,6 +0,0 @@ -= Reference -:page-has_children: true -:page-nav_order: 3 - -// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> -// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/tutorials.adoc b/Documentation/tutorials.adoc deleted file mode 100644 index cd1fb12..0000000 --- a/Documentation/tutorials.adoc +++ /dev/null @@ -1,6 +0,0 @@ -= Tutorials -:page-nav_order: 1 -:page-has_children: true - -// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> -// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/user-partition.adoc b/Documentation/user-partition.adoc deleted file mode 100644 index 73bc0d0..0000000 --- a/Documentation/user-partition.adoc +++ /dev/null @@ -1,12 +0,0 @@ -= The User Partition -:page-parent: Explanation - -// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> -// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 - -The Spectrum host system is immutable, so configuration and user data -lives on a separate partition. The host system discovers the user -partition by looking for the special partition type -`9293e1ff-cee4-4658-88be-898ec863944f`. This behavior can be -overridden with the `ext` parameter on the host's kernel command line, -which works in a similar way to the standard Linux `root` parameter. -- 2.34.1

2 3

[PATCH] Docs: new structure
by Jenni Nikolaenko 28 Oct '22

28 Oct '22

Create separate folders for new parent pages, update Introduction page, remove a and the articles from titles, quick check text for simple english Signed-off-by: Jenni Nikolaenko <evgeniia.nikolaenko(a)unikie.com> --- Documentation/{ => about}/architecture.adoc | 19 ++++----- Documentation/about/index.adoc | 21 ++++++++++ .../decisions/001-host-update-mechanism.adoc | 2 +- .../decisions/002-install-options.adoc | 4 +- Documentation/decisions/003-partitioning.adoc | 2 +- .../004-data-at-rest-encryption.adoc | 2 +- .../005-virtual-machine-monitor.adoc | 2 +- .../decisions/006-drivers-on-host.adoc | 2 +- .../decisions/007-usb-virtual-machines.adoc | 2 +- ...008-inter-vm-communication-mechanisms.adoc | 2 +- Documentation/decisions/index.adoc | 2 +- .../building-documentation.adoc | 10 ++--- .../{ => development}/debugging.adoc | 7 ++-- .../{ => development}/first-patch.adoc | 28 +++++++------ Documentation/development/index.adoc | 17 ++++++++ Documentation/{ => development}/replying.adoc | 4 +- .../{ => development}/reviewing-patches.adoc | 4 +- .../{ => development}/testing-patches.adoc | 42 ++++++++----------- .../{ => development}/uuid-reference.adoc | 4 +- Documentation/explanation.adoc | 3 +- .../{ => getting-started}/creating-vms.adoc | 2 +- Documentation/getting-started/index.adoc | 7 ++++ .../{ => getting-started}/running-vms.adoc | 2 +- .../{ => getting-started}/user-partition.adoc | 8 ++-- Documentation/how-to.adoc | 1 + Documentation/index.adoc | 22 +++++++--- Documentation/{ => installation}/b4.adoc | 3 +- .../{ => installation}/binary-cache.adoc | 11 ++--- .../{ => installation}/getting-spectrum.adoc | 11 ++--- Documentation/installation/index.adoc | 18 ++++++++ Documentation/reference.adoc | 3 +- Documentation/tutorials.adoc | 3 +- 32 files changed, 171 insertions(+), 99 deletions(-) rename Documentation/{ => about}/architecture.adoc (84%) create mode 100644 Documentation/about/index.adoc rename Documentation/{ => development}/building-documentation.adoc (85%) rename Documentation/{ => development}/debugging.adoc (92%) rename Documentation/{ => development}/first-patch.adoc (83%) create mode 100644 Documentation/development/index.adoc rename Documentation/{ => development}/replying.adoc (93%) rename Documentation/{ => development}/reviewing-patches.adoc (89%) rename Documentation/{ => development}/testing-patches.adoc (62%) rename Documentation/{ => development}/uuid-reference.adoc (98%) rename Documentation/{ => getting-started}/creating-vms.adoc (98%) create mode 100644 Documentation/getting-started/index.adoc rename Documentation/{ => getting-started}/running-vms.adoc (93%) rename Documentation/{ => getting-started}/user-partition.adoc (80%) rename Documentation/{ => installation}/b4.adoc (96%) rename Documentation/{ => installation}/binary-cache.adoc (90%) rename Documentation/{ => installation}/getting-spectrum.adoc (85%) create mode 100644 Documentation/installation/index.adoc diff --git a/Documentation/architecture.adoc b/Documentation/about/architecture.adoc similarity index 84% rename from Documentation/architecture.adoc rename to Documentation/about/architecture.adoc index 1c4307b..db82d60 100644 --- a/Documentation/architecture.adoc +++ b/Documentation/about/architecture.adoc @@ -1,17 +1,16 @@ = Architecture -:page-parent: Explanation +:page-parent: About Spectrum OS // SPDX-FileCopyrightText: 2022 Unikie +// SPDX-FileCopyrightText: 2022 Jenni Nikolaenko <evgeniia.nikolaenko(a)unikie.com> // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 -== Introduction +Spectrum OS is based on the principle of security by compartmentalization. -Spectrum is based on the principle of security by -compartmentalization. The high level stack is illustrated in the -following diagram: +The high level stack is illustrated in the following diagram: -image::diagrams/stack.svg[] +image::../diagrams/stack.svg[] The default set of virtual machines includes two application VMs, _appvm-catgirl_ (an IRC client) and _appvm-lynx_ (a text-based web @@ -26,7 +25,7 @@ https://en.wikipedia.org/wiki/Architectural_decision[Architecturally significant decisions] are xref:decisions/index.adoc[recorded] as lightweight https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions/[A…. -== The Spectrum host system +== Spectrum Host System Compartmentalization is implemented using https://cloud-hypervisor.org/[cloud-hypervisor] virtual machines. @@ -35,7 +34,7 @@ https://en.wikipedia.org/wiki/Kernel-based_Virtual_Machine[Kernel-based Virtual Machine] (KVM) to provide lightweight, hardware-accelerated VMs. While Linux (including KVM) is portable between many hardware architectures, -cloud-hypervisor supports only x86_64 and aarch64. Spectrum currently only +cloud-hypervisor supports only x86_64 and aarch64. Spectrum currently only works on x86_64, but aarch64 support is in development. https://skarnet.org/software/s6-rc/overview.html[s6-rc] is used for service @@ -44,7 +43,7 @@ and service scripts. https://wayland.freedesktop.org/[Wayland] is used for window management and display. The Wayland architecture is well documented -https://wayland.freedesktop.org/architecture.html[here]. The host provides only +https://wayland.freedesktop.org/architecture.html[here]. The host provides only a Wayland terminal client, https://codeberg.org/dnkl/foot/[foot], which is used for interacting with VM consoles. In future it will be possible for application VMs to display windows on the single Wayland compositor on the host system, @@ -57,7 +56,7 @@ https://www.etalabs.net/compare_libcs.html[added safety on resource exhaustion and security hardening on memory allocation]. Kernel hardening will be investigated in future. -== Exploring the Spectrum dependency tree +== Spectrum Dependency Tree For a detailed, interactive view of dependencies, use https://github.com/utdemir/nix-tree[nix-tree] in the Spectrum repository: diff --git a/Documentation/about/index.adoc b/Documentation/about/index.adoc new file mode 100644 index 0000000..a882852 --- /dev/null +++ b/Documentation/about/index.adoc @@ -0,0 +1,21 @@ += About Spectrum OS +:description: Some words about Spectrum as the operating system, not a project. Highlights the differences between common Linux distributions and Spectrum. +:page-nav_order: 1 +:page-has_children: true + +// SPDX-FileCopyrightText: 2022 Jenni Nikko <evgeniia.nikolaenko(a)unikie.com> +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Spectrum is a Linux-based system, derived from NixOS. This gives an actively-developed base with good hardware support, powerful and optimised compartmentalization primitives in KVM, and the reproducible packaging and configuration system that is important for a maintainable compartmentalized system. + +== Why Spectrum + +There are several features that make Spectrum OS unique: + +* User data and applications are managed centrally, while remaining isolated. +That means that the system can be backed up and managed as a whole, rather than mixed up in several dozen VMs. + +* The host system and isolated environments are managed declaratively and reproducibly using the Nix package manager. +This can save the user the burden of maintaining many different virtual computers, allowing finer-grained resource access controls and making it possible to verify the software running across all environments. + +TIP: If you are interested in why we do something _this_ way instead of _that_ way, see xref:../decisions/index.adoc[Architecture Decision Records]. diff --git a/Documentation/decisions/001-host-update-mechanism.adoc b/Documentation/decisions/001-host-update-mechanism.adoc index 574deb4..7032146 100644 --- a/Documentation/decisions/001-host-update-mechanism.adoc +++ b/Documentation/decisions/001-host-update-mechanism.adoc @@ -1,6 +1,6 @@ = 001 Host Update Mechanism :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum OS // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/002-install-options.adoc b/Documentation/decisions/002-install-options.adoc index 4412b53..a7c4175 100644 --- a/Documentation/decisions/002-install-options.adoc +++ b/Documentation/decisions/002-install-options.adoc @@ -1,6 +1,6 @@ -= 002 Install options += 002 Install Options :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum OS // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/003-partitioning.adoc b/Documentation/decisions/003-partitioning.adoc index 8494ea4..b00f528 100644 --- a/Documentation/decisions/003-partitioning.adoc +++ b/Documentation/decisions/003-partitioning.adoc @@ -1,6 +1,6 @@ = 003 Partitioning :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum OS // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/004-data-at-rest-encryption.adoc b/Documentation/decisions/004-data-at-rest-encryption.adoc index 26fe273..27323db 100644 --- a/Documentation/decisions/004-data-at-rest-encryption.adoc +++ b/Documentation/decisions/004-data-at-rest-encryption.adoc @@ -1,6 +1,6 @@ = 004 Data at Rest Encryption :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum OS // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/005-virtual-machine-monitor.adoc b/Documentation/decisions/005-virtual-machine-monitor.adoc index db81c72..df5a65e 100644 --- a/Documentation/decisions/005-virtual-machine-monitor.adoc +++ b/Documentation/decisions/005-virtual-machine-monitor.adoc @@ -1,6 +1,6 @@ = 005 Virtual Machine Monitor :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum OS // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/006-drivers-on-host.adoc b/Documentation/decisions/006-drivers-on-host.adoc index 872044e..86d3105 100644 --- a/Documentation/decisions/006-drivers-on-host.adoc +++ b/Documentation/decisions/006-drivers-on-host.adoc @@ -1,6 +1,6 @@ = 006 Drivers on Host :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum OS // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/007-usb-virtual-machines.adoc b/Documentation/decisions/007-usb-virtual-machines.adoc index 3bdf78b..24dac65 100644 --- a/Documentation/decisions/007-usb-virtual-machines.adoc +++ b/Documentation/decisions/007-usb-virtual-machines.adoc @@ -1,6 +1,6 @@ = 007 USB Virtual Machine :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum OS // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc b/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc index a1b7d49..9fce4ef 100644 --- a/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc +++ b/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc @@ -1,6 +1,6 @@ = 008 Inter-VM Communication Mechanisms :page-parent: Architecture Decision Records -:page-grand_parent: Explanation +:page-grand_parent: About Spectrum OS // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/decisions/index.adoc b/Documentation/decisions/index.adoc index 772f382..4f3a7e1 100644 --- a/Documentation/decisions/index.adoc +++ b/Documentation/decisions/index.adoc @@ -1,6 +1,6 @@ = Architecture Decision Records :page-has_children: true -:page-parent: Explanation +:page-parent: About Spectrum OS // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/building-documentation.adoc b/Documentation/development/building-documentation.adoc similarity index 85% rename from Documentation/building-documentation.adoc rename to Documentation/development/building-documentation.adoc index b491105..da5fa8c 100644 --- a/Documentation/building-documentation.adoc +++ b/Documentation/development/building-documentation.adoc @@ -1,5 +1,5 @@ -= Building the Documentation -:page-parent: Tutorials += Building Documentation +:page-parent: Development // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -47,6 +47,6 @@ IMPORTANT: Jekyll doesn't handle rendering of the draw.io diagrams, so if you modify any of those, or add new ones, you'll have to run `scripts/build.sh` again to do a full rebuild of the site. -Once you've made your changes to the documentation, see -xref:first-patch.adoc[Sending Your First Patch] for information -about how to submit them for review. +Once you made your changes to the documentation, see +xref:first-patch.adoc[Patching] for information +on how to submit your patch for review. diff --git a/Documentation/debugging.adoc b/Documentation/development/debugging.adoc similarity index 92% rename from Documentation/debugging.adoc rename to Documentation/development/debugging.adoc index 3871a7c..6e529a9 100644 --- a/Documentation/debugging.adoc +++ b/Documentation/development/debugging.adoc @@ -1,7 +1,6 @@ -= Debugging Spectrum -:page-parent: Explanation -:toc: -:toclevels: 1 += Debugging +:page-parent: Development +:page-nav_order: 2 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/first-patch.adoc b/Documentation/development/first-patch.adoc similarity index 83% rename from Documentation/first-patch.adoc rename to Documentation/development/first-patch.adoc index 30672b9..7b8dd1d 100644 --- a/Documentation/first-patch.adoc +++ b/Documentation/development/first-patch.adoc @@ -1,11 +1,12 @@ -= Sending Your First Patch -:page-parent: Tutorials += Patching +:page-parent: Development +:page-nav_order: 1 +:page-has_children: true +:toc: preamble // 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. @@ -14,10 +15,10 @@ 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 +== Making Changes -If you've worked on any git repository before, the process for making -your changes will probably be very familiar. +If you worked on any git repository before, the process for making +your changes will be very familiar. 1. Create a branch for your changes: + @@ -39,7 +40,7 @@ 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 +== Submitting Changes Once you're happy with how the commits on your branch look, run: @@ -64,13 +65,14 @@ message that will be sent before all of your patches. 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 +patch. You can respond to feedback in your mail client. + +Use the *Reply All* button to sent your messages 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, +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: +your patch(es) and then submit it like this: [source,shell] ---- @@ -81,7 +83,7 @@ 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 +If you would 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. diff --git a/Documentation/development/index.adoc b/Documentation/development/index.adoc new file mode 100644 index 0000000..471daf7 --- /dev/null +++ b/Documentation/development/index.adoc @@ -0,0 +1,17 @@ += Development +:description: Development progress, general development practices +:page-nav_order: 4 +:page-has_children: true + +// SPDX-FileCopyrightText: 2022 Jenni Nikko <evgeniia.nikolaenko(a)unikie.com> +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Spectrum is free software, currently under active development. + +== Developer Setup + +Before starting, make sure you are familiar with https://git.kernel.org/pub/scm/utils/b4/b4.git/about/[b4] and the https://nixos.org/manual/nix/stable/introduction.html[Nix package manager]. + +== Mailing Lists + +The Spectrum project runs several https://spectrum-os.org/mailman3/lists/?all-lists[mailing lists] on which you can ask your questions or help other people with the questions they have. All the Spectrum developers as well as many long time Linux and Spectrum users are on the lists. diff --git a/Documentation/replying.adoc b/Documentation/development/replying.adoc similarity index 93% rename from Documentation/replying.adoc rename to Documentation/development/replying.adoc index bb8e31a..05740a0 100644 --- a/Documentation/replying.adoc +++ b/Documentation/development/replying.adoc @@ -1,5 +1,7 @@ = Replying to Messages in the Mailing List Archives -:page-parent: Tutorials +:page-parent: Patching +:page-grand_parent: Development +:page-nav_order: 3 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/reviewing-patches.adoc b/Documentation/development/reviewing-patches.adoc similarity index 89% rename from Documentation/reviewing-patches.adoc rename to Documentation/development/reviewing-patches.adoc index 63ff24e..c8c971f 100644 --- a/Documentation/reviewing-patches.adoc +++ b/Documentation/development/reviewing-patches.adoc @@ -1,5 +1,7 @@ = Reviewing Patches -:page-parent: How-to Guides +:page-parent: Patching +:page-grand_parent: Development +:page-nav_order: 2 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/testing-patches.adoc b/Documentation/development/testing-patches.adoc similarity index 62% rename from Documentation/testing-patches.adoc rename to Documentation/development/testing-patches.adoc index 8ba7804..99adfd2 100644 --- a/Documentation/testing-patches.adoc +++ b/Documentation/development/testing-patches.adoc @@ -1,5 +1,8 @@ = Testing Patches -:page-parent: How-to Guides +:page-parent: Patching +:page-grand_parent: Development +:page-nav_order: 1 +:toc: preamble // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -8,52 +11,41 @@ Potential changes to Spectrum are posted to and discussed on the https://spectrum-os.org/participating.html#spectrum-devel[devel@spectrum-os… mailing list. -== Apply the patch +== Apply Patch If you haven't already, you'll first need to xref:b4.adoc[install and configure] https://git.kernel.org/pub/scm/utils/b4/b4.git/about/[b4]. Then: -. Find the patch series you want to test on - https://spectrum-os.org/lists/archives/spectrum-devel/[public-inbox]. -. Navigate to the "permalink" page for any patch in the series. -. Copy the Message-Id for the patch, as shown on the permalink page, e.g. - \20220511092352.70E54C980@atuin.qyliss.net. -. In a checkout of the appropriate git repository - (https://spectrum-os.org/git/spectrum[Spectrum] or - https://spectrum-os.org/git/nixpkgs[Spectrum Nixpkgs]), Run `b4 am` - with the patch's Message-Id to download all the patches in the - series into a file. +1. Find the patch series you want to test on https://spectrum-os.org/lists/archives/spectrum-devel/[public-inbox]. +2. Navigate to the "permalink" page for any patch in the series. +3. Copy the Message-Id for the patch, as shown on the permalink page, e.g. \20220511092352.70E54C980@atuin.qyliss.net. +4. In a checkout of the appropriate git repository (https://spectrum-os.org/git/spectrum[Spectrum] or https://spectrum-os.org/git/nixpkgs[Spectrum Nixpkgs]), run `b4 am` with the patch's Message-Id to download all the patches in the series into a file. + -[example] [source,shell] ---- b4 am 20220511092352.70E54C980(a)atuin.qyliss.net ---- - -. b4 will indicate the file name it has downloaded the patches into - with a line like: +b4 will indicate the file name it has downloaded the patches into with a line like: + -[example] -[listing] +[source,shell] +---- Writing ./20220424_hi_host_rootfs_fix_weston_hotplugging.mbx +---- +5. Run `git am` on that file to apply the patches, for example: + -Run `git am` on that file to apply the patches, for example: -+ -[example] [source,shell] ---- git am 20220424_hi_host_rootfs_fix_weston_hotplugging.mbx ---- -== Post your test results +== Post Your Results When you've tested a patch, it's really helpful to xref:replying.adoc[reply] with your test results. -If the patch worked for you, please reply to it and include a line -like the following, separated from any reply text: - +If the patch worked for you, please reply to it and include a line like the following, separated from any reply text: +[source,shell] ---- Tested-by: John Smith <john(a)example.com> ---- diff --git a/Documentation/uuid-reference.adoc b/Documentation/development/uuid-reference.adoc similarity index 98% rename from Documentation/uuid-reference.adoc rename to Documentation/development/uuid-reference.adoc index 4b0b481..0eccc82 100644 --- a/Documentation/uuid-reference.adoc +++ b/Documentation/development/uuid-reference.adoc @@ -1,5 +1,5 @@ = UUID Reference -:page-parent: Reference +:page-parent: Development :toc: preamble :toclevels: 1 @@ -40,7 +40,7 @@ xref:user-partition.adoc[Spectrum user partition]. === `56a3bbc3-aefa-43d9-a64d-7b3fd59bbc4e` -https://github.com/endlessm/eos-installer["eosimages"] partition on the +https://github.com/endlessm/eos-installer["eosimages"] partition on the Spectrum combined live system / installer image. == Combined Image Partition IDs diff --git a/Documentation/explanation.adoc b/Documentation/explanation.adoc index b39cc6d..f682129 100644 --- a/Documentation/explanation.adoc +++ b/Documentation/explanation.adoc @@ -1,6 +1,5 @@ = Explanation -:page-has_children: true -:page-nav_order: 4 +:page-nav_exclude: true // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/creating-vms.adoc b/Documentation/getting-started/creating-vms.adoc similarity index 98% rename from Documentation/creating-vms.adoc rename to Documentation/getting-started/creating-vms.adoc index d967098..e06be85 100644 --- a/Documentation/creating-vms.adoc +++ b/Documentation/getting-started/creating-vms.adoc @@ -1,5 +1,5 @@ = Creating VMs -:page-parent: Reference +:page-parent: Getting Started // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/getting-started/index.adoc b/Documentation/getting-started/index.adoc new file mode 100644 index 0000000..1b468ab --- /dev/null +++ b/Documentation/getting-started/index.adoc @@ -0,0 +1,7 @@ += Getting Started +:description: Exploring Spectrum OS. Using (=How-To-Guides), Configuring (adding smth). Ready to get started with Spectrum OS? After installing you can create VMs and then configure each one. +:page-nav_order: 3 +:page-has_children: true + +// SPDX-FileCopyrightText: 2022 Jenni Nikko <evgeniia.nikolaenko(a)unikie.com> +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/running-vms.adoc b/Documentation/getting-started/running-vms.adoc similarity index 93% rename from Documentation/running-vms.adoc rename to Documentation/getting-started/running-vms.adoc index d0d3f99..9073e3c 100644 --- a/Documentation/running-vms.adoc +++ b/Documentation/getting-started/running-vms.adoc @@ -1,5 +1,5 @@ = Running VMs -:page-parent: Reference +:page-parent: Getting Started // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/user-partition.adoc b/Documentation/getting-started/user-partition.adoc similarity index 80% rename from Documentation/user-partition.adoc rename to Documentation/getting-started/user-partition.adoc index 73bc0d0..a33d7fc 100644 --- a/Documentation/user-partition.adoc +++ b/Documentation/getting-started/user-partition.adoc @@ -1,11 +1,13 @@ -= The User Partition -:page-parent: Explanation += User Partition +:page-parent: Getting Started // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 The Spectrum host system is immutable, so configuration and user data -lives on a separate partition. The host system discovers the user +lives on a separate partition. + +The host system discovers the user partition by looking for the special partition type `9293e1ff-cee4-4658-88be-898ec863944f`. This behavior can be overridden with the `ext` parameter on the host's kernel command line, diff --git a/Documentation/how-to.adoc b/Documentation/how-to.adoc index f43fa13..98cc842 100644 --- a/Documentation/how-to.adoc +++ b/Documentation/how-to.adoc @@ -1,4 +1,5 @@ = How-to Guides +:page-nav_exclude: true :page-has_children: true :page-nav_order: 2 diff --git a/Documentation/index.adoc b/Documentation/index.adoc index 3079847..d26676b 100644 --- a/Documentation/index.adoc +++ b/Documentation/index.adoc @@ -1,13 +1,23 @@ -= Spectrum Docs += Spectrum Documentation :page-nav_exclude: true // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> +// SPDX-FileCopyrightText: 2022 Jenni Nikolaenko <evgeniia.nikolaenko(a)unikie.com> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 -Spectrum is a compartmentalized operating system. +== Spectrum Project -If you'd like to try Spectrum, see xref:getting-spectrum.adoc[Getting -Spectrum]. +Spectrum is an open source project that aims to create a computer operating system, based on the principle of security by compartmentalization, that has a lower barrier to entry and is easier to use and maintain than other such systems. For more information on the Spectrum project, see https://spectrum-os.org/. -To learn about what Spectrum is and how it's implemented, start with -the xref:architecture.adoc[architecture overview]. +Spectrum is made of free and open source software. It is free for anyone to use, modify, and distribute. If you want to be involved with the Spectrum project, see https://spectrum-os.org/contributing.html. + +The Spectrum project source code is https://spectrum-os.org/git/spectrum. + +== Spectrum OS + +Spectrum is an in-development operating system that aims to afford its users security by compartmentalization, while also improving upon other similar projects by maintaining a high level of usability. + +To learn about what Spectrum OS is and how it's implemented, start with +the xref:about/architecture.adoc[architecture overview]. + +If you want to try Spectrum, see xref:../installation/index.adoc[Build and Run]. diff --git a/Documentation/b4.adoc b/Documentation/installation/b4.adoc similarity index 96% rename from Documentation/b4.adoc rename to Documentation/installation/b4.adoc index 2519894..1ba87b2 100644 --- a/Documentation/b4.adoc +++ b/Documentation/installation/b4.adoc @@ -1,5 +1,6 @@ = Installing and Configuring b4 -:page-parent: Tutorials +:page-parent: Build and Run +:page-nav_order: 3 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/binary-cache.adoc b/Documentation/installation/binary-cache.adoc similarity index 90% rename from Documentation/binary-cache.adoc rename to Documentation/installation/binary-cache.adoc index 6e69b39..232f96c 100644 --- a/Documentation/binary-cache.adoc +++ b/Documentation/installation/binary-cache.adoc @@ -1,10 +1,11 @@ -= Setting Up the Binary Cache -:page-parent: How-to Guides += Setting Up Binary Cache +:page-parent: Build and Run +:page-nav_order: 1 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 -Building Spectrum from source can take a very long time. To avoid +Building Spectrum OS from source can take a very long time. To avoid having to wait when building the system to try it out or test patches, an x86_64 binary cache service is available. If configured to do so, Nix will download build outputs from the cache, instead of building @@ -20,7 +21,7 @@ encounter any trouble with it. The binary cache is currently not able to provide logs, due to a https://github.com/NixOS/nix/pull/6051[Nix bug]. -== On NixOS +== For NixOS The following configuration adds the Spectrum binary cache as a substituter, and tells Nix to trust builds signed with its public key. @@ -38,7 +39,7 @@ substituter, and tells Nix to trust builds signed with its public key. } ---- -== On Non-NixOS systems +== For Non-NixOS Systems Add the following configuration to /etc/nix/nix.conf: diff --git a/Documentation/getting-spectrum.adoc b/Documentation/installation/getting-spectrum.adoc similarity index 85% rename from Documentation/getting-spectrum.adoc rename to Documentation/installation/getting-spectrum.adoc index b3fa1ef..a0ea1c4 100644 --- a/Documentation/getting-spectrum.adoc +++ b/Documentation/installation/getting-spectrum.adoc @@ -1,10 +1,11 @@ = Getting Spectrum -:page-parent: Tutorials +:page-parent: Build and Run +:page-nav_order: 2 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 -To get Spectrum, you need to build it from source. As long as you're +To get Spectrum OS, you need to build it from source. As long as you're running Linuxfootnote:[Building from other operating systems might work, but hasn't been tested. Patches are welcome to support building from other operating systems, as long as they're not too invasive.] @@ -17,7 +18,7 @@ lot of time waiting for builds. == Trying Spectrum -If you want to try Spectrum out to get a feel for it, without +If you want to try Spectrum OS out to get a feel for it, without installing it, you can run it in a development VM with some example applications. @@ -34,7 +35,7 @@ nix-shell -I nixpkgs=../../../nixpkgs-spectrum --run 'make run' This builds just enough of Spectrum to try it out in a VM, but it will still take a very long time. -== Building an installer +== Building Installer [source,shell] ---- @@ -48,7 +49,7 @@ named "result" will appear, pointing to a Spectrum USB installer image. CAUTION: Spectrum is not yet suitable for real-world use. Do not use -your Spectrum system for anything important or sensitive. Spectrum is +your Spectrum OS for anything important or sensitive. Spectrum is currently missing many important security properties, and there is no procedure for updating to new versions of Spectrum -- you have to reinstall. diff --git a/Documentation/installation/index.adoc b/Documentation/installation/index.adoc new file mode 100644 index 0000000..99e9723 --- /dev/null +++ b/Documentation/installation/index.adoc @@ -0,0 +1,18 @@ += Build and Run +:description: How to download and install Spectrum OS. +:page-nav_order: 2 +:page-has_children: true + +// SPDX-FileCopyrightText: 2022 Jenni Nikko <evgeniia.nikolaenko(a)unikie.com> +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +To try Spectrum OS out or xref:../development/testing-patches.adoc[test patches], you need to build the system from the source. + +In order to speed up the build process, set up the binary cache. After building Spectrum OS, you can install and configure the b4 utility to be able to work with patches. + + +TIP: Note that Spectrum OS currently works only on x86-64. AAarch64 support is in development. + +Currently, there is no implementation for a software update. + +You can replace the installation with some other OS. diff --git a/Documentation/reference.adoc b/Documentation/reference.adoc index 44b359d..55259ea 100644 --- a/Documentation/reference.adoc +++ b/Documentation/reference.adoc @@ -1,6 +1,5 @@ = Reference -:page-has_children: true -:page-nav_order: 3 +:page-nav_exclude: true // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 diff --git a/Documentation/tutorials.adoc b/Documentation/tutorials.adoc index cd1fb12..fcef31b 100644 --- a/Documentation/tutorials.adoc +++ b/Documentation/tutorials.adoc @@ -1,6 +1,5 @@ = Tutorials -:page-nav_order: 1 -:page-has_children: true +:page-nav_exclude: true // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 -- 2.34.1

4 4

Branches for in-progress Wayland work
by Alyssa Ross 25 Oct '22

25 Oct '22

I've published branches called "wayland" on both the spectrum and nixpkgs repositories, to make it easier to follow the current state of that work. I've tested that both hello-wayland and foot work in a Spectrum VM. (To test foot I just found-and-replaced hello-wayland with foot in hello-wayland.nix.)

1 0

← Newer
1
...
20
21
22
23
24
25
26
...
39
Older →

Jump to page: