manual: convert existing documentation to the asciidoc format

Infrastructure for autotools-based packages

-------------------------------------------

[[autotargets-tutorial]]

+AUTOTARGETS+ tutorial

~~~~~~~~~~~~~~~~~~~~~~

First, let's see how to write a +.mk+ file for an autotools-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 = --enable-shared

12: LIBFOO_DEPENDENCIES = libglib2 host-pkg-config

13:

14: $(eval $(call AUTOTARGETS,package,libfoo))

------------------------

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 a custom configure option, that

will be passed to the +./configure+ script before configuring

and building 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 +AUTOTARGETS+

macro that generates all the Makefile rules that actually allows the

package to be built.

[[autotargets-reference]]

+AUTOTARGETS+ reference

~~~~~~~~~~~~~~~~~~~~~~~

The main macro of the autotools package infrastructure is

+AUTOTARGETS+. It has the same number of arguments and the

same semantic as the +GENTARGETS+ macro, which is the main

macro of the generic package infrastructure. For autotools packages, the

ability to have target and host packages is also available (and is

actually widely used).

Just like the generic infrastructure, the autotools infrastructure

works by defining a number of variables before calling the

+AUTOTARGETS+ macro.

First, all the package metadata information variables that exist in the

generic infrastructure also exist in the autotools 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 autotools 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 configure script. This is useful,

  if for example, the main configure script 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 the configure script. By default, empty.

* +LIBFOO_CONF_OPT+, to specify additional configure

  options to pass to the configure script. 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_AUTORECONF+, tells whether the package should

  be autoreconfigured or not (i.e, if the configure script and

  Makefile.in files should be re-generated by re-running autoconf,

  automake, libtool, etc.). Valid values are +YES+ and

  +NO+. By default, the value is +NO+

* +LIBFOO_AUTORECONF_OPT+ to specify additional options

  passed to the 'autoreconf' program if

  +LIBFOO_AUTORECONF=YES+. By default, empty.

* +LIBFOO_LIBTOOL_PATCH+ tells whether the Buildroot

  patch to fix libtool cross-compilation issues should be applied or

  not. Valid values are +YES+ and +NO+. By

  default, the value is +YES+

* +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 autotools 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 autotools 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+.

* +LIBFOO_UNINSTALL_STAGING_OPT+, contains the make

  options used to uninstall the package from the staging directory. By

  default, the value is +DESTDIR=$$(STAGING_DIR) uninstall+.

* +LIBFOO_UNINSTALL_TARGET_OPT+, contains the make

  options used to uninstall the package from the target directory. By

  default, the value is +DESTDIR=$$(TARGET_DIR) uninstall+.

With the autotools infrastructure, all the steps required to build

and install the packages are already defined, and they generally work

well for most autotools-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 autotools

  infrastructure is used, if the package +.mk+ file defines its

  own +LIBFOO_CONFIGURE_CMDS+ variable, it will be used

  instead of the default autotools one. However, using this method

  should be restricted to very specific cases. Do not use it in the

  general case.

Infrastructure for CMake-based packages

---------------------------------------

[[cmaketargets-tutorial]]

+CMAKETARGETS+ 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-pkg-config

13:

14: $(eval $(call CMAKETARGETS,package,libfoo))

------------------------

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 +CMAKETARGETS+

macro that generates all the Makefile rules that actually allows the

package to be built.

[[cmaketargets-reference]]

+CMAKETARGETS+ reference

~~~~~~~~~~~~~~~~~~~~~~~~

The main macro of the CMake package infrastructure is

+CMAKETARGETS+. It has the same number of arguments and the same

semantic as the +GENTARGETS+ macro, which is the main macro of the

generic package infrastructure. For CMake packages, the ability to

have target and host packages is also available.

Just like the generic infrastructure, the CMake infrastructure works

by defining a number of variables before calling the +CMAKETARGETS+

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.

Conclusion

----------

As you can see, adding a software package to Buildroot is simply a

matter of writing a Makefile using an  existing example and modifying it

according to the compilation process required by the package.

If you package software that might be useful for other people, don't

forget to send a patch to Buildroot developers!

Package directory

-----------------

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:

+multimedia+, +java+, +x11r7+, and +games+. If your package fits in

one of these categories, then create your package directory in these.

+Config.in+ file

~~~~~~~~~~~~~~~~

Then, create a file named +Config.in+. This file will contain the

option descriptions related to our +libfoo+ software that will be used

and displayed in the configuration tool. It should basically contain :

---------------------------

config BR2_PACKAGE_LIBFOO

	bool "libfoo"

	help

	  This is a comment that explains what libfoo is.

	  http://foosoftware.org/libfoo/

---------------------------

Of course, you can add other options 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

http://lxr.free-electrons.com/source/Documentation/kbuild/kconfig-language.txt[]

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"

--------------------------

The +.mk+ file

~~~~~~~~~~~~~~

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:

* *Makefiles for generic packages* (not using autotools): These are

  based on an infrastructure similar to the one used for

  autotools-based packages, but requires a little more work from the

  developer. They specify what should be done for the configuration,

  compilation, installation and cleanup of the package. This

  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

  them through in a xref:gentargets-tutorial[tutorial] and a

  xref:gentargets-reference[reference].

* *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

  system. We cover them through a xref:autotargets-tutorial[tutorial]

  and xref:autotargets-reference[reference].

* *Hand-written Makefiles:* These are currently obsolete, and no new

  manual Makefiles should be added. However, since there are still

  many of them in the tree, we keep them documented in a

  xref:handwritten-tutorial[tutorial].