NAME

burps_config - The burps configuration

DESCRIPTION

All configuration options can be defined in 3 different places :

  • in the main configuration in your working directory

  • in the global system configuration

  • in a project configuration

  • with a command line option

In each configuration file, it is possible to set per distribution options. See burps_distributions(7) for details.

The option values are used with the following priority order :

  • command line options

  • project config for matching target and distribution(s)

  • project config for matching target

  • project config for matching distribution(s)

  • project config

  • workspace config for matching target and distributions(s)

  • workspace config for matching target

  • workspace config for matching distributions(s)

  • workspace config

  • system config for matching target and distributions(s)

  • system config for matching target

  • system config for matching distributions(s)

  • system config

  • default config for matching distribution(s)

  • default config

  • undefined

The system configuration is by default located at /etc/burps.conf, or the path defined in the sysconf_file option. If the path does not exists, it is ignored. This is where you will put configuration only relevant to your local use of burps.

The main configuration file is burps.conf, in YAML format. It can be located anywhere on your filesystem, but you will need to run the burps commands from the same directory, or one of its subdirectories. This is where you will put configuration relevant to all projects under this working directory. All relative paths used in the configuration are relative from the burps.conf location.

An example burps.conf file will look like this :

projects_dir: projects
compress_tar: xz

The projects_dir option define the path to the directory containing the projects definitions.

Adding a new project is done by creating a directory with the name of the project inside the projects_dir directory, and adding a config file in this new directory. The config file contains the configuration for the project. At the minimum it should contain the git_url configuration, and any other configuration option you want to set for this project.

OPTIONS

The following configuration options are available :

sysconf_file

The path to an optional system configuration file. The default is /etc/burps.conf. This can also be set with the --sysconf-file command line parameter.

projects_dir

The directory containing the projects definitions. The default value is projects.

git_clone_dir

The directory used to store clones of git repositories. The default value is git_clones.

tmp_dir

The directory used to create temporary directories and files. This is the directory where builds will be done, so you want to use a directory on a fast device, with enough space available. This directory will contains some scripts that will be executed, so it should not be on a partition mounted as noexec.

output_dir

The directory where output files (tarballs, spec files or packages) are created. The default value is out.

fetch

The value should be 0 or 1, depending on whether the commits from the remote git repository should be fetched automatically.

git_hash

A git hash, branch name or tag. This is what is used to create the tarball.

compress_tar

If set, the tarball created will be compressed in the select format. Possible values: xz, gz, bz2.

commit_gpg_id

If set, the commit selected with git_hash will have its signature checked. The tarball will not be created if there is no valid signature, and if the key used to sign it does not match the key ID from commit_gpg_id. The option can be set to a single gpg ID, or to a list of gpg IDs. The IDs can be short or long IDs, or full fingerprint (with no spaces). For this to work, the GPG keys should be present in the selected keyring (see keyring option). If the option is set to 1 or an array containing 1 then any key from the selected keyring is accepted. On command line, the --commit-gpg-id option can be listed multiple times to define a list of keys.

tag_gpg_id

If set, the commit selected with git_hash should be a tag and will have its signature checked. The tarball will not be created if the tag doesn’t have a valid signature, and if the key used to sign it does not match the key ID from tag_gpg_id. The option can be set to a single gpg ID, or to a list of gpg IDs. The IDs can be short or long IDs, or full fingerprint (with no spaces). For this to work, the GPG keys should be present in the selected keyring (see keyring option). If the option is set to 1 or an array containing 1 then any key from the selected keyring is accepted. On command line, the --tag-gpg-id option can be listed multiple times to define a list of keys.

gpg_wrapper

This is a template for a gpg wrapper script. The default wrapper will call gpg with the keyring specified by option gpg_keyring if defined.

gpg_keyring

The filename of the gpg keyring to use. Path is relative to the gpg_keyring_dir directory. This can also be an absolute path.

gpg_keyring_dir

The directory containing gpg keyring files. The default is $basedir/keyring (with $basedir the directory where the main config file is located).

gpg_bin

The gpg command to be used. The default is gpg.

gpg_args

Optional gpg arguments. The default is empty.

arch

The architecture, as returned by uname -m.

version

Version number of the software. This is used to create the tarball, and as the package version number.

version_command

A command to run in the checked out source tree to determine the version, if the version option is not set. The command should print the version on stdout.

pkg_rel

Package release number.

distribution

The name of the distribution for which you wish to build a package. See burps_distributions(7) for details.

target

The target for which you want to build. This is usually set on command line. See burps_targets(7) for details.

targets

The targets definitions. See burps_targets(7) for details.

copy_files

A list of files that should be copied when building the package. Path is relative to the project’s template directory.

input_files

Configuration for external input files. See burps_input_files(7) for details.

input_files_by_name

