package.yml(5) -- Solus package build format

SYNOPSIS

The Solus package build format, with YAML syntax.

DESCRIPTION

The primary format of package builds in Solus, package.yml(5) provides a modern, declarative, and structured format in which to define metadata and steps, to convert a build operation into a package.

ypkg-build(1) will use the advanced patterns system and some very specific internal rules to automatically split the package into multiple packages, refered to here as "subpackages".

CONFIGURATION FORMAT

ypkg-build(1) uses the YAML file format. However, this is a very specialised flavour of YAML with very specific extensions and types.

Types

Some of the specialised types expected by package.yml(5) are explained below.

dict(s)

This is a set of one or more key:value mappings. These are always in a list format.
multimap

This is a key:value mapping where the key is IMPLICIT. That is to say, it is acceptable to omit the key. A single value passed as the value will set the implicit key's component.

In all instances the implicit key is the main package. The multimap format can accept a list instead of a string as a value, and each item in that list also follows the implicit key policy.

For each item in the list, if the key is EXPLICIT, by using dict style key:value mapping, then the key specified will be used.

Within ypkg(1), that key is always a package name. This name should be the shortform name, not the fully qualified name, i.e the subpackage name without the name prefix.

As a special exception to the subpackage rule, keys beginning with ^ will result in an explicitly named package lookup, i.e. one that doesn't follow the subpackage convention. This should be used only in rare cases where it is illogical to share a common root name, or a migration with name changes from a legacy format is too complex.

This allows a general key to accept sane defaults, but also allows the key to be extended to override attributes of a subpackage.

Mandatory Keys

name [string]

Set the name of the package. In general this should try to match the upstream source name wherever possible. All subpackages generated by ypkg-build(1) will have this name as a prefix.
version [string]

The version of the software being packaged. This should match the upstream version, i.e. that of the tarball or git tag.
release [integer]

Packages within Solus are updated by their release number. This number must start at 1 in new packages, and be incremented for every new update or change to the package that is published.

It is perfectly acceptable to push an update with a lower version by bumping the release number.
license [string(s)]

One or more strings that identify the software license of this package. This should in most cases be a recognised SPDX license name.
```
  * https://spdx.org/licenses/
```
source [dict(s)]

This key expects a list of key:value mappings, to declare the sources that this package will use. A "simple source" could be a tarball, where the key is the upstream URL, and the value must be a valid sha256sum(1) for that tarball.

You can list multiple sources and they will all be fetched for the build process, but only the first will be extracted. You can locate these other sources during your build with the $sources variable.

git(1) sources are also supported, and can be identified by prefixing the URI with git|. The expected value should be a commit, sha reference, or a tag.
component [multimap]

This key sets the package component, that is to say, the logical unit of organisation that it belongs to. Check eopkg lc for existing component names.

component is a multimap key, therefore if passed a single string value it will set the component for the main package. However, you may instead pass a list of the subpackage names, and set their component individually using the map value.
summary [multimap]

Set the "short" description of a package, i.e. a one line explanation of what an item is. Use the subpackage names in the explicit key for this multimap to override subpackage summaries.
description [multimap]

Set the full description of a package, i.e. a more in depth explanation of the software/package's functionality. This is the large description that will be displayed in eopkg and the solus-sc. Use the subpackage names in the explicit key for this multimap to override subpackage descriptions.

Optional Keys

These keys are not mandatory to a package.yml file, but may be used to configure additional functionality.

builddeps [list]

Specifies the build dependencies required to actually make this package build in an isolated environment (solbuild(1)).

You may use full package names here, though it is preferable to use the pkg-config(1) names.

ypkg-build(1) understands pkgconfig dependencies denoted inside either the pkgconfig($name) identifier, or pkgconfig32($name) for emul32 build dependencies.

It is not required to list any package here that exists in the system.base or system.devel component.
clang [boolean]

Set this key to yes to force building this package with the clang compiler. The build environment will be configured to use clang as the $CC and clang++ as the $CXX variables.

By default this key is set to no.
ccache [boolean]

If configured correctly, ypkg-build(1) will automatically use ccache(1). When using solbuild(1) this is almost always the case. However, there may be some cases when ccache can break the build, or is ill advised.

