Recipe format specification

From GoboLinux Knowledge Base

[edit] Contents 1 Recipe types 2 Supported options 3 Shell functions 4 Dynamic variables

[edit] Recipe types

Supported recipe types (also known as modes), to be given as argument to recipe_type:

• configure - recipe based on "configure" scripts (autoconf or not)
• cabal - recipe based on Haskell Cabal
• makefile - recipe based on Makefile
• python - recipe based on Python Distutils
• perl - recipe based on Makefile.PL
• xmkmf - recipe based on X11 Imake
• scons - recipe based on SCons
• cmake - recipe based on CMake
• manifest - recipe just needs to copy files over
• meta - meta-recipe: contains only calls to other recipes, which get all build relative to the same installation prefix

[edit] Supported options

[edit] compile_version=<version-number>

Valid modes: all

The version number of Compile used to create this recipe.

[edit] environment=(<array of variables>)

Valid modes: all

Environment variables to be applied to the shell where the compilation takes place. Each entry of the array must be in the format "variable=value".

Example:

environment=(
"PYTHONOPTIMIZE=2"
)

[edit] url=<url>

Note: For Sourceforge URLs, use this variable $httpSourceforge as below

url=$httpSourceforge/<project name>/<filename>
e.g.
url=$httpSourceforge/xmule/xmule-1.8.2.tar.bz2

[edit] urls=(<array of urls>)

Valid modes: all

The URL (or URLs) to be fetched in order to obtain the program's source package(s). If the file exists partially, resumption is attempted. FTP transfers are always performed in passive mode.

[edit] mirror_url=<url>

[edit] mirror_urls=(<array of urls>)

Valid modes: all

URLs to be used, in case the URLs listed in url/urls fail. Multiple mirrors may be specified. For sets of URLs, each mirror needs to specify the same number of URLs.

Example:

urls=(
"http://www.main-site.org/file1"
"http://www.main-site.org/file2"
)
mirror_urls=(
"http://www.mirror1.org/file1"
"http://www.mirror1.org/file2"
"http://www.mirror2.org/file1"
"http://www.mirror2.org/file2"
)

[edit] file=<filename>

[edit] files=(<array of filenames>)

Valid modes: all

The name of the package file containing the program's sources. If not specified, it is assumed to be the same as the final part of the URL, after the last slash. If "urls" is used instead of "url", "files" is expected to contain the same number of entries as "urls". All of them are unpacked relative to the same directory by default, to change this behaviour see "unpack_files" below.

[edit] file_size=<size>

This is the file size, in bytes, of the packed archive (e.g. foo.tar.gz) as reported by "ls -l".

[edit] file_sizes=(<array of sizes>)

Valid modes: all

This value contains the file size of the package file defined by the file value. You can find the size by using ls -l.

user@gobo /Files/Compile/Archives]ls -l gettext-0.16.1.tar.gz
-rw-r--r-- 1 root root 8539634 Jul 11 01:08 gettext-0.16.1.tar.gz

[edit] file_md5=<md5sum>

[edit] file_md5s=(<array of md5sums>)

Valid modes: all

This value contains the MD5Sum of the package file defined by the file value. You can find this MD5Sum by using the md5sum command.

user@gobo /Files/Compile/Archives]md5sum gettext-0.16.1.tar.gz
3d9ad24301c6d6b17ec30704a13fe127  gettext-0.16.1.tar.gz

[edit] uncompress=no

Valid modes: all

Used for urls where the files are going to be used directly. Not a common option.

[edit] unpack_files=inside_first

[edit] unpack_files=contents_inside_first

[edit] unpack_files=dirs

[edit] unpack_files=files_in_root

Valid modes: all

Relevant when "files=(more than one file to download)" is used. (is it ever relevant for a single-file download?)

By default, all entries in "files" are unpacked in the same directory. This flag can be used to override this behavior. "inside_first" tells it to unpack "files[0]" and then unpack all subsequent files inside it.

"contents_inside_first" tells it to unpack "files[0]" and then put the contents of subsequent unpacked "dirs" entries inside it. "dirs" tells it to use the directories explicitly specified in the "dirs" array as destinations.

For example, if "files" is (foo.tar.gz bar.tar.gz) and foo.tar.gz contains foo/1 foo/2 and bar.tar.gz contains foo/3 bar/4 bar/5 The default unpacking behavior, without redefining "dirs" explicitly, generates: foo/1 foo/2 foo/3 bar/4 bar/5 "unpack_files=inside_first" generates foo/1 foo/2 foo/foo/3 foo/bar/4 foo/bar/5 "unpack_files=contents_inside_first" generates foo/1 foo/2 foo/3 foo/4 foo/5

