5e84b8b73c
The new skeleton of the manual as it has been thought:
1. About Buildroot:
Presentation of Buildroot
2. Starting up:
Everything to quickly and easily start working with Buildroot
3. Working with Buildroot
Basics to make your work fitting your needs
4. Troubleshooting
5. Going further in Buildroot's innards
Explaination of how buildroot is organised, how it works, etc
6. Developer Guidelines
7. Getting involved
8. Contibuting to Buildroot
9. Legal notice
10. Appendix
It is easy to distinguish two parts in this plan:
- Sections 1 to 4 mainly address people starting with Buildroot
- Sections 5 to 10 are more focused on how to develop Buildroot itself
Most of the existing sections have just been moved in the hierarchy,
few were split and dispatch in, what i think was the relevant section,
and numerous others have been created.
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
Signed-off-by: Peter Korsgaard <jacmet@sunsite.dk>
144 lines
5.9 KiB
Plaintext
144 lines
5.9 KiB
Plaintext
// -*- mode:doc; -*-
|
|
|
|
Infrastructure for CMake-based packages
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
[[cmake-package-tutorial]]
|
|
|
|
+cmake-package+ tutorial
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
First, let's see how to write a +.mk+ file for a CMake-based package,
|
|
with an example :
|
|
|
|
------------------------
|
|
01: #############################################################
|
|
02: #
|
|
03: # libfoo
|
|
04: #
|
|
05: #############################################################
|
|
06: LIBFOO_VERSION = 1.0
|
|
07: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
|
|
08: LIBFOO_SITE = http://www.foosoftware.org/download
|
|
09: LIBFOO_INSTALL_STAGING = YES
|
|
10: LIBFOO_INSTALL_TARGET = YES
|
|
11: LIBFOO_CONF_OPT = -DBUILD_DEMOS=ON
|
|
12: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf
|
|
13:
|
|
14: $(eval $(cmake-package))
|
|
------------------------
|
|
|
|
On line 6, we declare the version of the package.
|
|
|
|
On line 7 and 8, we declare the name of the tarball and the location
|
|
of the tarball on the Web. Buildroot will automatically download the
|
|
tarball from this location.
|
|
|
|
On line 9, we tell Buildroot to install the package to the staging
|
|
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.
|
|
|
|
On line 10, we tell Buildroot to also install the package to the
|
|
target directory. This directory contains what will become the root
|
|
filesystem running on the target. Usually, we try not to install header
|
|
files and to install stripped versions of the binary. By default, target
|
|
installation is enabled, so in fact, this line is not strictly
|
|
necessary. Also by default, packages are installed in this location
|
|
using the +make install+ command.
|
|
|
|
On line 11, we tell Buildroot to pass custom options to CMake when it is
|
|
configuring the package.
|
|
|
|
On line 12, we declare our dependencies, so that they are built
|
|
before the build process of our package starts.
|
|
|
|
Finally, on line line 14, we invoke the +cmake-package+
|
|
macro that generates all the Makefile rules that actually allows the
|
|
package to be built.
|
|
|
|
[[cmake-package-reference]]
|
|
|
|
+cmake-package+ reference
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
The main macro of the CMake package infrastructure is
|
|
+cmake-package+. It is similar to the +generic-package+ macro. The ability to
|
|
have target and host packages is also available, with the
|
|
+host-cmake-package+ macro.
|
|
|
|
Just like the generic infrastructure, the CMake infrastructure works
|
|
by defining a number of variables before calling the +cmake-package+
|
|
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.
|
|
|
|
* +LIBFOO_CONF_OPT+, to specify additional configure options to pass
|
|
to CMake. By default, empty.
|
|
|
|
* +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.
|
|
|
|
* +LIBFOO_MAKE_OPT+, to specify additional variables to pass to make
|
|
in the build step. These are passed after the +make+ command. By
|
|
default, empty.
|
|
|
|
* +LIBFOO_INSTALL_STAGING_OPT+ contains the make options used to
|
|
install the package to the staging directory. By default, the value
|
|
is +DESTDIR=$$(STAGING_DIR) install+, which is correct for most
|
|
CMake packages. It is still possible to override it.
|
|
|
|
* +LIBFOO_INSTALL_TARGET_OPT+ contains the make options used to
|
|
install the package to the target directory. By default, the value
|
|
is +DESTDIR=$$(TARGET_DIR) install+. The default value is correct
|
|
for most CMake packages, but it is still possible to override it if
|
|
needed.
|
|
|
|
* +LIBFOO_CLEAN_OPT+ contains the make options used to clean the
|
|
package. By default, the value is +clean+.
|
|
|
|
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,
|
|
build or install). See the reference documentation of the generic
|
|
infrastructure for details.
|
|
|
|
* 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.
|