From a9d3a1d099bc2697354e7807c29ad5f3ce13b7c4 Mon Sep 17 00:00:00 2001 From: Michael Schroeder Date: Wed, 21 Feb 2024 14:22:40 +0100 Subject: [PATCH] Update docu --- docs/build_config.adoc | 51 +++++++++++++++++++ docs/pbuild.html | 108 ++++++++++++++++++++++++++++++----------- 2 files changed, 132 insertions(+), 27 deletions(-) diff --git a/docs/build_config.adoc b/docs/build_config.adoc index 0e704da06..f2fedbefa 100644 --- a/docs/build_config.adoc +++ b/docs/build_config.adoc @@ -36,6 +36,11 @@ an existing entry from the data. The following list contains all the allowed keywords in the project configuration: +==== AssetsURL: TYPE@URL + +Define a url for automatic asset downloading. Supported types +are currently `fedpkg` and `goproxy`. + ==== BinaryType: TYPE The binary type is the format of the packages that make up the build @@ -142,6 +147,13 @@ For podman container builds, it specifies the container config format. Possible are 'docker' and 'oci'. The default is 'docker'. The 'docker' format allows a few extensions like ONBUILD, SHELL, DOMAINNAME, COMMENT, HEALTHCHECK amongst others. +==== Conflict: PACKAGE + +Specify that a package must not be installed in the build environment. + +==== Conflict: PACKAGE_A:PACKAGE_B + +Specify a synthetic conflict between to packages. ==== Constraint: SELECTOR STRING @@ -151,6 +163,18 @@ Define build constraints for build jobs. The selector is a colon-separated list which gets a string assigned. See the build job constraints page for details. +==== DistMacro: NAME VALUE + +Define a macro to be used when parsing the spec files of packages. +This is similar to using a `Macros:` section with the difference +that the macro will not be written to the .rpmmacros file. It should +therefore be used for macros that come from packages of the +distributions. + +Note that the lines of the project config are macro expanded while +parsing, so you have to use `%%` for a literal percent sign in +the value. + ==== ExpandFlags: FLAG Flags which modify the behaviour during dependency resolution. @@ -234,6 +258,13 @@ for packages like `make` that are used to build itself. Preinstalled packages are automatically kept, as the package installation program needs to work all the time. +==== Macros: + +Defines the start of a literal macros block. The block is ended +by either reaching the end of the config or by a literal +`Macros:` line. See the section about macro definitions below for +more information. + ==== OptFlags: TARGET_ARCH FLAGS (RPM only) Optflags exports compiler flags to the build by adding lines to rpm's @@ -314,6 +345,13 @@ Defines the distversion to be used in group element of ymp files. This is used by the installer to check if the repository is suitable for the installed distribution. + * singleexport + +If multiple packages contain different versions of a rpm package, only +publish the one from the first package. If the project is of the type +`maintenance_release`, this will be the package with the highest +incident number. + ==== PublishFilter: REGEXP [REGEXP] CAUTION: OBS only @@ -340,6 +378,16 @@ appended, e.g.: This results in a debuginfo package repository being created in parallel to the package repository. +==== RegistryURL: URL + +Define a url for the downloading of containers. + +==== RepoURL: [TYPE@]URL + +Define a url for the downloading of repository packages. Supported types +are currently `arch`, `debian`, `hdlist2`, `rpmmd`, `suse`. If the +type is not specified, it is guessed from the build type. + ==== Required: PACKAGE Specify a package that always is installed for package builds. @@ -423,6 +471,9 @@ Example: %_hardened_build 0 :Macros +Note that the macro lines are copied verbatim, i.e. macro expansion +does not take place. + === Building with ccache or sccache The usage of ccache or sccache can be enabled for each package by diff --git a/docs/pbuild.html b/docs/pbuild.html index 9b35cd737..d6ab5154e 100644 --- a/docs/pbuild.html +++ b/docs/pbuild.html @@ -1104,14 +1104,19 @@

3.2. Available Keywords in

The following list contains all the allowed keywords in the project configuration:

-

3.2.1. BinaryType: TYPE

+

3.2.1. AssetsURL: TYPE@URL

+

Define a url for automatic asset downloading. Supported types +are currently fedpkg and goproxy.

+
+
+

3.2.2. BinaryType: TYPE

The binary type is the format of the packages that make up the build environment. This is usually set automatically depending on the recipe type and preinstall package list. Currently understood values are: rpm, deb, and arch.

-

3.2.2. BuildEngine: ENGINE

+

3.2.3. BuildEngine: ENGINE

Use an alternative build engine. Examples are mock (for Fedora and Red Hat) and debootstrap (for Debian), debbuild (to build debian packages with spec files), podman (container builds).

@@ -1126,7 +1131,7 @@

