doc/makefile-targets.txt

   1 This is a guide to explain various useful targets in Userland component
   2 Makefiles.  There is a set of targets that all Makefiles must include, plus
   3 some addtional targets that are there for convenience.
   4
   5 component-environment-check::
   6   This target is present in all Makefiles.  It is defined in
   7   $(WS_MAKE_RULES)/environment.mk which is included by
   8   $(WS_MAKE_RULES)/shares-macros.mk.  It reports on some interesting
   9   information about the current environment and whether or not it is suitable
  10   to build and/or publish the component.
  11
  12 component-environment-prep::
  13   This target is present in all Makefiles.  It is defined in
  14   $(WS_MAKE_RULES)/environment.mk which is included by
  15   $(WS_MAKE_RULES)/shares-macros.mk.  It uses both USERLAND_REQUIRED_PACKAGES
  16   and REQUIRED_PACKAGES macro contents to attempt to install any required
  17   packages in the current environment.  To use this target user has to be
  18   assigned "Software Installation" or "Primary Administrator" profile.
  19
  20 component-test-environment-check::
  21   This target is present in all Makefiles.  It is defined in
  22   $(WS_MAKE_RULES)/environment.mk which is included by
  23   $(WS_MAKE_RULES)/shares-macros.mk.  It reports on some interesting
  24   information about the current environment and whether or not it is suitable
  25   to test the component.
  26
  27 component-test-environment-prep::
  28   This target is present in all Makefiles.  It is defined in
  29   $(WS_MAKE_RULES)/environment.mk which is included by
  30   $(WS_MAKE_RULES)/shares-macros.mk.  It uses both
  31   USERLAND_TEST_REQUIRED_PACKAGES and TEST_REQUIRED_PACKAGES macro contents to
  32   attempt to install any required packages in the current environment.  To use
  33   this target user has to be assigned "Software Installation" or "Primary
  34   Administrator" profile.
  35
  36 download::
  37   This target is present in all Makefiles.  It can be used at the top level
  38   to act across all components, or on an individual component basis.  It is
  39   typically defined by including $(WS_MAKE_RULES)/common.mk in your component
  40   Makefile.  This target depends on your component Makefile, so changes to your
  41   component Makefile will automatically trigger a re-download and subsequent
  42   build steps that depend on it.  You can use the MAKEFILE_PREREQ macro to
  43   override this behaviour and avoid rebuilding with each Makefile change.  This
  44   macro should only be used in the calling environment via something like:
  45     $ gmake MAKEFILE_PREREQ= install
  46
  47 unpack::
  48   This target is present in all Makefiles.  It can be used at the top level
  49   to act across all components, or on an individual component basis.  It is
  50   typically defined by including $(WS_MAKE_RULES)/common.mk in your component
  51   Makefile.  This target depends on the previously described "download" target,
  52   This target will unpack any downloaded source archives.  It is an interim
  53   step in the source code preparation phase of the build.
  54
  55 patch::
  56   This target is present in all Makefiles.  It can be used at the top level
  57   to act across all components, or on an individual component basis.  It is
  58   typically defined by including $(WS_MAKE_RULES)/common.mk in your component
  59   Makefile.  This target depends on the previously described "unpack" target,
  60   This target will patch any unpacked source.  It is an interim step in the
  61   source code preparation phase of the build.
  62
  63 prep::
  64   This target is present in all Makefiles.  It can be used at the top level
  65   to act across all components, or on an individual component basis.  It is
  66   typically defined by including $(WS_MAKE_RULES)/common.mk in your component
  67   Makefile.  It depends on the previously described "download" target, as well
  68   as internal interim targets to unpack source archives and apply patches to
  69   the unpacked source.
  70
  71 build::
  72   This target must be present in all Makefiles.  It can be used at the top level
  73   to act across all components, or on an individual component basis.  It is
  74   defined in the individual component Makefiles, but most Makefile fragments
  75   under $(WS_MAKE_RULES) include targets that allow the definitions to depend
  76   on one of several convenience macros $(BUILD_32), $(BUILD_64),
  77   $(BUILD_32_and_64), and $(BUILD_NO_ARCH) to build 32-bit support, 64-bit
  78   support, both 32 and 64 bit support, or architecture neutral support.  The
  79   macro used will depend on the component.
  80
  81 install::
  82   This target must be present in all Makefiles.  It can be used at the top level
  83   to act across all components, or on an individual component basis.  It is
  84   defined in the individual component Makefiles, but most Makefile fragments
  85   under $(WS_MAKE_RULES) include targets that allow the definitions to depend
  86   on one of several convenience macros $(INSTALL_32), $(INSTALL_64),
  87   $(INSTALL_32_and_64), and $(INSTALL_NO_ARCH) to install 32-bit support, 64-bit
  88   support, both 32 and 64 bit support, or architecture neutral support.  The
  89   macro used will depend on the component and corresponds to the build target
  90   macro used.
  91
  92 pkglint::
  93   This target is an optional target is automatically defined in each Makefile
  94   by the inclusion of $(WS_MAKE_RULES)/common.mk.  It will run the build steps
  95   necessary to pkglint the manifests for a component.
  96
  97 pre-publish::
  98   This target is present in all Makefiles.  It can be used at the top level
  99   to act across all components, or on an individual component basis.  It is
 100   automatically defined by including $(WS_MAKE_RULES)/common.mk.  It depends
 101   on the previously described 'install' target and will perform a series of
 102   internal, intermediate steps to use the component package manifests to
 103   generate and validate consistency of packages for that component.
 104
 105   NOTE: The pre-publish target aims to help a recipe developer to make sure
 106   that the recipe can produce a valid package without actually pushing its
 107   bits into his or her repository (allows to experiment, saves some time, and
 108   avoids polluting the repository with known-bad code during development cycles).
 109
 110 publish::
 111   This target is present in all Makefiles.  It can be used at the top level
 112   to act across all components, or on an individual component basis.  It is
 113   automatically defined by including $(WS_MAKE_RULES)/common.mk.  It depends
 114   on the previously described 'pre-publish' target and will actually publish
 115   packages for that component to the repository configured in $(WS_REPO).
 116
 117 clean::
 118   This target is present in all Makefiles.  It can be used at the top level
 119   to act across all components, or on an individual component basis.  It is
 120   automatically defined by including $(WS_MAKE_RULES)/common.mk.  It cleans
 121   up any files created by building the component with the exception of any
 122   downloaded files.
 123
 124 clobber::
 125
 126   This target is present in all Makefiles.  It can be used at the top level
 127   to act across all components, or on an individual component basis.  It is
 128   automatically defined by including $(WS_MAKE_RULES)/common.mk.  It depends
 129   on the previously described 'clean' target and additionally cleans up any
 130   downloaded source archives.
 131
 132 REQUIRED_PACKAGES::
 133   This target is present in all component Makefiles.  It is automatically
 134   defined by including $(WS_MAKE_RULES)/common.mk.  It is a convenience that can
 135   be used to generate the set of REQUIRED_PACKAGES that is needed by the
 136   'pkgdepend resolve' portion of package generation and publication (publish
 137   target).  It automatically appends to the component Makefile, but the results
 138   should be manually verified.
 139
 140 env-check::
 141   This target serves as an alias for component-environment-check target. It exists
 142   only for user convenience.
 143
 144 env-prep::
 145   This target serves as an alias for component-environment-prep target. It exists
 146   only for user convenience.
 147
 148 test-env-check::
 149   This target serves as an alias for component-test-environment-check target.
 150   It exists only for user convenience.
 151
 152 test-env-prep::
 153   This target serves as an alias for component-test-environment-prep target. It
 154   exists only for user convenience.
 155
 156 print-VAR
 157   This target will print contents of variable VAR and also provide information
 158   about variable origin and variable flavor.
 159
 160 print-value-VAR
 161   This target will print contents of variable VAR.
 162
 163 format
 164   This target will apply different refactoring rules to update the Makefile
 165   to the current style: deprecation of macros, use of new target, autoindent...
 166   The rules are implemented in the userland-component utility.
 167
 168 update
 169   This target will format the Makefile then bump the COMPONENT_REVISION variable
 170   if no VERSION value is provided. If a VERSION value is provided it will set
 171   the COMPONENT_VERSION to the given value and remove COMPONENT_REVISION.
 172   For some supported build style it may peform additional actions like:
 173   - infering the latest version if VERSION=latest is passed,
 174   - updating the archive checksum.
 175
 176 update-latest
 177   This target is a convenience shortcut for 'update VERSION=latest'.