This is an automated email from the git hooks/post-receive script.
gk pushed a commit to branch master in repository builders/rbm.
commit ce18f12cc5114ca82dc2964a62bce835dcc5a1f0 Author: Nicolas Vigier boklm@torproject.org AuthorDate: Wed Jun 29 16:26:41 2022 +0200
Bug 40028: Add documentation for modules --- doc/Makefile | 1 + doc/documentation.asc | 1 + doc/rbm_config.asc | 36 +++++++++++++++++++----- doc/rbm_layout.asc | 77 ++++++++++++++++++++++++++++++++++----------------- doc/rbm_modules.asc | 54 ++++++++++++++++++++++++++++++++++++ 5 files changed, 137 insertions(+), 32 deletions(-)
diff --git a/doc/Makefile b/doc/Makefile index 8564a19..7aeb0f2 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -33,6 +33,7 @@ MAN1_ASC += rbm-build.asc MAN7_ASC += rbm_tutorial.asc MAN7_ASC += rbm_layout.asc MAN7_ASC += rbm_config.asc +MAN7_ASC += rbm_modules.asc MAN7_ASC += rbm_templates.asc MAN7_ASC += rbm_remote.asc MAN7_ASC += rbm_targets.asc diff --git a/doc/documentation.asc b/doc/documentation.asc index 4c5c9bc..eabf738 100644 --- a/doc/documentation.asc +++ b/doc/documentation.asc @@ -1,6 +1,7 @@ - link:rbm_tutorial.html[rbm_tutorial(7)] : A tutorial introduction to rbm - link:rbm_layout.html[rbm_layout(7)] : The rbm layout - link:rbm_config.html[rbm_config(7)] : The rbm configuration +- link:rbm_modules.html[rbm_modules(7)] : The rbm modules - link:rbm_cli.html[rbm_cli(7)] : The rbm command line interface - link:rbm_templates.html[rbm_templates(7)] : The rbm templates - link:rbm_remote.html[rbm_remote(7)] : The rbm remote builds diff --git a/doc/rbm_config.asc b/doc/rbm_config.asc index 0bfed04..46c1caf 100644 --- a/doc/rbm_config.asc +++ b/doc/rbm_config.asc @@ -8,10 +8,13 @@ rbm_config - The rbm configuration DESCRIPTION -----------
-All configuration options can be defined in 5 different places : +All configuration options can be defined in different places :
- in the main configuration in your working directory (+rbm.conf+)
+- in a module configuration at the root of a module directory + (+rbm.module.conf+) + - in the local configuration in your working directory (+rbm.local.conf+)
- in the global system configuration (+/etc/rbm.conf+) @@ -48,6 +51,14 @@ The option values are used with the following priority order :
- workspace config
+- modules config for matching step and target + +- modules config for matching step + +- modules config for matching target + +- modules config + - system config for matching step and target
- system config for matching step @@ -79,23 +90,33 @@ file is used to override some options from +rbm.conf+ relevent to your local setup, whithout modifying the +rbm.conf+ file which is usually maintained in a VCS.
+The module configuration files are +rbm.module.conf+ located at the +root of each module directory: a module named +A+ will have its +configuration in +modules/A/rbm.module.conf+. Module configuration +is used in alphabetical order: configuration from a module named ++A+ will have priority over a module named +B+. + An example +rbm.conf+ file will look like this :
---- -projects_dir: projects compress_tar: xz +output_dir: "out/[% project %]" ----
-The +projects_dir+ option define the path to the directory containing -the projects definitions. - Adding a new project is done by creating a directory with the name of -the project inside the +projects_dir+ directory, and adding a +config+ +the project inside the +projects+ directory, and adding a +config+ file in this new directory. The +config+ file contains the configuration for the project. At the minimum it should contain the +git_url+ configuration, and any other configuration option you want to set for this project.
+Projects can also be defined inside a module. In this case the module +directory will include a +projects+ directory working in a similar way +to the main +projects+ directory. If a project exists with the same +name both in a module and the main +projects+ directory, the module one +will be ignored. If a project is defined in multiple modules, only the +project from the first module in alphabetic order will be used. + OPTIONS -------
@@ -337,4 +358,5 @@ SEE ALSO -------- link:rbm.html[rbm(1)], link:rbm_targets.html[rbm_targets(7)], -link:rbm_templates.html[rbm_templates(7)] +link:rbm_templates.html[rbm_templates(7)], +link:rbm_modules.html[rbm_modules(7)] diff --git a/doc/rbm_layout.asc b/doc/rbm_layout.asc index c85658d..1261cf2 100644 --- a/doc/rbm_layout.asc +++ b/doc/rbm_layout.asc @@ -26,15 +26,17 @@ and 'project_2' will look like this : | | | |-- project_1 | | | - | | |-- project_1-0.1.tar.gz + | | |-- project_1-0.1-src.tar.gz | | | | | +-- project_1-0.1-1.x86_64.rpm + | | | + | | +-- project_1-0.1-1.x86_64.tar.gz | | | +-- project_2 | | - | |-- project_2-7.3.tar.bz2 + | |-- project_2-7.3.tar-src.bz2 | | - | +-- project_2-7.1-1.x86_64.rpm + | +-- project_2-7.1-1.x86_64.tar.gz | |-- git_clones | | @@ -46,29 +48,43 @@ and 'project_2' will look like this : | |-- keyring | | - | |-- keyring-1 + | |-- project_1.gpg | | - | +-- keyring-2 + | +-- project_2.gpg | +-- projects + | | + | |-- project_1 + | | | + | | |-- config + | | | + | | |-- project_1.spec + | | | + | | |-- bugfix.patch + | | + | +-- project_2 + | | + | |-- config + | | + | +-- build + | + +-- modules | - |-- project_1 - | | - | |-- config - | | - | |-- project_1.spec - | | - | |-- bugfix.patch - | | - | +-- debian_rules - | - +-- project_2 + +-- container | - |-- config + |-- rbm.module.conf | - |-- project_2.spec + |-- projects + | | + | +-- container-image + | | + | |-- config + | | + | +-- build | - +-- debian_rules + +-- keyring + | + +-- container-image.gpg ----
You will file the following files and directories : @@ -115,13 +131,24 @@ projects/project_1/project_1.spec:: projects/project_1/bugfix.patch:: This is an example patch file, used in the rpm package.
-projects/project_1/debian_rules:: - This is an example path for a debian/rules file to be used in - the debian packaging for the project_1 project. All the debian - packaging can be defined entirely inside the 'config' file, but - it is usually convenient to split some of it in separate files. +projects/project_1/build:: + This is a build script for project_1, containing instructions + for building the project and generating a tar.gz file containing + the build output. + +modules/container/rbm.local.conf:: + In this example we use an external rbm module named 'container' + (usually included as a git-submodule). The 'rbm.local.conf' file + located at the root of the module contains the options related + to the projects included in the module. + +modules/container/projects:: + The projects included in the projects directory of a module + work in the same way as those in the main projects directory. +
SEE ALSO -------- link:rbm.html[rbm(1)], -link:rbm_config.html[rbm_config(1)] +link:rbm_config.html[rbm_config(7)], +link:rbm_modules.html[rbm_modules(7)] diff --git a/doc/rbm_modules.asc b/doc/rbm_modules.asc new file mode 100644 index 0000000..9d0517a --- /dev/null +++ b/doc/rbm_modules.asc @@ -0,0 +1,54 @@ +rbm_modules(7) +============= + +NAME +---- +rbm_modules - rbm modules + +DESCRIPTION +----------- + +An rbm workspace can contain a number of different projects. In some +cases it can be useful to share some of those projects between multiple +workspaces. This can be done using modules. + +A module is a subdirectory in the +modules+ directory. If you are using +git, it is possible to store each module directory using a separate ++git-submodule+. + +A module directory structure is similar to the main workspace structure: +each module includes a +projects+ directory containing the projects, +a +keyring+ directory containing the gpg keyrings used by the projects, +and a +rbm.module.conf+ containing rbm configuration related to the +projects included in the module. + + +RBM CONFIGURATION +----------------- + +The rbm configuration from a module (the +rbm.module.conf+ and the +project +config+ files) can define any configuration option. +However, for clarity and to avoid name collisions with other modules or +with core rbm options, it is recommended to prefix all option names +with +var_${module_name}+ (where +${module_name}+ is the module name). + +The workspace configuration (+rbm.conf+) has priority over the modules +configuration (+rbm.module.conf+). Module configuration is used in +alphabetical order: configuration from a module named +A+ will have +priority over a module named +B+. See +link:rbm_config.html[rbm_config(1)] for more details. + +KEYRING +------- + +The keyring directory in a module contains gpg keyring files (see the ++gpg_keyring+ option). If a keyring file is available in multiple +modules, the one from the first module in alphabetical order will be +used. If a keyring file is also available in the main workspace's +keyring directory, then it will be used. + + +SEE ALSO +-------- +link:rbm.html[rbm(1)], +link:rbm_config.html[rbm_config(1)]