All packages are generated from a single build file, which provides all of the required metadata for the package manager, plus the packaging steps involved to produce a package. This follows the YAML specification.
package.yml files must be valid YAML.
The file is organised into a key→value hierarchy. The
ypkg tool parses a
package.yml file to build the corresponding package in a declarative manner, so most of the keys are simple strings, lists or nested key→value pairs. A special case consists in the packaging steps, which are scripts.
An example file follows:
name : nano version : 2.9.5 release : 96 source : - https://www.nano-editor.org/dist/v2.9/nano-2.9.5.tar.xz : 7b8d181cb57f42fa86a380bb9ad46abab859b60383607f731b65a9077f4b4e19 license : GPL-3.0-or-later summary : Small, friendly text editor inspired by Pico component : system.devel 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 : | %patch -p1 < $pkgfiles/0001-Use-a-stateless-configuration.patch %reconfigure --enable-utf8 --docdir=/usr/share/doc/nano build : | %make install : | %make_install install -D -m 00644 $pkgfiles/nanorc $installdir/usr/share/defaults/nano/nanorc install -D -m 00644 $pkgfiles/git.nanorc $installdir/usr/share/nano/git.nanorc # https://github.com/scopatz/nanorc for rcFile in $pkgfiles/nanorc-extras/*.nanorc; do install -m 00644 $rcFile $installdir/usr/share/nano done
Not all fields in
package.yml are mandatory, but a small selection are. Below is the complete list of the available fields.
||The name of the package. This is also used as the base of all sub-package names. Unless unavoidable, this should match the upstream name.|
||The version of the currently packaged software. This is taken from the tarball in most cases.|
||Specifies the current release number. Updates in the package number are based on this
||Valid upstream license(s). Try to ensure these use SPDX identifiers.|
||Upstream source URL (i.e. tarball), with the valid
||Component / group of packages this package belongs to. Check available components via
||Brief package summary, or display name.|
||More extensive description of the software, usually taken from the vendor website.|
||Specify packages that cannot be installed together with this one.|
||Specify preset keys to modify compiler and linker flags during build. You can learn more here.|
||Specify build dependencies for the package. You can learn more here.|
||Specify further runtime dependencies for the packages. You can learn more here.|
||Replace one package with another, used when renaming or deprecating packages for clean upgrade paths.|
||Allows fine grained control over file placement within the package or sub-packages. Useful for packages that are development only (i.e.
||Specify code that will be exported to all packaging steps of the build (i.e. exporting variables for the entire build).|
||Provides a link to the package’s homepage in the Software Center.|
The packaging steps are all considered optional, however the absence of the
install step will result in no package generated. Each of these keys contains content that will be placed within a script and executed within a controlled environment to perform the package build. For all intents and purposes, they are Bash scripts with a predefined environment.
|setup||Performed after the source extraction. This is the correct place to perform any
|build||Use this step to run the build portion, i.e.
|install||This is where you should install the files into the final packaging directory, i.e.
|check||This is where tests / checking should occur, i.e.
|profile||This is where profiling tests should be specified.
One or more optimize values can be specified in a list with the optimize key in the
package.yml file. Several values can override or conflict with each other and should be used only where they provide a performance benefit, or fix a bug in the package or build.
|speed||Optimise the package for performance
|size||Optimize the package build to minimize size
|no-bind-now||Configure the package to disable certain flags, where RELRO is unsupported.|
|thin-lto||Enable Thin Link Time Optimization
|lto||Enable Link Time Optimization
To further assist in packaging, a number of macros are available. These are simply shorthand ways to perform a normal build operation. They also ensure that the resulting package is consistent. These macros are only available in our packaging steps, as they are substituted within the script before execution.
Macros are prefixed with
%, and are substituted before your script is executed. Macros ending with
% are used to provide directory names or build values, to the script.
# Run the configure macro with the given arguments %configure --disable-static
|%autogen||Runs autogen with our
|%cmake||Configure cmake project with the distribution specific options, such as prefix and release type.|
|%cmake_ninja||Configure cmake project with ninja so it can be used with
|%patch||Sane patch macro to run in batch mode and not contaminate source tree on failure|
|%apply_patches||Applies all patches listed in the
|%reconfigure||Updates build scripts such as
|%cabal_configure||Runs cabal configure with prefix, libdir, etc. and ensures the necessary package.conf.d is copied to the correct location.|
|%cabal_build||Runs cabal build with
|%cabal_install||Runs cabal copy to
|%cabal_register||Runs cabal register to generate a pkg-config for package and version, then installs the conf file.|
|%meson_configure||Runs meson with our CFLAGS and appropriate flags such as libdir.|
|%ninja_build||Runs ninja and passes our
|%ninja_install||Runs meson install and passed the appropriate
|%ninja_check||Runs ninja test and passes our
|%perl_setup||Runs Perl setup scripts Build.pl or Makefile.pl with the appropriate variable flags.|
|%perl_build||Runs Perl build scripts or attempts
|%perl_install||Runs Perl install scripts or attempts
|%python_setup||Runs the build portion of a setup.py using python2.|
|%python_install||Runs the install portion of a setup.py, to the appropriate root, using python2.|
|%python_test||Without argument, runs the test portion of setup.py. With a
|%python3_setup||Runs the build portion of a setup.py using python3.|
|%python3_install||Runs the install portion of a setup.py, to the appropriate root, using python3.|
|%python3_test||Without argument, runs the test portion of setup.py. With a
|%gem_build||Runs gem build.|
|%gem_install||Runs gem install with the appropriate parameters.|
|%qmake||Runs qmake for Qt5 with the appropriate make flags.|
|%qmake4||Runs qmake for Qt4, as well as adding the necessary MOC, RCC, and UIC flags since those Qt4 executables end in -qt4.|
|%waf_configure||Runs waf configure with prefix.|
|%waf_build||Runs waf and passes our
|%waf_install||Runs waf install and passed the appropriate
|%ARCH%||Indicates the current build architecture.|
|%CFLAGS%||cflags as set in
|%CONFOPTS%||Flags / options for configuration, such as
|%CXXFLAGS%||cxxflags as set in
|%JOBS%||jobs, as set in
|%LDFLAGS%||ldflags as set in
|%LIBSUFFIX%||Library suffix (either 32 for 32-bit or 64 for 64-bit)|
|%YJOBS%||Job count without
|%installroot%||Hard-coded install directory|
|%libdir%||The distribution’s default library directory, i.e.
|%version%||Version of the package, as specified in the version key.|
|%workdir%||Hard-coded work directory (source tree)|
A set of variables are exported in our build stages. These are used to provide context and structure to the scripts.
|$CFLAGS||cflags as set in
|$CXXFLAGS||cxxflags as set in
|$LDFLAGS||ldflags as set in
|$EMUL32BUILD||Set only when compiling in
|$installdir||The install directory, i.e. where files are installed to for packaging|
|$pkgfiles||Refers to the
|$sources||Refers to the directory where your source files are stored e.g.
|$workdir||The work, or source, directory of the package build|
package.yml file uses native YAML types, however it follows syntactic conventions and may accept multiple value types for a given key.
This is simply text, which does not need to be quoted.
Indicates that it is possible to use a
list of strings, or one single
Whole, positive number, used in the
A YAML list (or array) can be expressed in multiple ways. A short array-notation would look like this:
[one, two, three]
They can also be expressed like this:
- First Value - Second Value - Third Value
Known as an associative array, this is key to value mapping. These are separated by a colon (
:), the token on the left is taken to be a key, and the token on the right is the value.
SomeKey: Some Value
Note that each
ypkg key in the YAML file is actually a dict.
dict(s) consists of a list of
dicts and some assumptions. We primarily make use of this to express advanced information within the package. These permit you to provide no key, and a value only.
In this instance, the key is implicitly assumed to be the package name (e.g.
- some value
An explicit key, usually a sub-package name:
- somekey: somevalue
A mix of both:
- somevalue - somekey: another value
The values may also be expressed in list form, still using the same default key logic:
- [one,two, three] - somekey: [one,two, three] - key: - value one - value two - value three
The concepts in this document merely expose the syntax of a
package.yml file. Solus adheres to strict packaging practices and conventions which packagers must follow. They are explained in the Packaging Practices article.