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
|
|
|
=== Package directory
|
2011-10-10 10:46:39 +02:00
|
|
|
|
|
|
|
|
First of all, create a directory under the +package+ directory for
|
|
|
|
|
your software, for example +libfoo+.
|
|
|
|
|
|
|
|
|
|
Some packages have been grouped by topic in a sub-directory:
|
2013-09-18 11:01:35 +02:00
|
|
|
+x11r7+, +efl+ and +matchbox+. If your package fits in
|
2011-10-10 10:46:39 +02:00
|
|
|
one of these categories, then create your package directory in these.
|
2012-11-27 12:59:17 +01:00
|
|
|
New subdirectories are discouraged, however.
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2012-03-18 09:54:02 +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
|
|
|
=== +Config.in+ file
|
2011-10-10 10:46:39 +02:00
|
|
|
|
|
|
|
|
Then, create a file named +Config.in+. This file will contain the
|
|
|
|
|
option descriptions related to our +libfoo+ software that will be used
|
2012-03-18 09:54:02 +01:00
|
|
|
and displayed in the configuration tool. It should basically contain:
|
2011-10-10 10:46:39 +02:00
|
|
|
|
|
|
|
|
---------------------------
|
|
|
|
|
config BR2_PACKAGE_LIBFOO
|
|
|
|
|
bool "libfoo"
|
|
|
|
|
help
|
|
|
|
|
This is a comment that explains what libfoo is.
|
|
|
|
|
|
|
|
|
|
http://foosoftware.org/libfoo/
|
|
|
|
|
---------------------------
|
|
|
|
|
|
2014-06-02 18:02:45 +02:00
|
|
|
The +bool+ line, +help+ line and other metadata information about the
|
2011-11-13 09:54:44 +01:00
|
|
|
configuration option must be indented with one tab. The help text
|
|
|
|
|
itself should be indented with one tab and two spaces, and it must
|
|
|
|
|
mention the upstream URL of the project.
|
|
|
|
|
|
2012-11-27 12:59:17 +01:00
|
|
|
You can add other sub-options into a +if
|
2011-11-13 09:54:43 +01:00
|
|
|
BR2_PACKAGE_LIBFOO...endif+ statement to configure particular things
|
|
|
|
|
in your software. You can look at examples in other packages. The
|
|
|
|
|
syntax of the +Config.in+ file is the same as the one for the kernel
|
|
|
|
|
Kconfig file. The documentation for this syntax is available at
|
2012-11-27 12:59:17 +01:00
|
|
|
http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt[]
|
2011-10-10 10:46:39 +02:00
|
|
|
|
|
|
|
|
Finally you have to add your new +libfoo/Config.in+ to
|
|
|
|
|
+package/Config.in+ (or in a category subdirectory if you decided to
|
|
|
|
|
put your package in one of the existing categories). The files
|
|
|
|
|
included there are 'sorted alphabetically' per category and are 'NOT'
|
|
|
|
|
supposed to contain anything but the 'bare' name of the package.
|
|
|
|
|
|
|
|
|
|
--------------------------
|
|
|
|
|
source "package/libfoo/Config.in"
|
|
|
|
|
--------------------------
|
|
|
|
|
|
2012-11-11 04:14:47 +01:00
|
|
|
[[depends-on-vs-select]]
|
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
|
|
|
==== Choosing +depends on+ or +select+
|
2012-11-27 12:59:20 +01:00
|
|
|
|
2011-11-13 09:54:45 +01:00
|
|
|
The +Config.in+ file of your package must also ensure that
|
|
|
|
|
dependencies are enabled. Typically, Buildroot uses the following
|
|
|
|
|
rules:
|
|
|
|
|
|
|
|
|
|
* Use a +select+ type of dependency for dependencies on
|
|
|
|
|
libraries. These dependencies are generally not obvious and it
|
|
|
|
|
therefore make sense to have the kconfig system ensure that the
|
|
|
|
|
dependencies are selected. For example, the _libgtk2_ package uses
|
|
|
|
|
+select BR2_PACKAGE_LIBGLIB2+ to make sure this library is also
|
|
|
|
|
enabled.
|
2013-09-18 11:01:34 +02:00
|
|
|
The +select+ keyword expresses the dependency with a backward
|
2012-11-11 04:14:47 +01:00
|
|
|
semantic.
|
2011-11-13 09:54:45 +01:00
|
|
|
|
|
|
|
|
* Use a +depends on+ type of dependency when the user really needs to
|
|
|
|
|
be aware of the dependency. Typically, Buildroot uses this type of
|
2013-10-13 16:55:31 +02:00
|
|
|
dependency for dependencies on target architecture, MMU support and
|
|
|
|
|
toolchain options (see xref:dependencies-target-toolchain-options[]),
|
|
|
|
|
or for dependencies on "big" things, such as the X.org system.
|
2013-09-18 11:01:34 +02:00
|
|
|
The +depends on+ keyword expresses the dependency with a forward
|
2012-11-11 04:14:47 +01:00
|
|
|
semantic.
|
|
|
|
|
|
|
|
|
|
.Note
|
|
|
|
|
The current problem with the _kconfig_ language is that these two
|
|
|
|
|
dependency semantics are not internally linked. Therefore, it may be
|
|
|
|
|
possible to select a package, whom one of its dependencies/requirement
|
|
|
|
|
is not met.
|
2011-11-13 09:54:45 +01:00
|
|
|
|
|
|
|
|
An example illustrates both the usage of +select+ and +depends on+.
|
|
|
|
|
|
|
|
|
|
--------------------------
|
|
|
|
|
config BR2_PACKAGE_ACL
|
|
|
|
|
bool "acl"
|
|
|
|
|
select BR2_PACKAGE_ATTR
|
|
|
|
|
depends on BR2_LARGEFILE
|
|
|
|
|
help
|
|
|
|
|
POSIX Access Control Lists, which are used to define more
|
|
|
|
|
fine-grained discretionary access rights for files and
|
|
|
|
|
directories.
|
|
|
|
|
This package also provides libacl.
|
|
|
|
|
|
|
|
|
|
http://savannah.nongnu.org/projects/acl
|
|
|
|
|
|
2013-10-13 16:55:31 +02:00
|
|
|
comment "acl needs a toolchain w/ largefile"
|
2011-11-13 09:54:45 +01:00
|
|
|
depends on !BR2_LARGEFILE
|
|
|
|
|
--------------------------
|
|
|
|
|
|
|
|
|
|
|
2012-03-18 09:54:03 +01:00
|
|
|
Note that these two dependency types are only transitive with the
|
|
|
|
|
dependencies of the same kind.
|
|
|
|
|
|
|
|
|
|
This means, in the following example:
|
|
|
|
|
|
|
|
|
|
--------------------------
|
|
|
|
|
config BR2_PACKAGE_A
|
|
|
|
|
bool "Package A"
|
|
|
|
|
|
|
|
|
|
config BR2_PACKAGE_B
|
|
|
|
|
bool "Package B"
|
|
|
|
|
depends on BR2_PACKAGE_A
|
|
|
|
|
|
|
|
|
|
config BR2_PACKAGE_C
|
|
|
|
|
bool "Package C"
|
|
|
|
|
depends on BR2_PACKAGE_B
|
|
|
|
|
|
|
|
|
|
config BR2_PACKAGE_D
|
|
|
|
|
bool "Package D"
|
|
|
|
|
select BR2_PACKAGE_B
|
|
|
|
|
|
|
|
|
|
config BR2_PACKAGE_E
|
|
|
|
|
bool "Package E"
|
|
|
|
|
select BR2_PACKAGE_D
|
|
|
|
|
--------------------------
|
|
|
|
|
|
|
|
|
|
* Selecting +Package C+ will be visible if +Package B+ has been
|
|
|
|
|
selected, which in turn is only visible if +Package A+ has been
|
|
|
|
|
selected.
|
|
|
|
|
|
|
|
|
|
* Selecting +Package E+ will select +Package D+, which will select
|
|
|
|
|
+Package B+, it will not check for the dependencies of +Package B+,
|
|
|
|
|
so it will not select +Package A+.
|
|
|
|
|
|
|
|
|
|
* Since +Package B+ is selected but +Package A+ is not, this violates
|
|
|
|
|
the dependency of +Package B+ on +Package A+. Therefore, in such a
|
|
|
|
|
situation, the transitive dependency has to be added explicitly:
|
|
|
|
|
|
|
|
|
|
--------------------------
|
|
|
|
|
config BR2_PACKAGE_D
|
|
|
|
|
bool "Package D"
|
|
|
|
|
select BR2_PACKAGE_B
|
|
|
|
|
depends on BR2_PACKAGE_A
|
|
|
|
|
|
|
|
|
|
config BR2_PACKAGE_E
|
|
|
|
|
bool "Package E"
|
|
|
|
|
select BR2_PACKAGE_D
|
|
|
|
|
depends on BR2_PACKAGE_A
|
|
|
|
|
--------------------------
|
|
|
|
|
|
|
|
|
|
Overall, for package library dependencies, +select+ should be
|
|
|
|
|
preferred.
|
|
|
|
|
|
2012-11-16 05:54:19 +01:00
|
|
|
Note that such dependencies will ensure that the dependency option
|
2011-11-13 09:54:45 +01:00
|
|
|
is also enabled, but not necessarily built before your package. To do
|
|
|
|
|
so, the dependency also needs to be expressed in the +.mk+ file of the
|
|
|
|
|
package.
|
|
|
|
|
|
2012-11-16 05:54:19 +01:00
|
|
|
Further formatting details: see xref:writing-rules-config-in[the
|
2012-11-27 12:59:17 +01:00
|
|
|
coding style].
|
2012-11-11 04:14:47 +01:00
|
|
|
|
2013-10-13 16:55:31 +02:00
|
|
|
[[dependencies-target-toolchain-options]]
|
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
|
|
|
==== Dependencies on target and toolchain options
|
|
|
|
|
|
2013-10-13 16:55:31 +02:00
|
|
|
Many packages depend on certain options of the toolchain: the choice of
|
|
|
|
|
C library, C++ support, largefile support, thread support, RPC support,
|
|
|
|
|
IPv6 support, wchar support, or dynamic library support. Some packages
|
|
|
|
|
can only be built on certain target architectures, or if an MMU is
|
|
|
|
|
available in the processor.
|
2013-11-07 09:24:36 +01:00
|
|
|
|
|
|
|
|
These dependencies have to be expressed with the appropriate 'depends
|
|
|
|
|
on' statements in the Config.in file. Additionally, for dependencies on
|
2013-10-13 16:55:31 +02:00
|
|
|
toolchain options, a +comment+ should be displayed when the option is
|
|
|
|
|
not enabled, so that the user knows why the package is not available.
|
|
|
|
|
Dependencies on target architecture or MMU support should not be
|
|
|
|
|
made visible in a comment: since it is unlikely that the user can
|
|
|
|
|
freely choose another target, it makes little sense to show these
|
|
|
|
|
dependencies explicitly.
|
|
|
|
|
|
2013-11-07 09:24:36 +01:00
|
|
|
The +comment+ should only be visible if the +config+ option itself would
|
|
|
|
|
be visible when the toolchain option dependencies are met. This means
|
|
|
|
|
that all other dependencies of the package (including dependencies on
|
|
|
|
|
target architecture and MMU support) have to be repeated on the
|
|
|
|
|
+comment+ definition. To keep it clear, the +depends on+ statement for
|
|
|
|
|
these non-toolchain option should be kept separate from the +depends on+
|
|
|
|
|
statement for the toolchain options.
|
|
|
|
|
If there is a dependency on a config option in that same file (typically
|
|
|
|
|
the main package) it is preferable to have a global +if ... endif+
|
|
|
|
|
construct rather than repeating the +depends on+ statement on the
|
|
|
|
|
comment and other config options.
|
|
|
|
|
|
2013-10-13 16:55:31 +02:00
|
|
|
The general format of a dependency +comment+ for package foo is:
|
|
|
|
|
--------------------------
|
|
|
|
|
foo needs a toolchain w/ featA, featB, featC
|
|
|
|
|
--------------------------
|
|
|
|
|
|
|
|
|
|
for example:
|
|
|
|
|
--------------------------
|
|
|
|
|
aircrack-ng needs a toolchain w/ largefile, threads
|
|
|
|
|
--------------------------
|
2014-03-28 19:48:34 +01:00
|
|
|
or
|
|
|
|
|
--------------------------
|
|
|
|
|
crda needs a toolchain w/ threads
|
|
|
|
|
--------------------------
|
2013-10-13 16:55:31 +02:00
|
|
|
|
|
|
|
|
Note that this text is kept brief on purpose, so that it will fit on a
|
|
|
|
|
80-character terminal.
|
|
|
|
|
|
|
|
|
|
The rest of this section enumerates the different target and toolchain
|
|
|
|
|
options, the corresponding config symbols to depend on, and the text to
|
|
|
|
|
use in the comment.
|
|
|
|
|
|
|
|
|
|
* Target architecture
|
|
|
|
|
** Dependency symbol: +BR2_powerpc+, +BR2_mips+, ... (see +arch/Config.in+)
|
|
|
|
|
** Comment string: no comment to be added
|
|
|
|
|
|
|
|
|
|
* MMU support
|
|
|
|
|
** Dependency symbol: +BR2_USE_MMU+
|
|
|
|
|
** Comment string: no comment to be added
|
|
|
|
|
|
2014-03-01 15:53:03 +01:00
|
|
|
* Kernel headers
|
|
|
|
|
** Dependency symbol: +BR2_TOOLCHAIN_HEADERS_AT_LEAST_X_Y+, (replace
|
|
|
|
|
+X_Y+ with the proper version, see +toolchain/toolchain-common.in+)
|
|
|
|
|
** Comment string: +headers >= X.Y+ (replace +X.Y+ with the
|
|
|
|
|
proper version)
|
|
|
|
|
|
2013-10-13 16:55:31 +02:00
|
|
|
* C library
|
|
|
|
|
** Dependency symbol: +BR2_TOOLCHAIN_USES_GLIBC+,
|
2014-05-02 12:49:28 +02:00
|
|
|
+BR2_TOOLCHAIN_USES_UCLIBC+
|
2013-10-13 16:55:31 +02:00
|
|
|
** Comment string: for the C library, a slightly different comment text
|
|
|
|
|
is used: +foo needs an (e)glibc toolchain+, or `foo needs an (e)glibc
|
2014-05-02 12:49:28 +02:00
|
|
|
toolchain w/ C++`
|
2013-10-13 16:55:31 +02:00
|
|
|
|
|
|
|
|
* C++ support
|
|
|
|
|
** Dependency symbol: +BR2_INSTALL_LIBSTDCPP+
|
|
|
|
|
** Comment string: `C++`
|
|
|
|
|
|
|
|
|
|
* largefile support
|
|
|
|
|
** Dependency symbol: +BR2_LARGEFILE+
|
|
|
|
|
** Comment string: +largefile+
|
|
|
|
|
|
|
|
|
|
* thread support
|
|
|
|
|
** Dependency symbol: +BR2_TOOLCHAIN_HAS_THREADS+
|
2014-02-18 22:09:00 +01:00
|
|
|
** Comment string: +threads+ (unless +BR2_TOOLCHAIN_HAS_THREADS_NPTL+
|
|
|
|
|
is also needed, in which case, specifying only +NPTL+ is sufficient)
|
|
|
|
|
|
|
|
|
|
* NPTL thread support
|
|
|
|
|
** Dependency symbol: +BR2_TOOLCHAIN_HAS_THREADS_NPTL+
|
|
|
|
|
** Comment string: +NPTL+
|
2013-10-13 16:55:31 +02:00
|
|
|
|
|
|
|
|
* RPC support
|
|
|
|
|
** Dependency symbol: +BR2_TOOLCHAIN_HAS_NATIVE_RPC+
|
|
|
|
|
** Comment string: +RPC+
|
|
|
|
|
|
|
|
|
|
* IPv6 support
|
|
|
|
|
** Dependency symbol: +BR2_INET_IPV6+
|
|
|
|
|
** Comment string: +IPv6+ (lowercase v)
|
|
|
|
|
|
|
|
|
|
* wchar support
|
|
|
|
|
** Dependency symbol: +BR2_USE_WCHAR+
|
|
|
|
|
** Comment string: +wchar+
|
|
|
|
|
|
|
|
|
|
* dynamic library
|
|
|
|
|
** Dependency symbol: +!BR2_PREFER_STATIC_LIB+
|
|
|
|
|
** Comment string: +dynamic library+
|
|
|
|
|
|
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
|
|
|
==== Dependencies on a Linux kernel built by buildroot
|
|
|
|
|
|
2013-12-15 13:20:40 +01:00
|
|
|
Some packages need a Linux kernel to be built by buildroot. These are
|
|
|
|
|
typically kernel modules or firmware. A comment should be added in the
|
|
|
|
|
Config.in file to express this dependency, similar to dependencies on
|
|
|
|
|
toolchain options. The general format is:
|
|
|
|
|
|
|
|
|
|
--------------------------
|
|
|
|
|
foo needs a Linux kernel to be built
|
|
|
|
|
--------------------------
|
|
|
|
|
|
|
|
|
|
If there is a dependency on both toolchain options and the Linux
|
|
|
|
|
kernel, use this format:
|
|
|
|
|
--------------------------
|
|
|
|
|
foo needs a toolchain w/ featA, featB, featC and a Linux kernel to be built
|
|
|
|
|
--------------------------
|
2013-10-13 16:55:31 +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
|
|
|
==== Dependencies on udev /dev management
|
|
|
|
|
|
2013-12-19 21:13:02 +01:00
|
|
|
If a package needs udev /dev management, it should depend on symbol
|
2014-02-07 14:21:33 +01:00
|
|
|
+BR2_PACKAGE_HAS_UDEV+, and the following comment should be added:
|
2013-12-19 21:13:02 +01:00
|
|
|
|
|
|
|
|
--------------------------
|
|
|
|
|
foo needs udev /dev management
|
|
|
|
|
--------------------------
|
|
|
|
|
|
|
|
|
|
If there is a dependency on both toolchain options and udev /dev
|
|
|
|
|
management, use this format:
|
|
|
|
|
|
|
|
|
|
--------------------------
|
|
|
|
|
foo needs udev /dev management and a toolchain w/ featA, featB, featC
|
|
|
|
|
--------------------------
|
|
|
|
|
|
2014-06-08 16:15:17 +02:00
|
|
|
==== Dependencies on features provided by virtual packages
|
|
|
|
|
|
|
|
|
|
Some features can be provided by more than one package, such as the
|
|
|
|
|
openGL libraries.
|
|
|
|
|
|
|
|
|
|
See xref:virtual-package-tutorial[] for more on the virtual packages.
|
|
|
|
|
|
|
|
|
|
See xref:virtual-package-list[] for the symbols to depend on if your package
|
|
|
|
|
depends on a feature provided by a virtual package.
|
|
|
|
|
|
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
|
|
|
=== The +.mk+ file
|
|
|
|
|
|
2013-02-05 08:15:59 +01:00
|
|
|
[[adding-packages-mk]]
|
2011-10-10 10:46:39 +02:00
|
|
|
|
|
|
|
|
Finally, here's the hardest part. Create a file named +libfoo.mk+. It
|
|
|
|
|
describes how the package should be downloaded, configured, built,
|
|
|
|
|
installed, etc.
|
|
|
|
|
|
|
|
|
|
Depending on the package type, the +.mk+ file must be written in a
|
|
|
|
|
different way, using different infrastructures:
|
|
|
|
|
|
2011-11-13 09:54:46 +01:00
|
|
|
* *Makefiles for generic packages* (not using autotools or CMake):
|
|
|
|
|
These are based on an infrastructure similar to the one used for
|
2012-11-16 05:54:19 +01:00
|
|
|
autotools-based packages, but require a little more work from the
|
2011-10-10 10:46:39 +02:00
|
|
|
developer. They specify what should be done for the configuration,
|
2013-12-07 10:16:47 +01:00
|
|
|
compilation and installation of the package. This
|
2011-10-10 10:46:39 +02:00
|
|
|
infrastructure must be used for all packages that do not use the
|
|
|
|
|
autotools as their build system. In the future, other specialized
|
|
|
|
|
infrastructures might be written for other build systems. We cover
|
2012-07-06 00:06:46 +02:00
|
|
|
them through in a xref:generic-package-tutorial[tutorial] and a
|
|
|
|
|
xref:generic-package-reference[reference].
|
2011-10-10 10:46:39 +02:00
|
|
|
|
|
|
|
|
* *Makefiles for autotools-based software* (autoconf, automake, etc.):
|
|
|
|
|
We provide a dedicated infrastructure for such packages, since
|
|
|
|
|
autotools is a very common build system. This infrastructure 'must'
|
|
|
|
|
be used for new packages that rely on the autotools as their build
|
2012-07-06 00:06:46 +02:00
|
|
|
system. We cover them through a xref:autotools-package-tutorial[tutorial]
|
|
|
|
|
and xref:autotools-package-reference[reference].
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2011-11-13 09:54:46 +01:00
|
|
|
* *Makefiles for cmake-based software*: We provide a dedicated
|
|
|
|
|
infrastructure for such packages, as CMake is a more and more
|
|
|
|
|
commonly used build system and has a standardized behaviour. This
|
|
|
|
|
infrastructure 'must' be used for new packages that rely on
|
2012-07-06 00:06:46 +02:00
|
|
|
CMake. We cover them through a xref:cmake-package-tutorial[tutorial]
|
|
|
|
|
and xref:cmake-package-reference[reference].
|
2011-11-13 09:54:46 +01:00
|
|
|
|
2014-02-23 16:04:30 +01:00
|
|
|
* *Makefiles for Python modules*: We have a dedicated infrastructure
|
|
|
|
|
for Python modules that use either the +distutils+ or the
|
|
|
|
|
+setuptools+ mechanism. We cover them through a
|
|
|
|
|
xref:python-package-tutorial[tutorial] and a
|
|
|
|
|
xref:python-package-reference[reference].
|
|
|
|
|
|
|
|
|
|
* *Makefiles for Lua modules*: We have a dedicated infrastructure for
|
|
|
|
|
Lua modules available through the LuaRocks web site. We cover them
|
|
|
|
|
through a xref:luarocks-package-tutorial[tutorial] and a
|
|
|
|
|
xref:luarocks-package-reference[reference].
|
|
|
|
|
|
2013-09-25 10:56:34 +02:00
|
|
|
Further formatting details: see xref:writing-rules-mk[the writing
|
2012-11-11 04:14:47 +01:00
|
|
|
rules].
|
2014-07-03 21:36:22 +02:00
|
|
|
|
|
|
|
|
[[adding-packages-hash]]
|
|
|
|
|
=== The +.hash+ file
|
|
|
|
|
|
|
|
|
|
Optionally, you can add a third file, named +libfoo.hash+, that contains
|
|
|
|
|
the hashes of the downloaded files for the +libfoo+ package.
|
|
|
|
|
|
|
|
|
|
The hashes stored in that file are used to validate the integrity of the
|
|
|
|
|
downloaded files.
|
|
|
|
|
|
|
|
|
|
The format of this file is one line for each file for which to check the
|
|
|
|
|
hash, each line being space-separated, with these three fields:
|
|
|
|
|
|
|
|
|
|
* the type of hash, one of:
|
|
|
|
|
** +sha1+, +sha224+, +sha256+, +sha384+, +sha512+
|
|
|
|
|
* the hash of the file:
|
|
|
|
|
** for +sha1+, 40 hexadecimal characters
|
|
|
|
|
** for +sha224+, 56 hexadecimal characters
|
|
|
|
|
** for +sha256+, 64 hexadecimal characters
|
|
|
|
|
** for +sha384+, 96 hexadecimal characters
|
|
|
|
|
** for +sha512+, 128 hexadecimal characters
|
|
|
|
|
* the name of the file, without any directory component
|
|
|
|
|
|
|
|
|
|
Lines starting with a +#+ sign are considered comments, and ignored. Empty
|
|
|
|
|
lines are ignored.
|
|
|
|
|
|
|
|
|
|
There can be more than one hash for a single file, each on its own line. In
|
|
|
|
|
this case, all hashes must match.
|
|
|
|
|
|
|
|
|
|
Ideally, the hashes stored in this file should match the hashes published by
|
|
|
|
|
upstream, e.g. on their website, in the e-mail announcement... If upstream
|
|
|
|
|
provides more than one type of hash (say, +sha1+ and +sha512+), then it is
|
|
|
|
|
best to add all those hashes in the +.hash+ file. If upstream does not
|
|
|
|
|
provide any hash, then compute at least one yourself, and mention this in a
|
|
|
|
|
comment line above the hashes.
|
|
|
|
|
|
|
|
|
|
*Note:* the number of spaces does not matter, so one can use spaces to
|
|
|
|
|
properly align the different fields.
|
|
|
|
|
|
|
|
|
|
The example below defines a +sha1+ and a +sha256+ published by upstream for
|
|
|
|
|
the main +libfoo-1.2.3.tar.bz2+ tarball, plus two locally-computed hashes,
|
|
|
|
|
a +sha256+ for a downloaded patch, and a +sha1+ for a downloaded binary blob:
|
|
|
|
|
|
|
|
|
|
----
|
|
|
|
|
# Hashes from: http://www.foosoftware.org/download/libfoo-1.2.3.tar.bz2.{sha1,sha256}:
|
|
|
|
|
sha1 486fb55c3efa71148fe07895fd713ea3a5ae343a libfoo-1.2.3.tar.bz2
|
|
|
|
|
sha256 efc8103cc3bcb06bda6a781532d12701eb081ad83e8f90004b39ab81b65d4369 libfoo-1.2.3.tar.bz2
|
|
|
|
|
|
|
|
|
|
# No upstream hashes for the following:
|
|
|
|
|
sha256 ff52101fb90bbfc3fe9475e425688c660f46216d7e751c4bbdb1dc85cdccacb9 libfoo-fix-blabla.patch
|
|
|
|
|
sha1 2d608f3c318c6b7557d551a5a09314f03452f1a1 libfoo-data.bin
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
If the +.hash+ file is present, and it contains one or more hashes for a
|
|
|
|
|
downloaded file, the hash(es) computed by Buildroot (after download) must
|
|
|
|
|
match the hash(es) stored in the +.hash+ file. If one or more hashes do
|
|
|
|
|
not match, Buildroot considers this an error, deletes the downloaded file,
|
|
|
|
|
and aborts.
|
|
|
|
|
|
|
|
|
|
If the +.hash+ file is present, but it does not contain a hash for a
|
|
|
|
|
downloaded file, no check is done for that file. If you set the
|
|
|
|
|
environment variable +BR2_ENFORCE_CHECK_HASH+ to a non-empty value, and
|
|
|
|
|
there is no hash for a downloaded file, Buildroot considers this an
|
|
|
|
|
error, deletes the downloaded file, and aborts.
|
|
|
|
|
|
|
|
|
|
If the +.hash+ file is missing, then no check is done at all.
|
