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 CMake-based packages
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2012-07-06 00:06:46 +02:00
|
|
|
[[cmake-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
|
|
|
==== +cmake-package+ tutorial
|
2011-10-10 10:46:39 +02:00
|
|
|
|
|
|
|
|
First, let's see how to write a +.mk+ file for a CMake-based package,
|
|
|
|
|
with an example :
|
|
|
|
|
|
|
|
|
|
------------------------
|
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
|
|
|
|
|
10: LIBFOO_INSTALL_STAGING = YES
|
|
|
|
|
11: LIBFOO_INSTALL_TARGET = NO
|
2014-09-27 21:32:44 +02:00
|
|
|
12: LIBFOO_CONF_OPTS = -DBUILD_DEMOS=ON
|
2013-02-25 12:31:31 +01:00
|
|
|
13: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf
|
|
|
|
|
14:
|
|
|
|
|
15: $(eval $(cmake-package))
|
2011-10-10 10:46:39 +02:00
|
|
|
------------------------
|
|
|
|
|
|
2013-02-25 12:31:31 +01:00
|
|
|
On line 7, we declare the version of the package.
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2013-09-06 08:14:15 +02:00
|
|
|
On line 8 and 9, we declare the name of the tarball (xz-ed tarball recommended)
|
|
|
|
|
and the location of the tarball on the Web. Buildroot will automatically
|
|
|
|
|
download the tarball from this location.
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2013-02-25 12:31:31 +01:00
|
|
|
On line 10, we tell Buildroot to install the package to the staging
|
2011-10-10 10:46:39 +02:00
|
|
|
directory. The staging directory, located in +output/staging/+
|
|
|
|
|
is the directory where all the packages are installed, including their
|
|
|
|
|
development files, etc. By default, packages are not installed to the
|
|
|
|
|
staging directory, since usually, only libraries need to be installed in
|
|
|
|
|
the staging directory: their development files are needed to compile
|
|
|
|
|
other libraries or applications depending on them. Also by default, when
|
|
|
|
|
staging installation is enabled, packages are installed in this location
|
|
|
|
|
using the +make install+ command.
|
|
|
|
|
|
2013-02-25 12:31:31 +01:00
|
|
|
On line 11, we tell Buildroot to not install the package to the
|
2011-10-10 10:46:39 +02:00
|
|
|
target directory. This directory contains what will become the root
|
2012-11-27 12:59:19 +01:00
|
|
|
filesystem running on the target. For purely static libraries, it is
|
|
|
|
|
not necessary to install them in the target directory because they will
|
|
|
|
|
not be used at runtime. By default, target installation is enabled; setting
|
|
|
|
|
this variable to NO is almost never needed. Also by default, packages are
|
|
|
|
|
installed in this location using the +make install+ command.
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2013-02-25 12:31:31 +01:00
|
|
|
On line 12, we tell Buildroot to pass custom options to CMake when it is
|
2011-10-10 10:46:39 +02:00
|
|
|
configuring the package.
|
|
|
|
|
|
2013-02-25 12:31:31 +01:00
|
|
|
On line 13, we declare our dependencies, so that they are built
|
2011-10-10 10:46:39 +02:00
|
|
|
before the build process of our package starts.
|
|
|
|
|
|
2013-02-25 12:31:31 +01:00
|
|
|
Finally, on line line 15, we invoke the +cmake-package+
|
2011-10-10 10:46:39 +02:00
|
|
|
macro that generates all the Makefile rules that actually allows the
|
|
|
|
|
package to be built.
|
|
|
|
|
|
2012-07-06 00:06:46 +02:00
|
|
|
[[cmake-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
|
|
|
==== +cmake-package+ reference
|
2011-10-10 10:46:39 +02:00
|
|
|
|
|
|
|
|
The main macro of the CMake package infrastructure is
|
2012-07-03 00:07:08 +02:00
|
|
|
+cmake-package+. It is similar to the +generic-package+ macro. The ability to
|
2012-07-03 00:05:46 +02:00
|
|
|
have target and host packages is also available, with the
|
|
|
|
|
+host-cmake-package+ macro.
|
2011-10-10 10:46:39 +02:00
|
|
|
|
|
|
|
|
Just like the generic infrastructure, the CMake infrastructure works
|
2012-07-03 00:07:08 +02:00
|
|
|
by defining a number of variables before calling the +cmake-package+
|
2011-10-10 10:46:39 +02:00
|
|
|
macro.
|
|
|
|
|
|
|
|
|
|
First, all the package metadata information variables that exist in
|
|
|
|
|
the generic infrastructure also exist in the CMake infrastructure:
|
|
|
|
|
+LIBFOO_VERSION+, +LIBFOO_SOURCE+, +LIBFOO_PATCH+, +LIBFOO_SITE+,
|
|
|
|
|
+LIBFOO_SUBDIR+, +LIBFOO_DEPENDENCIES+, +LIBFOO_INSTALL_STAGING+,
|
|
|
|
|
+LIBFOO_INSTALL_TARGET+.
|
|
|
|
|
|
|
|
|
|
A few additional variables, specific to the CMake infrastructure, can
|
|
|
|
|
also be defined. Many of them are only useful in very specific cases,
|
|
|
|
|
typical packages will therefore only use a few of them.
|
|
|
|
|
|
|
|
|
|
* +LIBFOO_SUBDIR+ may contain the name of a subdirectory inside the
|
|
|
|
|
package that contains the main CMakeLists.txt file. This is useful,
|
|
|
|
|
if for example, the main CMakeLists.txt file is not at the root of
|
|
|
|
|
the tree extracted by the tarball. If +HOST_LIBFOO_SUBDIR+ is not
|
|
|
|
|
specified, it defaults to +LIBFOO_SUBDIR+.
|
|
|
|
|
|
|
|
|
|
* +LIBFOO_CONF_ENV+, to specify additional environment variables to
|
|
|
|
|
pass to CMake. By default, empty.
|
|
|
|
|
|
2014-09-27 21:32:44 +02:00
|
|
|
* +LIBFOO_CONF_OPTS+, to specify additional configure options to pass
|
2014-10-19 20:04:51 +02:00
|
|
|
to CMake. By default, empty. A number of common CMake options are
|
|
|
|
|
set by the +cmake-package+ infrastructure; so it is normally not
|
|
|
|
|
necessary to set them in the package's +*.mk+ file unless you want
|
|
|
|
|
to override them:
|
|
|
|
|
|
package/pkg-cmake.mk: determine CMAKE_BUILD_TYPE depending on BR2_ENABLE_RUNTIME_DEBUG
The CMAKE_BUILD_TYPE is currently set as 'Debug' in case BR2_ENABLE_DEBUG is
set, and as 'Release' in other cases. However, while the description of
BR2_ENABLE_DEBUG is to enable debug symbols (no runtime impact), the 'Debug'
build type in CMake can actually have runtime impact. For one, because it
does not set -DNDEBUG like is done for 'Release', but also because packages
may do custom things based on it.
The question of which CMAKE_BUILD_TYPE Buildroot should set, be it 'Debug',
'Release', 'RelWithDebInfo' or others, has come up several times in the
past. See some references below:
- July 2016: switch from Debug to RelWithDebInfo:
https://git.buildroot.org/buildroot/commit/?id=4b0120183404913f7f7788ef4f0f6b51498ef363
- October 2016: switch from RelWithDebInfo back to Debug:
https://git.buildroot.org/buildroot/commit/?id=104bb29e0490bfb487e2e665448dd3ca07fcc2b5
and changes to make sure Buildroot's flags are respected:
https://git.buildroot.org/buildroot/commit/?id=12494ef48f893684d0800e7f6fe39a2ceaed0451
- August 2017: bug #10246 - "BR2_ENABLE_DEBUG does not have the expected
effect for cmake packages"
https://bugs.busybox.net/show_bug.cgi?id=10246
- August 2017: mail thread following bug #10246:
http://lists.busybox.net/pipermail/buildroot/2017-August/200778.html
In the last mail thread, Samuel Martin confirmed that the 'Release' build
type could be used in all cases, because Buildroot is actually making sure
that the optimization flags are those determined by Buildroot, not the
defaults of cmake, thanks to commit 12494ef48f.
But Arnout Vandecappelle objected to using always 'Release', stating that
users may actually want the extra assertions.
With the introduction of BR2_ENABLE_RUNTIME_DEBUG, Buildroot can now cater
for all cases:
- use CMAKE_BUILD_TYPE=Release by default. This makes sure that there is no
unexpected performance degradation triggered by enabling BR2_ENABLE_DEBUG.
- users can optionally enable BR2_ENABLE_RUNTIME_DEBUG if they want runtime
debug info like assertions, at the risk of introducing performance
degradation. In this case, we switch to CMAKE_BUILD_TYPE=Debug.
- orthogonally to the above, BR2_ENABLE_DEBUG still determines passing the
'-g' flag to enable debug symbols, and BR2_OPTIMIZE_X still determines the
used optimization flags.
Signed-off-by: Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
Acked-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
Reviewed-by: Yann E. MORIN <yann.morin.1998@free.fr>
Signed-off-by: Yann E. MORIN <yann.morin.1998@free.fr>
2021-06-01 16:34:08 +02:00
|
|
|
** +CMAKE_BUILD_TYPE+ is driven by +BR2_ENABLE_RUNTIME_DEBUG+;
|
2014-10-19 20:04:51 +02:00
|
|
|
** +CMAKE_INSTALL_PREFIX+;
|
2014-12-03 22:41:29 +01:00
|
|
|
** +BUILD_SHARED_LIBS+ is driven by +BR2_STATIC_LIBS+;
|
2014-10-19 20:04:51 +02:00
|
|
|
** +BUILD_DOC+, +BUILD_DOCS+ are disabled;
|
|
|
|
|
** +BUILD_EXAMPLE+, +BUILD_EXAMPLES+ are disabled;
|
|
|
|
|
** +BUILD_TEST+, +BUILD_TESTS+, +BUILD_TESTING+ are disabled.
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2015-03-13 09:24:08 +01:00
|
|
|
* +LIBFOO_SUPPORTS_IN_SOURCE_BUILD = NO+ should be set when the package
|
|
|
|
|
cannot be built inside the source tree but needs a separate build
|
|
|
|
|
directory.
|
|
|
|
|
|
2011-10-10 10:46:39 +02:00
|
|
|
* +LIBFOO_MAKE+, to specify an alternate +make+ command. This is
|
|
|
|
|
typically useful when parallel make is enabled in the configuration
|
|
|
|
|
(using +BR2_JLEVEL+) but that this feature should be disabled for
|
|
|
|
|
the given package, for one reason or another. By default, set to
|
|
|
|
|
+$(MAKE)+. If parallel building is not supported by the package,
|
|
|
|
|
then it should be set to +LIBFOO_MAKE=$(MAKE1)+.
|
|
|
|
|
|
|
|
|
|
* +LIBFOO_MAKE_ENV+, to specify additional environment variables to
|
|
|
|
|
pass to make in the build step. These are passed before the +make+
|
|
|
|
|
command. By default, empty.
|
|
|
|
|
|
2014-09-27 21:32:38 +02:00
|
|
|
* +LIBFOO_MAKE_OPTS+, to specify additional variables to pass to make
|
2011-10-10 10:46:39 +02:00
|
|
|
in the build step. These are passed after the +make+ command. By
|
|
|
|
|
default, empty.
|
|
|
|
|
|
2021-01-18 22:27:00 +01:00
|
|
|
* +LIBFOO_INSTALL_OPTS+ contains the make options used to
|
|
|
|
|
install the package to the host directory. By default, the value
|
|
|
|
|
is +install+, which is correct for most CMake packages. It is still
|
|
|
|
|
possible to override it.
|
|
|
|
|
|
2014-09-27 21:32:41 +02:00
|
|
|
* +LIBFOO_INSTALL_STAGING_OPTS+ contains the make options used to
|
2011-10-10 10:46:39 +02:00
|
|
|
install the package to the staging directory. By default, the value
|
2021-01-18 22:26:59 +01:00
|
|
|
is +DESTDIR=$(STAGING_DIR) install/fast+, which is correct for most
|
2011-10-10 10:46:39 +02:00
|
|
|
CMake packages. It is still possible to override it.
|
|
|
|
|
|
2014-09-27 21:32:40 +02:00
|
|
|
* +LIBFOO_INSTALL_TARGET_OPTS+ contains the make options used to
|
2011-10-10 10:46:39 +02:00
|
|
|
install the package to the target directory. By default, the value
|
2021-01-18 22:26:59 +01:00
|
|
|
is +DESTDIR=$(TARGET_DIR) install/fast+. The default value is correct
|
2011-10-10 10:46:39 +02:00
|
|
|
for most CMake packages, but it is still possible to override it if
|
|
|
|
|
needed.
|
|
|
|
|
|
|
|
|
|
With the CMake infrastructure, all the steps required to build and
|
|
|
|
|
install the packages are already defined, and they generally work well
|
|
|
|
|
for most CMake-based packages. However, when required, it is still
|
|
|
|
|
possible to customize what is done in any particular step:
|
|
|
|
|
|
|
|
|
|
* By adding a post-operation hook (after extract, patch, configure,
|
2013-11-07 11:41:23 +01:00
|
|
|
build or install). See xref:hooks[] for details.
|
2011-10-10 10:46:39 +02:00
|
|
|
|
|
|
|
|
* By overriding one of the steps. For example, even if the CMake
|
|
|
|
|
infrastructure is used, if the package +.mk+ file defines its own
|
|
|
|
|
+LIBFOO_CONFIGURE_CMDS+ variable, it will be used instead of the
|
|
|
|
|
default CMake one. However, using this method should be restricted
|
|
|
|
|
to very specific cases. Do not use it in the general case.
|
