Recipe description

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.

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.