This is a guide to explain various useful variables in Userland component
|
Makefiles. To distinguish these from the Makefile(s) that are part of each
|
component distribution, the latter will be referred to as native Makefiles.
|
|
The following are the basics that just about every Makefile should have.
|
* COMPONENT_NAME is typically a short name (e.g., vim).
|
* COMPONENT_VERSION is typically numbers separated by dots (e.g. 7.3).
|
* COMPONENT_SRC is where the archive is extracted. A common value for this is
|
"$(COMPONENT_NAME)-$(COMPONENT_VERSION)".
|
* COMPONENT_PROJECT_URL is the general web site for the component.
|
* COMPONENT_ARCHIVE is the base name of the archive to be downloaded. A common
|
value for this is "$(COMPONENT_SRC).tar.gz".
|
* COMPONENT_ARCHIVE_HASH is typically "sha256:" followed by the first output
|
field of `sha256sum $(COMPONENT_ARCHIVE)`.
|
* COMPONENT_ARCHIVE_URL is where the archive can be downloaded from. This is
|
typically constructed from $(COMPONENT_PROJECT_URL) and $(COMPONENT_ARCHIVE).
|
* COMPONENT_SIG_URL is the URL where the PGP signature for $(COMPONENT_ARCHIVE)
|
can be found. This can be used in addition to the hash in
|
$(COMPONENT_ARCHIVE_HASH) to verify the correctness of the archive. If
|
COMPONENT_SIG_URL is present, then COMPONENT_ARCHIVE_HASH needn't be, but its
|
presence is strongly encouraged to ensure that the archive contents don't
|
change silently. Note that when merging, because
|
$WS/tools/.gnupg/pubring.gpg is a binary file, you will have to choose
|
the correct version. To check if key is imported, run:
|
gpg2 --homedir=$(git rev-parse --show-toplevel)/tools/.gnupg --list-keys
|
before you 'git commit' your merge.
|
|
These two are both initialized in make-rules/shared-macros.mk rather than any
|
component-level Makefile, but are frequently referenced from the latter.
|
* COMPONENT_DIR is the top-level directory of the given component in question.
|
* SOURCE_DIR is set to $(COMPONENT_DIR)/$(COMPONENT_SRC).
|
|
Additional pre/post configure, build, or install actions can be specified in
|
a component Makefile by setting them in one of the following macros. None of
|
these have default values. These are mostly used for miscellaneous set-up or
|
clean-up tweaks as their names suggest.
|
* COMPONENT_PRE_CONFIGURE_ACTION is used by several components to clone a
|
source directory.
|
* COMPONENT_POST_CONFIGURE_ACTION
|
* COMPONENT_PRE_BUILD_ACTION
|
* COMPONENT_POST_BUILD_ACTION
|
* COMPONENT_PRE_INSTALL_ACTION
|
* COMPONENT_POST_INSTALL_ACTION
|
* COMPONENT_PRE_TEST_ACTION
|
* COMPONENT_POST_TEST_ACTION
|
|
If component specific make targets need to be used for build or install or
|
test, they can be specified via the following.
|
* COMPONENT_BUILD_TARGETS is not usually set because the default target of most
|
open source software is the equivalent of a 'build' target. This needs to be
|
set when building the software requires a different target than the default.
|
You should not override make macros here, but in COMPONENT_BUILD_ARGS.
|
* COMPONENT_INSTALL_TARGETS has a default value of "install". Very few
|
components need to alter this.
|
* COMPONENT_TEST_TARGETS has a default value of "check". Several components
|
need to set this to "test".
|
|
* COMPONENT_BUILD_ARGS is probably the mostly useful variable here for solving
|
subtle build issues. When you need to override a MACRO set in the native
|
Makefile of a component, do so by adding something like:
|
COMPONENT_BUILD_ARGS += MKDIR="$(MKDIR)"
|
Quoting is often important because values with white-space can be split up,
|
yielding the wrong results.
|
* COMPONENT_BUILD_ENV is for when you just need to override things in the
|
calling environment, like PATH.
|
* COMPONENT_INSTALL_ARGS is mainly used for altering target directories.
|
* COMPONENT_INSTALL_ENV is mainly used for altering target directories.
|
* COMPONENT_TEST_ARGS is little used.
|
* COMPONENT_TEST_ENV is mainly used for altering PATH and friends.
|
|
If your component needs to do some kind of cleanup after a "gmake test" run,
|
such as kill processes after doing a "gmake test" run, then this can be done
|
by setting COMPONENT_TEST_CLEANUP.
|
|
If you have created master test results file(s) for your component in the
|
COMPONENT_TEST_RESULTS_DIR directory, then in order to successfully compare
|
your test results against that master results file, you might need to
|
normalize some of the test output lines. This is done via a set of regular
|
expressions that are applied to the test results. There are some global
|
default ones in the COMPONENT_TEST_TRANSFORMS definition in shared-macros.mk,
|
but your component Makefile might have to += some more for specific transforms
|
that need to be applied to the test output for just this component.
|
|
* COMPONENT_POST_UNPACK_ACTION is for making minor alterations to the unpacked
|
source directory before any patching has taken place. It should almost never
|
be used.
|
* COMPONENT_PREP_ACTION is used to make alterations to the unpacked and patched
|
source. It should be used with care.
|
|
* CONFIGURE_DEFAULT_DIRS should be "yes" or "no". A value of "yes" (the
|
default) will trigger the following being passed to CONFIGURE_OPTIONS as
|
parameters to corresponding options.
|
* CONFIGURE_BINDIR is the value for the --bindir= option.
|
* CONFIGURE_LIBDIR is the value for the --libdir= option.
|
* CONFIGURE_MANDIR is the value for the --mandir= option.
|
* CONFIGURE_SBINDIR is the value for the --sbindir= option.
|
* CONFIGURE_ENV is mainly used for passing CFLAGS and other common Makefile
|
variables to configure. When should this be used as opposed to
|
CONFIGURE_OPTIONS and COMPONENT_BUILD_{ARGS,ENV}? In general, you want
|
to tell configure how to build the software using CONFIGURE_OPTIONS. But
|
sometimes you need to pass values in via the calling environment. On rare
|
occasions, you still need to do things like override MACRO settings in the
|
generated Makefiles with COMPONENT_BUILD_ARGS.
|
* CONFIGURE_LOCALEDIR is a cousin of the other *DIR variables above, but
|
rarely used and hence not triggered by CONFIGURE_DEFAULT_DIRS.
|
* CONFIGURE_OPTIONS is extremely useful, possibly our most used "add-on"
|
variable, for passing various options to configure. These tend to vary per
|
component, but --enable-foo and --disable-foo for various values of foo are
|
quite common.
|
* CONFIGURE_PREFIX is the prefix for the various *DIR variables above. Its
|
default is "/usr"; set it if some other value (e.g., "/usr/gnu") is needed.
|
* CONFIGURE_SCRIPT should be set if the default "$(SOURCE_DIR)/configure" is
|
unsuitable for whatever reason.
|
|
* gcc_OPT has a default value of "-O3". Occasional bugs in the optimizer
|
have been found which have required altering this to "-O2" or lower values.
|
There are also gcc_OPT.$(MACH).$(BITS) versions of this available if
|
greater specificity is needed.
|
|
* Variable PYTHON3_SOABI selects between two library naming schemes of
|
python3 extensions: *.cpython3Xm.so ("cpython") or *.abi3.so ("abi3").
|
Currently, only a few components use ABI3 compliant extensions,
|
therefore, the default value is set to "cpython".
|
|
If you frequently rebuild the same code, such as when you maintain a build server
|
or iterate recipes for the same component, you can benefit by caching the build
|
products with "ccache" - so for repeated input conditions you'd get same output
|
objects quickly.
|
|
Being experimental, the "ccache" integration in OI-Userland build system is
|
disabled by default. See below for hints how to enable and optionally configure it.
|
|
* To enable the "ccache" integration in OI-Userland build system you must
|
`export ENABLE_CCACHE=true` in the calling shell, or set the make-variable
|
like this: `gmake ENABLE_CCACHE=true build`
|
* The "ccache" program supports an inverted toggle CCACHE_DISABLE, which our
|
shared-macros.mk Makefile also honours. By original project's intent, if you
|
execute "ccache" then you want it to do its job. If you are debugging it or
|
unsure if it causes problems, you can easily temporarily disable the "ccache"
|
logic by `export CCACHE_DISABLE=true` so it quickly calls the real compiler.
|
So to enable the caching feature you can also `export CCACHE_DISABLE=false`.
|
* In case of conflicting environtment and/or makefile variables regarding this
|
feature, any explicit request to disable use of "ccache" takes precedence.
|
* With default settings (only `ENABLE_CCACHE=true` in place), the cache and
|
non-volatile configuration will be kept in your `$HOME/.ccache` subdirectory.
|
* To trace progress of "ccache" with your userland component build, you can
|
instrument the compilation-wrapper scripts in `tools/ccache-wrap` directory
|
(then `ccache -p` can be helpful to inspect actual parsing of configuration),
|
and/or use `export CCACHE_LOGFILE=/tmp/ccache.log` to trace its activities.
|
* You can dedicate a cache directory different from the default `$HOME/.ccache`
|
for example with `export CCACHE_DIR=/tmp/ccache-dir; mkdir -p $CCACHE_DIR`.
|
* Note: be wary of ccache's own CCACHE_DISABLE environment variable: any
|
value (empty, "false" etc.) is considered a "true" setting for ccache
|
booleans (and so CCACHE_DISABLE=false still disables the program, falling
|
through to real compiler). This is according to the project's documentation
|
and legacy (backwards compatibility), thus not accepted by upstream as a bug.
|
To negate ccache boolean environment variable settings you can use their
|
CCACHE_NO* counterparts, e.g. `export CCACHE_NODISABLE=anything`.
|
* Troubleshooting: If no files appear in the cache, verify permissions and disk
|
space. Also enable the log file and/or inspect configuration with `ccache -p`
|
(see above) to see details about wrapped compilations. In particular,
|
"ccache" might not actually cache the build products if the file types are
|
unsupported (see the `man ccache` page for options on extending the support),
|
if files are detected to have dynamic contents (e.g. `__TIME__` and similar
|
macros), or when a build product is comprised of several source files (like
|
running `gcc -o binprog *.c`).
|
* You can inspect caching statistics with `ccache -s` and wipe the cache with
|
`ccache -C -z`.
|
* For debugging or development of the ccache component itself, you can use a
|
custom build for oi-userland compilation with `export CCACHE=/path/to/ccache`
|
* The cache directory can contain a configuration file for "ccache" program,
|
which is the recommended way to provide tweaks to your setup. While exported
|
environment variables (e.g. from shell profile) may work, our Makefiles do
|
not make any guarantees about passing each and every possible variable into
|
sub-processes. We do make a best effort to pass the variables listed above.
|
* See `man ccache` for more details about the program and its configuration.
|
