summary refs log tree commit diff
path: root/Documentation
Commit message (Collapse)AuthorAge
* Documentation: clarify use of announce@Alyssa Ross2024-01-19
| | | | | | | | There has never been a message sent to this list, because I consider the announcement list to be for communicating actionable things to potential users, and we haven't had any of those yet. Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Documentation: mention that bugs go to devel@Alyssa Ross2024-01-19
| | | | Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Documentation: improve prose of communication pageAlyssa Ross2024-01-19
| | | | | | | | | | | | There was a lot of fluff here that got in the way of actually finding the information people are coming to this page to find. "You are strongly encouraged to mirror them." is probably confusing to people who don't know what mirroring this, so rephrase this to make it clearer that this isn't something people need to worry about in that case. Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Documentation: remove references to mailman-webAlyssa Ross2024-01-19
| | | | | | | | | | | | | | | | | | | | | | | Bots have been nonconsensually creating mailman-web accounts for people to flood them with spam. Aside from using reCAPTCHA (ugh) or modifying mailman-web, the only thing I can really do to prevent this is to disable unauthenticated web subscriptions, and the creation of mailman-web accounts, which I have now done. Ideally, it would be possible to configure it so that creating mailman-web accounts is only allowed for email addresses that have already subscribed to the list by sending an email, but that's not currently the case. This makes Postorius useless to people who don't already have an account. Hyperkitty is still useful, but people without existing accounts won't be able to use it to post to the lists, and the UI still shows Sign In and Sign Up links, which is pretty confusing when signups are disabled. It doesn't really offer anything that public-inbox doesn't any more. As a result of these changes, I'm removing all references to mailman-web from the documentation. Signed-off-by: Alyssa Ross <hi@alyssa.is>
* .editorconfig: indent shell scripts with tabsAlyssa Ross2024-01-06
| | | | | | This was already mostly the case, but now it will be consistent. Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Filter Spectrum sources for each componentAlyssa Ross2023-12-17
| | | | | | | At long last, changing one file somewhere won't cause every Spectrum component to be rebuilt unnecessarily. Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Fix spelling errorsAlyssa Ross2023-12-17
| | | | | | | Fixes: 5ad4b02 ("Documentation: Architecture Decision Record") Fixes: 6dfedf9 ("Documentation: copy-edit and integrate ADRs") Fixes: 5a83707 ("host/start-vm: use OnceLock") Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Documentation: remove unused argumentAlyssa Ross2023-12-17
| | | | Signed-off-by: Alyssa Ross <hi@alyssa.is>
* pkgs: use filesets for srcAlyssa Ross2023-12-17
| | | | | | | | This will make it possible later to specify which directories actually need to be present to build a component, so changing a single file somewhere won't force rebuilds of every Spectrum component. Signed-off-by: Alyssa Ross <hi@alyssa.is>
* pkgs: call nixpkgs entrypoint outside of configAlyssa Ross2023-11-26
| | | | | | | By moving this call under our control, we can insert our own default Nixpkgs arguments, for example overlays, or maybe crossSystem. Signed-off-by: Alyssa Ross <hi@alyssa.is>
* lib: adjust interface for Nix filesAlyssa Ross2023-11-26
| | | | | | | | | | | | | | | | | | | | | | | This moves every directly-buildable Nix file in Spectrum from the old eval-config.nix interface to a new callPackage-based interface. This moves us in the direction of stopping files from directly importing each other, in favor of having a global package set that contains the Spectrum-specific packages. Aside from consistency with packages from Nixpkgs, the main advantage to this is that the packages will be correctly spliced, and so e.g. lseek being in nativeBuildInputs will now do the right thing. This is implemented using a scope, so the Spectrum packages are invisible to Nixpkgs, and are applied on top afterwards, in contrast to if an overlay was used. Having a customised package set also paves the way for bringing modifications to upstream packages (e.g. the Cloud Hypervisor virtio-gpu patches) into the Spectrum repository, allowing us to use an unmodified upstream Nixpkgs. Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Documentation/Gemfile.lock: add aarch64-linuxAlyssa Ross2023-11-22
| | | | | | I'm not sure why these all need to be listed out explicitly… Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Documentation: emphasize Matrix over IRCAlyssa Ross2023-08-30
| | | | | | | Most people probably want Matrix. People looking for IRC will still easily find it. Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Documentation: update participating.html linksAlyssa Ross2023-08-26
| | | | | | This page has been moved into the documentation. Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Documentation: restore participating.html anchorsAlyssa Ross2023-08-26
| | | | | | | | | | | This page used to be at <https://spectrum-os.org/participating.html>, which now redirects here. Let's keep the original anchors working. To have anchors for each mailing list, they have to be their own section. This probably makes more sense than a table anyway, and will render better on narrow viewports. Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Documentation: add missing copyright noticeAlyssa Ross2023-08-23
| | | | | | | This documentation was copied from the Spectrum website's participating.html, which I wrote while not working for Unikie. Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Documentation: suggest the new Matrix channelAlyssa Ross2023-08-23
| | | | | | | This is a port of www commit 2a73682 ("participating.html: suggest the new Matrix room"). Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Documentation: fix accidental highlight textAlyssa Ross2023-08-23
| | | | | | | | | AsciiDoctor will generate <mark> elements around text enclosed in '#' characters. We mean a literal hash. (Escaping the later '#' for the Matrix channel alias is unnecessary and in fact will just render a '\'). Signed-off-by: Alyssa Ross <hi@alyssa.is>
* host: add support for Wayland in VMsAlyssa Ross2023-07-28
| | | | | | | | | | | When a VM is configured with Wayland support, the ext-rc-init service will create an additional service to supervise the crosvm GPU backend, and start-vm will pass the required arguments to cloud-hypervisor to tell it how to connect to crosvm. Signed-off-by: Alyssa Ross <alyssa.ross@unikie.com> Signed-off-by: Alyssa Ross <hi@alyssa.is> Message-Id: <20230721180015.597099-6-hi@alyssa.is>
* Fix mixed indentationAlyssa Ross2023-06-01
| | | | Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Documentation: fix accidental anchor linksAlyssa Ross2023-05-29
| | | | | | | | | | | | | | | The xref macro is for cross references to internal links within the documentation, not external links. xref:https://… results in an anchor link. The existing doc-links test didn't catch this, because it operates at the HTTP level. But the problem is easy to spot in the sources, so I've added a new check that just greps for this pattern. Reported-by: Ryan Lahfa <ryan@lahfa.xyz> Fixes: 97cceff ("Documentation: add contributing information") Signed-off-by: Alyssa Ross <hi@alyssa.is> Message-Id: <20230527151152.2016164-1-hi@alyssa.is>
* Documentation: fix IRC and Matrix channel namesAlyssa Ross2023-05-27
| | | | | Fixes: 97cceff ("Documentation: add contributing information") Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Documentation: fix missing space after periodAlyssa Ross2023-05-27
| | | | | Fixes: 97cceff ("Documentation: add contributing information") Signed-off-by: Alyssa Ross <hi@alyssa.is>
* .b4-config: addAlyssa Ross2023-05-18
| | | | | | | b4 now supports reading this config file, which obsoletes the hack that was in shell.nix before. Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Run deadnixAlyssa Ross2023-04-27
| | | | Signed-off-by: Alyssa Ross <hi@alyssa.is>
* lib/config.default.nix: pin NixpkgsAlyssa Ross2023-04-08
| | | | | | | | | | | | This makes the common case of building Spectrum, using the default Nixpkgs, much easier. It's easy to make mistakes setting up NIX_PATH, so we should leave custom Nixpkgs to the config file or nix command line. This doesn't preclude using Flakes to pin Nixpkgs in future, if we end up going that route. Signed-off-by: Alyssa Ross <hi@alyssa.is>
* lib/eval-config.nix: expose defaults to configAlyssa Ross2023-04-08
| | | | | | | | It's quite likely that somebody doing a custom build of Spectrum might want to use a custom overlay without changing the underlying version of Nixpkgs. Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Documentation: the binary cache has logs againAlyssa Ross2023-03-12
| | | | | | | The Nix bug is fixed, and other bugs in the builder configuration are also fixed. Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Documentation: explain release builds and checksAlyssa Ross2023-03-12
| | | | Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Documentation: add "Developing Built-in Application VMs"Alyssa Ross2023-03-10
| | | | Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Documentation: move User Partition ahead in orderAlyssa Ross2023-03-10
| | | | | | | | This introduces a concept, so I think it makes sense for it to come ahead of debugging information and the UUID index. People will need to learn how Spectrum works before they can start debugging it! Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Documentation: explain VM shared directoriesAlyssa Ross2023-02-26
| | | | | Signed-off-by: Alyssa Ross <hi@alyssa.is> Message-Id: <20221010232909.1953738-5-hi@alyssa.is>
* lib/common.mk: initAlyssa Ross2023-02-22
| | | | | | | | | | | | | | | | | | | | | | | | | We can simplify our Makefiles a bit by moving some things into a library file. So far, I've done this for non-component-specific macros, and inference rules. Some tar2ext4 rules used a temporary file for the tar2ext4 invocation, and then moved the file into place when it was done, to prevent a half-built image sticking around if tar2ext4 died. According to POSIX, make should clean up any targets that didn't finish building if it's interrupted, so we should only end up with a half-built image if tar2ext4 crashes, e.g. due to running out of disk space. I think we should just ignore that possibility, since otherwise we'd have to write annoying make rules using temporary file names for every target, and if it does happen recovery is just a make clean away. With this, I've also made a small reorganisation. I got rid of the "nix" directory and created a "lib" directory, where I put eval-config.nix and the new common.mk file, since both are library code. checks.nix isn't really a library though, so I moved it into the "release" directory, since the only reference to it is in release.nix. Signed-off-by: Alyssa Ross <hi@alyssa.is>
* nix/eval-config.nix: fix custom configurationAlyssa Ross2023-02-22
| | | | | | | | | | | | | | | | | When I introduced the global src attribute, I broke custom configurations, since they wouldn't be passing that key in, and nor should they. To allow for non-customisable globals like src, we need to separate them from config. Here, I've modified eval-config.nix to take a callback, so that it can provide multiple attributes, and handle command line arguments itself so that doesn't need to be in every entry point any more. This gives us an interface similar to the NixOS module system's, where a variety of globals are available that can be pulled out of the passed attribute set as required, but with the additional advantage that files are usable directly from nix-build, and support command line arguments. Signed-off-by: Alyssa Ross <hi@alyssa.is> Fixes: 0149885 ("nix: centralise source cleaning")
* nix: centralise source cleaningAlyssa Ross2023-02-22
| | | | | | | | | This was getting very repetitive. Having a single copy of the sources shared between builds will also save on store space, and means we don't need to support overriding the path to the scripts directory in Makefiles. Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Documentation: swap order of Creating/Running VMsAlyssa Ross2023-02-21
| | | | | | | | | Somebody who's just trying out Spectrum is probably going to want to try out the built-in demo VMs (which is easy) before they get started creating their own VMs (which is hard). Signed-off-by: Alyssa Ross <hi@alyssa.is> Message-Id: <20230213205804.14375-1-hi@alyssa.is>
* Documentation: add more info about the installerAlyssa Ross2023-02-21
| | | | | | | | | | | | | | | | | 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@alyssa.is> Message-Id: <20230211145825.740965-1-hi@alyssa.is>
* Documentation: move "Working with Patches" under "Contributing"Alyssa Ross2023-02-21
| | | | | | | | This is all information about how to contribute to Spectrum, so I think it makes more sense here than under "Development". Signed-off-by: Alyssa Ross <hi@alyssa.is> Message-Id: <20230211145650.740649-1-hi@alyssa.is>
* Documentation: add contributing informationJenni Nikolaenko2023-01-20
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Hello there! I decided to create a patch from my drafts so this information will not be lost. It still needs some attention. It is a good idea to have the documentation in one place. For us this means that information from these pages https://spectrum-os.org/contributing.html, https://spectrum-os.org/participating.html -- should be moved here https://spectrum-os.org/participating.html. What I did particularly: 1. Added a new chapter "Contributing". Copied here the information from here https://spectrum-os.org/contributing.html, adapting a bit to Spectrum Docs. 2. Moved the "Building Documentation" section from "Development" to "Contributing". 3. In the "Contributing" chapter you can find the following structure: - Communication in Spectrum (copied from https://spectrum-os.org/participating.html) - Documentation Style Guide - Building Documentation I tried to fix all cross-reference links, so this new content can be used right now. Any further updates are very welcome. Signed-off-by: Jenni Nikolaenko <evgeniia.nikolaenko@unikie.com> Message-Id: <20230119154307.28303-1-evgeniia.nikolaenko@unikie.com> Reviewed-by: Alyssa Ross <hi@alyssa.is> Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Documentation/scripts/build.sh: avoid unquoted varAlyssa Ross2023-01-17
| | | | | | | | | | | | | Recent versions of shellcheck warn about word splitting on JEKYLLFLAGS. To avoid this, let's switch to using "$@" to store the Jekyll command line we're building up. This also gives us a consistent way to pass extra arguments to Jekyll. They just need to be specified on the command line — we can remove special handling for the destination by just having the caller pass -d like they would when dealing with Jekyll directly. Signed-off-by: Alyssa Ross <hi@alyssa.is>
* Documentation: fix faviconAlyssa Ross2022-11-24
| | | | | | | | | | The Just the Docs default was pointing this to https://spectrum-os.org/doc/favicon.ico, which does not exist. Copyright notice (not that this is likely to be copyrightable) is myself from 2020 as I copied this from the Spectrum www repo. Signed-off-by: Alyssa Ross <alyssa.ross@unikie.com>
* Documentation: update gemsAlyssa Ross2022-11-24
| | | | Signed-off-by: Alyssa Ross <alyssa.ross@unikie.com>
* Documentation: update-gems.sh: cd to the right dirAlyssa Ross2022-11-24
| | | | | | | | This makes it possible to run Documentation/scripts/update-gems.sh from the root of the source tree as well as from the Documentation directory. Signed-off-by: Alyssa Ross <alyssa.ross@unikie.com>
* Documentation: move Appendices to Development, fixed linksJenni Nikolaenko2022-11-22
| | | | | | | | | | | | | | | 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 <evgeniia.nikolaenko@unikie.com> Message-Id: <20221121131817.15162-1-evgeniia.nikolaenko@unikie.com> Reviewed-by: Alyssa Ross <alyssa.ross@unikie.com> Tested-by: Alyssa Ross <alyssa.ross@unikie.com> Signed-off-by: Alyssa Ross <alyssa.ross@unikie.com>
* Documentation/scripts: fix shellcheck issuesAlyssa Ross2022-11-18
| | | | | | | | | There's an open issue about teaching shellcheck to automatically recognize nix-shell shebangs: https://github.com/koalaman/shellcheck/issues/1210 Signed-off-by: Alyssa Ross <alyssa.ross@unikie.com> Message-Id: <20221118100947.33597-1-alyssa.ross@unikie.com>
* Documentation: rename "Getting Started" to "Using Spectrum"Alyssa Ross2022-11-18
| | | | | | | | | | | | I clicked on "Getting Started" by mistake expecting to find the documentation about obtaining and installing a Spectrum image, but it actually contains documentation that explains how to use the system once it's installed. So I think it would be clearer if it were named "Using Spectrum". Signed-off-by: Alyssa Ross <alyssa.ross@unikie.com> Cc: Jenni Nikolaenko <evgeniia.nikolaenko@unikie.com> Message-Id: <20221116105450.610594-1-alyssa.ross@unikie.com>
* Documentation: rename "UUID" to "UUID Reference"Alyssa Ross2022-11-18
| | | | | | | | | | | | | | | | | | The purpose of this document is specifically to provide a reference table so that developers working with Spectrum can easily look up a given UUID to find out what it means. I think "UUID Reference" makes it clearer what the reader will find in this document, as I'd expect a document just called "UUID" to be something that explained e.g. what a UUID is. (I don't think we need to explain that at all in the Spectrum documentation, as we link to Wikipedia, which explains it well, and it's background knowledge that most developers looking to work with Spectrum will likely already have.) Signed-off-by: Alyssa Ross <alyssa.ross@unikie.com> Cc: Jenni Nikolaenko <evgeniia.nikolaenko@unikie.com> Message-Id: <20221116105423.610445-1-alyssa.ross@unikie.com>
* release: rename from "img"Alyssa Ross2022-11-13
| | | | | | | | I think this is more descriptive, and "img" is a name better used for VM images. Signed-off-by: Alyssa Ross <hi@alyssa.is> Message-Id: <20221009114036.463071-6-hi@alyssa.is>
* host/start-vm: support multiple block devicesAlyssa Ross2022-11-13
| | | | | | | | | | | | | | This is the first step to being able to do things like having a static base image for an application VM, and another image containing the application to run. When we actually use multiple images we'll need to change how we boot so we know the kernel is booting from the right image — probably by PARTUUID or PARTLABEL — because we can't guarantee how the kernel orders disks inside the VM. Signed-off-by: Alyssa Ross <hi@alyssa.is> Message-Id: <20221009114036.463071-2-hi@alyssa.is>
* Remove bashisms from spectrum shell scriptsHenri Rosten2022-11-09
| | | | | | | | | | | | | | | | 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. Also updates the path to the UUID reference used in undocumented-uuids.sh. Signed-off-by: Henri Rosten <henri.rosten@unikie.com> Message-Id: <20221109132730.941054-1-henri.rosten@unikie.com> Fixes: 0a2a5c6 ("Docs: new structure") Reviewed-by: Alyssa Ross <alyssa.ross@unikie.com> Tested-by: Alyssa Ross <alyssa.ross@unikie.com> Signed-off-by: Alyssa Ross <alyssa.ross@unikie.com>
generated by cgit-pink 1.4.1 (git 2.36.1) at 2024-05-17 21:06:14 +0000