Using "dirs", virtually any path structure can be used. Since the first entry in the "dirs" array is special, it is not used by "unpack_files". If any of the "dirs" entries contains the value of the "target" array, the "keep_existing_target" is implied (it can still be explicitly overridden in the recipe, but then the user might delete the data that was just unpacked).

Using "files_in_root", Compile assumes files are stored in the archive without a directory. A directory is created so that files are unpacked inside it, avoiding scattering files in $compileSourcesDir (typically /Files/Compile/Sources).

[edit] docs=(<array of filenames>)

Valid modes: all

A list of filenames, relative to the program's sources root, of files to be copied to the program's doc/ dir (or doc/$app/ for meta-packages). Wildcards are supported but must be single-quoted. Note that some default names such as README*, AUTHORS and TODO are automatically fetched.

Example:

  docs=(
     'docs/*.html'
  )

[edit] dir=<directory>

[edit] dirs=(<array of directories>)

Valid modes: all

Indicates the directory to "cd" into after the package is unpacked. If not specified, the name of the package file (stripped of its extension) is assumed. If "dirs" is used instead of "dir", "dirs" is expected to contain the same number of entries as "urls". The first entry in the array is special: the compilation method is applied only on the first directory. To compile multiple packages into a single program, use meta-packages ('is_meta'). The usage of "dirs" affects the way files are unpacked. See "unpack_files" for details.

[edit] include=(<array of recipes>)

Valid modes: meta

In a meta-recipe, this array holds the list of recipes that should be built to constitute the complete program. Recipe names should be in the format "App--1.0". The order of the entries in the array is significant, because it is the order in which the recipes are built. Note: be careful with the order, because re-building a meta-package that's already installed may cover up ordering problems.

[edit] keep_existing_target=yes

Valid modes: all

When set, it will not ask the user if they want to erase the contents (if any) prior to compiling the program. This is implicitly set if the "dirs" array contains any reference to "target". See "unpack_files" for details.

[edit] cabal_options=(<array of options>)

Valid modes: cabal

Flags to be passed to the Cabal configure operation. These flags are passed in addition to default flags detected by PrepareProgram (such as --prefix) unless the override_default_options declaration is used.

[edit] runhaskell

Valid modes: cabal

Specifies the method of invoking Haskell to perform a Cabal-based compilation. The default is "runhaskell".

[edit] configure_options=(<array of options>)

Valid modes: configure

Flags to be passed to the configure script. These flags are passed in addition to default flags detected by PrepareProgram (such as --prefix and --sysconfdir on autoconf-based configure scripts), unless the override_default_options declaration is used.

[edit] autogen_before_configure=yes

Valid modes: configure

Use it if you need to run ./autogen.sh in order to generate the configure script.

[edit] build_variables=(<array of assignments>)

Valid modes: configure, makefile, scons

An array used when redefining variables for the first execution of make

Example:

build_variables=(
"DESTDIR=$target"
"MANDIR=$target/man/man1"
)

[edit] install_variables=(<array of assignments>)

Valid modes: configure, makefile, scons

Variables to be passed to "make install". See build_variables.

[edit] make_variables=(<array of assignments>)

Valid modes: configure, makefile

Variables to be passed to both "make" and "make install". A shorthand to avoid having to set everything twice, once in build_variables and then again in install_variables.

[edit] configure=<program name>

Valid modes: configure

By default the configure script is assumed to be called "configure". Use this variable to override this value. Remember that the current directory during execution will still be the one set by the dir variable, even if a directory path is given (as in the second example below). If the behavior you intended is for Compile to "cd" to the "unix" directory and run its build sequence there, use dir instead.

Examples (only one applies at a time):

configure=Configure.gnu
configure=unix/configure

[edit] makefile=<makefile name>

Valid modes: configure, makefile, xmkmf

By default the makefile is assumed to be called "Makefile". Use this variable to override this value. See the note in configure for observations about directory names given in variables of this kind.

Examples (only one applies at a time):

makefile=GNUmakefile
makefile=makefile
makefile=Makefile.linux

[edit] make=<make command>

Valid modes: configure, makefile, xmkmf

By default the make command is assumed to be called "make". This variable can be used to override this value/

Example:

make=unsermake

[edit] build_target=<make target>

Valid modes: configure, makefile, xmkmf, python, scons

The target to be used when calling make or equivalent build script/program to build the program. More than one target may be given at a time, separating them with spaces in a single declaration (you must use quotes).

Examples (only one applies at a time):

