1// -*- mode:doc; -*-
2// vim: set syntax=asciidoc:
3
4[[hooks]]
5=== Hooks available in the various build steps
6
7The generic infrastructure (and as a result also the derived autotools
8and cmake infrastructures) allow packages to specify hooks.
9These define further actions to perform after existing steps.
10Most hooks aren't really useful for generic packages, since the +.mk+
11file already has full control over the actions performed in each step
12of the package construction.
13
14The 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* +LIBFOO_TARGET_FINALIZE_HOOKS+
50
51These variables are 'lists' of variable names containing actions to be
52performed at this hook point. This allows several hooks to be
53registered at a given hook point. Here is an example:
54
55----------------------
56define LIBFOO_POST_PATCH_FIXUP
57	action1
58	action2
59endef
60
61LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP
62----------------------
63
64[[hooks-rsync]]
65==== Using the +POST_RSYNC+ hook
66The +POST_RSYNC+ hook is run only for packages that use a local source,
67either through the +local+ site method or the +OVERRIDE_SRCDIR+
68mechanism. In this case, package sources are copied using +rsync+ from
69the local location into the buildroot build directory. The +rsync+
70command does not copy all files from the source directory, though.
71Files belonging to a version control system, like the directories
72+.git+, +.hg+, etc. are not copied. For most packages this is
73sufficient, but a given package can perform additional actions using
74the +POST_RSYNC+ hook.
75
76In principle, the hook can contain any command you want. One specific
77use case, though, is the intentional copying of the version control
78directory using +rsync+. The +rsync+ command you use in the hook can, among
79others, use the following variables:
80
81* +$(SRCDIR)+: the path to the overridden source directory
82* +$(@D)+: the path to the build directory
83
84==== Target-finalize hook
85
86Packages may also register hooks in +LIBFOO_TARGET_FINALIZE_HOOKS+.
87These hooks are run after all packages are built, but before the
88filesystem images are generated. They are seldom used, and your
89package probably do not need them.
90