Each recipe consists of 3 main parts: defining identifiers, setting build variables, and defining build commands.
The package "mylib" will be used here as an example
General tips:
those not in ALLOWED_LIBRARIES in contrib/devtools/symbol-check.py) don't
need to be shared and should be built statically whenever possible. See
below for more details.
Each package is required to define at least these variables:
$(package)_version: Version of the upstream library or program. If there is no version, a placeholder such as 1.0 can be used.
$(package)downloadpath: Location of the upstream source, without the file-name. Usually http, https or ftp. Secure transmission options like https should be preferred if available.
$(package)filename: The upstream source filename available at the download path.
$(package)sha256hash: The sha256 hash of the upstream file
These variables are optional:
$(package)buildsubdir: cd to this dir before running configure/build/stage commands.
$(package)downloadfile: The file-name of the upstream source if it differs from how it should be stored locally. This can be used to avoid storing file-names with strange characters.
$(package)_dependencies: Names of any other packages that this one depends on.
$(package)_patches: Filenames of any patches needed to build the package
$(package)extrasources: Any extra files that will be fetched via $(package)fetchcmds. These are specified so that they can be fetched and verified via 'make download'.
After defining the main identifiers, build variables may be added or customized before running the build commands. They should be added to a function called $(package)setvars. For example:
define $(package)setvars ... endef
Most variables can be prefixed with the host, architecture, or both, to make the modifications specific to that case. For example:
Universal: $(package)_cc=gcc Linux only: $(package)linuxcc=gcc x8664 only: $(package)x8664cc = gcc x8664 linux only: $(package)x8664linux_cc = gcc
These variables may be set to override or append their default values.
$(package)_cc $(package)_cxx $(package)_objc $(package)_objcxx $(package)_ar $(package)_ranlib $(package)_nm $(package)_cflags $(package)_cxxflags $(package)_ldflags $(package)_cppflags $(package)configenv $(package)buildenv $(package)stageenv $(package)buildopts $(package)configopts
The *_env variables are used to add environment variables to the respective commands.
Many variables respect a debug/release suffix as well, in order to use them for only the appropriate build config. For example:
$(package)cflagsrelease = -O3 $(package)cflagsi686_debug = -g $(package)configopts_release = --disable-debug
These will be used in addition to the options that do not specify debug/release. All builds are considered to be release unless DEBUG=1 is set by the user. Other variables may be defined as needed.
For each build, a unique build dir and staging dir are created. For example,
work/build/mylib/1.0-1adac830f6e and work/staging/mylib/1.0-1adac830f6e.
The following build commands are available for each recipe:
$(package)fetchcmds: Runs from: build dir Fetch the source file. If undefined, it will be fetched and verified against its hash.
$(package)extractcmds: Runs from: build dir Verify the source file against its hash and extract it. If undefined, the source is assumed to be a tarball.
$(package)preprocesscmds: Runs from: build dir/$(package)buildsubdir Preprocess the source as necessary. If undefined, does nothing.
$(package)configcmds: Runs from: build dir/$(package)buildsubdir Configure the source. If undefined, does nothing.
$(package)buildcmds: Runs from: build dir/$(package)buildsubdir Build the source. If undefined, does nothing.
$(package)stagecmds: Runs from: build dir/$(package)buildsubdir Stage the build results. If undefined, does nothing.
The following variables are available for each recipe:
$(1)stagingdir: package's destination sysroot path $(1)stagingprefix_dir: prefix path inside of the package's staging dir $(1)extractdir: path to the package's extracted sources $(1)builddir: path where configure/build/stage commands will be run $(1)patchdir: path where the package's patches (if any) are found
Notes on build commands:
For packages built with autotools, $($(package)_autoconf) can be used in the configure step to (usually) correctly configure automatically. Any $($(package)configopts) will be appended.
Most autotools projects can be properly staged using:
$(MAKE) DESTDIR=$($(package)stagingdir) install
In general, the output of a depends package should not contain any libtool
archives or .pc (pkg-config) files. Instead, the package should output
.cmake (CMake) files where possible.
From the Gentoo Wiki entry:
Libtool pulls in all direct and indirect dependencies into the .la files it creates. This leads to massive overlinking, which is toxic to the Gentoo ecosystem, as it leads to a massive number of unnecessary rebuilds.
Where possible, packages are built with Position Independent Code. Either using
the Autotools --with-pic flag, or CMAKE_POSITION_INDEPENDENT_CODE with CMake.
Secondary dependency packages relative to the limenka binaries/libraries (i.e.
those not in ALLOWED_LIBRARIES in contrib/devtools/symbol-check.py) don't
need to be shared and should be built statically whenever possible. This
improves general build reliability as illustrated by the following example:
When linking an executable against a shared library libprimary that has its
own shared dependency libsecondary, we may need to specify the path to
libsecondary on the link command using the -rpath/-rpath-link options, it is
not sufficient to just say libprimary.
For us, it's much easier to just link a static libsecondary into a shared
libprimary. Especially because in our case, we are linking against a dummy
libprimary anyway that we'll throw away. We don't care if the end-user has a
static or dynamic libsecondary, that's not our concern. With a static
libsecondary, when we need to link libprimary into our executable, there's no
dependency chain to worry about as libprimary has all the symbols.
To build an individual package (useful for debugging), following build targets are available.
make ${package} make ${package}_fetched make ${package}_extracted make ${package}_preprocessed make ${package}_configured make ${package}_built make ${package}_staged make ${package}_postprocessed make ${package}_cached make ${package}cachedchecksum