From 8ae8ca1e02bf151d98382496c4af78822630bb42 Mon Sep 17 00:00:00 2001 From: Jenni Nikolaenko Date: Mon, 21 Nov 2022 15:18:18 +0200 Subject: Documentation: move Appendices to Development, fixed links Both sections "User Partition" and "UUID Reference" are more development topics, so by Alyssa's advice they should go directly under the Development chapter. The section Appendices was removed. In addition, I replaced broken links. Signed-off-by: Jenni Nikolaenko Message-Id: <20221121131817.15162-1-evgeniia.nikolaenko@unikie.com> Reviewed-by: Alyssa Ross Tested-by: Alyssa Ross Signed-off-by: Alyssa Ross --- Documentation/about/architecture.adoc | 6 +-- Documentation/appendices/index.adoc | 13 ------ Documentation/appendices/user-partition.adoc | 17 ------- Documentation/appendices/uuid-reference.adoc | 61 -------------------------- Documentation/development/user-partition.adoc | 17 +++++++ Documentation/development/uuid-reference.adoc | 60 +++++++++++++++++++++++++ Documentation/index.adoc | 8 ++-- Documentation/scripts/undocumented-uuids.sh | 2 +- Documentation/using-spectrum/creating-vms.adoc | 2 +- 9 files changed, 86 insertions(+), 100 deletions(-) delete mode 100644 Documentation/appendices/index.adoc delete mode 100644 Documentation/appendices/user-partition.adoc delete mode 100644 Documentation/appendices/uuid-reference.adoc create mode 100644 Documentation/development/user-partition.adoc create mode 100644 Documentation/development/uuid-reference.adoc (limited to 'Documentation') diff --git a/Documentation/about/architecture.adoc b/Documentation/about/architecture.adoc index b311e77..38e0a22 100644 --- a/Documentation/about/architecture.adoc +++ b/Documentation/about/architecture.adoc @@ -15,8 +15,8 @@ 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:../getting-started/creating-vms.adoc[Creating VMs] and -xref:../getting-started/running-vms.adoc[Running +Refer to xref:../using-spectrum/creating-vms.adoc[Creating VMs] and +xref:../using-spectrum/running-vms.adoc[Running VMs] for more information about using VMs in Spectrum. == Architecture Decision Records (ADRs) @@ -28,7 +28,7 @@ https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions[ADRs]. == Spectrum Host System Compartmentalization is implemented using -https://cloud-hypervisor.org/[cloud-hypervisor] virtual machines. +https://cloudhypervisor.org/[cloud-hypervisor] virtual machines. cloud-hypervisor uses Linux's https://en.wikipedia.org/wiki/Kernel-based_Virtual_Machine[Kernel-based Virtual Machine] (KVM) to provide lightweight, hardware-accelerated VMs. diff --git a/Documentation/appendices/index.adoc b/Documentation/appendices/index.adoc deleted file mode 100644 index ebacda7..0000000 --- a/Documentation/appendices/index.adoc +++ /dev/null @@ -1,13 +0,0 @@ -= 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 deleted file mode 100644 index 4121340..0000000 --- a/Documentation/appendices/user-partition.adoc +++ /dev/null @@ -1,17 +0,0 @@ -= Appendix A. User Partition -:page-parent: Appendices -:page-nav_order: 1 - -// SPDX-FileCopyrightText: 2022 Alyssa Ross -// 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/appendices/uuid-reference.adoc b/Documentation/appendices/uuid-reference.adoc deleted file mode 100644 index 5099ec3..0000000 --- a/Documentation/appendices/uuid-reference.adoc +++ /dev/null @@ -1,61 +0,0 @@ -= Appendix B. UUID Reference -:page-parent: Appendices -:toclevels: 1 -:page-nav_order: 2 - -// SPDX-FileCopyrightText: 2022 Alyssa Ross -// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 - -https://en.wikipedia.org/wiki/Universally_unique_identifier[UUIDs] are -used extensively throughout Spectrum. When encountering a UUID in the -codebase, it can be difficult to understand what exactly the UUID -means, and where it originates from -- is it from some standard, or -Spectrum-specific? - -To solve this problem, this reference documents all of the UUIDs used -in Spectrum. - -== https://en.wikipedia.org/wiki/GUID_Partition_Table[GPT] Partition Types - -=== `c12a7328-f81f-11d2-ba4b-00a0c93ec93b` - -"EFI System Partition", from the https://uefi.org/specifications[UEFI -Specification]. - -=== `4f68bce3-e8cd-4db1-96e7-fbcaf984b709` - -"Root Partition (amd64/x86_64)" from the -https://systemd.io/DISCOVERABLE_PARTITIONS/[Discoverable Partitions -Specification]. - -=== `2c7357ed-ebd2-46d9-aec1-23d437ec2bf5` - -"Root Verity Partition (amd64/x86_64)" from the -https://systemd.io/DISCOVERABLE_PARTITIONS/[Discoverable Partitions -Specification]. - -=== `9293e1ff-cee4-4658-88be-898ec863944f` - -xref:user-partition.adoc[Spectrum user partition]. - -=== `56a3bbc3-aefa-43d9-a64d-7b3fd59bbc4e` - -https://github.com/endlessm/eos-installer["eosimages"] partition on the -Spectrum combined live system / installer image. - -== Combined Image Partition IDs - -These UUIDs are used as the unique partition identifiers for the -Spectrum combined live system / installer image. - -=== `6e23b026-9f1e-479d-8a58-a0cda382e1ce` - -The Spectrum installer system. - -''' - -== Finding Undocumented UUIDs - -Running the Documentation/scripts/undocumented-uuids.sh script from -the root of the Spectrum repository will scan the entire tree for -UUIDs not mentioned in this document. diff --git a/Documentation/development/user-partition.adoc b/Documentation/development/user-partition.adoc new file mode 100644 index 0000000..d8fd956 --- /dev/null +++ b/Documentation/development/user-partition.adoc @@ -0,0 +1,17 @@ += User Partition +:page-parent: Development +:page-nav_order: 5 + +// SPDX-FileCopyrightText: 2022 Alyssa Ross +// 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/development/uuid-reference.adoc b/Documentation/development/uuid-reference.adoc new file mode 100644 index 0000000..81300ee --- /dev/null +++ b/Documentation/development/uuid-reference.adoc @@ -0,0 +1,60 @@ += UUID Reference +:page-parent: Development +:page-nav_order: 6 + +// SPDX-FileCopyrightText: 2022 Alyssa Ross +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +https://en.wikipedia.org/wiki/Universally_unique_identifier[UUIDs] are +used extensively throughout Spectrum. When encountering a UUID in the +codebase, it can be difficult to understand what exactly the UUID +means, and where it originates from -- is it from some standard, or +Spectrum-specific? + +To solve this problem, this reference documents all of the UUIDs used +in Spectrum. + +== https://en.wikipedia.org/wiki/GUID_Partition_Table[GPT] Partition Types + +=== `c12a7328-f81f-11d2-ba4b-00a0c93ec93b` + +"EFI System Partition", from the https://uefi.org/specifications[UEFI +Specification]. + +=== `4f68bce3-e8cd-4db1-96e7-fbcaf984b709` + +"Root Partition (amd64/x86_64)" from the +https://uapi-group.org/specifications/specs/discoverable_partitions_specification/[Discoverable Partitions +Specification]. + +=== `2c7357ed-ebd2-46d9-aec1-23d437ec2bf5` + +"Root Verity Partition (amd64/x86_64)" from the +https://uapi-group.org/specifications/specs/discoverable_partitions_specification/[Discoverable Partitions +Specification]. + +=== `9293e1ff-cee4-4658-88be-898ec863944f` + +xref:user-partition.adoc[Spectrum user partition]. + +=== `56a3bbc3-aefa-43d9-a64d-7b3fd59bbc4e` + +https://github.com/endlessm/eos-installer["eosimages"] partition on the +Spectrum combined live system / installer image. + +== Combined Image Partition IDs + +These UUIDs are used as the unique partition identifiers for the +Spectrum combined live system / installer image. + +=== `6e23b026-9f1e-479d-8a58-a0cda382e1ce` + +The Spectrum installer system. + +''' + +== Finding Undocumented UUIDs + +Running the Documentation/scripts/undocumented-uuids.sh script from +the root of the Spectrum repository will scan the entire tree for +UUIDs not mentioned in this document. diff --git a/Documentation/index.adoc b/Documentation/index.adoc index e0a45c7..51a6e7d 100644 --- a/Documentation/index.adoc +++ b/Documentation/index.adoc @@ -15,7 +15,7 @@ lower barrier to entry and is easy to use and maintain. To learn about what Spectrum 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] +If you want to try Spectrum, see xref:installation/index.adoc[Build and Run] to setup a development environment. @@ -25,8 +25,8 @@ 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 + 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]. +If you are thinking of contributing to the Spectrum docs, see + xref:development/building-documentation.adoc[Building Documentation]. diff --git a/Documentation/scripts/undocumented-uuids.sh b/Documentation/scripts/undocumented-uuids.sh index c75bfd2..aa192e6 100755 --- a/Documentation/scripts/undocumented-uuids.sh +++ b/Documentation/scripts/undocumented-uuids.sh @@ -6,7 +6,7 @@ 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/appendices/uuid-reference.adoc +UUID_REFERENCE_PATH=Documentation/development/uuid-reference.adoc documented_uuids=$(mktemp) trap 'rm -f -- "$documented_uuids"' EXIT diff --git a/Documentation/using-spectrum/creating-vms.adoc b/Documentation/using-spectrum/creating-vms.adoc index 6847249..2c57562 100644 --- a/Documentation/using-spectrum/creating-vms.adoc +++ b/Documentation/using-spectrum/creating-vms.adoc @@ -8,7 +8,7 @@ == Configuration Each VM is configured using a directory under svc/data/ on the -xref:user-partition.adoc[user partition]. The name of the directory +xref:../development/user-partition.adoc[user partition]. The name of the directory determines the name of the VM. The directory can contain the following files: -- cgit 1.4.1