From ffba77d151a8a20f230aefeb08791d009fbfc208 Mon Sep 17 00:00:00 2001 From: ER Date: Mon, 11 Sep 2023 17:49:12 +0300 Subject: [PATCH 1/6] fix: clear up some issues in docs abt modules - better distinction between modules and module configuration - example for module configuration external from recipe.yml --- config/README.md | 19 +++++++++++++++---- config/recipe.yml | 2 +- 2 files changed, 16 insertions(+), 5 deletions(-) diff --git a/config/README.md b/config/README.md index 1e07befff2..ccc986875c 100644 --- a/config/README.md +++ b/config/README.md @@ -16,16 +16,27 @@ At the top of the recipe, there are four *mandatory* configuration options. ## Modules -The core of startingpoint's configuration is built around the idea of modules. Modules are scripts in the [`../modules`](../modules/) directory that you list out under `modules:` in the recipe. They are executed in order, and can run arbitrary shell commands and write any files. +The core of startingpoint's configuration is built around the idea of modules. Modules are scripts in the [`../modules`](../modules/) directory that you configure under `modules:` in the recipe. They are executed in order, and can run arbitrary shell commands and write any files. -This repository fetches some useful default modules from [`ublue-os/bling`](https://github.com/ublue-os/bling/), like [`rpm-ostree`](../modules/rpm-ostree) for pseudo-declarative package management, [`bling`](../modules/bling) for pulling extra components from [`ublue-os/bling`](https://github.com/ublue-os/bling), and [`files`](../modules/files) for copying files from the `config/files/` directory into your image. For a comprehensive list of modules and their in-depth documentation, check out [the modules page on the website](https://universal-blue.org/tinker/modules/). +This repository fetches some useful default modules from [`ublue-os/bling`](https://github.com/ublue-os/bling/), like [`rpm-ostree`](../modules/rpm-ostree) for pseudo-declarative package management, [`bling`](../modules/bling) for pulling extra components from [`ublue-os/bling`](https://github.com/ublue-os/bling), and [`files`](../modules/files) for copying files from the `config/files/` directory into your image. -### Including modules from other files and building multiple images +For a comprehensive list of modules, their in-depth documentation and example configuration, check out [the Modules page on the website](https://universal-blue.org/tinker/modules/). + +### Building multiple images and including module configuration from other files and To build multiple images, you need to create another recipe.yml file, which you should name based on what kind of image you want it to build. Then, edit the [`build.yml`](../.github/workflows/build.yml) file. Inside the file, under `jobs: strategy: matrix:`, there's a list of recipe files to build images, which you need to add your new recipe file to. These should be paths to files inside the `config` directory. -Module configuration can be included from other files using the `from-file` syntax. The valye should be a path to a file inside the `config` directory. For example, the following snippet could be used to include the configuration for installing a set of packages common to multiple images. +Module configuration can be included from other files using the `from-file` syntax. The value should be a path to a file inside the `config` directory. For example, the following snippet could be used to include the configuration for installing a set of packages common to multiple images. ```yml modules: - from-file: common-packages.yml +``` +And inside common-packages.yml +```yml +type: rpm-ostree +install: + - i3 + - dunst + - rofi + - kitty ``` \ No newline at end of file diff --git a/config/recipe.yml b/config/recipe.yml index 90d4cb16fa..9102e0d5bb 100644 --- a/config/recipe.yml +++ b/config/recipe.yml @@ -7,7 +7,7 @@ description: A starting point for further customization of uBlue images. Make yo base-image: ghcr.io/ublue-os/silverblue-main image-version: 38 # latest is also supported if you want new updates ASAP -# list of modules, executed in order +# module configuration, executed in order # you can include multiple instances of the same module modules: From 98ac633f4bad1f2cc64bf83fa511c804882ce744 Mon Sep 17 00:00:00 2001 From: ER Date: Mon, 11 Sep 2023 17:50:28 +0300 Subject: [PATCH 2/6] chore: create-ublue-image -> general mention --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 418d1613f9..a2d6450a21 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ Don't worry, it only requires some basic knowledge about using the terminal and After setup, it is recommended you update this README to describe your custom image. > **Note** -> Everywhere in this repository, make sure to replace `ublue-os/startingpoint` with the details of your own repository. Unless you used [`create-ublue-image`](https://github.com/EinoHR/create-ublue-image), in which case the previous repo identifier should already be your repo's details. +> Everywhere in this repository, make sure to replace `ublue-os/startingpoint` with the details of your own repository. Unless you used on of the automatic repository setup tools in which case the previous repo identifier should already be your repo's details. > **Warning** > To start, you *must* create a branch called `live` which is exclusively for your customizations. That is the **only** branch the GitHub workflow will deploy to your container registry. Don't make any changes to the original "template" branch. It should remain untouched. By using this branch structure, you ensure a clear separation between your own "published image" branch, your development branches, and the original upstream "template" branch. Periodically sync and fast-forward the upstream "template" branch to the most recent revision. Then, simply rebase your `live` branch onto the updated template to effortlessly incorporate the latest improvements into your own repository, without the need for any messy, manual "merge commits". From 47fc4385d5e4a07e17d0ab35fcef8cf795283de1 Mon Sep 17 00:00:00 2001 From: ER Date: Mon, 11 Sep 2023 15:28:43 +0000 Subject: [PATCH 3/6] fix: dead module links --- config/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/README.md b/config/README.md index ccc986875c..9d938c3c50 100644 --- a/config/README.md +++ b/config/README.md @@ -18,7 +18,7 @@ At the top of the recipe, there are four *mandatory* configuration options. The core of startingpoint's configuration is built around the idea of modules. Modules are scripts in the [`../modules`](../modules/) directory that you configure under `modules:` in the recipe. They are executed in order, and can run arbitrary shell commands and write any files. -This repository fetches some useful default modules from [`ublue-os/bling`](https://github.com/ublue-os/bling/), like [`rpm-ostree`](../modules/rpm-ostree) for pseudo-declarative package management, [`bling`](../modules/bling) for pulling extra components from [`ublue-os/bling`](https://github.com/ublue-os/bling), and [`files`](../modules/files) for copying files from the `config/files/` directory into your image. +This repository fetches some useful default modules from [`ublue-os/bling`](https://github.com/ublue-os/bling/), like [`rpm-ostree`](https://universal-blue.org/tinker/modules/rpm-ostree) for pseudo-declarative package management, [`bling`](https://universal-blue.org/tinker/modules/bling) for pulling extra components from [`ublue-os/bling`](https://github.com/ublue-os/bling), and [`files`](https://universal-blue.org/tinker/modules/files) for copying files from the `config/files/` directory into your image. For a comprehensive list of modules, their in-depth documentation and example configuration, check out [the Modules page on the website](https://universal-blue.org/tinker/modules/). From b8ed4983a6b8256e3de18db92ad215d7faa4431d Mon Sep 17 00:00:00 2001 From: ER Date: Mon, 11 Sep 2023 15:29:19 +0000 Subject: [PATCH 4/6] chore: use yaml for syntax highlighting --- config/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/config/README.md b/config/README.md index 9d938c3c50..f065254b7d 100644 --- a/config/README.md +++ b/config/README.md @@ -27,12 +27,12 @@ For a comprehensive list of modules, their in-depth documentation and example co To build multiple images, you need to create another recipe.yml file, which you should name based on what kind of image you want it to build. Then, edit the [`build.yml`](../.github/workflows/build.yml) file. Inside the file, under `jobs: strategy: matrix:`, there's a list of recipe files to build images, which you need to add your new recipe file to. These should be paths to files inside the `config` directory. Module configuration can be included from other files using the `from-file` syntax. The value should be a path to a file inside the `config` directory. For example, the following snippet could be used to include the configuration for installing a set of packages common to multiple images. -```yml +```yaml modules: - from-file: common-packages.yml ``` And inside common-packages.yml -```yml +```yaml type: rpm-ostree install: - i3 From 5b72227ce578ce0024c6abd596330f1c6ae44de4 Mon Sep 17 00:00:00 2001 From: xyny <60004820+xynydev@users.noreply.github.com> Date: Mon, 11 Sep 2023 18:21:38 +0000 Subject: [PATCH 5/6] fix: typo: one of --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a2d6450a21..603a61c686 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ Don't worry, it only requires some basic knowledge about using the terminal and After setup, it is recommended you update this README to describe your custom image. > **Note** -> Everywhere in this repository, make sure to replace `ublue-os/startingpoint` with the details of your own repository. Unless you used on of the automatic repository setup tools in which case the previous repo identifier should already be your repo's details. +> Everywhere in this repository, make sure to replace `ublue-os/startingpoint` with the details of your own repository. Unless you used one of the automatic repository setup tools in which case the previous repo identifier should already be your repo's details. > **Warning** > To start, you *must* create a branch called `live` which is exclusively for your customizations. That is the **only** branch the GitHub workflow will deploy to your container registry. Don't make any changes to the original "template" branch. It should remain untouched. By using this branch structure, you ensure a clear separation between your own "published image" branch, your development branches, and the original upstream "template" branch. Periodically sync and fast-forward the upstream "template" branch to the most recent revision. Then, simply rebase your `live` branch onto the updated template to effortlessly incorporate the latest improvements into your own repository, without the need for any messy, manual "merge commits". @@ -95,4 +95,4 @@ Then type `just` to list the just recipes available. The file `/usr/share/ublue-os/just/custom.just` is intended for the custom just commands (recipes) you wish to include in your image. By default, it includes the justfiles from [`ublue-os/bling`](https://github.com/ublue-os/bling), if you wish to disable that, you need to just remove the line that includes bling.just. -See [the just-page in the Universal Blue documentation](https://universal-blue.org/guide/just/) for more information. \ No newline at end of file +See [the just-page in the Universal Blue documentation](https://universal-blue.org/guide/just/) for more information. From 3a5509bd406b087557500f7bcd09ba3309ab1841 Mon Sep 17 00:00:00 2001 From: xyny <60004820+xynydev@users.noreply.github.com> Date: Mon, 18 Sep 2023 15:57:53 +0000 Subject: [PATCH 6/6] docs: common-packages.yml should be inside config/ --- config/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/config/README.md b/config/README.md index f065254b7d..23337d6d5b 100644 --- a/config/README.md +++ b/config/README.md @@ -31,7 +31,7 @@ Module configuration can be included from other files using the `from-file` synt modules: - from-file: common-packages.yml ``` -And inside common-packages.yml +And inside config/common-packages.yml ```yaml type: rpm-ostree install: @@ -39,4 +39,4 @@ install: - dunst - rofi - kitty -``` \ No newline at end of file +```