build_target=World
build_target="all shared"

[edit] install_target=<make target>

Valid modes: configure, makefile, xmkmf, python, scons

The target to be used when calling make or equivalent build script/program to build the program. More than one target may be given at a time, separating them with spaces in a single declaration (you must use quotes).

Example:

install_target="install install.man install_shared"

[edit] do_build=no

Valid modes: configure, makefile, python

Compile should skip the "build" phase, and only do the "install" run. That is, for Makefile-based recipes, it should run make only once.

[edit] do_install=no

Valid modes: configure, makefile, xmkmf, python, scons

Compile should skip the "install" phase, and only do the "build" run. That is, for Makefile-based recipes, it should run make only once.

[edit] needs_build_directory=yes

Valid modes: configure

Some programs like Glibc recommend that a directory is created and used as a working path during the execution of configure and make. Use of this variable is transparent to other relative paths in other variables (such as configure), but be aware that this special "build" directory will be active as a working directory during the hook shell functions, instead of dir.

[edit] needs_safe_linking=yes

Deprecated? Valid modes: all

This option was used in older versions of the Scripts package to ensure that some critical programs were symlinked into the /System/Links hierarchy in a single step.

[edit] sandbox_options=(<array of options>)

Valid modes: all

Additional options to be passed to SandboxInstall. This is typically used to expand the sandbox to allow additional directories in special situations (such as the installation of kernel modules). Avoid using this option as much as possible, and make sure you know what you're doing when you do use it.

Example:

sandbox_options=(
"--no-sandbox"
)

[edit] symlink_options=(<array of options>)

Valid modes: all

Additional options to be passed to SymlinkProgram. This should be used sparingly, in order to remedy unusual situations (the FreeType package used it to avoid a XFree86 conflict which affected the proper functioning of the system). Avoid using this option if possible; there are almost always better alternatives.

Example:

symlink_options=(
"--conflict overwrite"
)

[edit] manifest=(<array of "file:dir">)

Valid modes: manifest

Specify which files should be copied over, and to where. Destination is relative to target

Example:

manifest=(
"some_script:bin"
"include/a_header.h:include"
"lib/libfoo.so:lib"
)

[edit] without=(<array of submodules>)

Valid modes: perl

Some Perl modules assume the presence of other modules, but may be compiled without them. Use this array if you want to disable those extra dependencies.

Example:

without=(
"xml"
"nuclear_reactor"
)

[edit] create_dirs_first=yes

Valid modes: configure, makefile, perl

By default, Compile only generates directories in the target location right before the installation step. This is useful for the --no-install option (see the Compile reference entry). Unfortunately, some programs fail during the configuration of compilation step if the target directory does not already exist. Use this entry to appease those programs.

[edit] python_options=(<array of options>)

Valid modes: python

Array of options to be passed to the Python Distutils build script. This works similarly to the configure_options array.

[edit] override_default_options=yes

Valid modes: configure, python, scons

Compile chooses some options by default according to the specified target type. In configure recipes, it passes some standard autoconf options to the configure script; in python recipes, distutils options for the Python build script; in scons recipes, some standard options passed in invocations of scons.py. Use this option to disable those options and have your own options (given in configure_options or python_options) overwrite instead of append the option list.

[edit] build_script=<name>

Valid modes: python

Specify the same for the Python build script. If none is given, Compile tries a few default ones, such as setup.py.

[edit] cvs=<CVS server>

Valid modes: all

Specify the CVS server and repository to be used. Note that cvs, svn and url are mutually exclusive, since you should be either fetching from SCM or getting a tarball.

Example:

cvs=:pserver:anonymous:@anoncvs.gimp.org:/cvs/gnome

[edit] cvs_module=<module name to checkout>

Valid modes: all

CVS module to be checked out.

Example:

cvs_module=gimp

[edit] cvs_opts=<string added to cvs operation>

[edit] cvs_options=<string added to cvs operation>

Valid modes: all

Some server configurations require additional options to be passed to the cvs command. You shouldn't normally need this command, but it is available in case the documentation of the project you're checking out instructs you to give special options to cvs.

cvs_options is a synonym to cvs_opts.

[edit] cvs_checkout_options=<string added to cvs checkout operation>

Valid modes: all

Some configurations require additional options to be passed specifically to the cvs checkout command, such as for getting a snapshot from a specific date. Normally, you shouldn't need this command.

[edit] cvs_rsh=<string>

Valid modes: all

Specify a value for the CVS_RSH variable (see cvs documentation for details). If unset, "ssh" is used by default.

[edit] svn=<SVN server>

Valid modes: all