3.2.2. BuildEngine: ENGINE

-

3.2.3. BuildFlags: FLAG:VALUE

+

3.2.4. BuildFlags: FLAG:VALUE

The BuildFlags keyword defines flags for the build process. The following values for FLAG are usable.

    @@ -1261,7 +1266,15 @@

    3.2.3. BuildFlags: FLAG:VALUE

    extensions like ONBUILD, SHELL, DOMAINNAME, COMMENT, HEALTHCHECK amongst others.

-

3.2.4. Constraint: SELECTOR STRING

+

3.2.5. Conflict: PACKAGE

+

Specify that a package must not be installed in the build environment.

+
+
+

3.2.6. Conflict: PACKAGE_A:PACKAGE_B

+

Specify a synthetic conflict between to packages.

+
+
+

3.2.7. Constraint: SELECTOR STRING

@@ -1275,7 +1288,18 @@

3.2.4. Constraint: SELECTOR STRING

constraints page for details.

-

3.2.5. ExpandFlags: FLAG

+

3.2.8. DistMacro: NAME VALUE

+

Define a macro to be used when parsing the spec files of packages. +This is similar to using a Macros: section with the difference +that the macro will not be written to the .rpmmacros file. It should +therefore be used for macros that come from packages of the +distributions.

+

Note that the lines of the project config are macro expanded while +parsing, so you have to use %% for a literal percent sign in +the value.

+
+
+

3.2.9. ExpandFlags: FLAG

Flags which modify the behaviour during dependency resolution.

  • @@ -1331,7 +1355,7 @@

    3.2.5. ExpandFlags: FLAG

    offered to the kiwi build tool. This should have been the default.

-

3.2.6. ExportFilter: REGEX ARCHITECTURES

+

3.2.10. ExportFilter: REGEX ARCHITECTURES

The export filter can be used to export build results from one architecture to others. This is required when one architecture needs packages from another architecture for building. The REGEX placeholder @@ -1341,20 +1365,20 @@

3.2.6. ExportFilter: REGEX ARCHITECTU to also use them locally.

-

3.2.7. FileProvides: FILE PACKAGES

+

3.2.11. FileProvides: FILE PACKAGES

Due to memory consumption reasons dependencies to files as supported by rpm are ignored by default. As a workaround, FileProvides can be used to tell the systems which packages contain a file. The file needs to have the full path.

-

3.2.8. HostArch: HOST_ARCH

+

3.2.12. HostArch: HOST_ARCH

This is used for cross builds. It defines the host architecture used for building, while the scheduler architecture remains the target architecture.

-

3.2.9. Ignore: PACKAGE_OR_DEPENDENCY

+

3.2.13. Ignore: PACKAGE_OR_DEPENDENCY

Ignore can be used to break dependencies. This can be useful to reduce the number of needed packages or to break cyclic dependencies. If a package is specified, all capabilities provided by the package are @@ -1364,12 +1388,12 @@

3.2.9. Ignore: PACKAGE_OR_DEPENDENCY

originating package as described in the following section.

-

3.2.10. Ignore: ORIGIN_PACKAGE:PACKAGE_OR_DEPENDENCY

+

3.2.14. Ignore: ORIGIN_PACKAGE:PACKAGE_OR_DEPENDENCY

Ignore a dependency coming from ORIGIN_PACKAGE. See the previous section for more details.

-

3.2.11. Keep: PACKAGES

+

3.2.15. Keep: PACKAGES

To eliminate build cycles the to-be-built packages are not installed by default. Keep can be used to overwrite this behavior. It is usually needed for packages like make that are used to build itself. Preinstalled @@ -1377,14 +1401,21 @@

3.2.11. Keep: PACKAGES

to work all the time.

-

3.2.12. OptFlags: TARGET_ARCH FLAGS (RPM only)

+

3.2.16. Macros:

+

Defines the start of a literal macros block. The block is ended +by either reaching the end of the config or by a literal +Macros: line. See the section about macro definitions below for +more information.

+
+
+

3.2.17. OptFlags: TARGET_ARCH FLAGS (RPM only)

Optflags exports compiler flags to the build by adding lines to rpm’s rpmrc file. They will only have an effect when the spec file is using $RPM_OPT_FLAGS or %{optflags}. The target architecture may be set to * to affect all architectures.

-

3.2.13. Order: PACKAGE_A:PACKAGE_B

+

3.2.18. Order: PACKAGE_A:PACKAGE_B

The build script takes care about the installation order if they are defined via dependencies inside of the packages. However, there might be dependency loops (reported during setup of the build system) or missing @@ -1394,12 +1425,12 @@

3.2.13. Order: PACKAGE_A:PACKAGE_B

PACKAGE_B.

-

