Package.yml

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.

Format

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

Keys

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

Mandatory Keys

Optional, supported keys

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.

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.

Macros

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.

Usage

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

Haskell Actionable Macros

Ninja Actionable Macros

Perl Actionable Macros

Python Actionable Macros

Ruby Actionable Macros

Qt Actionable Macros

Waf Actionable Macros

Variable Macros

Variables

A set of variables are exported in our build stages. These are used to provide context and structure to the scripts.

Types

The package.yml file uses native YAML types, however it follows syntactic conventions and may accept multiple value types for a given key.

string

This is simply text, which does not need to be quoted.

string(s)

Indicates that it is possible to use a list of strings, or one single string.

integer

Whole, positive number, used in the release field.

list

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

dict

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)

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.