Sign Up
Log In
Log In
or
Sign Up
Places
All Projects
Status Monitor
Collapse sidebar
home:adrianSuSE
build
docs.obscpio
Overview
Repositories
Revisions
Requests
Users
Attributes
Meta
File docs.obscpio of Package build
07070100000000000081a400000000000000000000000163e504ba00000093000000000000000000000000000000000000000e00000000docs/Makefileall: asciidoc pbuild.adoc install: install -m755 -d \ $(DESTDIR)$(docdir) \ install -m644 \ pbuild.html \ $(DESTDIR)$(docdir) 07070100000001000081a400000000000000000000000163e504ba00003ade000000000000000000000000000000000000001700000000docs/build_config.adoc== About the Build Configuration The build configuration syntax is Switch on or off certain features during the build. Decide which package is installed during build if there are circular dependencies. Handle user decisions like package providing the same or special macros, packages, or flags in the build environment. === Configuration File Syntax The syntax is basically the same than in RPM spec files. However, it is independent of the used packaging format. The project configuration is parsed by &obsa;. This means, you can use RPM features like macros or conditions in the configuration. All lines have the form: keyword: arguments In addition to that rpm macro statement can get used, for example to activate some rules only for specific architectures via conditions. The following list contains a list of allowed keywords in the project configuration: Available Keywords in Project Configuration ==== BinaryType: TYPE The binary type is the format of the files which will be the result of the build jobs. This gets usually set depending on the build recipe type. In some situations, for example a &kiwi; build job result gets converted into an rpm, it can be used to overwrite it. Possible values are: rpm, deb or none. Sets the binary format used to set up the build environment. For example a package with spec build description may use and generate deb packages instead of RPMs. If no binary type is specified, OBS deduces it from the build recipe type. If the recipe type is also not set, OBS looks at the Preinstall package list for a hint. ==== BuildEngine: ENGINE Use an alternative build engine. This is still chained inside of the build script for security reasons. Alternatives are mock (for Fedora and Red Hat) and debootstrap (for Debian). This will avoid differences in the build environment setup, but it will also have an effect on speed and reduced features. It should only be used when you want to emulate the distribution build. debbuild engine will build deb files out of a spec file description. It can be used by the following definition inside of the project build config: Repotype: debian Type: spec Binarytype: deb BuildEngine: debbuild Support: pax Support: debbuild Keep: debbuild ==== BuildFlags: FLAG:VALUE The BuildFlags keyword defines flags for the build process. The following values for FLAG are usable. All flags with a leading colon (:) require an additional parameter directly following them. * vmfstype:TYPE Defines a specific file system when building inside of a VM. Possible values are ext2, ext3, ext4, btrfs, xfs, reiserfs (v3). * vmfsoptions:OPTIONS There is also an option to disable directory indexing for ext2, ext3, and ext4 file systems. This makes file ordering inside of directories reproducible but may have a negative performance impact. To apply this, specify vmfsoptions:nodirindex * kiwiprofile:PROFILE builds the selected profile in &kiwi; appliance builds. * logidlelimit:SECONDS Build jobs which don’t create any output get aborted after some time. This flag can be used to modify the limit. Specify the seconds behind flag. * excludebuild:PACKAGE Exclude a package from building. _multibuild flavors can be specified via package:flavor syntax. * onlybuild:PACKAGE DANGER: this may remove many build results when introduced the first time! It can be used to maintain a whitelist of packages to be built. All other packages will turn to excluded state. * ccachetype:TYPE Defines the ccache implementation, possible values are: ccache, sccache * useccache:PACKAGE Configure usage of ccache when building packages that match the value of this parameter. The ccache package will automatically be installed and configured. The directory /.ccache/ will be configured as cache directory. To configure ccache, the file /.ccache/ccache.conf can be modified as part of the build process by the $BUILD_USER environment variable. In some cases, there is no archive for the current package, such as when the package was newly branched or when binaries were deleted. In these cases, &obs; will check whether there is a package of the same name built for the same architecture within one of the repositories configured in the project’s meta configuration. If so, the archive of that package will be used. The repositories will be searched in the order they are configured in the meta configuration, starting from the top. An alternative way to enable caching based on build dependencies is to add "--enable-cache" as dependency, for example via a Substitute rule: Substitute: gcc-c++ gcc-c++ --enable-ccache This will always enable ccache when a direct build depdency to gcc-c++ is required. It is also possible to set the type, eg: Substitute: cargo cargo --enable-ccache=sccache * obsgendiff OBS can run an external program that has access to the current build and the previously successful result, e.g. to generate a difference or a changelog from the diff. build will run all scripts in /usr/lib/build/obsgendiff.d/ on the build host (not in the %buildroot) when this flag is set. If one of the scripts fails to run or no scripts are found, then the overall build fails. I.e. if BuildFlags: obsgendiff is set, then you must provide at least one script in /usr/lib/build/obsgendiff.d/, otherwise your build will fail. A common use case for obsgendiff is to run release-compare after the build. ==== Constraint: SELECTOR STRING CAUTION: OBS only 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. ==== ExpandFlags: FLAG Flags which modify the behaviour during dependency resolution. * unorderedimagerepos (OBS 2.10 or later) The priority of repositories defined in an image build is usually important. This is to avoid switching repositories when the same package is available in multiple repositories. However, it might be wanted to ignore that and just pick the highest version. This can be achieved by defining this flag * preinstallexpand Preinstall also all dependencies of a preinstalled package. Instead of manually listing all packages for a working package tool one can just install dependencies of it. However, these might be more then actually needed depending on the distribution. * module:NAME-STREAM Enable Red Hat-specific module support in repo md repositories. By default, modules are not used, but content can be made available by specifying the module name. To remove a module, add an exclamation mark (!) as prefix. ==== ExportFilter: REGEX ARCH 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 must match the resulting binary name of the package. It will export it to all listed scheduler architectures. Using a single dot will export it to the architecture which was used to build it. So not using a dot there will filter the package. ==== FileProvides: FILE PACKAGES &obsa; ignores dependencies to files (instead of package names) by default. This is mostly done to reduce the amount of memory needed, as the package file lists take up a considerable amount of repository meta data. As a workaround, FileProvides can be used to tell the systems which packages contain a file. The File needs to have the full path. ==== 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. ==== Ignore: PACKAGES Ignore can be used to break dependencies. This can be useful to reduce the number of needed packages or to break cyclic dependencies. Be careful with this feature, as breaking dependencies can have surprising results. ==== Ignore: PACKAGE_A:PACKAGES It is possible to define the ignore only for one package. This package must be listed first with a colon. ==== Keep: PACKAGES To eliminate build cycles the to-be-built package is not installed by default, even when it is required. Keep can be used to overwrite this behavior. It is usually needed 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. ==== OptFlags: TARGET_ARCH FLAGS (RPM only) Optflags exports compiler flags to the build. They will only have an effect when the spec file is using $RPM_OPT_FLAGS. The target architecture may be * to affect all architectures. ==== 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 dependencies. The Order statement can be used then to give a hint where to break the loop. The package in PACKAGE_A will get installed before the package in PACKAGE_B. ==== Patterntype: TYPES Defines the pattern format. Valid values are: none (default), ymp, comps. ==== Prefer: PACKAGES In case multiple packages satisfy a dependency, the OBS system will complain about that situation. This is unlike like most package managing tools, which just pick one of the package. Because one of OBS’ goal is to provide reproducible builds, it reports an error in this case instead of choosing a random package. The Prefer: tag lists packages to be preferred in case a choice exists. When the package name is prefixed with a dash, this is treated as a de-prefer. ==== Prefer: PACKAGE_A:PACKAGES It is possible to define the prefer only when one package is creating the choice error. This package must be listed first with a colon. ==== Preinstall: PACKAGES Are needed to run the package installation program. These packages get unpacked before the VM gets started. Included scripts are not executed during this phase. However, these packages will get installed again inside of the VM including script execution. ==== PublishFlag: FLAG CAUTION: OBS only Flags which modify the behaviour during repository generation. * create_empty Create a repository even with no content, but with meta data. * noearlykiwipublish Only publish kiwi build results after entire repository has finished building. Without this kiwi build results get published immediately after the build is finished. * nofailedpackages Block publishing if any build result was failed, broken, or unresolvable. This is evaluated individually for each architecture. That means, packages can be published for an architecture on which it builds, even if a package fails to build on another architecture. * withreports Also publish internal content tracking files (.report files). * ympdist:NAME (OBS 2.11 or later) 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. ==== PublishFilter: REGEXP [REGEXP] CAUTION: OBS only Limits the published binary packages in public repositories. Packages that match any REGEXP will not be put into the exported repository. There can be only one line of PublishFilter for historic reasons. However, multiple REGEXP can be defined. ==== Repotype: TYPE[:OPTIONS] Defines the repository format for published repositories. Valid values are: none, rpm-md, suse, debian, hdlist2, arch, staticlinks and vagrant. The OPTIONS parameter depends on the repository type, for rpm-md the known options are `legacy' to create the old rpm-md format, `deltainfo' or `prestodelta' to create delta rpm packages, `rsyncable' to use rsyncable gzip compression. To split the debug packages in an own published repository the option splitdebug:REPOSITORY_SUFFIX can be appended, e.g. ==== Repotype: rpm-md splitdebug:-debuginfo (the repository format may even be omitted to use the default type). This results in a debuginfo package repository being created in parallel to the package repository. ==== Required: PACKAGES Contain one or more packages that always get installed for package builds. A change in one of these packages triggers a new build. ==== Runscripts: PACKAGES Defines the scripts of preinstalled packages which needs to be executed directly after the preinstall phase, but before installing the remaining packages. ==== Substitute: PACKAGE_A PACKAGES 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. ==== Support: PACKAGES Contain one or more packages which also get installed for package builds, but a change in one of the packages does not trigger an automatic rebuild. This is useful for packages that most likely do not influence the build result, for example make or coreutils. ==== Target: TARGET_ARCH (RPM only) Defines the target architecture. This can be used to build for i686 on i586 schedulers for example. ==== Target: GNU_TRIPLET (DEB only) Defines the target architecture via a gnu triplet (not the debian architecture!). For example arm-linux-gnueabihf for armv7hl builds. ==== Type: TYPE Build recipe type. This is the format of the file which provides the build description. This gets usually autodetected, but in some rare cases it can be set here to either one of these: spec, dsc, kiwi, livebuild, arch, preinstallimage. Defines the build recipe format. Valid values are currently: none, spec, dsc, arch, kiwi, preinstallimage. If no type is specified, OBS deduces a type from the binary type. ==== VMInstall: PACKAGES 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. === Macros Macros are defined at the end of the project configuration. The macro section is only used on RPM builds. The project configuration knows two possible definitions: %define Macro Definition Starting with a %define line and are used in the project configuration only. These definitions are not available inside the build root. These are only needed when these macros are used elsewhere in the build config. For example: %define _use_profiler 1 %if 0%{?_use_profiler} Require: gprof %endif Another example doing it by architecture: %ifarch x86_64 Support: x86_64_only_package %endif === Macro Definitions Starting after the Macros: line and are exported into the .rpmmacros file of the build root. As such, these macro definitions can be used in a spec file. For example, you can define %define _with_pulseaudio 1 Macros Used in Spec Files Only The macro definition in the project configuration is located at the end and has the following structure: Structure of a Macro Definition Macros: # add your macro definitions here %_hardened_build 0 :Macros Everything that starts with a hash mark (#) is considered a comment. 07070100000002000081a400000000000000000000000163e504ba00000d18000000000000000000000000000000000000001b00000000docs/cross_arch_build.adoc=== Cross Architecture Build Cross architecture builds specify two sets of repositories, one for the build environement and one for the environment for the build result. ==== Terminology The terminiology for this is unfortunatly not standarised and tools have conflicting defintions. We use the following ===== Host: The architecture build environment which executes the for example the compiler. cmake is calling this HOST as well (eg. CMAKE_HOST_SYSTEM_PROCESSOR) GNU tools (esp. the configure scripts generated by autoconf) is using BUILD as abbrevasion here ===== Target: The architecture of the resulting binaries cmake has this as default without any abbrevasion (eg. CMAKE_SYSTEM_PROCESSOR) GNU tools (esp. the configure scripts generated by autoconf) is using HOST as abbrevasion here: The "TARGET" defintion of them is something else, usually only used for compilers where it defines the target architecture a from a cross build compiler. ===== The compatible terms can be found in the following table: Unfortunatly the naming of architecture areas is not consistent via the various build tooling. Please find the terminilogy mapping from our "build" script and other toolings in the list below. [width="15%"] |================================= |build || host | target | -/- |cmake || HOST | default | -/- |GNU || build | host | target |rpm || build | target | -/- |================================= Our build script just knows the host and target definition as described above. cmake is similar, just uses different namings. GNU (esp. in automake and autoconf) has actually three definitions, mainly for compiler toolchain. "build" is the environment which creates binaries. Host are the resulting binaries. And target is important when these binaries can build binaries as well for another target. ==== Dependency handling Dependencies need to be resolved always twice during a cross build. One time for the host architecture and one time for the target architecture. Build dependencies of a package get only installed for the target architecture by default. However, global rules in the build configuration can get created to modify this behaviour. ===== AlsoNative: PACKAGES Can be used to mark a package to get installed into the target and in the host system. ===== OnlyNative: PACKAGES Can be used to to install a package in the hostsystem, but not in the target system. Eg. for build tooling or code generators. ===== The target base system All packages for a host system which are configured as "Requrired" get installed only in the host system, but not in the target system. The reason behind is that this packages are only supposed to be able to execute commands and therefore they are not needed in the target environment. Only the build dependencies get installed there. However, some distributions may lack a complete set of dependencies (esp. debian based). In this case the base system for the target system can manually get configured via Substitute: sysroot-packages PACKAGES ==== Example Calls in spec files for cross build Note: the basic design of rpm was the GNU style, but it changed in the way that you have to specify the host architecture via %target macro on most distributions: ./configure --build=%build --host=%target === Repository setup === Build Config 07070100000003000081a400000000000000000000000163e504ba00000186000000000000000000000000000000000000001000000000docs/index.html<html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>The Build Script</title> <meta http-equiv="refresh" content="0;URL='http://opensuse.github.io/obs-build/pbuild.html'" /> </head> <body> <p>We just have the pbuild documentation atm: <a href="http://opensuse.github.io/obs-build/pbuild.html"> pbuild.html</a>.</p> </body> </html> 07070100000004000081a400000000000000000000000163e504ba00001119000000000000000000000000000000000000001100000000docs/pbuild.adoc= pbuild Reference Guide :toc: :icons: :numbered: :website: https://www.geckito.org/ == Goals == Design The pbuild tool is a level above "the build script" called "build". "build" is handling single build jobs, while pbuild is managing the dependencies between this build jobs. Both can get executed on any Linux system directly. pbuild is processing local sources, but may download remote sources and binaries when referenced. The local sources can get managed by any source revision management tool (eg. git). The tasks of the build script are: * Building a defined and reproducable environement for one build job * Calling the build tool for any supported format (rpm, deb, kiwi image, docker, ...) * Calling validations as provided by the build environement * Extract build results * Parse dependencies in binaries and build description files The tasks of pbuild are: * calculating the dependencies between the build jobs for a build order * calculating the need of rebuilds due to changed sources or dependencies * manage multiple running build jobs in the background * organize build results on the disk * download remote assets (sources or binaries) === Filesystem Structure pbuild expects to get call in a directory where it's project configuration files are living. Package sources live in directories inside of this project directory: * Top directory ** Package A *** source files ** Package B *** source files ** ... ** _pbuild ** _config ** _build.<preset> *** _jobhistory *** Package A results **** Build results *** Package B results **** Build results *** .pbuild ==== _config Can define build configurations. Usually defaults from a distribution are used, but this file can provide additional rules. These define which packages need to become available in the build environment, macro definitions and many more. See the build config topic for a detailed list. ==== _pbuild This file defines one or more presets. A preset defines which * distribution configuration * repositories * hardware architectures ==== _build.<preset> contains all binaries for the given preset. These are either downloaded or build local. Additional underscore prefixed files contain informations about the build history and current states of the build. === Important Options pbuild does not need any parameters by default. It will build inside of KVM by default which can work as user (non-root) in a proper environment. KVM will also ensure that the correct kernel is running during build. However, builds in chroot or containern is also possible via --vm-type=chroot --vm-type=docker Define the amount of provided memory in KVM via --vm-memory=MEGABYTES The build environment disk space can get defined via --vm-disk-size=MEGABYTES The KVM is fully isolated by default. This ensures that the build can become fully reproducibile and also that no attack by using untrusted sources or binaries can happen. However, one may want to use remote resources during build. In that case network access can get enabled via --vm-network Keep in mind that this can get usually avoided by using remote assets instead. === Important Debugging Options pbuild always creates a consistent state. That means it may not build actually anything, when the last build result look current. One can enforce a rebuild by using: --rebuild <PACKAGE> The build log is by default only stored on disk. The live build log can be made available by using the --showlog option. If you want to debug a problem with a single package, you can use the --single <PACKAGE> option to make pbuild only look at the specified package. This also triggers an rebuild of the package. It often makes sense to use --single <PACKAGE> --shell-after-fail to get a shell prompt in case a build failure occurs. Alternatively, one can reuse last build enviroment or create a new one by using the --shell option. This will give a prompt after the environment has been initialized. Extra packages needed for debugging can be specified with -x binary_package (eg. gdb, strace, valgrind or assumed missing dependencies for testing). include::source_assets.adoc[] include::build_config.adoc[] == Functionalities === package builds Package builds are supported for rpm, deb, arch and their variations. === image builds === container builds include::cross_arch_build.adoc[] 07070100000005000081a400000000000000000000000163e504ba0000db90000000000000000000000000000000000000001100000000docs/pbuild.html<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> <head> <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" /> <meta name="generator" content="AsciiDoc" /> <title>pbuild Reference Guide</title> <style type="text/css"> /* Shared CSS for AsciiDoc xhtml11 and html5 backends */ /* Default font. */ body { font-family: Georgia,serif; } /* Title font. */ h1, h2, h3, h4, h5, h6, div.title, caption.title, thead, p.table.header, #toctitle, #author, #revnumber, #revdate, #revremark, #footer { font-family: Arial,Helvetica,sans-serif; } body { margin: 1em 5% 1em 5%; } a { color: blue; text-decoration: underline; } a:visited { color: fuchsia; } em { font-style: italic; color: navy; } strong { font-weight: bold; color: #083194; } h1, h2, h3, h4, h5, h6 { color: #527bbd; margin-top: 1.2em; margin-bottom: 0.5em; line-height: 1.3; } h1, h2, h3 { border-bottom: 2px solid silver; } h2 { padding-top: 0.5em; } h3 { float: left; } h3 + * { clear: left; } h5 { font-size: 1.0em; } div.sectionbody { margin-left: 0; } hr { border: 1px solid silver; } p { margin-top: 0.5em; margin-bottom: 0.5em; } ul, ol, li > p { margin-top: 0; } ul > li { color: #aaa; } ul > li > * { color: black; } .monospaced, code, pre { font-family: "Courier New", Courier, monospace; font-size: inherit; color: navy; padding: 0; margin: 0; } pre { white-space: pre-wrap; } #author { color: #527bbd; font-weight: bold; font-size: 1.1em; } #email { } #revnumber, #revdate, #revremark { } #footer { font-size: small; border-top: 2px solid silver; padding-top: 0.5em; margin-top: 4.0em; } #footer-text { float: left; padding-bottom: 0.5em; } #footer-badges { float: right; padding-bottom: 0.5em; } #preamble { margin-top: 1.5em; margin-bottom: 1.5em; } div.imageblock, div.exampleblock, div.verseblock, div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock, div.admonitionblock { margin-top: 1.0em; margin-bottom: 1.5em; } div.admonitionblock { margin-top: 2.0em; margin-bottom: 2.0em; margin-right: 10%; color: #606060; } div.content { /* Block element content. */ padding: 0; } /* Block element titles. */ div.title, caption.title { color: #527bbd; font-weight: bold; text-align: left; margin-top: 1.0em; margin-bottom: 0.5em; } div.title + * { margin-top: 0; } td div.title:first-child { margin-top: 0.0em; } div.content div.title:first-child { margin-top: 0.0em; } div.content + div.title { margin-top: 0.0em; } div.sidebarblock > div.content { background: #ffffee; border: 1px solid #dddddd; border-left: 4px solid #f0f0f0; padding: 0.5em; } div.listingblock > div.content { border: 1px solid #dddddd; border-left: 5px solid #f0f0f0; background: #f8f8f8; padding: 0.5em; } div.quoteblock, div.verseblock { padding-left: 1.0em; margin-left: 1.0em; margin-right: 10%; border-left: 5px solid #f0f0f0; color: #888; } div.quoteblock > div.attribution { padding-top: 0.5em; text-align: right; } div.verseblock > pre.content { font-family: inherit; font-size: inherit; } div.verseblock > div.attribution { padding-top: 0.75em; text-align: left; } /* DEPRECATED: Pre version 8.2.7 verse style literal block. */ div.verseblock + div.attribution { text-align: left; } div.admonitionblock .icon { vertical-align: top; font-size: 1.1em; font-weight: bold; text-decoration: underline; color: #527bbd; padding-right: 0.5em; } div.admonitionblock td.content { padding-left: 0.5em; border-left: 3px solid #dddddd; } div.exampleblock > div.content { border-left: 3px solid #dddddd; padding-left: 0.5em; } div.imageblock div.content { padding-left: 0; } span.image img { border-style: none; vertical-align: text-bottom; } a.image:visited { color: white; } dl { margin-top: 0.8em; margin-bottom: 0.8em; } dt { margin-top: 0.5em; margin-bottom: 0; font-style: normal; color: navy; } dd > *:first-child { margin-top: 0.1em; } ul, ol { list-style-position: outside; } ol.arabic { list-style-type: decimal; } ol.loweralpha { list-style-type: lower-alpha; } ol.upperalpha { list-style-type: upper-alpha; } ol.lowerroman { list-style-type: lower-roman; } ol.upperroman { list-style-type: upper-roman; } div.compact ul, div.compact ol, div.compact p, div.compact p, div.compact div, div.compact div { margin-top: 0.1em; margin-bottom: 0.1em; } tfoot { font-weight: bold; } td > div.verse { white-space: pre; } div.hdlist { margin-top: 0.8em; margin-bottom: 0.8em; } div.hdlist tr { padding-bottom: 15px; } dt.hdlist1.strong, td.hdlist1.strong { font-weight: bold; } td.hdlist1 { vertical-align: top; font-style: normal; padding-right: 0.8em; color: navy; } td.hdlist2 { vertical-align: top; } div.hdlist.compact tr { margin: 0; padding-bottom: 0; } .comment { background: yellow; } .footnote, .footnoteref { font-size: 0.8em; } span.footnote, span.footnoteref { vertical-align: super; } #footnotes { margin: 20px 0 20px 0; padding: 7px 0 0 0; } #footnotes div.footnote { margin: 0 0 5px 0; } #footnotes hr { border: none; border-top: 1px solid silver; height: 1px; text-align: left; margin-left: 0; width: 20%; min-width: 100px; } div.colist td { padding-right: 0.5em; padding-bottom: 0.3em; vertical-align: top; } div.colist td img { margin-top: 0.3em; } @media print { #footer-badges { display: none; } } #toc { margin-bottom: 2.5em; } #toctitle { color: #527bbd; font-size: 1.1em; font-weight: bold; margin-top: 1.0em; margin-bottom: 0.1em; } div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 { margin-top: 0; margin-bottom: 0; } div.toclevel2 { margin-left: 2em; font-size: 0.9em; } div.toclevel3 { margin-left: 4em; font-size: 0.9em; } div.toclevel4 { margin-left: 6em; font-size: 0.9em; } span.aqua { color: aqua; } span.black { color: black; } span.blue { color: blue; } span.fuchsia { color: fuchsia; } span.gray { color: gray; } span.green { color: green; } span.lime { color: lime; } span.maroon { color: maroon; } span.navy { color: navy; } span.olive { color: olive; } span.purple { color: purple; } span.red { color: red; } span.silver { color: silver; } span.teal { color: teal; } span.white { color: white; } span.yellow { color: yellow; } span.aqua-background { background: aqua; } span.black-background { background: black; } span.blue-background { background: blue; } span.fuchsia-background { background: fuchsia; } span.gray-background { background: gray; } span.green-background { background: green; } span.lime-background { background: lime; } span.maroon-background { background: maroon; } span.navy-background { background: navy; } span.olive-background { background: olive; } span.purple-background { background: purple; } span.red-background { background: red; } span.silver-background { background: silver; } span.teal-background { background: teal; } span.white-background { background: white; } span.yellow-background { background: yellow; } span.big { font-size: 2em; } span.small { font-size: 0.6em; } span.underline { text-decoration: underline; } span.overline { text-decoration: overline; } span.line-through { text-decoration: line-through; } div.unbreakable { page-break-inside: avoid; } /* * xhtml11 specific * * */ div.tableblock { margin-top: 1.0em; margin-bottom: 1.5em; } div.tableblock > table { border: 3px solid #527bbd; } thead, p.table.header { font-weight: bold; color: #527bbd; } p.table { margin-top: 0; } /* Because the table frame attribute is overridden by CSS in most browsers. */ div.tableblock > table[frame="void"] { border-style: none; } div.tableblock > table[frame="hsides"] { border-left-style: none; border-right-style: none; } div.tableblock > table[frame="vsides"] { border-top-style: none; border-bottom-style: none; } /* * html5 specific * * */ table.tableblock { margin-top: 1.0em; margin-bottom: 1.5em; } thead, p.tableblock.header { font-weight: bold; color: #527bbd; } p.tableblock { margin-top: 0; } table.tableblock { border-width: 3px; border-spacing: 0px; border-style: solid; border-color: #527bbd; border-collapse: collapse; } th.tableblock, td.tableblock { border-width: 1px; padding: 4px; border-style: solid; border-color: #527bbd; } table.tableblock.frame-topbot { border-left-style: hidden; border-right-style: hidden; } table.tableblock.frame-sides { border-top-style: hidden; border-bottom-style: hidden; } table.tableblock.frame-none { border-style: hidden; } th.tableblock.halign-left, td.tableblock.halign-left { text-align: left; } th.tableblock.halign-center, td.tableblock.halign-center { text-align: center; } th.tableblock.halign-right, td.tableblock.halign-right { text-align: right; } th.tableblock.valign-top, td.tableblock.valign-top { vertical-align: top; } th.tableblock.valign-middle, td.tableblock.valign-middle { vertical-align: middle; } th.tableblock.valign-bottom, td.tableblock.valign-bottom { vertical-align: bottom; } /* * manpage specific * * */ body.manpage h1 { padding-top: 0.5em; padding-bottom: 0.5em; border-top: 2px solid silver; border-bottom: 2px solid silver; } body.manpage h2 { border-style: none; } body.manpage div.sectionbody { margin-left: 3em; } @media print { body.manpage div#toc { display: none; } } </style> <script type="text/javascript"> /*<+'])'); // Function that scans the DOM tree for header elements (the DOM2 // nodeIterator API would be a better technique but not supported by all // browsers). var iterate = function (el) { for (var i = el.firstChild; i != null; i = i.nextSibling) { if (i.nodeType == 1 /* Node.ELEMENT_NODE */) { var mo = re.exec(i.tagName); if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") { result[result.length] = new TocEntry(i, getText(i), mo[1]-1); } iterate(i); } } } iterate(el); return result; } var toc = document.getElementById("toc"); if (!toc) { return; } // Delete existing TOC entries in case we're reloading the TOC. var tocEntriesToRemove = []; var i; for (i = 0; i < toc.childNodes.length; i++) { var entry = toc.childNodes[i]; if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") && entry.getAttribute("class").match(/^toclevel/)) tocEntriesToRemove.push(entry); } for (i = 0; i < tocEntriesToRemove.length; i++) { toc.removeChild(tocEntriesToRemove[i]); } // Rebuild TOC entries. var entries = tocEntries(document.getElementById("content"), toclevels); for (var i = 0; i < entries.length; ++i) { var entry = entries[i]; if (entry.element.id == "") entry.element.id = "_toc_" + i; var a = document.createElement("a"); a.href = "#" + entry.element.id; a.appendChild(document.createTextNode(entry.text)); var div = document.createElement("div"); div.appendChild(a); div.className = "toclevel" + entry.toclevel; toc.appendChild(div); } if (entries.length == 0) toc.parentNode.removeChild(toc); }, ///////////////////////////////////////////////////////////////////// // Footnotes generator ///////////////////////////////////////////////////////////////////// /* Based on footnote generation code from: * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html */ footnotes: function () { // Delete existing footnote entries in case we're reloading the footnodes. var i; var noteholder = document.getElementById("footnotes"); if (!noteholder) { return; } var entriesToRemove = []; for (i = 0; i < noteholder.childNodes.length; i++) { var entry = noteholder.childNodes[i]; if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote") entriesToRemove.push(entry); } for (i = 0; i < entriesToRemove.length; i++) { noteholder.removeChild(entriesToRemove[i]); } // Rebuild footnote entries. var cont = document.getElementById("content"); var spans = cont.getElementsByTagName("span"); var refs = {}; var n = 0; for (i=0; i<spans.length; i++) { if (spans[i].className == "footnote") { n++; var note = spans[i].getAttribute("data-note"); if (!note) { // Use [\s\S] in place of . so multi-line matches work. // Because JavaScript has no s (dotall) regex flag. note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1]; spans[i].innerHTML = "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n + "' title='View footnote' class='footnote'>" + n + "</a>]"; spans[i].setAttribute("data-note", note); } noteholder.innerHTML += "<div class='footnote' id='_footnote_" + n + "'>" + "<a href='#_footnoteref_" + n + "' title='Return to text'>" + n + "</a>. " + note + "</div>"; var id =spans[i].getAttribute("id"); if (id != null) refs["#"+id] = n; } } if (n == 0) noteholder.parentNode.removeChild(noteholder); else { // Process footnoterefs. for (i=0; i<spans.length; i++) { if (spans[i].className == "footnoteref") { var href = spans[i].getElementsByTagName("a")[0].getAttribute("href"); href = href.match(/#.*/)[0]; // Because IE return full URL. n = refs[href]; spans[i].innerHTML = "[<a href='#_footnote_" + n + "' title='View footnote' class='footnote'>" + n + "</a>]"; } } } }, install: function(toclevels) { var timerId; function reinstall() { asciidoc.footnotes(); if (toclevels) { asciidoc.toc(toclevels); } } function reinstallAndRemoveTimer() { clearInterval(timerId); reinstall(); } timerId = setInterval(reinstall, 500); if (document.addEventListener) document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false); else window.onload = reinstallAndRemoveTimer; } } asciidoc.install(2); /*]]>*/ </script> </head> <body class="article"> <div id="header"> <h1>pbuild Reference Guide</h1> <div id="toc"> <div id="toctitle">Table of Contents</div> <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript> </div> </div> <div id="content"> <div class="sect1"> <h2 id="_goals">1. Goals</h2> <div class="sectionbody"> </div> </div> <div class="sect1"> <h2 id="_design">2. Design</h2> <div class="sectionbody"> <div class="paragraph"><p>The pbuild tool is a level above "the build script" called "build". "build" is handling single build jobs, while pbuild is managing the dependencies between this build jobs. Both can get executed on any Linux system directly.</p></div> <div class="paragraph"><p>pbuild is processing local sources, but may download remote sources and binaries when referenced. The local sources can get managed by any source revision management tool (eg. git).</p></div> <div class="paragraph"><p>The tasks of the build script are: * Building a defined and reproducable environement for one build job * Calling the build tool for any supported format (rpm, deb, kiwi image, docker, …) * Calling validations as provided by the build environement * Extract build results * Parse dependencies in binaries and build description files</p></div> <div class="paragraph"><p>The tasks of pbuild are: * calculating the dependencies between the build jobs for a build order * calculating the need of rebuilds due to changed sources or dependencies * manage multiple running build jobs in the background * organize build results on the disk * download remote assets (sources or binaries)</p></div> <div class="sect2"> <h3 id="_filesystem_structure">2.1. Filesystem Structure</h3> <div class="paragraph"><p>pbuild expects to get call in a directory where it’s project configuration files are living. Package sources live in directories inside of this project directory:</p></div> <div class="ulist"><ul> <li> <p> Top directory </p> <div class="ulist"><ul> <li> <p> Package A </p> <div class="ulist"><ul> <li> <p> source files </p> </li> </ul></div> </li> <li> <p> Package B </p> <div class="ulist"><ul> <li> <p> source files </p> </li> </ul></div> </li> <li> <p> … </p> </li> <li> <p> _pbuild </p> </li> <li> <p> _config </p> </li> <li> <p> _build.<preset> </p> <div class="ulist"><ul> <li> <p> _jobhistory </p> </li> <li> <p> Package A results </p> <div class="ulist"><ul> <li> <p> Build results </p> </li> </ul></div> </li> <li> <p> Package B results </p> <div class="ulist"><ul> <li> <p> Build results </p> </li> </ul></div> </li> <li> <p> .pbuild </p> </li> </ul></div> </li> </ul></div> </li> </ul></div> <div class="sect3"> <h4 id="_config">2.1.1. _config</h4> <div class="paragraph"><p>Can define build configurations. Usually defaults from a distribution are used, but this file can provide additional rules. These define which packages need to become available in the build environment, macro definitions and many more. See the build config topic for a detailed list.</p></div> </div> <div class="sect3"> <h4 id="_pbuild">2.1.2. _pbuild</h4> <div class="paragraph"><p>This file defines one or more presets. A preset defines which</p></div> <div class="ulist"><ul> <li> <p> distribution configuration </p> </li> <li> <p> repositories </p> </li> <li> <p> hardware architectures </p> </li> </ul></div> </div> <div class="sect3"> <h4 id="_build_lt_preset_gt">2.1.3. _build.<preset></h4> <div class="paragraph"><p>contains all binaries for the given preset. These are either downloaded or build local. Additional underscore prefixed files contain informations about the build history and current states of the build.</p></div> </div> </div> <div class="sect2"> <h3 id="_important_options">2.2. Important Options</h3> <div class="paragraph"><p>pbuild does not need any parameters by default. It will build inside of KVM by default which can work as user (non-root) in a proper environment. KVM will also ensure that the correct kernel is running during build. However, builds in chroot or containern is also possible via</p></div> <div class="literalblock"> <div class="content"> <pre><code>--vm-type=chroot --vm-type=docker</code></pre> </div></div> <div class="paragraph"><p>Define the amount of provided memory in KVM via</p></div> <div class="literalblock"> <div class="content"> <pre><code>--vm-memory=MEGABYTES</code></pre> </div></div> <div class="paragraph"><p>The build environment disk space can get defined via</p></div> <div class="literalblock"> <div class="content"> <pre><code>--vm-disk-size=MEGABYTES</code></pre> </div></div> <div class="paragraph"><p>The KVM is fully isolated by default. This ensures that the build can become fully reproducibile and also that no attack by using untrusted sources or binaries can happen. However, one may want to use remote resources during build. In that case network access can get enabled via</p></div> <div class="literalblock"> <div class="content"> <pre><code>--vm-network</code></pre> </div></div> <div class="paragraph"><p>Keep in mind that this can get usually avoided by using remote assets instead.</p></div> </div> <div class="sect2"> <h3 id="_important_debugging_options">2.3. Important Debugging Options</h3> <div class="paragraph"><p>pbuild always creates a consistent state. That means it may not build actually anything, when the last build result look current. One can enforce a rebuild by using:</p></div> <div class="literalblock"> <div class="content"> <pre><code>--rebuild <PACKAGE></code></pre> </div></div> <div class="paragraph"><p>The build log is by default only stored on disk. The live build log can be made available by using the</p></div> <div class="literalblock"> <div class="content"> <pre><code>--showlog</code></pre> </div></div> <div class="paragraph"><p>option. If you want to debug a problem with a single package, you can use the</p></div> <div class="literalblock"> <div class="content"> <pre><code>--single <PACKAGE></code></pre> </div></div> <div class="paragraph"><p>option to make pbuild only look at the specified package. This also triggers an rebuild of the package. It often makes sense to use</p></div> <div class="literalblock"> <div class="content"> <pre><code>--single <PACKAGE> --shell-after-fail</code></pre> </div></div> <div class="paragraph"><p>to get a shell prompt in case a build failure occurs.</p></div> <div class="paragraph"><p>Alternatively, one can reuse last build enviroment or create a new one by using the</p></div> <div class="literalblock"> <div class="content"> <pre><code>--shell</code></pre> </div></div> <div class="paragraph"><p>option. This will give a prompt after the environment has been initialized.</p></div> <div class="paragraph"><p>Extra packages needed for debugging can be specified with</p></div> <div class="literalblock"> <div class="content"> <pre><code>-x binary_package</code></pre> </div></div> <div class="paragraph"><p>(eg. gdb, strace, valgrind or assumed missing dependencies for testing).</p></div> </div> <div class="sect2"> <h3 id="_remote_assets">2.4. Remote Assets</h3> <div class="paragraph"><p>Remote Assets can be defined inside of the build descriptions. They are resources from a remote servers and will be downloaded and validated by pbuild before the corresponding build is started.</p></div> <div class="paragraph"><p>Supported protocols for resources using an url are:</p></div> <div class="ulist"><ul> <li> <p> http </p> </li> <li> <p> https </p> </li> <li> <p> git+http </p> </li> <li> <p> git+https </p> </li> </ul></div> <div class="paragraph"><p>This depends on the build description format as described below.</p></div> <div class="sect3"> <h4 id="_rpm_spec_files">2.4.1. rpm spec files</h4> <div class="paragraph"><p>Source lines in spec files can declare remote assets. Rpm is already supporting to use an URL as source definition. A comment before such a line marks it as remote asset for pbuild:</p></div> <div class="literalblock"> <div class="content"> <pre><code>#!RemoteAsset Source: <URL></code></pre> </div></div> <div class="paragraph"><p>It is also possible to specify a checksum to make sure that the asset is correct.</p></div> <div class="literalblock"> <div class="content"> <pre><code>#!RemoteAsset: <CHECKSUM> Source: <URL></code></pre> </div></div> <div class="paragraph"><p>An alternative is just to use the</p></div> <div class="literalblock"> <div class="content"> <pre><code>#!RemoteAssetUrl: <URL></code></pre> </div></div> <div class="paragraph"><p>marker without any Source: tag when the downloaded file should not become part of the source rpm.</p></div> </div> <div class="sect3"> <h4 id="_kiwi_build_description">2.4.2. kiwi build description</h4> <div class="paragraph"><p>The kiwi format is not supporting remote source specifications, but they can be specified via XML comments.</p></div> <div class="literalblock"> <div class="content"> <pre><code><!-- OBS-RemoteAsset: <URL> --></code></pre> </div></div> <div class="paragraph"><p>The resulting downloaded file can be copied into the image using</p></div> <div class="literalblock"> <div class="content"> <pre><code><!-- OBS-CopyToImage: <source> <destination> --></code></pre> </div></div> <div class="paragraph"><p>The kiwi profile name is added to container names by default. This can be disabled via</p></div> <div class="literalblock"> <div class="content"> <pre><code><!-- OBS-DoNotAppendProfileToContainername --></code></pre> </div></div> </div> <div class="sect3"> <h4 id="_dockerfile_description">2.4.3. Dockerfile description</h4> <div class="paragraph"><p>Has no support for assets yet.</p></div> </div> <div class="sect3"> <h4 id="_arch_linux_pkgbuild">2.4.4. Arch Linux PKGBUILD</h4> <div class="paragraph"><p>PKGBuild files already contain the needed URLs and Checksums, so no extra treatment is needed.</p></div> </div> <div class="sect3"> <h4 id="_fedpkg_sources_file">2.4.5. FedPkg "sources" file</h4> <div class="paragraph"><p>The sources file contains a list of file names with checksums. PBuild will automatically download the missing files from a FedPkg Server that needs to be configured in the project config via the "AssetsURL:" directive or set with the "--assets" option.</p></div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_about_the_build_configuration">3. About the Build Configuration</h2> <div class="sectionbody"> <div class="paragraph"><p>The build configuration syntax is</p></div> <div class="paragraph"><p>Switch on or off certain features during the build.</p></div> <div class="paragraph"><p>Decide which package is installed during build if there are circular dependencies.</p></div> <div class="paragraph"><p>Handle user decisions like package providing the same or special macros, packages, or flags in the build environment.</p></div> <div class="sect2"> <h3 id="_configuration_file_syntax">3.1. Configuration File Syntax</h3> <div class="paragraph"><p>The syntax is basically the same than in RPM spec files. However, it is independent of the used packaging format. The project configuration is parsed by &obsa;. This means, you can use RPM features like macros or conditions in the configuration. All lines have the form:</p></div> <div class="paragraph"><p>keyword: arguments</p></div> <div class="paragraph"><p>In addition to that rpm macro statement can get used, for example to activate some rules only for specific architectures via conditions.</p></div> <div class="paragraph"><p>The following list contains a list of allowed keywords in the project configuration:</p></div> <div class="paragraph"><p>Available Keywords in Project Configuration</p></div> <div class="sect3"> <h4 id="_binarytype_type">3.1.1. BinaryType: TYPE</h4> <div class="paragraph"><p>The binary type is the format of the files which will be the result of the build jobs. This gets usually set depending on the build recipe type. In some situations, for example a &kiwi; build job result gets converted into an rpm, it can be used to overwrite it. Possible values are: rpm, deb or none.</p></div> <div class="paragraph"><p>Sets the binary format used to set up the build environment. For example a package with spec build description may use and generate deb packages instead of RPMs. If no binary type is specified, OBS deduces it from the build recipe type. If the recipe type is also not set, OBS looks at the Preinstall package list for a hint.</p></div> </div> <div class="sect3"> <h4 id="_buildengine_engine">3.1.2. BuildEngine: ENGINE</h4> <div class="paragraph"><p>Use an alternative build engine. This is still chained inside of the build script for security reasons. Alternatives are mock (for Fedora and Red Hat) and debootstrap (for Debian). This will avoid differences in the build environment setup, but it will also have an effect on speed and reduced features. It should only be used when you want to emulate the distribution build. debbuild engine will build deb files out of a spec file description. It can be used by the following definition inside of the project build config:</p></div> <div class="literalblock"> <div class="content"> <pre><code>Repotype: debian Type: spec Binarytype: deb BuildEngine: debbuild Support: pax Support: debbuild Keep: debbuild</code></pre> </div></div> </div> <div class="sect3"> <h4 id="_buildflags_flag_value">3.1.3. BuildFlags: FLAG:VALUE</h4> <div class="paragraph"><p>The BuildFlags keyword defines flags for the build process. The following values for FLAG are usable. All flags with a leading colon (:) require an additional parameter directly following them.</p></div> <div class="ulist"><ul> <li> <p> vmfstype:TYPE </p> </li> </ul></div> <div class="paragraph"><p>Defines a specific file system when building inside of a VM. Possible values are ext2, ext3, ext4, btrfs, xfs, reiserfs (v3).</p></div> <div class="ulist"><ul> <li> <p> vmfsoptions:OPTIONS </p> </li> </ul></div> <div class="paragraph"><p>There is also an option to disable directory indexing for ext2, ext3, and ext4 file systems. This makes file ordering inside of directories reproducible but may have a negative performance impact. To apply this, specify vmfsoptions:nodirindex</p></div> <div class="ulist"><ul> <li> <p> kiwiprofile:PROFILE </p> </li> </ul></div> <div class="paragraph"><p>builds the selected profile in &kiwi; appliance builds.</p></div> <div class="ulist"><ul> <li> <p> logidlelimit:SECONDS </p> </li> </ul></div> <div class="paragraph"><p>Build jobs which don’t create any output get aborted after some time. This flag can be used to modify the limit. Specify the seconds behind flag.</p></div> <div class="ulist"><ul> <li> <p> excludebuild:PACKAGE </p> </li> </ul></div> <div class="paragraph"><p>Exclude a package from building. _multibuild flavors can be specified via package:flavor syntax.</p></div> <div class="ulist"><ul> <li> <p> onlybuild:PACKAGE </p> </li> </ul></div> <div class="paragraph"><p>DANGER: this may remove many build results when introduced the first time! It can be used to maintain a whitelist of packages to be built. All other packages will turn to excluded state.</p></div> <div class="ulist"><ul> <li> <p> ccachetype:TYPE </p> </li> </ul></div> <div class="paragraph"><p>Defines the ccache implementation, possible values are: ccache, sccache</p></div> <div class="ulist"><ul> <li> <p> useccache:PACKAGE </p> </li> </ul></div> <div class="paragraph"><p>Configure usage of ccache when building packages that match the value of this parameter. The ccache package will automatically be installed and configured. The directory /.ccache/ will be configured as cache directory. To configure ccache, the file /.ccache/ccache.conf can be modified as part of the build process by the $BUILD_USER environment variable.</p></div> <div class="paragraph"><p>In some cases, there is no archive for the current package, such as when the package was newly branched or when binaries were deleted. In these cases, &obs; will check whether there is a package of the same name built for the same architecture within one of the repositories configured in the project’s meta configuration. If so, the archive of that package will be used. The repositories will be searched in the order they are configured in the meta configuration, starting from the top.</p></div> <div class="paragraph"><p>An alternative way to enable caching based on build dependencies is to add "--enable-cache" as dependency, for example via a Substitute rule:</p></div> <div class="literalblock"> <div class="content"> <pre><code>Substitute: gcc-c++ gcc-c++ --enable-ccache</code></pre> </div></div> <div class="paragraph"><p>This will always enable ccache when a direct build depdency to gcc-c++ is required.</p></div> <div class="paragraph"><p>It is also possible to set the type, eg:</p></div> <div class="literalblock"> <div class="content"> <pre><code>Substitute: cargo cargo --enable-ccache=sccache</code></pre> </div></div> <div class="ulist"><ul> <li> <p> obsgendiff </p> </li> </ul></div> <div class="paragraph"><p>OBS can run an external program that has access to the current build and the previously successful result, e.g. to generate a difference or a changelog from the diff.</p></div> <div class="paragraph"><p>build will run all scripts in /usr/lib/build/obsgendiff.d/ on the build host (not in the %buildroot) when this flag is set. If one of the scripts fails to run or no scripts are found, then the overall build fails. I.e. if BuildFlags: obsgendiff is set, then you must provide at least one script in /usr/lib/build/obsgendiff.d/, otherwise your build will fail.</p></div> <div class="paragraph"><p>A common use case for obsgendiff is to run release-compare after the build.</p></div> </div> <div class="sect3"> <h4 id="_constraint_selector_string">3.1.4. Constraint: SELECTOR STRING</h4> <div class="admonitionblock"> <table><tr> <td class="icon"> <img src="./images/icons/caution.png" alt="Caution" /> </td> <td class="content">OBS only</td> </tr></table> </div> <div class="paragraph"><p>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.</p></div> </div> <div class="sect3"> <h4 id="_expandflags_flag">3.1.5. ExpandFlags: FLAG</h4> <div class="paragraph"><p>Flags which modify the behaviour during dependency resolution.</p></div> <div class="ulist"><ul> <li> <p> unorderedimagerepos (OBS 2.10 or later) </p> </li> </ul></div> <div class="paragraph"><p>The priority of repositories defined in an image build is usually important. This is to avoid switching repositories when the same package is available in multiple repositories. However, it might be wanted to ignore that and just pick the highest version. This can be achieved by defining this flag</p></div> <div class="ulist"><ul> <li> <p> preinstallexpand </p> </li> </ul></div> <div class="paragraph"><p>Preinstall also all dependencies of a preinstalled package. Instead of manually listing all packages for a working package tool one can just install dependencies of it. However, these might be more then actually needed depending on the distribution.</p></div> <div class="ulist"><ul> <li> <p> module:NAME-STREAM </p> </li> </ul></div> <div class="paragraph"><p>Enable Red Hat-specific module support in repo md repositories. By default, modules are not used, but content can be made available by specifying the module name. To remove a module, add an exclamation mark (!) as prefix.</p></div> </div> <div class="sect3"> <h4 id="_exportfilter_regex_arch">3.1.6. ExportFilter: REGEX ARCH</h4> <div class="paragraph"><p>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 must match the resulting binary name of the package. It will export it to all listed scheduler architectures. Using a single dot will export it to the architecture which was used to build it. So not using a dot there will filter the package.</p></div> </div> <div class="sect3"> <h4 id="_fileprovides_file_packages">3.1.7. FileProvides: FILE PACKAGES</h4> <div class="paragraph"><p>&obsa; ignores dependencies to files (instead of package names) by default. This is mostly done to reduce the amount of memory needed, as the package file lists take up a considerable amount of repository meta data. As a workaround, FileProvides can be used to tell the systems which packages contain a file. The File needs to have the full path.</p></div> </div> <div class="sect3"> <h4 id="_hostarch_host_arch">3.1.8. HostArch: HOST_ARCH</h4> <div class="paragraph"><p>This is used for cross builds. It defines the host architecture used for building, while the scheduler architecture remains the target architecture.</p></div> </div> <div class="sect3"> <h4 id="_ignore_packages">3.1.9. Ignore: PACKAGES</h4> <div class="paragraph"><p>Ignore can be used to break dependencies. This can be useful to reduce the number of needed packages or to break cyclic dependencies. Be careful with this feature, as breaking dependencies can have surprising results.</p></div> </div> <div class="sect3"> <h4 id="_ignore_package_a_packages">3.1.10. Ignore: PACKAGE_A:PACKAGES</h4> <div class="paragraph"><p>It is possible to define the ignore only for one package. This package must be listed first with a colon.</p></div> </div> <div class="sect3"> <h4 id="_keep_packages">3.1.11. Keep: PACKAGES</h4> <div class="paragraph"><p>To eliminate build cycles the to-be-built package is not installed by default, even when it is required. Keep can be used to overwrite this behavior. It is usually needed 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.</p></div> </div> <div class="sect3"> <h4 id="_optflags_target_arch_flags_rpm_only">3.1.12. OptFlags: TARGET_ARCH FLAGS (RPM only)</h4> <div class="paragraph"><p>Optflags exports compiler flags to the build. They will only have an effect when the spec file is using $RPM_OPT_FLAGS. The target architecture may be * to affect all architectures.</p></div> </div> <div class="sect3"> <h4 id="_order_package_a_package_b">3.1.13. Order: PACKAGE_A:PACKAGE_B</h4> <div class="paragraph"><p>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 dependencies. The Order statement can be used then to give a hint where to break the loop.</p></div> <div class="paragraph"><p>The package in PACKAGE_A will get installed before the package in PACKAGE_B.</p></div> </div> <div class="sect3"> <h4 id="_patterntype_types">3.1.14. Patterntype: TYPES</h4> <div class="paragraph"><p>Defines the pattern format. Valid values are: none (default), ymp, comps.</p></div> </div> <div class="sect3"> <h4 id="_prefer_packages">3.1.15. Prefer: PACKAGES</h4> <div class="paragraph"><p>In case multiple packages satisfy a dependency, the OBS system will complain about that situation. This is unlike like most package managing tools, which just pick one of the package. Because one of OBS’ goal is to provide reproducible builds, it reports an error in this case instead of choosing a random package. The Prefer: tag lists packages to be preferred in case a choice exists. When the package name is prefixed with a dash, this is treated as a de-prefer.</p></div> </div> <div class="sect3"> <h4 id="_prefer_package_a_packages">3.1.16. Prefer: PACKAGE_A:PACKAGES</h4> <div class="paragraph"><p>It is possible to define the prefer only when one package is creating the choice error. This package must be listed first with a colon.</p></div> </div> <div class="sect3"> <h4 id="_preinstall_packages">3.1.17. Preinstall: PACKAGES</h4> <div class="paragraph"><p>Are needed to run the package installation program. These packages get unpacked before the VM gets started. Included scripts are not executed during this phase. However, these packages will get installed again inside of the VM including script execution.</p></div> </div> <div class="sect3"> <h4 id="_publishflag_flag">3.1.18. PublishFlag: FLAG</h4> <div class="admonitionblock"> <table><tr> <td class="icon"> <img src="./images/icons/caution.png" alt="Caution" /> </td> <td class="content">OBS only</td> </tr></table> </div> <div class="paragraph"><p>Flags which modify the behaviour during repository generation.</p></div> <div class="ulist"><ul> <li> <p> create_empty </p> </li> </ul></div> <div class="paragraph"><p>Create a repository even with no content, but with meta data.</p></div> <div class="ulist"><ul> <li> <p> noearlykiwipublish </p> </li> </ul></div> <div class="paragraph"><p>Only publish kiwi build results after entire repository has finished building. Without this kiwi build results get published immediately after the build is finished.</p></div> <div class="ulist"><ul> <li> <p> nofailedpackages </p> </li> </ul></div> <div class="paragraph"><p>Block publishing if any build result was failed, broken, or unresolvable. This is evaluated individually for each architecture. That means, packages can be published for an architecture on which it builds, even if a package fails to build on another architecture.</p></div> <div class="ulist"><ul> <li> <p> withreports </p> </li> </ul></div> <div class="paragraph"><p>Also publish internal content tracking files (.report files).</p></div> <div class="ulist"><ul> <li> <p> ympdist:NAME (OBS 2.11 or later) </p> </li> </ul></div> <div class="paragraph"><p>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.</p></div> </div> <div class="sect3"> <h4 id="_publishfilter_regexp_regexp">3.1.19. PublishFilter: REGEXP [REGEXP]</h4> <div class="admonitionblock"> <table><tr> <td class="icon"> <img src="./images/icons/caution.png" alt="Caution" /> </td> <td class="content">OBS only</td> </tr></table> </div> <div class="paragraph"><p>Limits the published binary packages in public repositories. Packages that match any REGEXP will not be put into the exported repository. There can be only one line of PublishFilter for historic reasons. However, multiple REGEXP can be defined.</p></div> </div> <div class="sect3"> <h4 id="_repotype_type_options">3.1.20. Repotype: TYPE[:OPTIONS]</h4> <div class="paragraph"><p>Defines the repository format for published repositories. Valid values are: none, rpm-md, suse, debian, hdlist2, arch, staticlinks and vagrant. The OPTIONS parameter depends on the repository type, for rpm-md the known options are ‘legacy’ to create the old rpm-md format, ‘deltainfo’ or ‘prestodelta’ to create delta rpm packages, ‘rsyncable’ to use rsyncable gzip compression. To split the debug packages in an own published repository the option splitdebug:REPOSITORY_SUFFIX can be appended, e.g.</p></div> </div> <div class="sect3"> <h4 id="_repotype_rpm_md_splitdebug_debuginfo">3.1.21. Repotype: rpm-md splitdebug:-debuginfo</h4> <div class="paragraph"><p>(the repository format may even be omitted to use the default type). This results in a debuginfo package repository being created in parallel to the package repository.</p></div> </div> <div class="sect3"> <h4 id="_required_packages">3.1.22. Required: PACKAGES</h4> <div class="paragraph"><p>Contain one or more packages that always get installed for package builds. A change in one of these packages triggers a new build.</p></div> </div> <div class="sect3"> <h4 id="_runscripts_packages">3.1.23. Runscripts: PACKAGES</h4> <div class="paragraph"><p>Defines the scripts of preinstalled packages which needs to be executed directly after the preinstall phase, but before installing the remaining packages.</p></div> </div> <div class="sect3"> <h4 id="_substitute_package_a_packages">3.1.24. Substitute: PACKAGE_A PACKAGES</h4> <div class="paragraph"><p>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.</p></div> </div> <div class="sect3"> <h4 id="_support_packages">3.1.25. Support: PACKAGES</h4> <div class="paragraph"><p>Contain one or more packages which also get installed for package builds, but a change in one of the packages does not trigger an automatic rebuild.</p></div> <div class="paragraph"><p>This is useful for packages that most likely do not influence the build result, for example make or coreutils.</p></div> </div> <div class="sect3"> <h4 id="_target_target_arch_rpm_only">3.1.26. Target: TARGET_ARCH (RPM only)</h4> <div class="paragraph"><p>Defines the target architecture. This can be used to build for i686 on i586 schedulers for example.</p></div> </div> <div class="sect3"> <h4 id="_target_gnu_triplet_deb_only">3.1.27. Target: GNU_TRIPLET (DEB only)</h4> <div class="paragraph"><p>Defines the target architecture via a gnu triplet (not the debian architecture!). For example arm-linux-gnueabihf for armv7hl builds.</p></div> </div> <div class="sect3"> <h4 id="_type_type">3.1.28. Type: TYPE</h4> <div class="paragraph"><p>Build recipe type. This is the format of the file which provides the build description. This gets usually autodetected, but in some rare cases it can be set here to either one of these: spec, dsc, kiwi, livebuild, arch, preinstallimage.</p></div> <div class="paragraph"><p>Defines the build recipe format. Valid values are currently: none, spec, dsc, arch, kiwi, preinstallimage. If no type is specified, OBS deduces a type from the binary type.</p></div> </div> <div class="sect3"> <h4 id="_vminstall_packages">3.1.29. VMInstall: PACKAGES</h4> <div class="paragraph"><p>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.</p></div> </div> </div> <div class="sect2"> <h3 id="_macros">3.2. Macros</h3> <div class="paragraph"><p>Macros are defined at the end of the project configuration. The macro section is only used on RPM builds.</p></div> <div class="paragraph"><p>The project configuration knows two possible definitions:</p></div> <div class="literalblock"> <div class="content"> <pre><code>%define Macro Definition</code></pre> </div></div> <div class="paragraph"><p>Starting with a %define line and are used in the project configuration only. These definitions are not available inside the build root. These are only needed when these macros are used elsewhere in the build config.</p></div> <div class="paragraph"><p>For example:</p></div> <div class="literalblock"> <div class="content"> <pre><code>%define _use_profiler 1 %if 0%{?_use_profiler} Require: gprof %endif</code></pre> </div></div> <div class="paragraph"><p>Another example doing it by architecture:</p></div> <div class="literalblock"> <div class="content"> <pre><code>%ifarch x86_64 Support: x86_64_only_package %endif</code></pre> </div></div> </div> <div class="sect2"> <h3 id="_macro_definitions">3.3. Macro Definitions</h3> <div class="paragraph"><p>Starting after the Macros: line and are exported into the .rpmmacros file of the build root. As such, these macro definitions can be used in a spec file.</p></div> <div class="paragraph"><p>For example, you can define</p></div> <div class="paragraph"><p>%define _with_pulseaudio 1</p></div> <div class="paragraph"><p>Macros Used in Spec Files Only</p></div> <div class="paragraph"><p>The macro definition in the project configuration is located at the end and has the following structure:</p></div> <div class="paragraph"><p>Structure of a Macro Definition</p></div> <div class="paragraph"><p>Macros: # add your macro definitions here %_hardened_build 0 :Macros</p></div> <div class="paragraph"><p>Everything that starts with a hash mark (#) is considered a comment.</p></div> </div> </div> </div> <div class="sect1"> <h2 id="_functionalities">4. Functionalities</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_package_builds">4.1. package builds</h3> <div class="paragraph"><p>Package builds are supported for rpm, deb, arch and their variations.</p></div> </div> <div class="sect2"> <h3 id="_image_builds">4.2. image builds</h3> </div> <div class="sect2"> <h3 id="_container_builds">4.3. container builds</h3> </div> <div class="sect2"> <h3 id="_cross_architecture_build">4.4. Cross Architecture Build</h3> <div class="paragraph"><p>Cross architecture builds specify two sets of repositories, one for the build environement and one for the environment for the build result.</p></div> <div class="sect3"> <h4 id="_terminology">4.4.1. Terminology</h4> <div class="paragraph"><p>The terminiology for this is unfortunatly not standarised and tools have conflicting defintions.</p></div> <div class="paragraph"><p>We use the following</p></div> <div class="sect4"> <h5 id="_host_the_architecture_build_environment_which_executes_the_for_example_the_compiler">Host: The architecture build environment which executes the for example the compiler.</h5> <div class="paragraph"><p>cmake is calling this HOST as well (eg. CMAKE_HOST_SYSTEM_PROCESSOR)</p></div> <div class="paragraph"><p>GNU tools (esp. the configure scripts generated by autoconf) is using BUILD as abbrevasion here</p></div> </div> <div class="sect4"> <h5 id="_target_the_architecture_of_the_resulting_binaries">Target: The architecture of the resulting binaries</h5> <div class="paragraph"><p>cmake has this as default without any abbrevasion (eg. CMAKE_SYSTEM_PROCESSOR)</p></div> <div class="paragraph"><p>GNU tools (esp. the configure scripts generated by autoconf) is using HOST as abbrevasion here: The "TARGET" defintion of them is something else, usually only used for compilers where it defines the target architecture a from a cross build compiler.</p></div> </div> <div class="sect4"> <h5 id="_the_compatible_terms_can_be_found_in_the_following_table">The compatible terms can be found in the following table:</h5> <div class="paragraph"><p>Unfortunatly the naming of architecture areas is not consistent via the various build tooling. Please find the terminilogy mapping from our "build" script and other toolings in the list below.</p></div> <div class="tableblock"> <table rules="all" width="15%" frame="border" cellspacing="0" cellpadding="4"> <col width="20%" /> <col width="20%" /> <col width="20%" /> <col width="20%" /> <col width="20%" /> <tbody> <tr> <td align="left" valign="top"><p class="table">build</p></td> <td align="left" valign="top"><p class="table"></p></td> <td align="left" valign="top"><p class="table">host</p></td> <td align="left" valign="top"><p class="table">target</p></td> <td align="left" valign="top"><p class="table">-/-</p></td> </tr> <tr> <td align="left" valign="top"><p class="table">cmake</p></td> <td align="left" valign="top"><p class="table"></p></td> <td align="left" valign="top"><p class="table">HOST</p></td> <td align="left" valign="top"><p class="table">default</p></td> <td align="left" valign="top"><p class="table">-/-</p></td> </tr> <tr> <td align="left" valign="top"><p class="table">GNU</p></td> <td align="left" valign="top"><p class="table"></p></td> <td align="left" valign="top"><p class="table">build</p></td> <td align="left" valign="top"><p class="table">host</p></td> <td align="left" valign="top"><p class="table">target</p></td> </tr> <tr> <td align="left" valign="top"><p class="table">rpm</p></td> <td align="left" valign="top"><p class="table"></p></td> <td align="left" valign="top"><p class="table">build</p></td> <td align="left" valign="top"><p class="table">target</p></td> <td align="left" valign="top"><p class="table">-/-</p></td> </tr> </tbody> </table> </div> <div class="paragraph"><p>Our build script just knows the host and target definition as described above.</p></div> <div class="paragraph"><p>cmake is similar, just uses different namings.</p></div> <div class="paragraph"><p>GNU (esp. in automake and autoconf) has actually three definitions, mainly for compiler toolchain. "build" is the environment which creates binaries. Host are the resulting binaries. And target is important when these binaries can build binaries as well for another target.</p></div> </div> </div> <div class="sect3"> <h4 id="_dependency_handling">4.4.2. Dependency handling</h4> <div class="paragraph"><p>Dependencies need to be resolved always twice during a cross build. One time for the host architecture and one time for the target architecture. Build dependencies of a package get only installed for the target architecture by default.</p></div> <div class="paragraph"><p>However, global rules in the build configuration can get created to modify this behaviour.</p></div> <div class="sect4"> <h5 id="_alsonative_packages">AlsoNative: PACKAGES</h5> <div class="paragraph"><p>Can be used to mark a package to get installed into the target and in the host system.</p></div> </div> <div class="sect4"> <h5 id="_onlynative_packages">OnlyNative: PACKAGES</h5> <div class="paragraph"><p>Can be used to to install a package in the hostsystem, but not in the target system. Eg. for build tooling or code generators.</p></div> </div> <div class="sect4"> <h5 id="_the_target_base_system">The target base system</h5> <div class="paragraph"><p>All packages for a host system which are configured as "Requrired" get installed only in the host system, but not in the target system. The reason behind is that this packages are only supposed to be able to execute commands and therefore they are not needed in the target environment. Only the build dependencies get installed there.</p></div> <div class="paragraph"><p>However, some distributions may lack a complete set of dependencies (esp. debian based). In this case the base system for the target system can manually get configured via</p></div> <div class="paragraph"><p>Substitute: sysroot-packages PACKAGES</p></div> </div> </div> <div class="sect3"> <h4 id="_example_calls_in_spec_files_for_cross_build">4.4.3. Example Calls in spec files for cross build</h4> <div class="paragraph"><p>Note: the basic design of rpm was the GNU style, but it changed in the way that you have to specify the host architecture via %target macro on most distributions:</p></div> <div class="literalblock"> <div class="content"> <pre><code>./configure --build=%build --host=%target</code></pre> </div></div> </div> </div> <div class="sect2"> <h3 id="_repository_setup">4.5. Repository setup</h3> </div> <div class="sect2"> <h3 id="_build_config">4.6. Build Config</h3> </div> </div> </div> </div> <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> Last updated 2022-03-24 09:17:43 CET </div> </div> </body> </html> 07070100000006000081a400000000000000000000000163e504ba0000086a000000000000000000000000000000000000001800000000docs/source_assets.adoc=== Remote Assets Remote Assets can be defined inside of the build descriptions. They are resources from a remote servers and will be downloaded and validated by pbuild before the corresponding build is started. Supported protocols for resources using an url are: * http * https * git+http * git+https This depends on the build description format as described below. ==== rpm spec files Source lines in spec files can declare remote assets. Rpm is already supporting to use an URL as source definition. A comment before such a line marks it as remote asset for pbuild: #!RemoteAsset Source: <URL> It is also possible to specify a checksum to make sure that the asset is correct. #!RemoteAsset: <CHECKSUM> Source: <URL> An alternative is just to use the #!RemoteAssetUrl: <URL> marker without any Source: tag when the downloaded file should not become part of the source rpm. ==== kiwi build description The kiwi format is not supporting remote source specifications, but they can be specified via XML comments. <!-- OBS-RemoteAsset: <URL> --> The resulting downloaded file can be copied into the image using <!-- OBS-CopyToImage: <source> <destination> --> The kiwi profile name is added to container names by default. This can be disabled via <!-- OBS-DoNotAppendProfileToContainername --> ==== Dockerfile description Remote assets that will be downloaded before the build can be added via the comment `#!RemoteAssetUrl: https://my.url/asset.tar`. `pbuild` will fetch the asset before the build and will make it available in the buildroot so that the asset can copied into the container as follows: [source,Dockerfile] ---- #!RemoteAssetUrl: https://my.url/asset.tar COPY asset.tar . RUN tar -xvzf asset.tar ---- ==== Arch Linux PKGBUILD PKGBuild files already contain the needed URLs and Checksums, so no extra treatment is needed. ==== FedPkg "sources" file The sources file contains a list of file names with checksums. PBuild will automatically download the missing files from a FedPkg Server that needs to be configured in the project config via the "AssetsURL:" directive or set with the "--assets" option. 07070100000007000041ed00000000000000000000000163e504ba00000000000000000000000000000000000000000000000500000000docs07070100000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000b00000000TRAILER!!!
Locations
Projects
Search
Status Monitor
Help
OpenBuildService.org
Documentation
API Documentation
Code of Conduct
Contact
Support
@OBShq
The Open Build Service is an
openSUSE project
.
Sign Up
Log In
Places
Places
All Projects
Status Monitor
