Skip to content
This repository was archived by the owner on Nov 9, 2025. It is now read-only.

Recipe description

Jump to bottom
Aleksei Bobylev edited this page Mar 5, 2019 · 3 revisions

The recipe is used to create binary software packages. The creation process includes the following sequence of actions:

  1. Preparation:
    1. Check the quality of the recipe.
    2. Preparation of sources:
      1. download using the Internet;
      2. caching;
      3. verification;
      4. extraction;
      5. patching;
      6. duplication (if necessary).
    3. Preparation of assembly environment:
      • installing the necessary packages or their analogues.
  2. Compiling the sources:
    • using one of the predefined algorithms or a given sequence of commands;
    • tracking errors during compilation;
    • testing (if necessary).
  3. Making the packages:
    • splitting the compiled files into packages using default or specified rules;
    • determination of package architecture;
    • determination of dependencies.
  4. Updating the database:
    • maintaining a database is always up to date.
  5. Uploading updated packages and database to the mirror on a schedule.

BBQ uses recipes in the YAML format, which allows you to describe the visually clear tree structure of the data needed to create packages. The YAML format was chosen among the few similar formats (XML, JSON) because of the greater user friendliness and less visual clutter.

An example of a simple recipe:

name      : libgcrypt
version   : 1.8.4
category  : security
summary   : Cryptographic library based on GnuPG
maintainer: devel@slitaz.org
license   : [GPL2, LGPL2.1]
home      : https://www.gnupg.org/related_software/libgcrypt/
lfs       : http://www.linuxfromscratch.org/blfs/view/svn/general/libgcrypt.html

src:
- url:  https://www.gnupg.org/ftp/gcrypt/libgcrypt/<n>-<v>.tar.bz2
  # https://www.gnupg.org/download/integrity_check.html
  sha1: 4a8ef9db6922f3a31992aca5640b4198a69b58fc

cookopts: force-arch # different configs

bdeps: libgpg-error-dev

make:
- type: gnu

pkgs:
- pkg : main
  deps: libgpg-error
  description: |
    Libgcrypt - The GNU Crypto Library
    Libgcrypt is a general purpose crypto library based on the code used
    in GnuPG.

- pkg : dev
  deps: [std, libgpg-error-dev]

Short notes about the syntax

More complete information can be found in Wikipedia at the YAML article.

The recipe is organized in a hierarchical structure (tree). The smallest element of the tree is the "key:value" pair. For the best visual perception, you can add an arbitrary number of spaces on either side of the colon:

key  : value
other: one

Arrays (lists) can be written in two ways, depending on how you prefer. The following two entries are identical:

license: [GPL2, LGPL2.1]

license:
  - GPL2    # some comment
  # some other comment
  - LGPL2.1

Wherever lists are required in the YAML recipe, it is allowed to use a simple string if the list consists of one element. The following two options give the same result:

license: [GPL3]  # required

license: GPL3    # acceptably

Short aliases for the packages names

The following values are reserved aliases for the most commonly used names:

alias description
main main package itself; substiruted by the original base name
lib shared library package; the actual name is the concatenation of the "lib" at the beginning and the original base name
dev development package; the actual name is the concatenation of the original base name and the "-dev" at the end
lang language package; the actual name is the concatenation of the original base name and the "-lang" at the end

Slightly less common values, beginning or ending with a hyphen, have special meaning:

alias description
value- (prefix) the actual name is the concatenation of the specified prefix (including the hyphen) and the original base name
-value (suffix) the actual name is the concatenation of the original base name and the specified suffix (including the hyphen)

All other package names will be used "as is".

Some examples for the package foo:

alias treated as
std foo
lib libfoo
dev foo-dev
lang foo-lang
core- core-foo
-base foo-base
base base

Description of recipe fields

Top-level fields