This option contains an hash of all the input_files filenames, with their name as index. The input files without a name are not in this hash.

timestamp

This is the UNIX timestamp, set as modification time on files created such as the sources tarball and rpm spec file. The default is to use the commit time of the commit used. If set to 0 it will use the current time.

notmpl

An array containing a list of options that should not be processed as template (see the template section below for details).

rpm_rel

RPM package release number. The default is to use the option pkg_rel if defined, otherwise use a release number containing the number of commits since the last git tag, and the hash of the commit used.

rpmspec

This is the content of the rpm spec file, used by the rpm and srpm commands. The default is to include the template file named project.spec (with project replaced by the project’s name).

rpmbuild

This is the content of the script to build a rpm or srpm. It is using the rpmbuild_action option to select the build action (-bs to build a source package, or -ba to build all packages).

rpm

This is the script that is used to build an rpm package, in the rpm command. By default it is using the rpmbuild option with the -ba action.

srpm

This is the script that is used to build a source rpm package, in the srpm command. By default it is using the rpmbuild option with the -bs action.

debian_revision

The package revision used in debian packages. By default, when the option pkg_rel is defined, this is what is used. Otherwise a revision containing the number of commits since the last git tag, and the hash of the commit is used.

deb_src

This is the script that is used to create the debian source package. By default it will use the debian files listed in the option debian_files and create the source package with dpkg-source.

deb

This is the script that is used to create the debian packages. By default it will use the debian files listed in the option debian_files and build the package using debuild or pdebuild depending on whether the use_pbuilder option is set. The packages will be signed using the key defined in the option debsign_keyid.

debian_files

This is an array containing the files to create in the debian directory. Each item in the array is an hash, with the following two keys : name is the file name in the debian directory of the file to create, and content is the content of the file. The filename and content are processed as template, so for instance if you want to store the content of a file in a separate file, you can use the INCLUDE directive.

use_pbuilder

If set to a true value, pbuilder will be used to build the debian packages.

debsign_keyid

This is the gpg key that will be used to sign the debian packages. Set to 0 if you don’t want to sign the packages.

remote/deb_src, remote/deb

The options to configure build on an external node. See the section about remote build for details.

pkg_type

This is the name of the option that will be used by the pkg command as the script to build the package. This can be rpm or deb for rpm and debian packages. This option is usually set in distribution specific configuration as it depends on the distribution being used.

build

This is the content of the build script used by the build command. The default is to include the template file named build.

publish

This is the content of the script that is used to upload the packages or files to a repository. This script will be executed from the directory containing the files to publish. This option has no default value.

remote/publish

If you want to publish the files on a remote server, you can use this option. See burps_remote(7) for details.

debug

This option enable or disable the debug mode. When enabled, a shell will be opened in the temporary build directory in case of build failure.

abbrev

This option returns the abbreviated commit hash of the git_hash commit.

abbrev_lenght

This option sets the lenght of the abbreviated commits, when using the abbrev option.

tar

Use this options instead of tar in build scripts when you want to create deterministic tar files. This options set tar arguments so that owner and group of files is set to root, and mtime is set to timestamp. This option takes a tar_src argument which is an array containing source files or directories, and a tar_args argument which is the tar arguments to create the file (something like -cf filename.tar).

zip

Use this option instead of zip in build scripts when you want to create deterministic zip files. This option takes a zip_src argument which is an array containing source files or directories, and a zip_args arguments which is usually the destination zip file, and optionaly other zip options.

In addition to the configuration options listed here, you are free to add any other options that you want, and use them in the template files. Unfortunately this also means that you won’t have an error message in case of typo in an option name.

WRITTING CONFIGURATION IN PERL

The configuration is in YAML, but you can also use the perl syntax to set some configuration options. A YAML file can contain multiple documents, separated by a line with tree dashes (---). When reading a configuration file, burps will read all documents contained in the file, and for each of them will :

  • if the document is a hash, use it as configuration

  • if the document is a string, evaluate it as perl, and get the return value as as hash containing configuration

If multpiple documents define the same options, the value from the last one override the values from previous documents.

A configuration file that includes perl code will look like this :

option_1: value 1
option_2: value 2
option_3: value 3
--- |
 (
      option_4 => "value 4",
      option_5 => "value 5",
 )

In this example, option_4 and option_5 and defined using perl syntax. Note that the perl code block needs to be indented with at least one space.

An interesting benefit of writting options in perl is that you can define some options using a perl function reference. If the value of an option is a function reference, then when that option is looked up the function will be executed, and the value of the option will be the return value of the function. The function will receive as parameters the project’s name, an options array reference, and the option that is queried.

An option defined using a perl function will look like this :

option_1: value 1
--- |
 (
    option_2 => "value 2",
    option_3 => sub {
        my ($project, @option) = @_;
        return "value 3";
    },
 )

SEE ALSO