Specify the Subversion server and repository to be used. Note that cvs, svn and url are mutually exclusive, since you should be either fetching from a SCM or getting a tarball.

Example:

svn=http://svn.apache.org/repos/asf/httpd/httpd/branches/2.2.x

[edit] update_each_settings=yes

Valid modes: all

In meta-recipes, Compile only calls UpdateSettings for the meta-recipe and not for its sub-recipes. Set this variable to override this behavior and have UpdateSettings called in every sub-recipe.

[edit] unmanaged_files=(<files>)

Valid modes: all

Files to be installed in an unmanaged way to system locations such as /System/Variable. One cannot install files under Programs using this array.

Basically, unmanaged files are used to place files outside a program's $target directory, and are to be used only when no real alternatives exist. That is, you should not use this array to install files under /usr just because the recipe's makefile define it as the default install location (this can be fixed by changing the makefile variable defining it to $target). Good examples of such files are kernel modules, which can't be linked but need to be actually present under /System/Kernel/Modules.

[edit] Shell functions

Besides the declarative variables, recipes can also contain imperative commands, in form of shell functions. This is the order the functions are called for each recipe type:

Note: pre_patch will not be called if there are no patches.

[edit] configure:

• pre_patch()
• patch, if any
• pre_build()
• configure
• make
• pre_install()
• make install
• pre_link()
• symlink
• post_install()

[edit] cabal:

• pre_patch()
• patch, if any
• cabal configure (affected by "$runhaskell" and "$cabal_options"
• pre_build()
• cabal build (affected by "$runhaskell")
• pre_install()
• cabal install (affected by "$runhaskell")
• symlink
• post_install()

[edit] makefile:

• pre_patch()
• patch, if any
• pre_build()
• make
• pre_install()
• make install
• pre_link()
• symlink
• post_install()

[edit] perl:

• same as makefile

[edit] python:

• pre_patch()
• patch, if any
• pre_build()
• python setup.py build
• pre_install()
• python setup.py install
• pre_link()
• symlink
• post_install()

[edit] xmkmf:

• pre_patch()
• patch, if any
• pre_build()
• xmkmf
• make
• pre_install()
• make install
• pre_link()
• symlink
• post_install()

[edit] manifest:

• pre_patch()
• patch, if any
• pre_install()
• copy files
• pre_link()
• symlink
• post_install()

[edit] scons:

• pre_patch()
• patch, if any
• pre_build()
• scons.py
• pre_install()
• scons.py install
• pre_link()
• symlink
• post_install()

[edit] Private shell functions

For shell functionality to be shared, for example between sub-recipes of different architectures, it is possible to define additional shell functions in the recipe. Their names must be prefixed with private__.

[edit] Useflags

For description of useflags take a look at: http://lists.gobolinux.org/pipermail/gobolinux-devel/2008-April/003489.html

explaination will follow

[edit] Dynamic variables

Compile automatically creates variables that can be used in the functions.

[edit] System variables

To help you in recipes writing, Compile gives you the following run-time variables to use, each referring to a specific filesystem hierarchy's member.

• $goboExecutables
• $goboHeaders
• $goboModules
• $goboLibraries
• $goboPrograms
• $goboSettings
• $goboTemp
• $goboVariable

Which respectively point to (by default):

• /System/Links/Executables
• /System/Links/Headers
• /System/Kernel/Modules
• /System/Links/Libraries
• /Programs
• /System/Settings
• /System/Variable/tmp
• /System/Variable

Thus, if you're writing a recipe for some program which accepts configure options and for which you need to manually specify a library path, you can use the $goboLibraries variable like

configure_options=(
    "--with-extra-libraries=$goboLibraries/<path_to_the_library>"
)

The same applies to the remaining as well, depending on specific program's needs.

[edit] Program variables

For every recipe there will always be variables for the program prefix as well as variables for the settings directory and the variable directory for the program.

• $target
• $settings_target
• $variable_target

For the recipe for Foobar 2.1 those variables will have the values of $goboPrograms/FooBar/2.1, $goboPrograms/FooBar/Settings and $goboPrograms/FooBar/Variable respectively.

[edit] Dependency variables

There will also be variables for every dependency listed in the Dependency file. If for example Foo 1.2 is listed as dependency, the variables will be called

• $foo_path
• $foo_settings_path
• $foo_variable_path

Note that these variables will point to the latest installed version of Foo, instead of the version listed in the Dependency file. Also note that special characters will be replaced with underscore. If, for example, GTK+ is listed in the Dependency file, the variable will be called $gtk__path, and Tcl-Tk will be $tcl_tk_path.