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!!!