field required? description
origin optional the name of the project that may be useful to be included in the address of the sourcesinstead of the placeholder <o> in the fields "url" and "file" of the "src" sub-tree
name mandatory base name; the value of this field can be used instead of the placeholder <n> in the fields "url" and "file" of the "src" sub-tree
version mandatory base version; the value of this field can be used instead of the placeholder <v> in the fields "url" and "file" of the "src" sub-tree; also, the two major digits of the version (in the example above, for the version "1.8.4" this is "1.8") are available as <V> (high version) — useful for GNOME mirror
subversion optional an array of two arguments to the replace function (what to look for and what to replace); this value is available as <s> (substituted version). For example, if the name of the source tarball uses an underscores instead of a dots, you need to specify the following array: ['%.', '_'] (the dot is escaped by the symbol "%") and then use <s> instead of <v> in the "url" or "file" fields
category mandatory base category, one from the predefined list; each created package can use its own category
summary mandatory base short description
maintainer mandatory email of the person who maintains the recipe; use "devel@slitaz.org" if the package currently not maintained
license mandatory array (or string) from predefined licenses
home mandatory the address of the project (package) home page
lfs optional the address of the page dedicated to this package in Linux From Scratch
repology optional the name of the meta package in Repology, if it differs from the name given in the recipe
src optional a tree that includes information about one or more sources. See below for more details.
cookopts optional array (or string): options that remap the default behavior (see file cookopts for details).
bdeps optional array (or string): list of packages required for processing this recipe (build dependencies)
prepare optional this tree is dedicated to source preparation. If you continue to create a package after a failure (using the --continue option), preparation will be skipped completely. See below for more details.
make optional this tree is dedicated to source processing and compilation in particular. See below for more details.
post optional final post-make operations. See below for more details.
pkgs mandatory it lists the names of all the packages produced from the source data. See below for more details.

The "src" sub-tree

src (optional) — a tree that includes information about one or more sources:

  • app (optional) — the name of the VCS application used to get the source: one value from the list (hg for Mercurial, git for Git, svn for Subversion, bzr for Bazaar)

  • url (mandatory) — the address used to get the source. Here you can use placeholders and pseudo-protocols.

    Placeholders include:

    • <o> — the value of the origin field;
    • <n> — the value of the name field;
    • <v> — the value of the version field;
    • <V> — the "high version" — two major digits of the version;
    • <s> — the "substituted version".

    Pseudo-protocols include:

    • gnu:// — the GNU mirror;
    • sf:// — the SourceForge "mirror";
    • xorg:// — the Xorg mirror;
    • gnome:// — the GNOME mirror;
    • github:// — the GitHub "mirror";
    • cpan:// — the CPAN (metacpan) mirror.

  • file (optional) — the name of the file used to cache the received source.

    If not specified, the source will be saved with its original name (basename of the url).

    The file in the cache must have a unique name that includes the name (<n> or <o>) and version (<v>, <V> or <s>).

    If the original source name is not unique (for example, includes only the version), then this field should be defined.

  • dir (optional) — most likely, you will want to extract the secondary sources not into $src, but into some specified subdirectory

  • checksum (optional) — for the integrity cheking purposes you can use one or more fields:

    • md5 for MD5 message digest (32 hex digits);
    • sha1 for SHA-1 message digest (40 hex digits);
    • sha256 for SHA-256 message digest (64 hex digits);
    • sha512 for SHA-512 message digest (128 hex digits);
    • sha3 for SHA-3 message digest using default (224 bits, SHA3-224) output size (56 hex digits);
    • b2 for BLAKE2 using default (BLAKE2b) algorithm (128 hex digits);
    • b2b for BLAKE2 using BLAKE2b algorithm (128 hex digits);
    • b2s for BLAKE2 using BLAKE2s algorithm (64 hex digits);
    • b2bp for BLAKE2 using BLAKE2bp algorithm (128 hex digits);
    • b2sp for BLAKE2 using BLAKE2sp algorithm (64 hex digits).

  • noextract (optional) — specify noextract: true if the source code archive should not be unpacked. In this case, the archive will be simply copied to src (or to the folder specified in dir).

  • rev (optional) — switch to the specified revision when using VCS (Mercurial, Git, Subversion, Bazaar)

  • branch (optional) — switch to the specified branch when using VCS

  • opts (optional) — arguments passed to the run script (may be used when your source is the *.run file)

The "prepare" sub-tree

prepare (optional) — this tree is dedicated to source preparation. If you continue to create a package after a failure (using the --continue option), preparation will be skipped completely.

