Skip to main content


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.


All 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
- 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: |
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
for rcFile in $pkgfiles/nanorc-extras/*.nanorc; do
install -m 00644 $rcFile $installdir/usr/share/nano


Not all fields in package.yml are mandatory, but a small selection are. Below is the complete list of the available fields.

Mandatory Keys

Key NameTypeDescription
namestringThe name of the package. This is also used as the base of all sub-package names. Unless unavoidable, this should match the upstream name.
versionstringThe version of the currently packaged software. This is taken from the tarball in most cases.
releaseintegerSpecifies the current release number. Updates in the package number are based on this release number, not the version number. As such, to release an update to users, this number must be incremented by one.
licensestring(s)Valid upstream license(s). Try to ensure these use SPDX identifiers.
sourcedict(s)Upstream source URL (i.e. tarball), with the valid sha256sum as a value. Alternatively, the git repository URL prefixed with "git|" and a git tag or commit hash as a value.
componentstringComponent / group of packages this package belongs to. Check available components via eopkg lc
summarystringBrief package summary, or display name.
descriptionstringMore extensive description of the software, usually taken from the vendor website.

Optional, supported keys

Key NameTypeDescription
clangboolSet to yes if this package benefits from being built with Clang.
extractboolSet to no to disable automatic source extraction.
autodepboolSet to no to disable automatic binary dependency resolution at build time.
emul32boolSet to yes to enable an -m32 build (32-bit libs).
libsplitboolSet to no to disable splitting of libraries into devel sub-packages.
conflictsstring(s)Specify packages that cannot be installed together with this one.
optimizelistSpecify preset keys to modify compiler and linker flags during build. You can learn more here.
builddepslistSpecify build dependencies for the package. You can learn more here.
rundepsdict(s)Specify further runtime dependencies for the packages. You can learn more here.
replacesdict(s)Replace one package with another, used when renaming or deprecating packages for clean upgrade paths.
patternsdict(s)Allows fine grained control over file placement within the package or sub-packages. Useful for packages that are development only (i.e. /usr/bin files).
environmentunicodeSpecify code that will be exported to all packaging steps of the build (i.e. exporting variables for the entire build).
networkingboolSet to yes to enable networking within solbuild.
homepagestringProvides a link to the package's homepage in the Software Center.

Packaging Step Keys, optional

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.

Step NameDescription
setupPerformed after the source extraction. This is the correct place to perform any configure routine, or to patch the sources.
buildUse this step to run the build portion, i.e. make
installThis is where you should install the files into the final packaging directory, i.e. make install
checkThis is where tests / checking should occur, i.e. make check
profileThis is where profiling tests should be specified. ypkg will handle setting flags to generate profiling data and using that data for an optimized build.

Optimize values

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.

Optimize ValueDescription
speedOptimise the package for performance -O3 plus other flags.
sizeOptimize the package build to minimize size -Os. Not supported with clang.
no-bind-nowConfigure the package to disable certain flags, where RELRO is unsupported.
no-symbolicDisable -Wl,-Bsymbolic-functions linker flag.
unroll-loopsEnable -funroll-loops. Use this sparingly, only when it provides proven benefit.
runpathEnable -Wl,--enable-new-dtags to make linker use RUNPATH's instead of RPATH's.
avx256Disables -mprefer-vector-width=128 in avx2 builds.
thin-ltoEnable Thin Link Time Optimization -flto=thin with a supported linker.
ltoEnable Link Time Optimization -flto.


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

Actionable Macros

%autogenRuns autogen with our %CONFOPTS% to create a configure script then proceeds to run %configure.
%cmakeConfigure cmake project with the distribution specific options, such as prefix and release type.
%cmake_ninjaConfigure cmake project with ninja so it can be used with %ninja_build, %ninja_install and %ninja_check macros.
%configureRuns ./configure with our %CONFOPTS% variable macro.
%makeRuns the make command with the job count specified in eopkg.conf
%make_installPerform a make install, using the DESTDIR variant. Should work for the vast majority of packages.
%patchSane patch macro to run in batch mode and not contaminate source tree on failure
%apply_patchesApplies all patches listed in the series file in ./files folder.
%reconfigureUpdates build scripts such as ./configure and proceeds to run %configure.

Haskell Actionable Macros

%cabal_configureRuns cabal configure with prefix, libdir, etc. and ensures the necessary package.conf.d is copied to the correct location.
%cabal_buildRuns cabal build with %JOBS%
%cabal_installRuns cabal copy to $installdir
%cabal_registerRuns cabal register to generate a pkg-config for package and version, then installs the conf file.

Ninja Actionable Macros

%meson_configureRuns meson with our CFLAGS and appropriate flags such as libdir.
%ninja_buildRuns ninja and passes our %JOBS% variable. This macro obsoletes %meson_build.
%ninja_installRuns meson install and passed the appropriate DESTDIR and %JOBS% variable. This macro obsoletes %meson_install.
%ninja_checkRuns ninja test and passes our %JOBS% variable. This macro obsoletes %meson_check.

Perl Actionable Macros

%perl_setupRuns Perl setup scripts or with the appropriate variable flags.
%perl_buildRuns Perl build scripts or attempts %make.
%perl_installRuns Perl install scripts or attempts %make_install.

Python Actionable Macros

%python_setupRuns the build portion of a using python2.
%python_installRuns the install portion of a, to the appropriate root, using python2.
%python_testWithout argument, runs the test portion of With a .py script, execute the script with python2. With something else execute the command "as it is". (More info)
%python_compileCompiles *.py files using python2. This is only useful where the build doesn't compile them already (indicated by availability of *.pyc files).
%python3_setupRuns the build portion of a using python3.
%python3_installRuns the install portion of a, to the appropriate root, using python3.
%python3_testWithout argument, runs the test portion of With a .py script, execute the script with python3. With something else execute the command "as it is". (More info)
%python3_compileCompiles *.py files using python3. This is only useful where the build doesn't compile them already (indicated by availability of *.pyc files).

Ruby Actionable Macros

%gem_buildRuns gem build.
%gem_installRuns gem install with the appropriate parameters.

Qt Actionable Macros

%qmakeRuns qmake for Qt5 with the appropriate make flags.
%qmake4Runs qmake for Qt4, as well as adding the necessary MOC, RCC, and UIC flags since those Qt4 executables end in -qt4.
%qml_cacheCompiles *.qml files into *.qmlc so they are compiled ahead of time.

Waf Actionable Macros

%waf_configureRuns waf configure with prefix.
%waf_buildRuns waf and passes our %JOBS% variable.
%waf_installRuns waf install and passed the appropriate destdir and %JOBS% variable

Variable Macros

%ARCH%Indicates the current build architecture.
%CC%C compiler
%CFLAGS%cflags as set in eopkg.conf
%CONFOPTS%Flags / options for configuration, such as --prefix=%PREFIX%. Full List.
%CXX%C++ compiler
%CXXFLAGS%cxxflags as set in eopkg.conf
%JOBS%jobs, as set in eopkg.conf
%LDFLAGS%ldflags as set in eopkg.conf
%LIBSUFFIX%Library suffix (either 32 for 32-bit or 64 for 64-bit)
%PREFIX%Hard-coded prefix /usr
%YJOBS%Job count without -j as set in eopkg.conf
%installroot%Hard-coded install directory
%libdir%The distribution’s default library directory, i.e. /usr/lib64 (Alters for emul32)
%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.

$CFLAGScflags as set in eopkg.conf
$CXXFLAGScxxflags as set in eopkg.conf
$LDFLAGSldflags as set in eopkg.conf
$CCC compiler
$CXXC++ compiler
$EMUL32BUILDSet only when compiling in emul32 mode
$installdirThe install directory, i.e. where files are installed to for packaging
$pkgfilesRefers to the ./files directory relative to the package.yml file
$sourcesRefers to the directory where your source files are stored e.g. $sources/nano.tar.gz
$workdirThe work, or source, directory of the package build


The 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 string.


Whole, positive number, used in the release field.


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. nano):

- 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

Packaging Practices

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.