2012-11-11 04:14:42 +01:00
|
|
|
// -*- mode:doc; -*-
|
2013-02-13 13:59:02 +01:00
|
|
|
// vim: set syntax=asciidoc:
|
2012-11-11 04:14:42 +01:00
|
|
|
|
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
|
|
|
=== Infrastructure for packages with specific build systems
|
2011-10-10 10:46:39 +02:00
|
|
|
|
|
|
|
|
By 'packages with specific build systems' we mean all the packages
|
|
|
|
|
whose build system is not one of the standard ones, such as
|
|
|
|
|
'autotools' or 'CMake'. This typically includes packages whose build
|
|
|
|
|
system is based on hand-written Makefiles or shell scripts.
|
|
|
|
|
|
2012-07-06 00:06:46 +02:00
|
|
|
[[generic-package-tutorial]]
|
2011-10-10 10:46:39 +02:00
|
|
|
|
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
|
|
|
==== +generic-package+ tutorial
|
2011-10-10 10:46:39 +02:00
|
|
|
|
|
|
|
|
------------------------------
|
2013-06-08 00:34:38 +02:00
|
|
|
01: ################################################################################
|
2011-10-10 10:46:39 +02:00
|
|
|
02: #
|
|
|
|
|
03: # libfoo
|
|
|
|
|
04: #
|
2013-06-08 00:34:38 +02:00
|
|
|
05: ################################################################################
|
2013-02-25 12:31:31 +01:00
|
|
|
06:
|
|
|
|
|
07: LIBFOO_VERSION = 1.0
|
|
|
|
|
08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
|
|
|
|
|
09: LIBFOO_SITE = http://www.foosoftware.org/download
|
2017-03-30 15:43:30 +02:00
|
|
|
10: LIBFOO_LICENSE = GPL-3.0+
|
2013-02-25 12:31:31 +01:00
|
|
|
11: LIBFOO_LICENSE_FILES = COPYING
|
|
|
|
|
12: LIBFOO_INSTALL_STAGING = YES
|
|
|
|
|
13: LIBFOO_CONFIG_SCRIPTS = libfoo-config
|
|
|
|
|
14: LIBFOO_DEPENDENCIES = host-libaaa libbbb
|
|
|
|
|
15:
|
|
|
|
|
16: define LIBFOO_BUILD_CMDS
|
2016-07-25 20:35:18 +02:00
|
|
|
17: $(MAKE) $(TARGET_CONFIGURE_OPTS) -C $(@D) all
|
2013-02-25 12:31:31 +01:00
|
|
|
18: endef
|
|
|
|
|
19:
|
|
|
|
|
20: define LIBFOO_INSTALL_STAGING_CMDS
|
|
|
|
|
21: $(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a
|
|
|
|
|
22: $(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h
|
|
|
|
|
23: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib
|
|
|
|
|
24: endef
|
|
|
|
|
25:
|
|
|
|
|
26: define LIBFOO_INSTALL_TARGET_CMDS
|
|
|
|
|
27: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib
|
|
|
|
|
28: $(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
|
|
|
|
|
29: endef
|
|
|
|
|
30:
|
2016-01-21 22:23:38 +01:00
|
|
|
31: define LIBFOO_USERS
|
|
|
|
|
32: foo -1 libfoo -1 * - - - LibFoo daemon
|
2013-02-25 12:31:31 +01:00
|
|
|
33: endef
|
|
|
|
|
34:
|
2016-01-21 22:23:38 +01:00
|
|
|
35: define LIBFOO_DEVICES
|
2021-12-01 08:36:08 +01:00
|
|
|
36: /dev/foo c 666 0 0 42 0 - - -
|
2013-02-25 12:31:31 +01:00
|
|
|
37: endef
|
|
|
|
|
38:
|
2016-01-21 22:23:38 +01:00
|
|
|
39: define LIBFOO_PERMISSIONS
|
2021-12-01 08:36:08 +01:00
|
|
|
40: /bin/foo f 4755 foo libfoo - - - - -
|
2013-04-12 09:14:18 +02:00
|
|
|
41: endef
|
|
|
|
|
42:
|
|
|
|
|
43: $(eval $(generic-package))
|
2011-10-10 10:46:39 +02:00
|
|
|
--------------------------------
|
|
|
|
|
|
2013-02-25 12:31:31 +01:00
|
|
|
The Makefile begins on line 7 to 11 with metadata information: the
|
2011-10-10 10:46:39 +02:00
|
|
|
version of the package (+LIBFOO_VERSION+), the name of the
|
2013-09-06 08:14:15 +02:00
|
|
|
tarball containing the package (+LIBFOO_SOURCE+) (xz-ed tarball recommended)
|
|
|
|
|
the Internet location at which the tarball can be downloaded from
|
2012-12-30 11:47:21 +01:00
|
|
|
(+LIBFOO_SITE+), the license (+LIBFOO_LICENSE+) and file with the
|
|
|
|
|
license text (+LIBFOO_LICENSE_FILES+). All variables must start with
|
|
|
|
|
the same prefix, +LIBFOO_+ in this case. This prefix is always the
|
|
|
|
|
uppercased version of the package name (see below to understand where
|
|
|
|
|
the package name is defined).
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2013-02-25 12:31:31 +01:00
|
|
|
On line 12, we specify that this package wants to install something to
|
2011-10-10 10:46:39 +02:00
|
|
|
the staging space. This is often needed for libraries, since they must
|
|
|
|
|
install header files and other development files in the staging space.
|
|
|
|
|
This will ensure that the commands listed in the
|
|
|
|
|
+LIBFOO_INSTALL_STAGING_CMDS+ variable will be executed.
|
|
|
|
|
|
2013-02-25 12:31:31 +01:00
|
|
|
On line 13, we specify that there is some fixing to be done to some
|
2013-01-30 03:46:40 +01:00
|
|
|
of the 'libfoo-config' files that were installed during
|
|
|
|
|
+LIBFOO_INSTALL_STAGING_CMDS+ phase.
|
|
|
|
|
These *-config files are executable shell script files that are
|
|
|
|
|
located in '$(STAGING_DIR)/usr/bin' directory and are executed
|
|
|
|
|
by other 3rd party packages to find out the location and the linking
|
|
|
|
|
flags of this particular package.
|
|
|
|
|
|
|
|
|
|
The problem is that all these *-config files by default give wrong,
|
|
|
|
|
host system linking flags that are unsuitable for cross-compiling.
|
|
|
|
|
|
|
|
|
|
For example: '-I/usr/include' instead of '-I$(STAGING_DIR)/usr/include'
|
|
|
|
|
or: '-L/usr/lib' instead of '-L$(STAGING_DIR)/usr/lib'
|
|
|
|
|
|
|
|
|
|
So some sed magic is done to these scripts to make them give correct
|
|
|
|
|
flags.
|
2013-02-07 13:35:03 +01:00
|
|
|
The argument to be given to +LIBFOO_CONFIG_SCRIPTS+ is the file name(s)
|
2013-01-30 03:46:40 +01:00
|
|
|
of the shell script(s) needing fixing. All these names are relative to
|
|
|
|
|
'$(STAGING_DIR)/usr/bin' and if needed multiple names can be given.
|
|
|
|
|
|
2013-02-07 13:35:04 +01:00
|
|
|
In addition, the scripts listed in +LIBFOO_CONFIG_SCRIPTS+ are removed
|
|
|
|
|
from +$(TARGET_DIR)/usr/bin+, since they are not needed on the target.
|
|
|
|
|
|
2013-08-09 12:16:48 +02:00
|
|
|
.Config script: 'divine' package
|
|
|
|
|
================================
|
2013-01-30 03:46:40 +01:00
|
|
|
Package divine installs shell script '$(STAGING_DIR)/usr/bin/divine-config'.
|
|
|
|
|
|
2013-08-09 12:16:48 +02:00
|
|
|
So its fixup would be:
|
2013-01-30 03:46:40 +01:00
|
|
|
|
2013-08-09 12:16:48 +02:00
|
|
|
--------------------------------
|
2013-02-07 13:35:03 +01:00
|
|
|
DIVINE_CONFIG_SCRIPTS = divine-config
|
2013-08-09 12:16:48 +02:00
|
|
|
--------------------------------
|
|
|
|
|
================================
|
2013-01-30 03:46:40 +01:00
|
|
|
|
2013-08-09 12:16:48 +02:00
|
|
|
.Config script: 'imagemagick' package:
|
|
|
|
|
================================
|
2013-01-30 03:46:40 +01:00
|
|
|
Package imagemagick installs the following scripts:
|
|
|
|
|
'$(STAGING_DIR)/usr/bin/{Magick,Magick++,MagickCore,MagickWand,Wand}-config'
|
|
|
|
|
|
|
|
|
|
So it's fixup would be:
|
|
|
|
|
|
2013-08-09 12:16:48 +02:00
|
|
|
--------------------------------
|
2013-02-07 13:35:03 +01:00
|
|
|
IMAGEMAGICK_CONFIG_SCRIPTS = \
|
|
|
|
|
Magick-config Magick++-config \
|
|
|
|
|
MagickCore-config MagickWand-config Wand-config
|
2013-08-09 12:16:48 +02:00
|
|
|
--------------------------------
|
|
|
|
|
================================
|
2013-01-30 03:46:40 +01:00
|
|
|
|
2013-02-25 12:31:31 +01:00
|
|
|
On line 14, we specify the list of dependencies this package relies
|
2011-10-10 10:46:39 +02:00
|
|
|
on. These dependencies are listed in terms of lower-case package names,
|
|
|
|
|
which can be packages for the target (without the +host-+
|
|
|
|
|
prefix) or packages for the host (with the +host-+) prefix).
|
|
|
|
|
Buildroot will ensure that all these packages are built and installed
|
|
|
|
|
'before' the current package starts its configuration.
|
|
|
|
|
|
2013-02-25 12:31:31 +01:00
|
|
|
The rest of the Makefile, lines 16..29, defines what should be done
|
2012-12-30 11:47:21 +01:00
|
|
|
at the different steps of the package configuration, compilation and
|
|
|
|
|
installation.
|
2011-10-10 10:46:39 +02:00
|
|
|
+LIBFOO_BUILD_CMDS+ tells what steps should be performed to
|
|
|
|
|
build the package. +LIBFOO_INSTALL_STAGING_CMDS+ tells what
|
|
|
|
|
steps should be performed to install the package in the staging space.
|
|
|
|
|
+LIBFOO_INSTALL_TARGET_CMDS+ tells what steps should be
|
|
|
|
|
performed to install the package in the target space.
|
|
|
|
|
|
|
|
|
|
All these steps rely on the +$(@D)+ variable, which
|
|
|
|
|
contains the directory where the source code of the package has been
|
|
|
|
|
extracted.
|
|
|
|
|
|
2020-04-02 14:41:12 +02:00
|
|
|
On lines 31..33, we define a user that is used by this package (e.g.
|
2016-01-21 22:23:38 +01:00
|
|
|
to run a daemon as non-root) (+LIBFOO_USERS+).
|
|
|
|
|
|
|
|
|
|
On line 35..37, we define a device-node file used by this package
|
2012-12-30 11:47:21 +01:00
|
|
|
(+LIBFOO_DEVICES+).
|
|
|
|
|
|
2016-01-21 22:23:38 +01:00
|
|
|
On line 39..41, we define the permissions to set to specific files
|
2012-12-30 11:47:21 +01:00
|
|
|
installed by this package (+LIBFOO_PERMISSIONS+).
|
|
|
|
|
|
2013-04-12 09:14:18 +02:00
|
|
|
Finally, on line 43, we call the +generic-package+ function, which
|
2011-10-10 10:46:39 +02:00
|
|
|
generates, according to the variables defined previously, all the
|
|
|
|
|
Makefile code necessary to make your package working.
|
|
|
|
|
|
2012-07-06 00:06:46 +02:00
|
|
|
[[generic-package-reference]]
|
2011-10-10 10:46:39 +02:00
|
|
|
|
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
|
|
|
==== +generic-package+ reference
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2012-07-03 00:07:08 +02:00
|
|
|
There are two variants of the generic target. The +generic-package+ macro is
|
2014-12-19 08:12:33 +01:00
|
|
|
used for packages to be cross-compiled for the target. The
|
2012-07-03 00:05:46 +02:00
|
|
|
+host-generic-package+ macro is used for host packages, natively compiled
|
2014-12-19 08:12:33 +01:00
|
|
|
for the host. It is possible to call both of them in a single +.mk+
|
2012-07-03 00:05:46 +02:00
|
|
|
file: once to create the rules to generate a target
|
2011-10-10 10:46:39 +02:00
|
|
|
package and once to create the rules to generate a host package:
|
|
|
|
|
|
|
|
|
|
----------------------
|
2012-07-03 00:07:08 +02:00
|
|
|
$(eval $(generic-package))
|
2012-07-03 00:05:46 +02:00
|
|
|
$(eval $(host-generic-package))
|
2011-10-10 10:46:39 +02:00
|
|
|
----------------------
|
|
|
|
|
|
|
|
|
|
This might be useful if the compilation of the target package requires
|
|
|
|
|
some tools to be installed on the host. If the package name is
|
|
|
|
|
+libfoo+, then the name of the package for the target is also
|
|
|
|
|
+libfoo+, while the name of the package for the host is
|
|
|
|
|
+host-libfoo+. These names should be used in the DEPENDENCIES
|
|
|
|
|
variables of other packages, if they depend on +libfoo+ or
|
|
|
|
|
+host-libfoo+.
|
|
|
|
|
|
2018-04-29 14:15:22 +02:00
|
|
|
The call to the +generic-package+ and/or +host-generic-package+ macro
|
|
|
|
|
*must* be at the end of the +.mk+ file, after all variable definitions.
|
|
|
|
|
The call to +host-generic-package+ *must* be after the call to
|
|
|
|
|
+generic-package+, if any.
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2012-07-03 00:07:08 +02:00
|
|
|
For the target package, the +generic-package+ uses the variables defined by
|
2011-10-10 10:46:39 +02:00
|
|
|
the .mk file and prefixed by the uppercased package name:
|
2012-07-03 00:05:46 +02:00
|
|
|
+LIBFOO_*+. +host-generic-package+ uses the +HOST_LIBFOO_*+ variables. For
|
2011-10-10 10:46:39 +02:00
|
|
|
'some' variables, if the +HOST_LIBFOO_+ prefixed variable doesn't
|
|
|
|
|
exist, the package infrastructure uses the corresponding variable
|
|
|
|
|
prefixed by +LIBFOO_+. This is done for variables that are likely to
|
|
|
|
|
have the same value for both the target and host packages. See below
|
|
|
|
|
for details.
|
|
|
|
|
|
|
|
|
|
The list of variables that can be set in a +.mk+ file to give metadata
|
|
|
|
|
information is (assuming the package name is +libfoo+) :
|
|
|
|
|
|
|
|
|
|
* +LIBFOO_VERSION+, mandatory, must contain the version of the
|
|
|
|
|
package. Note that if +HOST_LIBFOO_VERSION+ doesn't exist, it is
|
|
|
|
|
assumed to be the same as +LIBFOO_VERSION+. It can also be a
|
docs/manual: using a branch name as FOO_VERSION does not work
For various reasons, we've always suggested users to avoid using a
branch as version string for their packages, because it does not work
as a they would expect:
- it is not reproducible, because the branch may change between two
builds that are done at different times;
- it does not even follow the branch, as Buildroot anyway generates
a local tarball, which it will reuse on subsequent builds.
Furthermore, since we fetch and not pull, any existing local branch
is not updated.
Yet, until recently, using a branch name would just work (with the
above limitations): the git tree was cloned, the branch checked out,
and the tarball created.
But with the advent of the git caching, using a branch name does not
work anymore. Indeed, we now do a git-fetch, and that does not create
a local master branch. So we can't check out master, because it does
not exist locally. And for other branches, as noticed above, the local
branch does not get udpated to the remote one.
Furthermore, the local branches are only created by chance, again as a
side-effect of trying to fetch the "special refs".
So, we can't say that we reliably support the use of a branch name.
Update the manual to state that using a branch does not work. Remove
the 'stable' example, as it looked like the name of a stable branch;
instead, replace it with a version string that ressemble a tag.
Fix the layout of the manual by making the version examples an actual
bulleted list.
Note: the above is only entirely true for git. For Mercurial, CVS and
subversion, the status may be mixed, but nonetheless, using branches is
still a bad idea, if at least because it is not reproducible, and
because Buildroot does not even follow the branch. So, we do not
differentiate between the various SCMs, and just flatly state that using
a branch name is not supported.
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Cc: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
Cc: Maxime Hadjinlian <maxime.hadjinlian@gmail.com>
Cc: Peter Korsgaard <peter@korsgaard.com>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
2018-05-11 17:50:58 +02:00
|
|
|
revision number or a tag for packages that are fetched directly
|
2018-08-23 12:04:33 +02:00
|
|
|
from their version control system. Examples:
|
docs/manual: using a branch name as FOO_VERSION does not work
For various reasons, we've always suggested users to avoid using a
branch as version string for their packages, because it does not work
as a they would expect:
- it is not reproducible, because the branch may change between two
builds that are done at different times;
- it does not even follow the branch, as Buildroot anyway generates
a local tarball, which it will reuse on subsequent builds.
Furthermore, since we fetch and not pull, any existing local branch
is not updated.
Yet, until recently, using a branch name would just work (with the
above limitations): the git tree was cloned, the branch checked out,
and the tarball created.
But with the advent of the git caching, using a branch name does not
work anymore. Indeed, we now do a git-fetch, and that does not create
a local master branch. So we can't check out master, because it does
not exist locally. And for other branches, as noticed above, the local
branch does not get udpated to the remote one.
Furthermore, the local branches are only created by chance, again as a
side-effect of trying to fetch the "special refs".
So, we can't say that we reliably support the use of a branch name.
Update the manual to state that using a branch does not work. Remove
the 'stable' example, as it looked like the name of a stable branch;
instead, replace it with a version string that ressemble a tag.
Fix the layout of the manual by making the version examples an actual
bulleted list.
Note: the above is only entirely true for git. For Mercurial, CVS and
subversion, the status may be mixed, but nonetheless, using branches is
still a bad idea, if at least because it is not reproducible, and
because Buildroot does not even follow the branch. So, we do not
differentiate between the various SCMs, and just flatly state that using
a branch name is not supported.
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Cc: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
Cc: Maxime Hadjinlian <maxime.hadjinlian@gmail.com>
Cc: Peter Korsgaard <peter@korsgaard.com>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
2018-05-11 17:50:58 +02:00
|
|
|
** a version for a release tarball: +LIBFOO_VERSION = 0.1.2+
|
|
|
|
|
** a sha1 for a git tree: +LIBFOO_VERSION = cb9d6aa9429e838f0e54faa3d455bcbab5eef057+
|
|
|
|
|
** a tag for a git tree +LIBFOO_VERSION = v0.1.2+
|
2018-08-23 12:04:33 +02:00
|
|
|
+
|
|
|
|
|
.Note:
|
|
|
|
|
Using a branch name as +FOO_VERSION+ is not supported, because it does
|
|
|
|
|
not and can not work as people would expect it should:
|
|
|
|
|
+
|
|
|
|
|
1. due to local caching, Buildroot will not re-fetch the repository,
|
|
|
|
|
so people who expect to be able to follow the remote repository
|
|
|
|
|
would be quite surprised and disappointed;
|
|
|
|
|
2. because two builds can never be perfectly simultaneous, and because
|
|
|
|
|
the remote repository may get new commits on the branch anytime,
|
|
|
|
|
two users, using the same Buildroot tree and building the same
|
|
|
|
|
configuration, may get different source, thus rendering the build
|
|
|
|
|
non reproducible, and people would be quite surprised and
|
|
|
|
|
disappointed.
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2015-03-29 19:33:20 +02:00
|
|
|
* +LIBFOO_SOURCE+ may contain the name of the tarball of the package,
|
|
|
|
|
which Buildroot will use to download the tarball from
|
|
|
|
|
+LIBFOO_SITE+. If +HOST_LIBFOO_SOURCE+ is not specified, it defaults
|
|
|
|
|
to +LIBFOO_SOURCE+. If none are specified, then the value is assumed
|
|
|
|
|
to be +libfoo-$(LIBFOO_VERSION).tar.gz+. +
|
2011-10-10 10:46:39 +02:00
|
|
|
Example: +LIBFOO_SOURCE = foobar-$(LIBFOO_VERSION).tar.bz2+
|
|
|
|
|
|
2013-01-06 06:22:42 +01:00
|
|
|
* +LIBFOO_PATCH+ may contain a space-separated list of patch file
|
2015-03-29 19:33:20 +02:00
|
|
|
names, that Buildroot will download and apply to the package source
|
|
|
|
|
code. If an entry contains +://+, then Buildroot will assume it is a
|
|
|
|
|
full URL and download the patch from this location. Otherwise,
|
|
|
|
|
Buildroot will assume that the patch should be downloaded from
|
|
|
|
|
+LIBFOO_SITE+. If +HOST_LIBFOO_PATCH+ is not specified, it defaults
|
|
|
|
|
to +LIBFOO_PATCH+. Note that patches that are included in Buildroot
|
2013-01-06 06:22:42 +01:00
|
|
|
itself use a different mechanism: all files of the form
|
2015-03-29 19:33:23 +02:00
|
|
|
+*.patch+ present in the package directory inside
|
2012-11-27 12:59:17 +01:00
|
|
|
Buildroot will be applied to the package after extraction (see
|
2013-01-06 06:22:42 +01:00
|
|
|
xref:patch-policy[patching a package]). Finally, patches listed in
|
|
|
|
|
the +LIBFOO_PATCH+ variable are applied _before_ the patches stored
|
|
|
|
|
in the Buildroot package directory.
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2012-06-17 13:53:59 +02:00
|
|
|
* +LIBFOO_SITE+ provides the location of the package, which can be a
|
|
|
|
|
URL or a local filesystem path. HTTP, FTP and SCP are supported URL
|
2015-09-28 18:10:33 +02:00
|
|
|
types for retrieving package tarballs. In these cases don't include a
|
|
|
|
|
trailing slash: it will be added by Buildroot between the directory
|
|
|
|
|
and the filename as appropriate. Git, Subversion, Mercurial,
|
2012-06-17 13:53:59 +02:00
|
|
|
and Bazaar are supported URL types for retrieving packages directly
|
2013-12-05 18:20:45 +01:00
|
|
|
from source code management systems. There is a helper function to make
|
2014-06-02 17:55:59 +02:00
|
|
|
it easier to download source tarballs from GitHub (refer to
|
2013-12-05 18:20:45 +01:00
|
|
|
xref:github-download-url[] for details). A filesystem path may be used
|
2012-06-17 13:53:59 +02:00
|
|
|
to specify either a tarball or a directory containing the package
|
|
|
|
|
source code. See +LIBFOO_SITE_METHOD+ below for more details on how
|
|
|
|
|
retrieval works. +
|
|
|
|
|
Note that SCP URLs should be of the form
|
|
|
|
|
+scp://[user@]host:filepath+, and that filepath is relative to the
|
|
|
|
|
user's home directory, so you may want to prepend the path with a
|
|
|
|
|
slash for absolute paths:
|
2020-04-15 18:48:45 +02:00
|
|
|
+scp://[user@]host:/absolutepath+. The same goes for SFTP URLs. +
|
2012-02-06 21:41:08 +01:00
|
|
|
If +HOST_LIBFOO_SITE+ is not specified, it defaults to
|
2012-11-07 00:10:43 +01:00
|
|
|
+LIBFOO_SITE+.
|
2012-02-06 21:41:08 +01:00
|
|
|
Examples: +
|
|
|
|
|
+LIBFOO_SITE=http://www.libfoosoftware.org/libfoo+ +
|
2015-03-09 23:14:50 +01:00
|
|
|
+LIBFOO_SITE=http://svn.xiph.org/trunk/Tremor+ +
|
2012-11-27 12:59:16 +01:00
|
|
|
+LIBFOO_SITE=/opt/software/libfoo.tar.gz+ +
|
2015-09-28 18:10:33 +02:00
|
|
|
+LIBFOO_SITE=$(TOPDIR)/../src/libfoo+
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2016-08-23 14:19:46 +02:00
|
|
|
* +LIBFOO_DL_OPTS+ is a space-separated list of additional options to
|
|
|
|
|
pass to the downloader. Useful for retrieving documents with
|
|
|
|
|
server-side checking for user logins and passwords, or to use a proxy.
|
|
|
|
|
All download methods valid for +LIBFOO_SITE_METHOD+ are supported;
|
|
|
|
|
valid options depend on the download method (consult the man page
|
|
|
|
|
for the respective download utilities).
|
|
|
|
|
|
2015-03-29 19:33:20 +02:00
|
|
|
* +LIBFOO_EXTRA_DOWNLOADS+ is a space-separated list of additional
|
|
|
|
|
files that Buildroot should download. If an entry contains +://+
|
|
|
|
|
then Buildroot will assume it is a complete URL and will download
|
|
|
|
|
the file using this URL. Otherwise, Buildroot will assume the file
|
|
|
|
|
to be downloaded is located at +LIBFOO_SITE+. Buildroot will not do
|
|
|
|
|
anything with those additional files, except download them: it will
|
2018-04-02 16:57:59 +02:00
|
|
|
be up to the package recipe to use them from +$(LIBFOO_DL_DIR)+.
|
2013-10-08 20:17:00 +02:00
|
|
|
|
2012-06-17 13:54:00 +02:00
|
|
|
* +LIBFOO_SITE_METHOD+ determines the method used to fetch or copy the
|
|
|
|
|
package source code. In many cases, Buildroot guesses the method
|
|
|
|
|
from the contents of +LIBFOO_SITE+ and setting +LIBFOO_SITE_METHOD+
|
|
|
|
|
is unnecessary. When +HOST_LIBFOO_SITE_METHOD+ is not specified, it
|
|
|
|
|
defaults to the value of +LIBFOO_SITE_METHOD+. +
|
|
|
|
|
The possible values of +LIBFOO_SITE_METHOD+ are:
|
2014-12-19 08:12:33 +01:00
|
|
|
** +wget+ for normal FTP/HTTP downloads of tarballs. Used by
|
2012-06-17 13:54:00 +02:00
|
|
|
default when +LIBFOO_SITE+ begins with +http://+, +https://+ or
|
|
|
|
|
+ftp://+.
|
2014-12-19 08:12:33 +01:00
|
|
|
** +scp+ for downloads of tarballs over SSH with scp. Used by
|
2012-06-17 13:54:00 +02:00
|
|
|
default when +LIBFOO_SITE+ begins with +scp://+.
|
2020-04-15 18:48:45 +02:00
|
|
|
** +sftp+ for downloads of tarballs over SSH with sftp. Used by
|
|
|
|
|
default when +LIBFOO_SITE+ begins with +sftp://+.
|
2012-06-17 13:54:00 +02:00
|
|
|
** +svn+ for retrieving source code from a Subversion repository.
|
2014-12-19 08:12:33 +01:00
|
|
|
Used by default when +LIBFOO_SITE+ begins with +svn://+. When a
|
2012-06-17 13:54:00 +02:00
|
|
|
+http://+ Subversion repository URL is specified in
|
|
|
|
|
+LIBFOO_SITE+, one 'must' specify +LIBFOO_SITE_METHOD=svn+.
|
|
|
|
|
Buildroot performs a checkout which is preserved as a tarball in
|
|
|
|
|
the download cache; subsequent builds use the tarball instead of
|
|
|
|
|
performing another checkout.
|
2013-09-11 14:12:05 +02:00
|
|
|
** +cvs+ for retrieving source code from a CVS repository.
|
|
|
|
|
Used by default when +LIBFOO_SITE+ begins with +cvs://+.
|
|
|
|
|
The downloaded source code is cached as with the +svn+ method.
|
2016-01-15 21:13:15 +01:00
|
|
|
Anonymous pserver mode is assumed otherwise explicitly defined
|
|
|
|
|
on +LIBFOO_SITE+. Both
|
|
|
|
|
+LIBFOO_SITE=cvs://libfoo.net:/cvsroot/libfoo+ and
|
|
|
|
|
+LIBFOO_SITE=cvs://:ext:libfoo.net:/cvsroot/libfoo+
|
|
|
|
|
are accepted, on the former anonymous pserver access mode is
|
|
|
|
|
assumed.
|
2013-09-11 14:12:05 +02:00
|
|
|
+LIBFOO_SITE+ 'must' contain the source URL as well as the remote
|
|
|
|
|
repository directory. The module is the package name.
|
2015-05-06 14:17:49 +02:00
|
|
|
+LIBFOO_VERSION+ is 'mandatory' and 'must' be a tag, a branch, or
|
|
|
|
|
a date (e.g. "2014-10-20", "2014-10-20 13:45", "2014-10-20
|
|
|
|
|
13:45+01" see "man cvs" for further details).
|
2014-12-19 08:12:33 +01:00
|
|
|
** +git+ for retrieving source code from a Git repository. Used by
|
2012-06-17 13:54:00 +02:00
|
|
|
default when +LIBFOO_SITE+ begins with +git://+. The downloaded
|
2022-02-11 06:26:29 +01:00
|
|
|
source code is cached as with the +svn+ method.
|
2012-06-17 13:54:00 +02:00
|
|
|
** +hg+ for retrieving source code from a Mercurial repository. One
|
|
|
|
|
'must' specify +LIBFOO_SITE_METHOD=hg+ when +LIBFOO_SITE+
|
|
|
|
|
contains a Mercurial repository URL. The downloaded source code
|
|
|
|
|
is cached as with the +svn+ method.
|
|
|
|
|
** +bzr+ for retrieving source code from a Bazaar repository. Used
|
|
|
|
|
by default when +LIBFOO_SITE+ begins with +bzr://+. The
|
|
|
|
|
downloaded source code is cached as with the +svn+ method.
|
2014-12-19 08:12:33 +01:00
|
|
|
** +file+ for a local tarball. One should use this when
|
2012-06-17 13:54:01 +02:00
|
|
|
+LIBFOO_SITE+ specifies a package tarball as a local filename.
|
|
|
|
|
Useful for software that isn't available publicly or in version
|
|
|
|
|
control.
|
2014-12-19 08:12:33 +01:00
|
|
|
** +local+ for a local source code directory. One should use this
|
2012-06-17 13:54:01 +02:00
|
|
|
when +LIBFOO_SITE+ specifies a local directory path containing
|
2014-12-19 08:12:33 +01:00
|
|
|
the package source code. Buildroot copies the contents of the
|
2017-07-08 22:15:07 +02:00
|
|
|
source directory into the package's build directory. Note that
|
|
|
|
|
for +local+ packages, no patches are applied. If you need to
|
|
|
|
|
still patch the source code, use +LIBFOO_POST_RSYNC_HOOKS+, see
|
|
|
|
|
xref:hooks-rsync[].
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2017-02-07 12:08:17 +01:00
|
|
|
* +LIBFOO_GIT_SUBMODULES+ can be set to +YES+ to create an archive
|
|
|
|
|
with the git submodules in the repository. This is only available
|
|
|
|
|
for packages downloaded with git (i.e. when
|
|
|
|
|
+LIBFOO_SITE_METHOD=git+). Note that we try not to use such git
|
|
|
|
|
submodules when they contain bundled libraries, in which case we
|
|
|
|
|
prefer to use those libraries from their own package.
|
2016-07-03 10:33:09 +02:00
|
|
|
|
2020-01-21 21:33:37 +01:00
|
|
|
* +LIBFOO_GIT_LFS+ should be set to +YES+ if the Git repository uses
|
|
|
|
|
Git LFS to store large files out of band. This is only available for
|
|
|
|
|
packages downloaded with git (i.e. when +LIBFOO_SITE_METHOD=git+).
|
|
|
|
|
|
2023-09-17 22:59:16 +02:00
|
|
|
* +LIBFOO_SVN_EXTERNALS+ can be set to +YES+ to create an archive with
|
package/pkg-generic: don't download svn externals by default
Commit 7dd27cbe5b9e (support/download: add support to exclude svn
externals) departed from the usual opt-in scheme, like is done for
git submodule or large files, in an attempt to keep the previous
behaviour unchanged, that is to download externals by default.
As an afterthought, we've concluded that the chances for svn-hosted
packages with externals that are indeed required to do the build,
are relatively slim. For those cases, it even makes sense to explicitly
requested the use of the externals.
So, we change the default to not download svn externals.
Since the generated archives may change, we bump the version suffix.
This will allow users to more easily catch the situation and decide if
they really need the externals or not.
We have a single in-tree package that uses svn, and it does not use
externals, so the generated archive does not change, and we just need
to update the archive filename in the hash file.
Finally, we add a new section to the manual, in the chapter about
migrating Buildroot to a newer version.
Reported-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Signed-off-by: Yann E. MORIN <yann.morin.1998@free.fr>
2023-08-08 15:17:41 +02:00
|
|
|
the svn external references. This is only available for packages
|
|
|
|
|
downloaded with subversion.
|
support/download: add support to exclude svn externals
Like git which can have submodules, subversion can have externals. The
default behaviour for subversion is to retrieve all the externals,
unless told otherwise.
For some repositories, the externals may be huge (e.g. a dataset or some
assets) and may not be required for building the package. In such a
case, retrieving the externals is both a waste of network bandwitdh and
time, and a waste of disk storage.
Like for git submodules and git lfs, add an option that packages can set
to specify whether they want externals or not.
Since we've so far been retrieving externals, we keep that the default,
and packages can opt-out (rather than the opt-in for git submodules or
git lfs).
We must only set it when the package is actually hosted on svn, to avoid
passing -r when the package is not hosted by svn; otherwise, -r would
also be passed e.g. to a git-hosted package, triggering the download of
git submodules even when they are not requested. We need to do so,
because we have a default value, which we usually do not have in other
download options.
Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
2023-08-01 15:11:17 +02:00
|
|
|
|
2015-07-11 16:15:05 +02:00
|
|
|
* +LIBFOO_STRIP_COMPONENTS+ is the number of leading components
|
|
|
|
|
(directories) that tar must strip from file names on extraction.
|
|
|
|
|
The tarball for most packages has one leading component named
|
|
|
|
|
"<pkg-name>-<pkg-version>", thus Buildroot passes
|
|
|
|
|
--strip-components=1 to tar to remove it.
|
|
|
|
|
For non-standard packages that don't have this component, or
|
|
|
|
|
that have more than one leading component to strip, set this
|
|
|
|
|
variable with the value to be passed to tar. Default: 1.
|
|
|
|
|
|
2015-10-24 14:48:53 +02:00
|
|
|
* +LIBFOO_EXCLUDES+ is a space-separated list of patterns to exclude
|
|
|
|
|
when extracting the archive. Each item from that list is passed as
|
|
|
|
|
a tar's +--exclude+ option. By default, empty.
|
|
|
|
|
|
2011-10-10 10:46:39 +02:00
|
|
|
* +LIBFOO_DEPENDENCIES+ lists the dependencies (in terms of package
|
|
|
|
|
name) that are required for the current target package to
|
|
|
|
|
compile. These dependencies are guaranteed to be compiled and
|
2019-10-16 19:55:45 +02:00
|
|
|
installed before the configuration of the current package starts.
|
|
|
|
|
However, modifications to configuration of these dependencies will
|
|
|
|
|
not force a rebuild of the current package. In a similar way,
|
|
|
|
|
+HOST_LIBFOO_DEPENDENCIES+ lists the dependencies for the current
|
|
|
|
|
host package.
|
2011-10-10 10:46:39 +02:00
|
|
|
|
package/pkg-generic: add the concept of extract dependency
Extract dependencies are dependencies that must be ready before the
extract step of a package, i.e for tools that are needed to extract
packages themselves. Current examples of such tools are host-tar,
host-lzip and host-xz.
They are currently handled through DEPENDENCIES_HOST_PREREQ. However,
this mechanism has a number of drawbacks:
- First and foremost, because host-tar/host-lzip/host-xz are not
listed in the dependencies of packages, the package infrastructure
does not know it should rsync them in the context of per-package
SDK.
- Second, there is no dependency handling *between* them. I.e, we
have no mechanism that says host-tar should be built before
host-lzip, while it is in fact the case: if you need to build
host-lzip, you need to extract a tarball, so you may need host-tar
if your system tarball is not capable enough.
For those reasons, it makes sense to add explicit support for "extract
dependencies" in the package infrastructure, through the
<pkg>_EXTRACT_DEPENDENCIES variable. It is unlikely this variable will
ever be used by a package .mk file, but it will be used internally by
the package infrastructure.
[Peter: fix typo in manual]
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
Reviewed-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Tested-by: Matt Weber <matthew.weber@rockwellcollins.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2018-03-24 15:20:02 +01:00
|
|
|
* +LIBFOO_EXTRACT_DEPENDENCIES+ lists the dependencies (in terms of
|
|
|
|
|
package name) that are required for the current target package to be
|
|
|
|
|
extracted. These dependencies are guaranteed to be compiled and
|
|
|
|
|
installed before the extract step of the current package
|
|
|
|
|
starts. This is only used internally by the package infrastructure,
|
|
|
|
|
and should typically not be used directly by packages.
|
|
|
|
|
|
2015-03-14 15:25:18 +01:00
|
|
|
* +LIBFOO_PATCH_DEPENDENCIES+ lists the dependencies (in terms of
|
|
|
|
|
package name) that are required for the current package to be
|
|
|
|
|
patched. These dependencies are guaranteed to be extracted and
|
2020-02-21 06:34:42 +01:00
|
|
|
patched (but not necessarily built) before the current package is
|
|
|
|
|
patched. In a similar way, +HOST_LIBFOO_PATCH_DEPENDENCIES+ lists
|
|
|
|
|
the dependencies for the current host package.
|
2015-03-14 15:25:18 +01:00
|
|
|
This is seldom used; usually, +LIBFOO_DEPENDENCIES+ is what you
|
|
|
|
|
really want to use.
|
|
|
|
|
|
2014-05-15 19:37:04 +02:00
|
|
|
* +LIBFOO_PROVIDES+ lists all the virtual packages +libfoo+ is an
|
|
|
|
|
implementation of. See xref:virtual-package-tutorial[].
|
|
|
|
|
|
2011-10-10 10:46:39 +02:00
|
|
|
* +LIBFOO_INSTALL_STAGING+ can be set to +YES+ or +NO+ (default). If
|
|
|
|
|
set to +YES+, then the commands in the +LIBFOO_INSTALL_STAGING_CMDS+
|
|
|
|
|
variables are executed to install the package into the staging
|
|
|
|
|
directory.
|
|
|
|
|
|
|
|
|
|
* +LIBFOO_INSTALL_TARGET+ can be set to +YES+ (default) or +NO+. If
|
|
|
|
|
set to +YES+, then the commands in the +LIBFOO_INSTALL_TARGET_CMDS+
|
|
|
|
|
variables are executed to install the package into the target
|
|
|
|
|
directory.
|
|
|
|
|
|
2015-01-01 21:23:49 +01:00
|
|
|
* +LIBFOO_INSTALL_IMAGES+ can be set to +YES+ or +NO+ (default). If
|
|
|
|
|
set to +YES+, then the commands in the +LIBFOO_INSTALL_IMAGES_CMDS+
|
|
|
|
|
variable are executed to install the package into the images
|
|
|
|
|
directory.
|
|
|
|
|
|
2013-02-07 13:35:03 +01:00
|
|
|
* +LIBFOO_CONFIG_SCRIPTS+ lists the names of the files in
|
2013-01-30 03:46:40 +01:00
|
|
|
'$(STAGING_DIR)/usr/bin' that need some special fixing to make them
|
2013-02-07 13:35:03 +01:00
|
|
|
cross-compiling friendly. Multiple file names separated by space can
|
2013-02-07 13:35:04 +01:00
|
|
|
be given and all are relative to '$(STAGING_DIR)/usr/bin'. The files
|
|
|
|
|
listed in +LIBFOO_CONFIG_SCRIPTS+ are also removed from
|
|
|
|
|
+$(TARGET_DIR)/usr/bin+ since they are not needed on the target.
|
2013-01-30 03:46:40 +01:00
|
|
|
|
2012-01-11 18:53:41 +01:00
|
|
|
* +LIBFOO_DEVICES+ lists the device files to be created by Buildroot
|
|
|
|
|
when using the static device table. The syntax to use is the
|
2012-02-18 00:30:58 +01:00
|
|
|
makedevs one. You can find some documentation for this syntax in the
|
|
|
|
|
xref:makedev-syntax[]. This variable is optional.
|
2012-01-11 18:53:41 +01:00
|
|
|
|
|
|
|
|
* +LIBFOO_PERMISSIONS+ lists the changes of permissions to be done at
|
|
|
|
|
the end of the build process. The syntax is once again the makedevs one.
|
2012-02-18 00:30:58 +01:00
|
|
|
You can find some documentation for this syntax in the xref:makedev-syntax[].
|
|
|
|
|
This variable is optional.
|
2012-01-11 18:53:41 +01:00
|
|
|
|
2013-04-12 09:14:18 +02:00
|
|
|
* +LIBFOO_USERS+ lists the users to create for this package, if it installs
|
2014-03-28 22:24:49 +01:00
|
|
|
a program you want to run as a specific user (e.g. as a daemon, or as a
|
2013-04-12 09:14:18 +02:00
|
|
|
cron-job). The syntax is similar in spirit to the makedevs one, and is
|
|
|
|
|
described in the xref:makeuser-syntax[]. This variable is optional.
|
|
|
|
|
|
2012-05-17 19:33:07 +02:00
|
|
|
* +LIBFOO_LICENSE+ defines the license (or licenses) under which the package
|
|
|
|
|
is released.
|
|
|
|
|
This name will appear in the manifest file produced by +make legal-info+.
|
2017-03-30 15:43:30 +02:00
|
|
|
If the license appears in https://spdx.org/licenses/[the SPDX License List],
|
|
|
|
|
use the SPDX short identifier to make the manifest file uniform.
|
2012-05-17 19:33:07 +02:00
|
|
|
Otherwise, describe the license in a precise and concise way, avoiding
|
|
|
|
|
ambiguous names such as +BSD+ which actually name a family of licenses.
|
|
|
|
|
This variable is optional. If it is not defined, +unknown+ will appear in
|
2016-01-25 06:05:40 +01:00
|
|
|
the +license+ field of the manifest file for this package. +
|
|
|
|
|
The expected format for this variable must comply with the following rules:
|
|
|
|
|
** If different parts of the package are released under different
|
2019-10-26 10:45:53 +02:00
|
|
|
licenses, then +comma+ separate licenses (e.g. +`LIBFOO_LICENSE =
|
|
|
|
|
GPL-2.0+, LGPL-2.1+`+). If there is clear distinction between which
|
|
|
|
|
component is licensed under what license, then annotate the license
|
|
|
|
|
with that component, between parenthesis (e.g. +`LIBFOO_LICENSE =
|
|
|
|
|
GPL-2.0+ (programs), LGPL-2.1+ (libraries)`+).
|
|
|
|
|
** If some licenses are conditioned on a sub-option being enabled, append
|
|
|
|
|
the conditional licenses with a comma (e.g.: `FOO_LICENSE += , GPL-2.0+
|
|
|
|
|
(programs)`); the infrastructure will internally remove the space before
|
|
|
|
|
the comma.
|
2016-01-25 06:05:40 +01:00
|
|
|
** If the package is dual licensed, then separate licenses with the
|
2019-10-26 10:45:53 +02:00
|
|
|
+or+ keyword (e.g. +`LIBFOO_LICENSE = AFL-2.1 or GPL-2.0+`+).
|
2012-05-17 19:33:07 +02:00
|
|
|
|
|
|
|
|
* +LIBFOO_LICENSE_FILES+ is a space-separated list of files in the package
|
|
|
|
|
tarball that contain the license(s) under which the package is released.
|
|
|
|
|
+make legal-info+ copies all of these files in the +legal-info+ directory.
|
|
|
|
|
See xref:legal-info[] for more information.
|
|
|
|
|
This variable is optional. If it is not defined, a warning will be produced
|
|
|
|
|
to let you know, and +not saved+ will appear in the +license files+ field
|
|
|
|
|
of the manifest file for this package.
|
|
|
|
|
|
2015-10-03 23:18:21 +02:00
|
|
|
* +LIBFOO_ACTUAL_SOURCE_TARBALL+ only applies to packages whose
|
2020-06-06 14:36:38 +02:00
|
|
|
+LIBFOO_SITE+ / +LIBFOO_SOURCE+ pair points to an archive that does
|
2015-10-03 23:18:21 +02:00
|
|
|
not actually contain source code, but binary code. This a very
|
|
|
|
|
uncommon case, only known to apply to external toolchains which come
|
|
|
|
|
already compiled, although theoretically it might apply to other
|
|
|
|
|
packages. In such cases a separate tarball is usually available with
|
|
|
|
|
the actual source code. Set +LIBFOO_ACTUAL_SOURCE_TARBALL+ to the
|
|
|
|
|
name of the actual source code archive and Buildroot will download
|
|
|
|
|
it and use it when you run +make legal-info+ to collect
|
|
|
|
|
legally-relevant material. Note this file will not be downloaded
|
|
|
|
|
during regular builds nor by +make source+.
|
|
|
|
|
|
|
|
|
|
* +LIBFOO_ACTUAL_SOURCE_SITE+ provides the location of the actual
|
|
|
|
|
source tarball. The default value is +LIBFOO_SITE+, so you don't
|
|
|
|
|
need to set this variable if the binary and source archives are
|
|
|
|
|
hosted on the same directory. If +LIBFOO_ACTUAL_SOURCE_TARBALL+ is
|
|
|
|
|
not set, it doesn't make sense to define
|
|
|
|
|
+LIBFOO_ACTUAL_SOURCE_SITE+.
|
|
|
|
|
|
2012-11-27 12:59:17 +01:00
|
|
|
* +LIBFOO_REDISTRIBUTE+ can be set to +YES+ (default) or +NO+ to indicate if
|
|
|
|
|
the package source code is allowed to be redistributed. Set it to +NO+ for
|
|
|
|
|
non-opensource packages: Buildroot will not save the source code for this
|
|
|
|
|
package when collecting the +legal-info+.
|
|
|
|
|
|
2013-06-06 00:47:30 +02:00
|
|
|
* +LIBFOO_FLAT_STACKSIZE+ defines the stack size of an application built into
|
|
|
|
|
the FLAT binary format. The application stack size on the NOMMU architecture
|
|
|
|
|
processors can't be enlarged at run time. The default stack size for the
|
|
|
|
|
FLAT binary format is only 4k bytes. If the application consumes more stack,
|
|
|
|
|
append the required number here.
|
|
|
|
|
|
2018-03-07 22:51:23 +01:00
|
|
|
* +LIBFOO_BIN_ARCH_EXCLUDE+ is a space-separated list of paths (relative
|
|
|
|
|
to the target directory) to ignore when checking that the package
|
|
|
|
|
installs correctly cross-compiled binaries. You seldom need to set this
|
|
|
|
|
variable, unless the package installs binary blobs outside the default
|
2018-03-07 22:51:24 +01:00
|
|
|
locations, `/lib/firmware`, `/usr/lib/firmware`, `/lib/modules`,
|
|
|
|
|
`/usr/lib/modules`, and `/usr/share`, which are automatically excluded.
|
2018-03-07 22:51:23 +01:00
|
|
|
|
2020-02-15 13:44:17 +01:00
|
|
|
* +LIBFOO_IGNORE_CVES+ is a space-separated list of CVEs that tells
|
|
|
|
|
Buildroot CVE tracking tools which CVEs should be ignored for this
|
|
|
|
|
package. This is typically used when the CVE is fixed by a patch in
|
|
|
|
|
the package, or when the CVE for some reason does not affect the
|
|
|
|
|
Buildroot package. A Makefile comment must always precede the
|
|
|
|
|
addition of a CVE to this variable. Example:
|
2024-02-10 22:24:56 +01:00
|
|
|
+
|
2020-02-15 13:44:17 +01:00
|
|
|
----------------------
|
|
|
|
|
# 0001-fix-cve-2020-12345.patch
|
|
|
|
|
LIBFOO_IGNORE_CVES += CVE-2020-12345
|
|
|
|
|
# only when built with libbaz, which Buildroot doesn't support
|
|
|
|
|
LIBFOO_IGNORE_CVES += CVE-2020-54321
|
|
|
|
|
----------------------
|
|
|
|
|
|
2024-02-10 22:24:59 +01:00
|
|
|
* [[cpe-id]] +LIBFOO_CPE_ID_*+ variables is a set of variables that allows the
|
2020-11-04 15:51:38 +01:00
|
|
|
package to define its https://nvd.nist.gov/products/cpe[CPE
|
|
|
|
|
identifier]. The available variables are:
|
|
|
|
|
+
|
|
|
|
|
--
|
doc/manual: document _CPE_ID_VALID
The way we handle CPE_ID variable is unusual compared to the other
variables: we mostly compute defaults for all of them, and eventually
aggregate the various CPE_ID variables to form the CPE ID name.
However, we do not consider that CPE ID to valid, unless there is one
(or more) CPE_ID variables actually set by the package; this shows that
the CPE ID has been checked to be valid against the NVD CPE database. In
that situation, we internally define the duly undocumented _CPE_ID_VALID
variable.
However, it is totally possible (and very often the case) that the
default value we set to those variables are appropriate, and do defne a
valid CPE ID. In this case, the package will define any arbitrary CPE_ID
variable to its default value, usually by setting either the VENDOR or
PRODUCT field, though there is no rule or requirement that be the case.
This is not very clean, non-obvious, and does not allow for easily
adding checks in check-package.
Add the _CPE_ID_VALID variable to the manual, to make it official that
it should be used when the default values of the others are valid.
Signed-off-by: Yann E. MORIN <yann.morin.1998@free.fr>
Cc: Fabrice Fontaine <fontaine.fabrice@gmail.com>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
2024-02-10 22:24:57 +01:00
|
|
|
** +LIBFOO_CPE_ID_VALID+, if set to +YES+, specifies that the default
|
|
|
|
|
values for each of the following variables is appropriate, and
|
|
|
|
|
generates a valid CPE ID.
|
|
|
|
|
|
2020-11-04 15:51:38 +01:00
|
|
|
** +LIBFOO_CPE_ID_PREFIX+, specifies the prefix of the CPE identifier,
|
|
|
|
|
i.e the first three fields. When not defined, the default value is
|
|
|
|
|
+cpe:2.3:a+.
|
|
|
|
|
|
|
|
|
|
** +LIBFOO_CPE_ID_VENDOR+, specifies the vendor part of the CPE
|
|
|
|
|
identifier. When not defined, the default value is
|
|
|
|
|
+<pkgname>_project+.
|
|
|
|
|
|
2021-01-18 18:41:50 +01:00
|
|
|
** +LIBFOO_CPE_ID_PRODUCT+, specifies the product part of the CPE
|
2020-11-04 15:51:38 +01:00
|
|
|
identifier. When not defined, the default value is +<pkgname>+.
|
|
|
|
|
|
|
|
|
|
** +LIBFOO_CPE_ID_VERSION+, specifies the version part of the CPE
|
|
|
|
|
identifier. When not defined the default value is
|
|
|
|
|
+$(LIBFOO_VERSION)+.
|
|
|
|
|
|
2021-01-29 18:56:40 +01:00
|
|
|
** +LIBFOO_CPE_ID_UPDATE+ specifies the _update_ part of the CPE
|
|
|
|
|
identifier. When not defined the default value is +*+.
|
2020-11-04 15:51:38 +01:00
|
|
|
--
|
|
|
|
|
+
|
|
|
|
|
If any of those variables is defined, then the generic package
|
|
|
|
|
infrastructure assumes the package provides valid CPE information. In
|
2021-03-05 23:27:42 +01:00
|
|
|
this case, the generic package infrastructure will define
|
|
|
|
|
+LIBFOO_CPE_ID+.
|
2020-11-04 15:51:38 +01:00
|
|
|
+
|
|
|
|
|
For a host package, if its +LIBFOO_CPE_ID_*+ variables are not
|
|
|
|
|
defined, it inherits the value of those variables from the
|
|
|
|
|
corresponding target package.
|
|
|
|
|
|
2011-10-10 10:46:39 +02:00
|
|
|
The recommended way to define these variables is to use the following
|
|
|
|
|
syntax:
|
|
|
|
|
|
|
|
|
|
----------------------
|
|
|
|
|
LIBFOO_VERSION = 2.32
|
|
|
|
|
----------------------
|
|
|
|
|
|
|
|
|
|
Now, the variables that define what should be performed at the
|
|
|
|
|
different steps of the build process.
|
|
|
|
|
|
2013-08-06 23:36:20 +02:00
|
|
|
* +LIBFOO_EXTRACT_CMDS+ lists the actions to be performed to extract
|
|
|
|
|
the package. This is generally not needed as tarballs are
|
|
|
|
|
automatically handled by Buildroot. However, if the package uses a
|
|
|
|
|
non-standard archive format, such as a ZIP or RAR file, or has a
|
|
|
|
|
tarball with a non-standard organization, this variable allows to
|
|
|
|
|
override the package infrastructure default behavior.
|
|
|
|
|
|
2012-11-27 12:59:16 +01:00
|
|
|
* +LIBFOO_CONFIGURE_CMDS+ lists the actions to be performed to
|
|
|
|
|
configure the package before its compilation.
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2012-11-27 12:59:16 +01:00
|
|
|
* +LIBFOO_BUILD_CMDS+ lists the actions to be performed to
|
|
|
|
|
compile the package.
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2012-11-27 12:59:16 +01:00
|
|
|
* +HOST_LIBFOO_INSTALL_CMDS+ lists the actions to be performed
|
2011-10-10 10:46:39 +02:00
|
|
|
to install the package, when the package is a host package. The
|
|
|
|
|
package must install its files to the directory given by
|
|
|
|
|
+$(HOST_DIR)+. All files, including development files such as
|
|
|
|
|
headers should be installed, since other packages might be compiled
|
|
|
|
|
on top of this package.
|
|
|
|
|
|
2012-11-27 12:59:16 +01:00
|
|
|
* +LIBFOO_INSTALL_TARGET_CMDS+ lists the actions to be
|
2011-10-10 10:46:39 +02:00
|
|
|
performed to install the package to the target directory, when the
|
|
|
|
|
package is a target package. The package must install its files to
|
|
|
|
|
the directory given by +$(TARGET_DIR)+. Only the files required for
|
2012-11-27 12:59:17 +01:00
|
|
|
'execution' of the package have to be
|
|
|
|
|
installed. Header files, static libraries and documentation will be
|
|
|
|
|
removed again when the target filesystem is finalized.
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2012-11-27 12:59:16 +01:00
|
|
|
* +LIBFOO_INSTALL_STAGING_CMDS+ lists the actions to be
|
2011-10-10 10:46:39 +02:00
|
|
|
performed to install the package to the staging directory, when the
|
|
|
|
|
package is a target package. The package must install its files to
|
|
|
|
|
the directory given by +$(STAGING_DIR)+. All development files
|
|
|
|
|
should be installed, since they might be needed to compile other
|
|
|
|
|
packages.
|
|
|
|
|
|
2014-05-09 02:20:11 +02:00
|
|
|
* +LIBFOO_INSTALL_IMAGES_CMDS+ lists the actions to be performed to
|
|
|
|
|
install the package to the images directory, when the package is a
|
|
|
|
|
target package. The package must install its files to the directory
|
|
|
|
|
given by +$(BINARIES_DIR)+. Only files that are binary images (aka
|
|
|
|
|
images) that do not belong in the +TARGET_DIR+ but are necessary
|
|
|
|
|
for booting the board should be placed here. For example, a package
|
|
|
|
|
should utilize this step if it has binaries which would be similar
|
|
|
|
|
to the kernel image, bootloader or root filesystem images.
|
|
|
|
|
|
2019-05-12 21:55:42 +02:00
|
|
|
* +LIBFOO_INSTALL_INIT_SYSV+, +LIBFOO_INSTALL_INIT_OPENRC+ and
|
|
|
|
|
+LIBFOO_INSTALL_INIT_SYSTEMD+ list the actions to install init
|
|
|
|
|
scripts either for the systemV-like init systems (busybox,
|
|
|
|
|
sysvinit, etc.), openrc or for the systemd units. These commands
|
|
|
|
|
will be run only when the relevant init system is installed (i.e.
|
|
|
|
|
if systemd is selected as the init system in the configuration,
|
2019-08-04 14:14:15 +02:00
|
|
|
only +LIBFOO_INSTALL_INIT_SYSTEMD+ will be run). The only exception
|
|
|
|
|
is when openrc is chosen as init system and +LIBFOO_INSTALL_INIT_OPENRC+
|
|
|
|
|
has not been set, in such situation +LIBFOO_INSTALL_INIT_SYSV+ will
|
|
|
|
|
be called, since openrc supports sysv init scripts.
|
2019-12-16 11:30:41 +01:00
|
|
|
When systemd is used as the init system, buildroot will automatically enable
|
|
|
|
|
all services using the +systemctl preset-all+ command in the final phase of
|
|
|
|
|
image building. You can add preset files to prevent a particular unit from
|
|
|
|
|
being automatically enabled by buildroot.
|
2012-07-28 09:21:22 +02:00
|
|
|
|
2016-06-04 18:30:47 +02:00
|
|
|
* +LIBFOO_HELP_CMDS+ lists the actions to print the package help, which
|
|
|
|
|
is included to the main +make help+ output. These commands can print
|
|
|
|
|
anything in any format.
|
|
|
|
|
This is seldom used, as packages rarely have custom rules. *Do not use
|
|
|
|
|
this variable*, unless you really know that you need to print help.
|
|
|
|
|
|
linux: allow packages to set kernel config options
Currently, the linux kernel will apply some fixups on its .config file,
based on whether some packages are enabled or not. That list of
conditional fixups is getting bigger and bigger with each new package
that needs such fixups, culminating with the pending firewalld one [0].
Furthermore, these fixups are not accessible to packages in br2-external
trees.
Add a new per-package variable, that packages may set to the commands to
run to fixup the kernel .config file, which is added at the end of the
linux' own fixups.
This opens the possibility to write things like;
define FOO_LINUX_CONFIG_FIXUPS
$(call KCONFIG_ENABLE_OPT,BLA)
endef
Of course, it also opens the way to run arbitrary commands in there, but
any alternative that would be declarative only, such as a list of
options to enable or disable (as an example):
FOO_LINUX_CONFIG_FIXUPS = +BAR -FOO +BUZ="value"
.. is not very nice either, and such lists fall flat when a value would
have a space.
For packages that we have in-tree, we can ensure they won't play foul
with their _LINUX_CONFIG_FIXUPS. For packages in br2-external trees,
there's nothing we can do; users already have the opportunity to hack
into the linux configure process by providing LINUX_PRE_CONFIGURE_HOOKS
or LINUX_POST_CONFIGURE_HOOKS anyway...
.. which brings the question of why we don't use that to implement the
per-package fixups. We don't, because _PRE or _POST_CONFIGURE_HOOKS are
run after we run 'make oldconfig' to sanitise the mangled .config.
[0] http://lists.busybox.net/pipermail/buildroot/2020-March/278683.html
Signed-off-by: Yann E. MORIN <yann.morin.1998@free.fr>
Cc: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Cc: Peter Korsgaard <peter@korsgaard.com>
Cc: Adam Duskett <aduskett@gmail.com>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
2020-04-04 14:10:21 +02:00
|
|
|
* +LIBFOO_LINUX_CONFIG_FIXUPS+ lists the Linux kernel configuration
|
|
|
|
|
options that are needed to build and use this package, and without
|
|
|
|
|
which the package is fundamentally broken. This shall be a set of
|
|
|
|
|
calls to one of the kconfig tweaking option: `KCONFIG_ENABLE_OPT`,
|
|
|
|
|
`KCONFIG_DISABLE_OPT`, or `KCONFIG_SET_OPT`.
|
|
|
|
|
This is seldom used, as package usually have no strict requirements on
|
|
|
|
|
the kernel options.
|
|
|
|
|
|
2011-10-10 10:46:39 +02:00
|
|
|
The preferred way to define these variables is:
|
|
|
|
|
|
|
|
|
|
----------------------
|
|
|
|
|
define LIBFOO_CONFIGURE_CMDS
|
|
|
|
|
action 1
|
|
|
|
|
action 2
|
|
|
|
|
action 3
|
|
|
|
|
endef
|
|
|
|
|
----------------------
|
|
|
|
|
|
|
|
|
|
In the action definitions, you can use the following variables:
|
|
|
|
|
|
2016-12-02 03:41:52 +01:00
|
|
|
* +$(LIBFOO_PKGDIR)+ contains the path to the directory containing the
|
|
|
|
|
+libfoo.mk+ and +Config.in+ files. This variable is useful when it is
|
2015-11-04 23:11:23 +01:00
|
|
|
necessary to install a file bundled in Buildroot, like a runtime
|
2015-11-05 00:10:50 +01:00
|
|
|
configuration file, a splashscreen image...
|
2015-11-04 23:11:23 +01:00
|
|
|
|
2011-10-10 10:46:39 +02:00
|
|
|
* +$(@D)+, which contains the directory in which the package source
|
|
|
|
|
code has been uncompressed.
|
|
|
|
|
|
2018-04-02 16:57:59 +02:00
|
|
|
* +$(LIBFOO_DL_DIR)+ contains the path to the directory where all the downloads
|
|
|
|
|
made by Buildroot for +libfoo+ are stored in.
|
2017-07-04 11:40:38 +02:00
|
|
|
|
2011-10-10 10:46:39 +02:00
|
|
|
* +$(TARGET_CC)+, +$(TARGET_LD)+, etc. to get the target
|
|
|
|
|
cross-compilation utilities
|
|
|
|
|
|
|
|
|
|
* +$(TARGET_CROSS)+ to get the cross-compilation toolchain prefix
|
|
|
|
|
|
|
|
|
|
* Of course the +$(HOST_DIR)+, +$(STAGING_DIR)+ and +$(TARGET_DIR)+
|
2019-11-05 17:46:45 +01:00
|
|
|
variables to install the packages properly. Those variables point to
|
|
|
|
|
the global _host_, _staging_ and _target_ directories, unless
|
|
|
|
|
_per-package directory_ support is used, in which case they point to
|
|
|
|
|
the current package _host_, _staging_ and _target_ directories. In
|
|
|
|
|
both cases, it doesn't make any difference from the package point of
|
|
|
|
|
view: it should simply use +HOST_DIR+, +STAGING_DIR+ and
|
|
|
|
|
+TARGET_DIR+. See xref:top-level-parallel-build[] for more details
|
|
|
|
|
about _per-package directory_ support.
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2013-11-07 11:41:23 +01:00
|
|
|
Finally, you can also use hooks. See xref:hooks[] for more information.
|