This tree can contain the following fields:

  • patches (optional) — sub-tree dedicated to the patching. See below for more details.

  • rules (optional) — shell script commands such as sed..., cp... or ./autogen.sh....

    Use the | symbol as indicated below to write your preparation rules:

    rules: |
  sed -i 's|/usr/local|/usr|' Makefile
  cp $stuff/file src/config

The "patches" sub-tree

patches (optional) — sub-tree dedicated to the patching. Each entry definition may include the following:

  • url (optional) — the address from which you want to download the patch.

    The patch file can be packaged (.gz and so on).

    The file will be saved in the source cache with the original name, or with the name given by the field "file".

  • file (optional) — alternate file name for patch caching

  • name (optional) — local patch file name (from the patches sub-folder)

  • args (optional) — patch command arguments, such as -p0 (default is -Np1)

  • checksum (md5, sha1 and so on) (optional) — the patch file checksum.

Note that you can use either the url or name, but not both at the same time. Using a checksum for local patches will add nothing to security, while you cannot control sources of third-party patches and checksums are essential in this case.

The "make" sub-tree

make (optional) — this tree is dedicated to source processing and compilation in particular

  • type (mandatory) — type of compilation rules, value one of:
    • gnu — GNU build tools AKA Autotools — executes the following commands: 
      [ export <env...> ]
<vars> ./configure <args> &&
fix libtool && # if libtool present
<makevars> make <jobs> <makeargs> &&
<makevars> make <jobs> <makeargs> <destdir> install
      For the <args>, <jobs>, <makeargs> and <destdir> please see following optional fields: args, jobs, makeargs and destdir.
    • cmake — executes the following commands: 
      [ export <env...> ]
mkdir -p build # or other, if "build" already exists in the sources tree
cd       build
cmake <args> .. &&
make <jobs> <makeargs> &&
make <jobs> <makeargs> <destdir> install
    • meson — executes the following commands: 
      [ export <env...> ]
mkdir -p build # or other, if "build" already exists in the sources tree
cd       build
meson-wrapper <args> &&
ninja &&
ninja install
  • rules (optional) — custom commands for processing the sources. The result of the specified commands should be the file system tree in the "install" folder: 
    rules: |
  install -Dm755 src/foo $install/usr/bin/foo
  • env (optional) — environment varisbles for the build process mentioned above;
  • vars (optional) — varisbles passed to ./configure mentioned above;
  • args (optional) — <args> mentioned above;
  • jobs (optional) — specify jobs: 1 if the source code does not support parallel build;
  • makevars (optional) — <makevars> mentioned above;
  • makeargs (optional) — <makeargs> mentioned above;
  • destdir (optional) — specify destdir: keep if make install can't install files to the right place without the DESTDIR=... definition.

The "post" sub-tree

post (optional) — final post-make operations.

  • doc (optional) — install documentation files and folders
  • man (optional) — install manual pages
  • desktop (optional) — install desktop files
  • icon (optional) — install icons
  • cmd (optional) — install executables to /usr/bin/
  • files (optional) — install arbitrary files
  • rules (optional) — execute arbitrary shell script

The "pkgs" sub-tree

pkgs (mandatory) — it lists the names of all the packages produced from the source data. Each entry has the following fields:

  • pkg (mandatory) — the name of the package.
    You can use aliases (std, lib, dev, lang, -foo, foo-) or the full package names here.

  • copy (optional) — copy rules.
    Place the copy rules containing symbols @ or * into quoted strings.
    Default copy rules for the predefined alises:

    alias rules
    std @std
    lib *.so.*
    dev @dev
    lang *.mo

    The absence of the copy rules for other types of aliases or for the full package names will be treated as error.

  • set (optional) — the set name from which the files will be copied.

  • deps (optional) — array (or string) of the dependency packages. You can use here the same aliases as in pkg field.

  • suggested (optional) — array (or string) of the soft dependencies.

  • tags (optional) — array (or string) of the tags attached to this package.

  • note (optional) — the final portion of the summary that will be added inside the parentheses to the end of the base summary.

  • cat (optional) — package category. Default categories for the predefined aliases:

    alias cat
    main base category
    lib libs
    dev development
    lang localization

    In other cases the package category will be the same as base category.

  • provide (optional) — array (or string)

  • description (optional) — (not very) long preformatted text in the Markdown format.

Clone this wiki locally