Whilst the default value of this key is yes, you can force disable the use of ccache by setting it to no.
devel [boolean]

Force all built packages to belong to the system.devel component. This will become deprecated in future, and currently defaults to no.
extract [boolean]

By default, ypkg-build(1) will extract all sources listed in the file. If this is undesirable, set this key to no to disable this automatic extraction.
autodep [boolean]

After a build has finished, ypkg-build(1) will automatically scan the package files to determine dependencies between the package and any of it's subpackages, and to external packages in the build environment.

This is essential in most cases, as it allows packages to benefit from automatic dependencies and ensures the user always gets all of the packages needed to run this software when installing it.

If for any reason you need to disable this functionality, i.e. for bootstrapping or sideloading, set this key to no.
emul32 [boolean]

ypkg-build(1) can optionally build your package in a multilib configuration. If this key is set to yes, the buildset will double, and the first build configuration will be set up for a 32-bit ("emul32") build. ypkg will automatically split off -32bit and -32bit-devel subpackages in this instance, using the /usr/lib32 library directory. It will also add additional build dependencies automatically for 32-bit builds.

By default, this key is set to no.
libsplit [boolean]

The default patterns include logic to split subpackages according to the library files in library directory. It is standard practice for ypkg to split *.so symlinks into the automatic devel subpackage, along with other development assets such as pkgconfig and *.h files.

Some software packages provide *.so files in the libdir that are not symlinks, or are required for "main" operation. In this instance you can set this key to no to disable this pattern.

By default, this key is set to yes, and should only be disabled if truly required.
rundeps [multimap]

Provide a list of additional runtime dependencies for the main package. These names should be fully qualified package names in the list, even for subpackages.

If the EXPLICIT multimap key is set, then the runtime dependencies will be added to the subpackage instead. Note that you can pass a list or a single string value to the EXPLICIT rundep.
replaces [multimap]

When exported in the package index, this will indicate to the package manager that THIS package now replaces the name in the value.

You may also set replaces on subpackages using the multimap notation. Only one value per subpackage is allowed.
patterns [multimap]

Control package splitting and dynamically generate subpackages. The EXPLICIT key is used to specify the new (or existing!) subpackage name. The "pattern" is a shell compatible glob(3) expression.

All files captured by this expression will then end up in that subpackage. Each successive pattern takes priority over the one listed before it, so if your first pattern unavoidably captures files you need in ANOTHER subpackage, simply list that pattern later.

