kumquat-buildroot/docs/manual/adding-packages-hooks.txt

87 lines
2.9 KiB
Plaintext
Raw Normal View History

// -*- mode:doc; -*-
// vim: set syntax=asciidoc:
[[hooks]]
manual: use one-line titles instead of two-line titles (trivial) Asciidoc supports two syntaxes for section titles: two-line titles (title plus underline consisting of a particular symbol), and one-line titles (title prefixed with a specific number of = signs). The two-line title underlines are: Level 0 (top level): ====================== Level 1: ---------------------- Level 2: ~~~~~~~~~~~~~~~~~~~~~~ Level 3: ^^^^^^^^^^^^^^^^^^^^^^ Level 4 (bottom level): ++++++++++++++++++++++ and the one-line title prefixes: = Document Title (level 0) = == Section title (level 1) == === Section title (level 2) === ==== Section title (level 3) ==== ===== Section title (level 4) ===== The buildroot manual is currenly using the two-line titles, but this has multiple disadvantages: - asciidoc also uses some of the underline symbols for other purposes (like preformatted code, example blocks, ...), which makes it difficult to do mass replacements, such as a planned follow-up patch that needs to move all sections one level down. - it is difficult to remember which level a given underline symbol (=-~^+) corresponds to, while counting = signs is easy. This patch changes all two-level titles to one-level titles in the manual. The bulk of the change was done with the following Python script, except for the level 1 titles (-----) as these underlines are also used for literal code blocks. This patch only changes the titles, no other changes. In adding-packages-directory.txt, I did add missing newlines between some titles and their content. ---------------------------------------------------------------------------- #!/usr/bin/env python import sys import mmap import re for input in sys.argv[1:]: f = open(input, 'r+') f.flush() s = mmap.mmap(f.fileno(), 0) # Level 0 (top level): ====================== = # Level 1: ---------------------- == # Level 2: ~~~~~~~~~~~~~~~~~~~~~~ === # Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ==== # Level 4 (bottom level): ++++++++++++++++++++++ ===== def replace_title(s, symbol, replacement): pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE) return pattern.sub(r'%s \1' % replacement, s) new = s new = replace_title(new, '=', '=') new = replace_title(new, '+', '=====') new = replace_title(new, '^', '====') new = replace_title(new, '~', '===') #new = replace_title(new, '-', '==') s.seek(0) s.write(new) s.resize(s.tell()) s.close() f.close() ---------------------------------------------------------------------------- Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
=== Hooks available in the various build steps
The generic infrastructure (and as a result also the derived autotools
and cmake infrastructures) allow packages to specify hooks.
These define further actions to perform after existing steps.
Most hooks aren't really useful for generic packages, since the +.mk+
file already has full control over the actions performed in each step
of the package construction.
The following hook points are available:
* +LIBFOO_PRE_DOWNLOAD_HOOKS+
* +LIBFOO_POST_DOWNLOAD_HOOKS+
* +LIBFOO_PRE_EXTRACT_HOOKS+
* +LIBFOO_POST_EXTRACT_HOOKS+
* +LIBFOO_PRE_RSYNC_HOOKS+
* +LIBFOO_POST_RSYNC_HOOKS+
* +LIBFOO_PRE_PATCH_HOOKS+
* +LIBFOO_POST_PATCH_HOOKS+
* +LIBFOO_PRE_CONFIGURE_HOOKS+
* +LIBFOO_POST_CONFIGURE_HOOKS+
* +LIBFOO_PRE_BUILD_HOOKS+
* +LIBFOO_POST_BUILD_HOOKS+
* +LIBFOO_PRE_INSTALL_HOOKS+ (for host packages only)
* +LIBFOO_POST_INSTALL_HOOKS+ (for host packages only)
* +LIBFOO_PRE_INSTALL_STAGING_HOOKS+ (for target packages only)
* +LIBFOO_POST_INSTALL_STAGING_HOOKS+ (for target packages only)
* +LIBFOO_PRE_INSTALL_TARGET_HOOKS+ (for target packages only)
* +LIBFOO_POST_INSTALL_TARGET_HOOKS+ (for target packages only)
* +LIBFOO_PRE_INSTALL_IMAGES_HOOKS+
* +LIBFOO_POST_INSTALL_IMAGES_HOOKS+
* +LIBFOO_PRE_LEGAL_INFO_HOOKS+
* +LIBFOO_POST_LEGAL_INFO_HOOKS+
These variables are 'lists' of variable names containing actions to be
performed at this hook point. This allows several hooks to be
registered at a given hook point. Here is an example:
----------------------
define LIBFOO_POST_PATCH_FIXUP
action1
action2
endef
LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP
----------------------
manual: use one-line titles instead of two-line titles (trivial) Asciidoc supports two syntaxes for section titles: two-line titles (title plus underline consisting of a particular symbol), and one-line titles (title prefixed with a specific number of = signs). The two-line title underlines are: Level 0 (top level): ====================== Level 1: ---------------------- Level 2: ~~~~~~~~~~~~~~~~~~~~~~ Level 3: ^^^^^^^^^^^^^^^^^^^^^^ Level 4 (bottom level): ++++++++++++++++++++++ and the one-line title prefixes: = Document Title (level 0) = == Section title (level 1) == === Section title (level 2) === ==== Section title (level 3) ==== ===== Section title (level 4) ===== The buildroot manual is currenly using the two-line titles, but this has multiple disadvantages: - asciidoc also uses some of the underline symbols for other purposes (like preformatted code, example blocks, ...), which makes it difficult to do mass replacements, such as a planned follow-up patch that needs to move all sections one level down. - it is difficult to remember which level a given underline symbol (=-~^+) corresponds to, while counting = signs is easy. This patch changes all two-level titles to one-level titles in the manual. The bulk of the change was done with the following Python script, except for the level 1 titles (-----) as these underlines are also used for literal code blocks. This patch only changes the titles, no other changes. In adding-packages-directory.txt, I did add missing newlines between some titles and their content. ---------------------------------------------------------------------------- #!/usr/bin/env python import sys import mmap import re for input in sys.argv[1:]: f = open(input, 'r+') f.flush() s = mmap.mmap(f.fileno(), 0) # Level 0 (top level): ====================== = # Level 1: ---------------------- == # Level 2: ~~~~~~~~~~~~~~~~~~~~~~ === # Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ==== # Level 4 (bottom level): ++++++++++++++++++++++ ===== def replace_title(s, symbol, replacement): pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE) return pattern.sub(r'%s \1' % replacement, s) new = s new = replace_title(new, '=', '=') new = replace_title(new, '+', '=====') new = replace_title(new, '^', '====') new = replace_title(new, '~', '===') #new = replace_title(new, '-', '==') s.seek(0) s.write(new) s.resize(s.tell()) s.close() f.close() ---------------------------------------------------------------------------- Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
==== Using the +POST_RSYNC+ hook
The +POST_RSYNC+ hook is run only for packages that use a local source,
either through the +local+ site method or the +OVERRIDE_SRCDIR+
mechanism. In this case, package sources are copied using +rsync+ from
the local location into the buildroot build directory. The +rsync+
command does not copy all files from the source directory, though.
Files belonging to a version control system, like the directories
+.git+, +.hg+, etc. are not copied. For most packages this is
sufficient, but a given package can perform additional actions using
the +POST_RSYNC+ hook.
In principle, the hook can contain any command you want. One specific
use case, though, is the intentional copying of the version control
directory using +rsync+. The +rsync+ command you use in the hook can, among
others, use the following variables:
* +$(SRCDIR)+: the path to the overridden source directory
* +$(@D)+: the path to the build directory
==== Target-finalize hook
Packages may also register hooks in +LIBFOO_TARGET_FINALIZE_HOOKS+.
These hooks are run after all packages are built, but before the
filesystem images are generated. They are seldom used, and your
package probably do not need them.