[tor-commits] [builders/rbm] 06/06: Bug 40028: Add documentation for modules
gitolite role
git at cupani.torproject.org
Fri Jul 1 09:33:04 UTC 2022
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 at 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)]
--
To stop receiving notification emails like this one, please contact
the administrator of this repository.
More information about the tor-commits
mailing list