3778N/AThis is a guide to explain various useful variables in Userland component
3778N/AMakefiles. To distinguish these from the Makefile(s) that are part of each
3778N/Acomponent distribution, the latter will be referred to as native Makefiles.
3778N/AThe following are the basics that just about every Makefile should have.
3778N/A* COMPONENT_NAME is typically a short name (
e.g., vim).
3778N/A* COMPONENT_VERSION is typically numbers separated by dots (
e.g. 7.3).
3778N/A* COMPONENT_SRC is where the archive is extracted. A common value for this is
3778N/A "$(COMPONENT_NAME)-$(COMPONENT_VERSION)".
3778N/A* COMPONENT_PROJECT_URL is the general web site for the component.
3778N/A* COMPONENT_ARCHIVE is the base name of the archive to be downloaded. A common
3778N/A* COMPONENT_ARCHIVE_HASH is typically "sha256:" followed by the first output
3778N/A field of `sha256sum $(COMPONENT_ARCHIVE)`.
3778N/A* COMPONENT_ARCHIVE_URL is where the archive can be downloaded from. This is
3778N/A typically constructed from $(COMPONENT_PROJECT_URL) and $(COMPONENT_ARCHIVE).
3996N/A* REQUIRED_PACKAGES is a list of packages required to build or run the
3778N/Acomponent-level Makefile, but are frequently referenced from the latter.
3778N/A* COMPONENT_DIR is the top-level directory of the given component in question.
3778N/A* SOURCE_DIR is set to $(COMPONENT_DIR)/$(COMPONENT_SRC).
3778N/AAdditional
pre/post configure, build, or install actions can be specified in
3778N/Aa component Makefile by setting them in one of the following macros. None of
3778N/Athese have default values. These are mostly used for miscellaneous set-up or
3778N/Aclean-up tweaks as their names suggest.
3778N/A* COMPONENT_PRE_CONFIGURE_ACTION is used by several components to clone a
3778N/A* COMPONENT_POST_CONFIGURE_ACTION
3778N/A* COMPONENT_PRE_BUILD_ACTION
3778N/A* COMPONENT_POST_BUILD_ACTION
3778N/A* COMPONENT_PRE_INSTALL_ACTION
3778N/A* COMPONENT_POST_INSTALL_ACTION
3778N/A* COMPONENT_POST_TEST_ACTION
3778N/AIf component specific make targets need to be used for build or install or
3778N/Atest, they can be specified via the following.
3778N/A* COMPONENT_BUILD_TARGETS is not usually set because the default target of most
3778N/A open source software is the equivalent of a 'build' target. This needs to be
3778N/A set when building the software requires a different target than the default.
3778N/A You should not override make macros here, but in COMPONENT_BUILD_ARGS.
3778N/A* COMPONENT_INSTALL_TARGETS has a default value of "install". Very few
3778N/A components need to alter this.
3778N/A* COMPONENT_TEST_TARGETS has a default value of "check". Several components
3778N/A need to set this to "test".
3778N/A* COMPONENT_BUILD_ARGS is probably the mostly useful variable here for solving
3778N/A subtle build issues. When you need to override a MACRO set in the native
3778N/A Makefile of a component, do so by adding something like:
3778N/A COMPONENT_BUILD_ARGS += MKDIR="$(MKDIR)"
3778N/A Quoting is often important because values with white-space can be split up,
3778N/A yielding the wrong results.
3778N/A* COMPONENT_BUILD_ENV is for when you just need to override things in the
3778N/A calling environment, like PATH.
3778N/A* COMPONENT_INSTALL_ARGS is mainly used for altering target directories.
3778N/A* COMPONENT_INSTALL_ENV is mainly used for altering target directories.
3778N/A* COMPONENT_PUBLISH_ENV is so far only used to work around Python issues when
3778N/A used by "pkgdepend generate", though the variable may be extended in the
3778N/A future for general "gmake publish" usage.
3778N/A* COMPONENT_TEST_ARGS is little used.
3778N/A* COMPONENT_TEST_ENV is mainly used for altering PATH and friends.
3778N/A* COMPONENT_POST_UNPACK_ACTION is for making minor alterations to the unpacked
3778N/A source directory before any patching has taken place. It should almost never
3778N/A* COMPONENT_PREP_ACTION is used to make alterations to the unpacked and patched
3778N/A source. It should be used with care.
3778N/A* CONFIGURE_DEFAULT_DIRS should be "yes" or "no". A value of "yes" (the
3778N/A default) will trigger the following being passed to CONFIGURE_OPTIONS as
3778N/A parameters to corresponding options.
3778N/A * CONFIGURE_BINDIR is the value for the --bindir= option.
3778N/A * CONFIGURE_LIBDIR is the value for the --libdir= option.
3778N/A * CONFIGURE_MANDIR is the value for the --mandir= option.
3778N/A * CONFIGURE_SBINDIR is the value for the --sbindir= option.
3778N/A* CONFIGURE_ENV is mainly used for passing CFLAGS and other common Makefile
3778N/A variables to configure. When should this be used as opposed to
3778N/A CONFIGURE_OPTIONS and COMPONENT_BUILD_{ARGS,ENV}? In general, you want
3778N/A to tell configure how to build the software using CONFIGURE_OPTIONS. But
3778N/A sometimes you need to pass values in via the calling environment. On rare
3778N/A occasions, you still need to do things like override MACRO settings in the
3778N/A generated Makefiles with COMPONENT_BUILD_ARGS.
3778N/A* CONFIGURE_LOCALEDIR is a cousin of the other *DIR variables above, but
3778N/A rarely used and hence not triggered by CONFIGURE_DEFAULT_DIRS.
3778N/A* CONFIGURE_OPTIONS is extremely useful, possibly our most used "add-on"
3778N/A variable, for passing various options to configure. These tend to vary per
3778N/A component, but --enable-foo and --disable-foo for various values of foo are
3778N/A* CONFIGURE_PREFIX is the prefix for the various *DIR variables above. Its
3778N/A* CONFIGURE_SCRIPT should be set if the default "$(SOURCE_DIR)/configure" is
3778N/A unsuitable for whatever reason.
3778N/A* studio_OPT has a default value of "-xO4". Occasional bugs in the optimizer
3778N/A have been found which have required altering this to "-xO3". There are also
3778N/A studio_OPT.$(MACH).$(BITS) versions of this available if greater specificity
3778N/A* TPNO is the Third Party number (
i.e., a numeric value): the License
3778N/A Technology from the Product Lifecycle Suite tool. This should be used
3778N/A in the common case when there is just one TPNO for a component. We
3778N/A recommend that this be near the top of any Makefile, just below the
3778N/A various COMPONENT_foo definitions.
3778N/A* TPNO_foo is for the rare case (~3% of components) when a component has
3778N/A more than one TPNO. Each one should have a separate short but descriptive
3778N/A name substituted for "foo". This likewise should be near the top of any
3778N/A Makefile, just below the various COMPONENT_foo definitions, and it must
6033N/A* PKGREPO_REMOVE_BEFORE_PUBLISH allows automatic removal of previously
6033N/A published components from PKG_REPO (including obsolete and renamed
6033N/A versions). When set as PKGREPO_REMOVE_BEFORE_PUBLISH=yes removal
6033N/A occurs immediately prior to pkgsend. default: "no"
3778N/ANow switching from explaining the function of specific variables to a more
3778N/Ageneral discussion about how to use them to solve problems. One method that
3778N/Ahas served time and again is adding a level of indirection. For example,
3778N/Awhen Python 3 came along, we decided to build it 64-bit only, which meant
3778N/Aits various modules also needed to be built 64-bit only. But many of them
3778N/Ahad BUILD_32_and_64 in their native Makefile. So how to tweak that macro
3778N/Ato do one thing for Python
2.x but another for
3.x? JBeck spent an entire
3778N/Aday trying various combinations that seemed right, but none of them worked.
3778N/AThen Norm pointed out that changing PYTHON_VERSIONS from "3.4 2.7 2.6" to
3778N/A$(PYTHON3_VERSIONS) and $(PYTHON2_VERSIONS) which in turn were "3.4" and
3778N/A"2.7 2.6" would do the trick.
I.e., adding a level of indirection solved
3778N/Athe problem, as it allowed $(PYTHON_VERSIONS) to be used to specify 64-bit
3778N/Amacros but $(PYTHON2_VERSIONS) to specify 32-bit macros. There are many
3778N/Aother places where constructs like this are used.