Some shortcomings in this section were reported to me privately:
• It wasn't clear what the image being built was for. Was it a live
image, or an installer image? (It's both.)
• It wasn't clear what to do with the built image, so I've explained
that it should be put on a USB drive and booted from.
I've also made it clear that there's not much point going through the
extra step to actually install Spectrum yet, at least until we have
some sort of exposed persistent storage.
Signed-off-by: Alyssa Ross <hi(a)alyssa.is>
---
.../installation/getting-spectrum.adoc | 28 +++++++++++++++++--
1 file changed, 25 insertions(+), 3 deletions(-)
diff --git a/Documentation/installation/getting-spectrum.adoc b/Documentation/installation/getting-spectrum.adoc
index 6aec34f..8ee31b7 100644
--- a/Documentation/installation/getting-spectrum.adoc
+++ b/Documentation/installation/getting-spectrum.adoc
@@ -2,7 +2,7 @@
:page-parent: Build and Run
:page-nav_order: 2
-// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi(a)alyssa.is>
+// SPDX-FileCopyrightText: 2022-2023 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
@@ -35,7 +35,15 @@ 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 Installer
+== Installing Spectrum
+
+To install Spectrum on a computer, you can use a USB drive as a
+bootable Spectrum installer device. When booting a system from the
+installer device, you will be able to choose whether to try out
+Spectrum without installing it on your system (as a live image), or to
+install it to your computer's internal storage.
+
+First, you need to build the Spectrum image:
[source,shell]
----
@@ -46,7 +54,21 @@ nix-build spectrum/release/combined \
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.
+"result" will appear in the current directory, pointing to the
+installer image. Write that image to a USB drive, for example using
+`dd` (command line) or
+https://gitlab.com/bztsrc/usbimager[`usbimager`] (graphical, available
+in Nixpkgs). Boot your system from the USB drive, and you should see
+a menu allowing you to choose between "Try Spectrum" and "Install
+Spectrum".
+
+NOTE: While it's possible to install Spectrum to your internal
+storage, at this point in Spectrum's development there is not much
+reason to, as OS updates are not yet implemented, and persistent
+storage is not yet exposed to VMs. Using the "Try Spectrum" option to
+boot Spectrum will let you try out everything in Spectrum, without
+having to go through the additional step of reinstalling Spectrum
+every time you want to use a newer version.
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
--
2.37.1
