docs: move usage guides to usage/, add quickstart and porting

docs/source/usage/config.md

@@ -0,0 +1,121 @@
+# Configuration
+
+Kupferbootstrap uses [toml](https://en.wikipedia.org/wiki/TOML) for its configuration file.
+
+The file can either be edited manually or managed via the {doc}`../cli/config` subcommand.
+
+You can quickly generate a default config by running {code}`kupferbootstrap config init -N`.
+
+## File Location
+
+The configuration is stored in `~/.config/kupfer/kupferbootstrap.toml`, where `~` is your user's home folder.
+
+Kupferbootstrap needs to create a number of folders, e.g. to download `PKGBUILDs.git` and store binary packages.
+By default, all of those folders live inside `~/.cache/kupfer/`.
+
+See also the `[paths]` section in your config.
+
+## Sections
+
+A config file is split into sections like so:
+
+```toml
+[pkgbuilds]
+git_repo = "https://gitlab.com/kupfer/packages/pkgbuilds.git"
+git_branch = "dev"
+
+[pacman]
+parallel_downloads = 3
+```
+
+Here, we have two sections: `pkgbuilds` and `pacman`.
+
+## Flavours
+
+Flavours are preset collections of software and functionality to enable,
+i.e. desktop environments like [Gnome](https://en.wikipedia.org/wiki/GNOME)
+and [Phosh](https://en.wikipedia.org/wiki/Phosh).
+
+## Profiles
+
+The last section and currently the only one with subsections is the `profiles` section.
+
+A profile is the configuration of a specific device image. It specifies (amongst others):
+
+- the device model
+- the flavour (desktop environment)
+- the host- and user name
+- extra packages to install
+
+Using a profile's `parent` key,
+you can inherit settings from another profile.
+
+This allows you to easily keep a number of slight variations of the same target profile around
+without the need to constantly modify your Kupferbootstrap configuration file.
+
+You can easily create new profiles with
+[kupferbootstrap config profile init](/cli/config/#kupferbootstrap-config-profile-init).
+
+Here's an example:
+
+```toml
+[profiles]
+current = "graphical"
+
+[profiles.default]
+parent = ""
+device = "sdm845-oneplus-enchilada"
+flavour = "barebone"
+pkgs_include = [ "wget", "rsync", "nano", "tmux", "zsh", "pv", ]
+pkgs_exclude = []
+hostname = "kupferphone"
+username = "prawn"
+size_extra_mb = 800
+
+[profiles.graphical]
+parent = "default"
+flavour = "phosh"
+pkgs_include = [ "firefox", "tilix", "gnome-tweaks" ]
+size_extra_mb = "+3000"
+
+[profiles.hades]
+parent = "graphical"
+flavour = "phosh"
+hostname = "hades"
+
+[profiles.recovery]
+parent = "default"
+flavour = "debug-shell"
+
+[profiles.beryllium]
+parent = "graphical"
+device = "sdm845-xiaomi-beryllium-ebbg"
+flavour = "gnome"
+hostname = "pocof1"
+```
+
+The `current` key in the `profiles` section controlls which profile gets used by Kupferbootstrap by default.
+
+The first subsection (`profiles.default`) describes the `default` profile
+which gets created by [config init](/cli/config/#kupferbootstrap-config-init).
+
+Next, we have a `graphical` profile that defines a couple of graphical programs for all but the `recovery` profile,
+since that doesn't have a GUI.
+
+### `size_extra_mb`
+
+Note how `size_extra_mb` can either be a plain integer (`800`) or a string,
+optionally leading with a plus sign (`+3000`),
+which instructs Kupferbootstrap to add the value to the parent profile's `size_extra_mb`.
+
+### `pkgs_include` / `pkgs_exclude`
+
+Like `size_extra_mb`, `pkgs_include` will be merged with the parent profile's `pkgs_include`.
+
+To exclude unwanted packages from being inherited from a parent profile, use `pkgs_exclude` in the child profile.
+
+```{hint}
+`pkgs_exclude` has no influence on Pacman's dependency resolution.
+It only blocks packages during image build that would usually be explicitly installed
+due to being listed in a parent profile or the selected flavour.
+```

docs/source/usage/faq.md

@@ -0,0 +1,39 @@
+# FAQ
+
+
+```{contents} Table of Contents
+:class: this-will-duplicate-information-and-it-is-still-useful-here
+:depth: 3
+```
+
+
+## Which devices are currently supported?
+
+Currently very few!  
+See [the `devices` repo](https://gitlab.com/kupfer/packages/pkgbuilds/-/tree/dev/device). We use the same codenames as [postmarketOS](https://wiki.postmarketos.org/wiki/Devices) (although we prefix them with the SoC)
+
+
+## How to port a new device or package?
+
+See [Porting](../porting)
+
+## How to build a specific package
+
+See also: The full [`kupferbootstrap packages build` docs](/cli/packages#kupferbootstrap-packages-build)
+
+### Example
+
+For rebuilding `kupfer-config` and `crossdirect`, defaulting to your device's architecture
+
+```sh
+kupferbootstrap packages build [--force] [--arch $target_arch] kupfer-config crossdirect
+```
+
+
+### By package path
+You can also use the a path snippet (`$repo/$pkgbase`) to the PKGBUILD folder as seen inside your pkgbuilds.git:
+
+```sh
+kupferbootstrap packages build [--force] main/kupfer-config cross/crossdirect
+```
+

docs/source/usage/index.md

@@ -0,0 +1,9 @@
+# Usage
+
+```{toctree}
+quickstart
+faq
+install
+config
+porting
+```

docs/source/usage/install.md

@@ -0,0 +1,32 @@
+# Installation
+
+1. Install Python 3, Docker, and git.
+
+   On Arch: `pacman -S python docker git --needed --noconfirm`
+
+   ```{Hint}
+   After installing Docker you will have to add your user to the `docker` group:
+
+   `sudo usermod -aG docker "$(whoami)"`
+
+   Then restart your desktop session for the new group to take effect.
+   ```
+
+2. Pick which Kupferbootstrap branch to clone: usually either `main` or `dev`
+
+3. Clone the repository: `git clone -b INSERT_BRANCHNAME_HERE https://gitlab.com/kupfer/kupferbootstrap`
+
+4. Change into the folder: `cd kupferbootstrap`
+
+5. Install python dependencies: `pip3 install -r requirements.txt`
+
+   ```{Note}
+   Most of our python dependencies are available as distro packages on most distros,
+   sadly it's incomplete on Arch.
+
+   See `requirements.txt` for the list of required python packages.
+   ```
+
+6. Symlink `kupferbootstrap` into your `$PATH`: `sudo ln -s "$(pwd)/bin/kupferbootstrap" /usr/local/bin/`
+
+7. You should now be able to run `kupferbootstrap --help`!

docs/source/usage/porting.md

@@ -0,0 +1,94 @@
+# Porting
+## Porting devices
+
+### Homework
+Before you can get started porting a device, you'll need to do some research:
+
+1. Familiarize yourself with git basics.
+1. Familiarize yourself with Arch Linux packaging, i.e. `PKGBUILD`s and `makepkg`
+1. Familiarize yourself with the postmarketOS port of the device.
+   ```{warning}
+    If there is no postmarketOS port yet, you'll probably need to get deep into kernel development.  
+    We suggest [starting with a port to pmOS](https://wiki.postmarketos.org/wiki/Porting_to_a_new_device) then, especially if you're not familiar with the process already.
+    ```
+
+### Porting
+1. Navigate to your pkgbuilds checkout
+1. Follow the [general package porting guidelines](#porting-packages) to create a device-, kernel- and probably also a firmware-package for the device and SoC. Usually this roughly means porting the postmarketOS APKBUILDs to our PKGBUILD scheme.  
+   You can get inspiration by comparing existing Kupfer ports (e.g. one of the SDM845 devices) to the [postmarketOS packages](https://gitlab.com/postmarketOS/pmaports/-/tree/master/device) for that device.
+   Usually you should start out by copying and then customizing the Kupfer packages for a device that's as similar to yours as possible, i.e. uses the same or a related SoC, if something like that is already available in Kupfer.
+   ```{hint} Package Repos:
+   Device packages belong into `device/`, kernels into `linux/` and firmware into `firmware/`.
+   ```
+1. When submitting your MR, please include some information:
+    - what you have found to be working, broken, and not tested (and why)
+    - any necessary instructions for testing
+    - whether you'd be willing to maintain the device long-term (test kernel upgrades, submit device package updates, etc.)
+
+
+### Gotchas
+
+Please be aware of these gotchas:
+- As of now, Kupfer only really supports platforms using Android's `aboot` bootloader, i.e. ex-Android phones. In order to support other boot modes (e.g. uboot on the Librem5 and Pine devices), we'll need to port and switch to postmarketOS's [boot-deploy](https://gitlab.com/postmarketOS/boot-deploy) first and add support for EFI setups to Kupferbootstrap.
+
+
+## Porting packages
+
+### Homework
+Before you can get started, you'll need to do some research:
+
+1. Familiarize yourself with git basics.
+1. Familiarize yourself with Arch Linux packaging, i.e. `PKGBUILD`s and `makepkg`
+
+### Development
+
+```{warning}
+Throughout the process, use git to version your changes.  
+- Don't procrastinate using git or committing until you're "done" or "have got something working", you'll regret it.  
+- Don't worry about a "clean" git history while you're developing; we can squash it up later.
+- \[Force-]Push your changes regularly, just like committing. Don't wait for perfection.
+```
+1. Create a new git branch for your package locally.
+   ```{hint}
+   It might be a good ideaa to get into the habit of prefixing branch names with \[a part of] your username and a slash like so:  
+   `myNickname/myFeatureNme`  
+   This makes it easier to work in the same remote repo with multiple people.
+   ```
+1. 
+   ```{note}
+   The pkgbuilds git repo contains multiple package repositories, represented by folders at the top level (`main`, `cross`, `phosh`, etc.).  
+   ```
+   Try to choose a sensible package repo for your new packages and create new folders for each `pkgbase` inside the repo folder.
+1. Navigate into the folder of the new package and create a new `PKGBUILD`; fill it with life!
+1. **`_mode`**: Add the build mode at the top of the PKGBUILD.
+   ```{hint}
+   If you're unsure what to pick, go with `_mode=host`. It'll use `crossdirect` to get speeds close to proper cross-compiling.
+   ```
+   This determines whether it's built using a foreign-arch chroot (`_mode=host`) executed with qemu-user, or using real cross-compilation (`_mode=cross`) from a host-architecture chroot, but the package's build tooling has to specifically support the latter, so it's mostly useful for kernels and uncompiled packages.
+1. **`_nodeps`**: (Optional) If your package doesn't require its listed dependencies to build
+   (usually because you're packaging a meta-package or only configs or scripts)
+   you can add `_nodeps=true` as the next line after the `_mode=` line to speed up packaging.
+   `makedeps` are still installed anyway.
+1. Test building it with `kupferbootstrap packages build $pkgbname`
+1. For any files and git repos downloaded by your PKGBUILD,
+   add them to a new `.gitignore` file in the same directory as your `PKGBUILD`.  
+   ```{hint}
+   Don't forget to `git add` the new `.gitignore` file!
+   ```
+1. Run `kupferbootstrap packages check` to make sure the formatting for your PKGBUILDs is okay.
+   ```{warning}
+   This is **not** optional. MRs with failing CI will **not** be merged.
+   ```
+
+### Pushing
+1. Fork the Kupfer pkgbuilds repo on Gitlab using the Fork button
+1. Add your fork's **SSH** URI to your local git repo as a **new remote**: `git remote add fork git@gitlab...`
+1. `git push -u fork $branchname` it
+
+### Submitting the MR
+When you're ready, open a Merge Request on the Kupfer pkgbuilds repo.
+
+```{hint}
+Prefix the MR title with `Draft: ` to indicate a Work In Progress state.
+```
+

docs/source/usage/quickstart.md

@@ -0,0 +1,9 @@
+# Quickstart
+
+1. [Install](../install) Kupferbootstrap
+1. [Configure](../config) it: `kuperbootstrap config init`
+1. [Update your PKGBUILDs + SRCINFO cache](/cli/packages#kupferbootstrap-packages-update): `kupferbootstrap packages update`
+1. [Build an image](/cli/image#kupferbootstrap-image-build): `kupferbootstrap image build`
+1. [Flash the image](/cli/image#kupferbootstrap-image-flash): `kupferbootstrap image flash abootimg && kupferbootstrap image flash full userdata`
+
+See also: [Frequently Asked Questions](../faq)