particle-os/particle-os-modules
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: Update documentation to reflect change from config/ to files/ (#283)

Browse source 
* 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>
This commit is contained in:
fiftydinar 2024-07-21 21:21:28 +02:00 • committed by GitHub
parent 3b30283a6a
commit c0929e759c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 44 additions and 42 deletions
Download patch file Download diff file Expand all files Collapse all files

36
modules/files/README.md
View file

@ -1,32 +1,32 @@
# `files` # `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 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/<username>`, because users build time (e.g. you can't put files in `/home/<username>/`, because users
haven't been created yet prior to first boot). haven't been created yet prior to first boot).
:::note :::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 files at build time, or
2. putting the files you want there in `/usr/etc` as part of copying things 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. 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" 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 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 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 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 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 that it is used by a `rpm-ostree` module later on --- then the former option
will be necessary. will be necessary.
::: :::
:::caution :::caution
The `files` module **cannot write to directories that will later be symlinked 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 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 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 here is a list of the directories that `rpm-ostree` symlinks to other
locations: locations:
- `/home` → `/var/home` - `/home/` → `/var/home/`
- `/opt` → `/var/opt` - `/opt/` → `/var/opt/`
- `/srv` → `/var/srv` - `/srv/` → `/var/srv/`
- `/root` → `/var/roothome` - `/root/` → `/var/roothome/`
- `/usr/local` → `/var/usrlocal` - `/usr/local/` → `/var/usrlocal/`
- `/mnt` → `/var/mnt` - `/mnt/` → `/var/mnt/`
- `/tmp` → `/sysroot/tmp` - `/tmp/` → `/sysroot/tmp/`
So don't use `files` to copy any files to any of the directories on the left, 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 because at runtime `rpm-ostree` will want to link them to the ones on the

9
modules/files/files.tsp
View file

@ -8,6 +8,9 @@ model FilesModule {
*/ */
type: "files"; type: "files";
/** List of files / folders to copy. Format is: `sourcefile.txt: /destination/file.txt` */ /** List of files / folders to copy. */
files: Array<Record<string>>; files: Array<Record<string>> | Array<{
} source: string;
destination: string;
}>;
}

9
modules/files/module.yml
View file

@ -6,8 +6,7 @@ example: |
modules: modules:
- type: files - type: files
files: files:
- usr: /usr # copies config/files/usr into your images /usr - source: system # copies `files/system/*` (* means everything inside it) into your image's root folder `/`
# put configuration files you want in /etc/ on a *booted* destination: /
# system in /usr/etc/ in the image. - source: my-image/usr # copies `files/my-image/usr/*` to `/usr/` inside the image
- etc: /etc # copies config/files/etc into your image's /etc immediately, destination: /usr
# for use with further modules.

14
modules/gschema-overrides/README.md
View file

@ -6,27 +6,27 @@ This module is similar to using `dconf` configuration, but is better because it
What does this module do? 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 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 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. - 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`. - 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. - It compiles gschema using `glib-compile-schemas` in `/usr/share/glib-2.0/schemas/` location to include your changes.
Temporary test location is: Temporary test location is:
`/tmp/bluebuild-schema-test` `/tmp/bluebuild-schema-test/`
## Usage ## Usage
To use this module, you need to include your gschema.override file(s) in this location (make folder if it doesn't exist): 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. 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. 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 ## Creating gschema.override files

10
modules/justfiles/README.md
View file

@ -18,15 +18,15 @@ For more information, refer to these links:
## What the module does ## 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. * 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. * 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. * Optionally, the `.just` files can be validated.
@ -42,9 +42,9 @@ For more information, refer to these links:
## How to use the module ## 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. If you also want to validate your justfiles, set `validate: true`. The validation can be very unforgiving and is turned off by default.

4
modules/script/README.md
View file

@ -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 `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 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 ## Creating a Script
@ -16,4 +16,4 @@ When creating a script, please make sure
- ...it starts with a [shebang](<https://en.wikipedia.org/wiki/Shebang_(Unix)>) like `#!/usr/bin/env bash`. - ...it starts with a [shebang](<https://en.wikipedia.org/wiki/Shebang_(Unix)>) like `#!/usr/bin/env bash`.
- This ensures the script is ran with the correct interpreter / shell. - This ensures the script is ran with the correct interpreter / shell.
- ...it contains the command `set -euo pipefail` right after the shebang. - ...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. - 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.

4
modules/systemd/README.md
View file

@ -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, 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: depending if your unit is `system` or `user` based:
`config/systemd/system` `files/systemd/system/`
`config/systemd/user` `files/systemd/user/`
Those units are then copied into these folders (depending on unit base): Those units are then copied into these folders (depending on unit base):
`/usr/lib/systemd/system` `/usr/lib/systemd/system`