1 This is a guide to explain various useful variables in Userland component

     2 Makefiles.  To distinguish these from the Makefile(s) that are part of each

     3 component distribution, the latter will be referred to as native Makefiles.

     4 

     5 The following are the basics that just about every Makefile should have.

     6 * COMPONENT_NAME is typically a short name (e.g., vim).

     7 * COMPONENT_VERSION is typically numbers separated by dots (e.g. 7.3).

     8 * COMPONENT_SRC is where the archive is extracted.  A common value for this is

     9   "$(COMPONENT_NAME)-$(COMPONENT_VERSION)".

    10 * COMPONENT_PROJECT_URL is the general web site for the component.

    11 * COMPONENT_ARCHIVE is the base name of the archive to be downloaded.  A common

    12   value for this is "$(COMPONENT_SRC).tar.gz".

    13 * COMPONENT_ARCHIVE_HASH is typically "sha256:" followed by the first output

    14   field of `sha256sum $(COMPONENT_ARCHIVE)`.

    15 * COMPONENT_ARCHIVE_URL is where the archive can be downloaded from.  This is

    16   typically constructed from $(COMPONENT_PROJECT_URL) and $(COMPONENT_ARCHIVE).

    17 * COMPONENT_BUGDB is the lower-case rendering of the BugDB cat/subcat.

    18 

    19 These two are both initialized in make-rules/shared-macros.mk rather than any

    20 component-level Makefile, but are frequently referenced from the latter.

    21 * COMPONENT_DIR is the top-level directory of the given component in question.

    22 * SOURCE_DIR is set to $(COMPONENT_DIR)/$(COMPONENT_SRC).

    23 

    24 Additional pre/post configure, build, or install actions can be specified in

    25 a component Makefile by setting them in one of the following macros.  None of

    26 these have default values.  These are mostly used for miscellaneous set-up or

    27 clean-up tweaks as their names suggest.

    28 * COMPONENT_PRE_CONFIGURE_ACTION is used by several components to clone a

    29   source directory.

    30 * COMPONENT_POST_CONFIGURE_ACTION

    31 * COMPONENT_PRE_BUILD_ACTION

    32 * COMPONENT_POST_BUILD_ACTION

    33 * COMPONENT_PRE_INSTALL_ACTION

    34 * COMPONENT_POST_INSTALL_ACTION

    35 * COMPONENT_PRE_TEST_ACTION

    36 * COMPONENT_POST_TEST_ACTION

    37 

    38 If component specific make targets need to be used for build or install or

    39 test, they can be specified via the following.

    40 * COMPONENT_BUILD_TARGETS is not usually set because the default target of most

    41   open source software is the equivalent of a 'build' target.  This needs to be

    42   set when building the software requires a different target than the default.

    43   You should not override make macros here, but in COMPONENT_BUILD_ARGS.

    44 * COMPONENT_INSTALL_TARGETS has a default value of "install".  Very few

    45   components need to alter this.

    46 * COMPONENT_TEST_TARGETS has a default value of "check".  Several components

    47   need to set this to "test".

    48 

    49 * COMPONENT_BUILD_ARGS is probably the mostly useful variable here for solving

    50   subtle build issues.  When you need to override a MACRO set in the native

    51   Makefile of a component, do so by adding something like:

    52      COMPONENT_BUILD_ARGS += MKDIR="$(MKDIR)"

    53   Quoting is often important because values with white-space can be split up,

    54   yielding the wrong results.

    55 * COMPONENT_BUILD_ENV is for when you just need to override things in the

    56   calling environment, like PATH.

    57 * COMPONENT_INSTALL_ARGS is mainly used for altering target directories.

    58 * COMPONENT_INSTALL_ENV is mainly used for altering target directories.

    59 * COMPONENT_TEST_ARGS is little used.

    60 * COMPONENT_TEST_ENV is mainly used for altering PATH and friends.

    61 

    62 * COMPONENT_POST_UNPACK_ACTION is for making minor alterations to the unpacked

    63   source directory before any patching has taken place.  It should almost never

    64   be used.

    65 * COMPONENT_PREP_ACTION is used to make alterations to the unpacked and patched

    66   source.  It should be used with care.

    67 

    68 * CONFIGURE_DEFAULT_DIRS should be "yes" or "no".  A value of "yes" (the

    69   default) will trigger the following being passed to CONFIGURE_OPTIONS as

    70   parameters to corresponding options.

    71   * CONFIGURE_BINDIR is the value for the --bindir= option.

    72   * CONFIGURE_LIBDIR is the value for the --libdir= option.

    73   * CONFIGURE_MANDIR is the value for the --mandir= option.

    74   * CONFIGURE_SBINDIR is the value for the --sbindir= option.

    75 * CONFIGURE_ENV is mainly used for passing CFLAGS and other common Makefile

    76   variables to configure.  When should this be used as opposed to

    77   CONFIGURE_OPTIONS and COMPONENT_BUILD_{ARGS,ENV}?  In general, you want

    78   to tell configure how to build the software using CONFIGURE_OPTIONS.  But

    79   sometimes you need to pass values in via the calling environment.  On rare

    80   occasions, you still need to do things like override MACRO settings in the

    81   generated Makefiles with COMPONENT_BUILD_ARGS.

    82 * CONFIGURE_LOCALEDIR is a cousin of the other *DIR variables above, but

    83   rarely used and hence not triggered by CONFIGURE_DEFAULT_DIRS.

    84 * CONFIGURE_OPTIONS is extremely useful, possibly our most used "add-on"

    85   variable, for passing various options to configure.  These tend to vary per

    86   component, but --enable-foo and --disable-foo for various values of foo are

    87   quite common.

    88 * CONFIGURE_PREFIX is the prefix for the various *DIR variables above.  Its

    89   default is "/usr"; set it if some other value (e.g., "/usr/gnu") is needed.

    90 * CONFIGURE_SCRIPT should be set if the default "$(SOURCE_DIR)/configure" is

    91   unsuitable for whatever reason.