From c0929e759c7fc024c59ec3aacabb23fc390bc2ea Mon Sep 17 00:00:00 2001 From: fiftydinar <65243233+fiftydinar@users.noreply.github.com> Date: Sun, 21 Jul 2024 21:21:28 +0200 Subject: [PATCH] docs: Update documentation to reflect change from `config/` to `files/` (#283) * docs: Update documentation to reflect change from `config/` to `files/` * docs(files): Match documentation between template & module.yml * docs(files): Add example about using subfolder * docs(files): Some small style fixes * docs: Fix `files/system` typo Co-authored-by: xyny <60004820+xynydev@users.noreply.github.com> * docs: Fix `files/system` typo pt. 2 Co-authored-by: xyny <60004820+xynydev@users.noreply.github.com> * chore(files): Update typespec to be compatible with legacy & new recipe Co-authored-by: xyny <60004820+xynydev@users.noreply.github.com> --------- Co-authored-by: xyny <60004820+xynydev@users.noreply.github.com> --- modules/files/README.md | 36 ++++++++++++++--------------- modules/files/files.tsp | 9 +++++--- modules/files/module.yml | 9 ++++---- modules/gschema-overrides/README.md | 14 +++++------ modules/justfiles/README.md | 10 ++++---- modules/script/README.md | 4 ++-- modules/systemd/README.md | 4 ++-- 7 files changed, 44 insertions(+), 42 deletions(-) diff --git a/modules/files/README.md b/modules/files/README.md index fae4ce2..84b6ef0 100644 --- a/modules/files/README.md +++ b/modules/files/README.md @@ -1,32 +1,32 @@ # `files` -The `files` module can be used to copy directories from `config/files` to +The `files` module can be used to copy directories from `files/` to any location in your image at build time, as long as the location exists at -build time (e.g. you can't put files in `/home/`, because users +build time (e.g. you can't put files in `/home//`, because users haven't been created yet prior to first boot). :::note -If you want to place files into `/etc`, there are two ways to do it: +If you want to place files into `/etc/`, there are two ways to do it: -1. copying a directory in `config/files` directly to `/etc` to add all of its +1. copying a directory in `files/` directly to `/etc` to add all of its files at build time, or -2. putting the files you want there in `/usr/etc` as part of copying things - over to `/usr`, which `rpm-ostree` will then copy to `/etc` at runtime/boot. +2. putting the files you want there in `/usr/etc/` as part of copying things + over to `/usr/`, which `rpm-ostree` will then copy to `/etc/` at runtime/boot. -Typically, you will want to use the latter option (putting files in `/usr/etc`) +Typically, you will want to use the latter option (putting files in `/usr/etc/`) in almost all cases, since that is the proper directory for "system" -configuration templates on atomic Fedora distros, whereas `/etc` is meant for +configuration templates on atomic Fedora distros, whereas `/etc/` is meant for manual overrides and editing by the machine's admin *after* installation (see issue https://github.com/blue-build/legacy-template/issues/28). However, if you -really need something to be in `/etc` *at build time* --- for instance, if you -for some reason need to place a repo file in `/etc/yum.repos.d` in such a way +really need something to be in `/etc/` *at build time* --- for instance, if you +for some reason need to place a repo file in `/etc/yum.repos.d/` in such a way that it is used by a `rpm-ostree` module later on --- then the former option will be necessary. ::: :::caution The `files` module **cannot write to directories that will later be symlinked -to point to other places (typically `/var`) by `rpm-ostree`**. +to point to other places (typically `/var/`) by `rpm-ostree`**. This is because it doesn't make sense for a directory to be both a symlink and a real directory that has had actual files directly copied to it, so the @@ -39,13 +39,13 @@ documentation](https://docs.fedoraproject.org/en-US/fedora-silverblue/technical- here is a list of the directories that `rpm-ostree` symlinks to other locations: -- `/home` → `/var/home` -- `/opt` → `/var/opt` -- `/srv` → `/var/srv` -- `/root` → `/var/roothome` -- `/usr/local` → `/var/usrlocal` -- `/mnt` → `/var/mnt` -- `/tmp` → `/sysroot/tmp` +- `/home/` → `/var/home/` +- `/opt/` → `/var/opt/` +- `/srv/` → `/var/srv/` +- `/root/` → `/var/roothome/` +- `/usr/local/` → `/var/usrlocal/` +- `/mnt/` → `/var/mnt/` +- `/tmp/` → `/sysroot/tmp/` So don't use `files` to copy any files to any of the directories on the left, because at runtime `rpm-ostree` will want to link them to the ones on the diff --git a/modules/files/files.tsp b/modules/files/files.tsp index a80c994..f6a826a 100644 --- a/modules/files/files.tsp +++ b/modules/files/files.tsp @@ -8,6 +8,9 @@ model FilesModule { */ type: "files"; - /** List of files / folders to copy. Format is: `sourcefile.txt: /destination/file.txt` */ - files: Array>; -} \ No newline at end of file + /** List of files / folders to copy. */ + files: Array> | Array<{ + source: string; + destination: string; + }>; +} diff --git a/modules/files/module.yml b/modules/files/module.yml index daebb9c..bc89139 100644 --- a/modules/files/module.yml +++ b/modules/files/module.yml @@ -6,8 +6,7 @@ example: | modules: - type: files files: - - usr: /usr # copies config/files/usr into your images /usr - # put configuration files you want in /etc/ on a *booted* - # system in /usr/etc/ in the image. - - etc: /etc # copies config/files/etc into your image's /etc immediately, - # for use with further modules. + - source: system # copies `files/system/*` (* means everything inside it) into your image's root folder `/` + destination: / + - source: my-image/usr # copies `files/my-image/usr/*` to `/usr/` inside the image + destination: /usr diff --git a/modules/gschema-overrides/README.md b/modules/gschema-overrides/README.md index 43ce535..50cf20e 100644 --- a/modules/gschema-overrides/README.md +++ b/modules/gschema-overrides/README.md @@ -6,27 +6,27 @@ This module is similar to using `dconf` configuration, but is better because it What does this module do? -- It copies all content from `/usr/share/glib-2.0/schemas`, except existing gschema.overrides to avoid conflicts, into temporary test location. -- It copies your gschema.overrides you provided in this module from `config/gschema-overrides` into temporary test location. +- It copies all content from `/usr/share/glib-2.0/schemas/`, except existing gschema.overrides to avoid conflicts, into temporary test location. +- It copies your gschema.overrides you provided in this module from `files/gschema-overrides/` into temporary test location. - It tests them for errors in temporary test location by using `glib-compile-schemas` with `--strict` flag. If errors are found, build will fail. -- If test is passed successfully, it copies your gschema.overrides to `/usr/share/glib-2.0/schemas`. -- It compiles gschema using `glib-compile-schemas` in `/usr/share/glib-2.0/schemas` location to include your changes. +- If test is passed successfully, it copies your gschema.overrides to `/usr/share/glib-2.0/schemas/`. +- It compiles gschema using `glib-compile-schemas` in `/usr/share/glib-2.0/schemas/` location to include your changes. Temporary test location is: -`/tmp/bluebuild-schema-test` +`/tmp/bluebuild-schema-test/` ## Usage To use this module, you need to include your gschema.override file(s) in this location (make folder if it doesn't exist): -`config/gschema-overrides` +`files/gschema-overrides/` Then you need to include those file(s) in recipe file, like in example configuration. It is highly recommended to use `zz1-` prefix before your gschema.override name, to ensure that your changes are going to be applied. -Also don't forget to rename your file(s) too with this prefix in `config/gschema-overrides`. +Also don't forget to rename your file(s) too with this prefix in `files/gschema-overrides/`. ## Creating gschema.override files diff --git a/modules/justfiles/README.md b/modules/justfiles/README.md index 605fb60..6b0f063 100644 --- a/modules/justfiles/README.md +++ b/modules/justfiles/README.md @@ -18,15 +18,15 @@ For more information, refer to these links: ## What the module does -1. The module checks if the `config/justfiles/` folder is present. +1. The module checks if the `files/justfiles/` folder is present. * If it's not there, it fails. -2. The module finds all `.just` files inside of the `config/justfiles/` folder or starting from the relative path specified under `include`. +2. The module finds all `.just` files inside of the `files/justfiles/` folder or starting from the relative path specified under `include`. * If no `.just` files are found, it fails. - * The structure of the `config/justfiles/` folder does not matter, folders/files can be placed in there however desired, the module will find all `.just` files. + * The structure of the `files/justfiles/` folder does not matter, folders/files can be placed in there however desired, the module will find all `.just` files. * Optionally, the `.just` files can be validated. @@ -42,9 +42,9 @@ For more information, refer to these links: ## How to use the module -Place all your `.just` files or folders with `.just` files inside the `config/justfiles/` folder. If that folder doesn't exist, create it. +Place all your `.just` files or folders with `.just` files inside the `files/justfiles/` folder. If that folder doesn't exist, create it. -By default, the module will import all files with names ending in `.just` from `config/justfiles/`. You can also specify files or subfolders under `include`, and they will be the only ones imported. +By default, the module will import all files with names ending in `.just` from `files/justfiles/`. You can also specify files or subfolders under `include`, and they will be the only ones imported. If you also want to validate your justfiles, set `validate: true`. The validation can be very unforgiving and is turned off by default. diff --git a/modules/script/README.md b/modules/script/README.md index ecdde85..05d5945 100644 --- a/modules/script/README.md +++ b/modules/script/README.md @@ -3,7 +3,7 @@ The `script` module can be used to run arbitrary bash snippets and scripts at image build time. This is intended for running commands that need no YAML configuration. The snippets, which are run in a bash subshell, are declared under `snippets:`. -The scripts, which are run from the `config/scripts` directory, are declared under `scripts:`. +The scripts, which are run from the `files/scripts/` directory, are declared under `scripts:`. ## Creating a Script @@ -16,4 +16,4 @@ When creating a script, please make sure - ...it starts with a [shebang]() like `#!/usr/bin/env bash`. - This ensures the script is ran with the correct interpreter / shell. - ...it contains the command `set -euo pipefail` right after the shebang. - - This will make the image build fail if your script fails. If you do not care if your script works or not, you can omit this line. \ No newline at end of file + - This will make the image build fail if your script fails. If you do not care if your script works or not, you can omit this line. diff --git a/modules/systemd/README.md b/modules/systemd/README.md index 41adbfd..5ffda91 100644 --- a/modules/systemd/README.md +++ b/modules/systemd/README.md @@ -4,8 +4,8 @@ The `systemd` module streamlines the management of systemd units during image bu You can also include your systemd units to be copied into system directories into these locations, depending if your unit is `system` or `user` based: -`config/systemd/system` -`config/systemd/user` +`files/systemd/system/` +`files/systemd/user/` Those units are then copied into these folders (depending on unit base): `/usr/lib/systemd/system`