ypkg-build(1) ensures that a file cannot belong to multiple packages, and that the last specified pattern, if matching, ALWAYS wins. It is even possible to supress generation of the main package, by pattern globbing /* to a subpackage. This will not cause any breakage.
permanent [list]

A list of patterns used to mark files as permanent. Any file within the resulting binary packages that matches the path pattern, is marked as a permanent file.

These files will not be removed from the filesystem when upgrading or reinstalling the package. They will persist during standard upgrade operations.

This should only be used in critical chain packages such as the kernel or drivers, where the domain of control is outside of the package manager, and the package is simply used as an update delivery mechanism.
strip [boolean]

By default, this key is enabled, and as a result ypkg-build(1) will automatically strip files after the build has done, including ELF libraries & binaries.

In most cases, stripping should remain enabled. However, there are known cases when stripping should be avoided, such as when complying with a distribution policy of binary only software, or when dealing with files that only appear to be standard ELF files.

The Go programming language generates *.a archive files that under no circumstance should be stripped, and there are likely other cases. This key, when set to no, will disable any and all stripping.
debug [boolean]

By default, this key is enabled, and as a result ypkg-build(1) will automatically create resulting -dbginfo packages where it can.

In the majority of cases, this is the desired behaviour in full build environments, such as a build server. However in very rare cases, this may cause problems for the package, especially if it contains binaries that have not been bootstrapped with the native toolchain.
avx2 [boolean]

If set, the package will be rebuilt again specifically to enable libraries to be optimised to use Advanced Vector Extensions.

The build will be configured with a library directory suffix of avx2, i.e. /usr/lib64/avx2 or /usr/lib32/avx2. These libraries will be automatically loaded on the Solus installation if the hardware support is present.
optimize [list]

Valid keys are restricted to:
- speed: Optimise this package for speed performance
- size: Optimize the package build solely for size.
- no-bind-now: Configure the package to disable certain flags, where RELRO is unsupported.
- no-symbolic: Disable -Wl,-Bsymbolic-functions linker flag
- unroll-loops: Enable -funroll-loops. Use this sparingly, only when it provides benefit.
- thin-lto: Enable Thin Link Time Optimization
- lto: Enable Link Time Optimization
networking [boolean]

When built using solbuild(1), access to the network is removed. A new loopback device will be provided within the container. This ensures that packages do not accidently download unverifiable content during build.

If for any reason, networking is still required, you can set this key to yes. However, always evalaute whether it is avoidable first.

Build Steps

The build steps are text-only data values. ypkg-build(1) will interpret special "macro" values in these steps, and evaluate them in a new environment via the bash(1) shell.

setup

Performed immediately after source preparation and extraction. This is where you should look to patch your package if necessary, and perform any configuration routines (i.e. %configure)
build

The main build step. This is where you compile code and do long running code. An example would be running %make
install

The install step will install of the built files into the final installation directory, to be converted into a native .eopkg file. This is where your %make_install would happen, for example.

Remember, this is to install inside the package. This doesn't impact the package installation on another users computer. There is no "postinstall" concept currently supported by ypkg.
check

Run any test suites in this step. This is the final step in the chain, and allows you to verify what you just built. This is a good place to run %make check
profile

If this step is present, then each build set that is enabled (native, emul32), will gain a series of new steps. The build will be configured for profile guided optimisation, and this step will be used to execute the PGO workload.

In essence the workflow looks like this:
```
  - `setup` as PGO
  - `build` as PGO
  - `profile` as PGO
  - Clean happens here.
  - `setup` to use PGO data
  - `build` to use PGO data
  - `install`
  - `check`
```
The compiler flags will be modifed automatically during each step to make PGO integration seamless. For an real world case on how this helps, check out:
- https://clearlinux.org/blogs/profile-guided-optimization-mariadb-benchmarks

Macros

ypkg supports a wide range of macros for easier package building. They evolve often and quickly, so you should always refer to the main package.yml documentation:

It may also be beneficial to study the rc.yml file defining the build macros:

https://github.com/solus-project/ypkg/blob/master/ypkg2/rc.yml

EXAMPLES

A Complete package

name       : nano
version    : 2.7.1
release    : 63
source     :
    - https://www.nano-editor.org/dist/v2.7/nano-2.7.1.tar.xz : df5cbe69831d7394c0a32fb27373ab313335ea4dc586d6f4be4081eb1de857cd
license    :
    - GPL-3.0
summary    : Small, friendly text editor inspired by Pico
component  : editor
description: |
    GNU nano is an easy-to-use text editor originally designed as a
    replacement for Pico, the ncurses-based editor from the non-free
    mailer package Pine (itself now available under the Apache License
    as Alpine).
setup      : |
    %configure --enable-utf8 --docdir=/usr/share/doc/nano
build      : |
    %make
install    : |
    %make_install

Git sources

source     :
    - git|https://github.com/solus-project/ypkg.git : v17.0

Multimap examples

# Set the component for the main package to `system.base`
component: system.base

# Also setting the main component to `system.base`
component:
    - system.base

# Set the component of the main package to system.base, but set the
# component for subpackage `devel` to `programming.devel`
component:
    - system.base
    - devel: programming.devel

# Rundeps multimap
rundeps:
    - somepkg
    - devel: somepkg2

# Rundeps, list as explicit key's value
rundeps:
    - somepkg
    - devel:
        - somepkg
        - somepkg2

Build dependencies examples

# Build dependencies, in various flavours:
builddeps:
    - glibc-32bit-devel
    - pkgconfig(gtk+-3.0)
    - pkgconfig32(zlib)

COPYRIGHT

NOTES

Creative Commons Attribution-ShareAlike 3.0 Unported

http://creativecommons.org/licenses/by-sa/3.0/

solus-project/ypkg