From 7e03133c8fd7fefded5e88e2e123e74e607d5bc3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lubom=C3=ADr=20Sedl=C3=A1=C5=99?= Date: Tue, 8 Aug 2017 14:15:17 +0200 Subject: [PATCH] docs: Add documentation for scm_dict MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Lubomír Sedlář --- doc/configuration.rst | 34 +++++++++++++++----------- doc/index.rst | 1 + doc/scm_support.rst | 55 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 76 insertions(+), 14 deletions(-) create mode 100644 doc/scm_support.rst diff --git a/doc/configuration.rst b/doc/configuration.rst index 26222695..c69e0ef6 100644 --- a/doc/configuration.rst +++ b/doc/configuration.rst @@ -127,10 +127,12 @@ Options ------- **comps_file** [mandatory] - (*scm_dict*, *str* or None) -- reference to comps XML file with installation groups + (:ref:`scm_dict `, *str* or None) -- reference to comps XML + file with installation groups **variants_file** [mandatory] - (*scm_dict* or *str*) -- reference to variants XML file that defines release variants and architectures + (:ref:`scm_dict ` or *str*) -- reference to variants XML file + that defines release variants and architectures **failable_deliverables** [optional] (*list*) -- list which deliverables on which variant and architecture can @@ -393,9 +395,9 @@ Options cause the SQLite databases to be compressed with xz. **product_id** = None - (*scm_dict*) -- If specified, it should point to a directory with - certificates ``--*.pem``. This certificate will be - injected into the repository. + (:ref:`scm_dict `) -- If specified, it should point to a + directory with certificates ``--*.pem``. This + certificate will be injected into the repository. **product_id_allow_missing** = False (*bool*) -- When ``product_id`` is used and a certificate for some variant @@ -469,8 +471,8 @@ Options * ``nomacboot`` -- *bool* (default ``True``) * ``noupgrade`` -- *bool* (default ``True``) **buildinstall_kickstart** - (*scm_dict*) -- If specified, this kickstart file will be copied into each - file and pointed to in boot configuration. + (:ref:`scm_dict `) -- If specified, this kickstart file will + be copied into each file and pointed to in boot configuration. Example ------- @@ -600,10 +602,10 @@ Options one system release package. In such case, set this option to ``False``. **gather_prepopulate** = None - (*scm_dict*) -- If specified, you can use this to add additional packages. - The format of the file pointed to by this option is a JSON mapping - ``{variant_uid: {arch: {build: [package]}}}``. Packages added through this - option can not be removed by ``filter_packages``. + (:ref:`scm_dict `) -- If specified, you can use this to add + additional packages. The format of the file pointed to by this option is a + JSON mapping ``{variant_uid: {arch: {build: [package]}}}``. Packages added + through this option can not be removed by ``filter_packages``. **multilib_blacklist** (*dict*) -- multilib blacklist; format: ``{arch|*: [package_globs]}``. The @@ -751,7 +753,10 @@ Options ------- **extra_files** - (*list*) -- references to external files to be placed in os/ directory and media; format: [(variant_uid_regex, {arch|*: [scm_dicts]})] + (*list*) -- references to external files to be placed in os/ directory and + media; format: ``[(variant_uid_regex, {arch|*: [scm_dict]})]``. See + :ref:`scm_support` for details. If the dict specifies a ``target`` key, an + additional subdirectory will be used. Example @@ -827,10 +832,11 @@ Options (*bool*) -- create product images; requires bootable=True **productimg_install_class** - (*scm_dict*, *str*) -- reference to install class **file** + (:ref:`scm_dict `, *str*) -- reference to install class **file** **productimg_po_files** - (*scm_dict*, *str*) -- reference to a **directory** with po files for install class translations + (:ref:`scm_dict `, *str*) -- reference to a **directory** with + po files for install class translations Example diff --git a/doc/index.rst b/doc/index.rst index 031495b7..73c29c48 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -16,6 +16,7 @@ Contents: testing format configuration + scm_support messaging phases gathering diff --git a/doc/scm_support.rst b/doc/scm_support.rst new file mode 100644 index 00000000..33c8ba95 --- /dev/null +++ b/doc/scm_support.rst @@ -0,0 +1,55 @@ +.. _scm_support: + +Exporting files from SCM +======================== + +Multiple places in Pungi can use files from external storage. The configuration +is similar independently of the backend that is used, although some features +may be different. + +The so-called ``scm_dict`` is always put into configuration as a dictionary, +which can contain following keys. + +* ``scm`` -- indicates which SCM system is used. This is always required. + Allowed values are: + + * ``file`` -- copies files from local filesystem + * ``git`` -- copies files from a Git repository + * ``cvs`` -- copies files from a CVS repository + * ``rpm`` -- copies files from a package in the compose + +* ``repo`` -- for Git and CVS backends URL to the repository, for RPM a shell + glob for matching package names (or a list of such globs); for ``file`` + backend this option should be empty (or left out) + +* ``branch`` -- branch name for Git and CVS backends, with ``master`` and + ``HEAD`` as defaults. Ignored for other backends. + +* ``file`` -- a list of files that should be exported. + +* ``dir`` -- a directory that should be exported. All its contents will be + exported. This option is mutually exclusive with ``file``. + +* ``command`` -- defines a shell command to run after Git clone to generate the + needed file (for example to run ``make``). Only supported in Git backend. + + +``file`` vs. ``dir`` +-------------------- + +Exactly one of these two options has to be specified. Documentation for each +configuration option should specify whether it expects a file or a directory. + +For ``extra_files`` phase either key is valid and should be chosen depending on +what the actual use case. + + +Caveats +------- + +The ``rpm`` backend can only be used in phases that would extract the files +after ``pkgset`` phase finished. You can't get comps file from a package. + +Depending on Git repository URL configuration Pungi can only export the +requested content using ``git archive``. When a command should run this is not +possible and a clone is always needed.