[tbb-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 tbb-commits mailing list