docs/manual/adding-packages-hooks.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 [[hooks]]
   5 === Hooks available in the various build steps
   6
   7 The generic infrastructure (and as a result also the derived autotools
   8 and cmake infrastructures) allow packages to specify hooks.
   9 These define further actions to perform after existing steps.
  10 Most hooks aren't really useful for generic packages, since the +.mk+
  11 file already has full control over the actions performed in each step
  12 of the package construction.
  13
  14 The following hook points are available:
  15
  16 * +LIBFOO_PRE_DOWNLOAD_HOOKS+
  17 * +LIBFOO_POST_DOWNLOAD_HOOKS+
  18
  19 * +LIBFOO_PRE_EXTRACT_HOOKS+
  20 * +LIBFOO_POST_EXTRACT_HOOKS+
  21
  22 * +LIBFOO_PRE_RSYNC_HOOKS+
  23 * +LIBFOO_POST_RSYNC_HOOKS+
  24
  25 * +LIBFOO_PRE_PATCH_HOOKS+
  26 * +LIBFOO_POST_PATCH_HOOKS+
  27
  28 * +LIBFOO_PRE_CONFIGURE_HOOKS+
  29 * +LIBFOO_POST_CONFIGURE_HOOKS+
  30
  31 * +LIBFOO_PRE_BUILD_HOOKS+
  32 * +LIBFOO_POST_BUILD_HOOKS+
  33
  34 * +LIBFOO_PRE_INSTALL_HOOKS+ (for host packages only)
  35 * +LIBFOO_POST_INSTALL_HOOKS+ (for host packages only)
  36
  37 * +LIBFOO_PRE_INSTALL_STAGING_HOOKS+ (for target packages only)
  38 * +LIBFOO_POST_INSTALL_STAGING_HOOKS+ (for target packages only)
  39
  40 * +LIBFOO_PRE_INSTALL_TARGET_HOOKS+ (for target packages only)
  41 * +LIBFOO_POST_INSTALL_TARGET_HOOKS+ (for target packages only)
  42
  43 * +LIBFOO_PRE_INSTALL_IMAGES_HOOKS+
  44 * +LIBFOO_POST_INSTALL_IMAGES_HOOKS+
  45
  46 * +LIBFOO_PRE_LEGAL_INFO_HOOKS+
  47 * +LIBFOO_POST_LEGAL_INFO_HOOKS+
  48
  49 These variables are 'lists' of variable names containing actions to be
  50 performed at this hook point. This allows several hooks to be
  51 registered at a given hook point. Here is an example:
  52
  53 ----------------------
  54 define LIBFOO_POST_PATCH_FIXUP
  55         action1
  56         action2
  57 endef
  58
  59 LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP
  60 ----------------------
  61
  62 ==== Using the +POST_RSYNC+ hook
  63 The +POST_RSYNC+ hook is run only for packages that use a local source,
  64 either through the +local+ site method or the +OVERRIDE_SRCDIR+
  65 mechanism. In this case, package sources are copied using +rsync+ from
  66 the local location into the buildroot build directory. The +rsync+
  67 command does not copy all files from the source directory, though.
  68 Files belonging to a version control system, like the directories
  69 +.git+, +.hg+, etc. are not copied. For most packages this is
  70 sufficient, but a given package can perform additional actions using
  71 the +POST_RSYNC+ hook.
  72
  73 In principle, the hook can contain any command you want. One specific
  74 use case, though, is the intentional copying of the version control
  75 directory using +rsync+. The +rsync+ command you use in the hook can, among
  76 others, use the following variables:
  77
  78 * +$(SRCDIR)+: the path to the overridden source directory
  79 * +$(@D)+: the path to the build directory
  80
  81 ==== Target-finalize hook
  82
  83 Packages may also register hooks in +LIBFOO_TARGET_FINALIZE_HOOKS+.
  84 These hooks are run after all packages are built, but before the
  85 filesystem images are generated. They are seldom used, and your
  86 package probably do not need them.