3.2.14. Patterntype: TYPES

+

3.2.19. Patterntype: TYPES

Defines the pattern format. Valid values are: none (default), ymp, comps.

-

3.2.15. Prefer: PACKAGE

+

3.2.20. Prefer: PACKAGE

In case multiple packages satisfy a dependency, the dependency expansion will fail. This is unlike like most package managing tools, which just pick one of the package. It is done that way to provide reproducible @@ -1410,12 +1441,12 @@

3.2.15. Prefer: PACKAGE

as a de-prefer.

-

3.2.16. Prefer: ORIGIN_PACKAGE:PACKAGE

+

3.2.21. Prefer: ORIGIN_PACKAGE:PACKAGE

It is possible to define the prefer only when the dependency comes from the specified originating package.

-

3.2.17. Preinstall: PACKAGE

+

3.2.22. Preinstall: PACKAGE

This is used to specify packages needed to run the package installation program. These packages are unpacked so that the native installation program can be used to install the build environment. @@ -1423,7 +1454,7 @@

3.2.17. Preinstall: PACKAGE

packages will be re-installed later on including script execution.

-

3.2.18. PublishFlag: FLAG

+

3.2.23. PublishFlag: FLAG

@@ -1480,9 +1511,20 @@

3.2.18. PublishFlag: FLAG

Defines the distversion to be used in group element of ymp files. This is used by the installer to check if the repository is suitable for the installed distribution.

+
    +
  • +

    +singleexport +

    +
    • +
+

If multiple packages contain different versions of a rpm package, only +publish the one from the first package. If the project is of the type +maintenance_release, this will be the package with the highest +incident number.

-

3.2.19. PublishFilter: REGEXP [REGEXP]

+

3.2.24. PublishFilter: REGEXP [REGEXP]

@@ -1497,7 +1539,7 @@

3.2.19. PublishFilter: REGEXP [REGEXP]

-

3.2.20. Repotype: TYPE[:OPTIONS]

+

3.2.25. Repotype: TYPE[:OPTIONS]

Defines the repository format for published repositories. Valid values are: none, rpm-md, suse, debian, hdlist2, arch, staticlinks and vagrant. @@ -1515,24 +1557,34 @@

3.2.20. Repotype: TYPE[:OPTIONS]

to the package repository.

-

3.2.21. Required: PACKAGE

+

3.2.26. RegistryURL: URL

+

Define a url for the downloading of containers.

+
+
+

3.2.27. RepoURL: [TYPE@]URL

+

Define a url for the downloading of repository packages. Supported types +are currently arch, debian, hdlist2, rpmmd, suse. If the +type is not specified, it is guessed from the build type.

+
+
+

3.2.28. Required: PACKAGE

Specify a package that always is installed for package builds. A change in one of these packages triggers a new build.

-

3.2.22. Runscripts: PACKAGE

+

3.2.29. Runscripts: PACKAGE

Execute the scriptlets of the specified preinstalled package. Scriptlet execution takes place after the preinstall phase, but before installing the remaining packages.

-

3.2.23. Substitute: DEPENDENCY DEPENDENCY…

+

3.2.30. Substitute: DEPENDENCY DEPENDENCY…

It is possible to replace to BuildRequires with other packages. This will have only an effect on directly BuildRequired packages, not on indirectly required packages.

-

3.2.24. Support: PACKAGE

+

3.2.31. Support: PACKAGE

Specify a package that always is installed for package builds. Unlike Required:, a change in one of these packages does not trigger an automatic rebuild.

@@ -1540,13 +1592,13 @@

3.2.24. Support: PACKAGE

result, for example make or coreutils.

-

3.2.25. Target: GNU_TRIPLET

+

3.2.32. Target: GNU_TRIPLET

Defines the target architecture via a gnu triplet (not the debian architecture!). For example arm-linux-gnueabihf for armv7hl builds, or i686 for building i686 packages.

-

3.2.26. Type: TYPE

+

3.2.33. Type: TYPE

Build recipe type. This is the format of the file which provides the build description (the "build recipe"). This is usually autodetected from the binary type, but in some rare cases it may be needed to manually @@ -1554,7 +1606,7 @@

3.2.26. Type: TYPE

spec, dsc, arch, kiwi, livebuild, productcompose, preinstallimage.

-

3.2.27. VMInstall: PACKAGE

+

3.2.34. VMInstall: PACKAGE

Like Preinstall, but these packages get only installed when a virtual machine like Xen or KVM is used for building. Usually packages like mount are listed here.

@@ -1601,6 +1653,8 @@

3.4. Macro Definitions for the %_hardened_build 0 :Macros

+

Note that the macro lines are copied verbatim, i.e. macro expansion +does not take place.

3.5. Building with ccache or sccache