NetCube-Systems-Austria/kumquat-buildroot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
c9b07cbdd0
kumquat-buildroot/docs/manual/adding-packages-autotools.adoc
Ricardo Martincoski c9b07cbdd0 docs/manual: standardize references to the generic infra 
Currently the text for each package infra that mentions the usage of
variables already provided by the generic infra diverge from each other:
- some (golang, kconfig, python) add a cross-referece to the generic
  infra chapter;
- kconfig does not list any example;
- some mention _LICENSE as an example, others don't;
- some (cargo, golang, python) add an 'etc.' at the end of the examples,
  giving the idea that can be more symbols provided by the generic
  infra than the ones listed;
- most have the text 'works by defining a number of variables before
  calling the +<macro-name>+ macro', except golang and kconfig;
- some actually list 'A few additional variables' but keep using some
  old reference as 'An additional variable';
- some say 'First, all the package metadata' and other only 'All the
  package metadata';
- most mention _SUBDIR as an example of variable supported by the
  generic infra, even the generic infra manual not mentioning it.

Improve the correctness for the manual by standardizing the text among
the package infras:
- use the same text "All the package metadata information variables that
  exist in the generic package infrastructure also exist in the
  <name> infrastructure:" for all of them;
- add the cross-reference for all of them;
- remove the examples of variables inherited from the generic infra -
  this also solves the _SUBDIR problem, there no longer is any reference
  to _SUBDIR;
- wrap the modified text at 80 columns;
- add "macro" to golang and luarocks infra;
- use "A few additional variables" for qmake and waf.

At same time, add a missing format on golang manual for
BR2_PACKAGE_HOST_GO_HOST_ARCH_SUPPORTS.

Cc: Eric Le Bihan <eric.le.bihan.dev@free.fr>
Cc: Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
Signed-off-by: Ricardo Martincoski <ricardo.martincoski@gmail.com>
[Arnout:
 - remove the examples;
 - add "the" where "macro" was added;
 - rewrite the preceding paragraphs for kconfig to make it more
   consistent.
]
Signed-off-by: Arnout Vandecappelle <arnout@mind.be>
(cherry picked from commit 4286c89f9d987f5f3bcbb14dfd58ba440944f4c2)
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2024-08-07 00:38:14 +02:00

166 lines
6.9 KiB
Plaintext
Raw Blame History

// -*- mode:doc; -*-
// vim: set syntax=asciidoc:
=== Infrastructure for autotools-based packages
[[autotools-package-tutorial]]
==== +autotools-package+ 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:
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
12: LIBFOO_CONF_OPTS = --disable-shared
13: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf
14:
15: $(eval $(autotools-package))
------------------------
On line 7, we declare the version of the package.
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.
On line 10, 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 11, we tell Buildroot to not install the package to the
target directory. This directory contains what will become the root
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.
On line 12, 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 13, we declare our dependencies, so that they are built
before the build process of our package starts.
Finally, on line line 15, we invoke the +autotools-package+
macro that generates all the Makefile rules that actually allows the
package to be built.
[[autotools-package-reference]]
==== +autotools-package+ reference
The main macro of the autotools package infrastructure is
+autotools-package+. It is similar to the +generic-package+ macro. The ability to
have target and host packages is also available, with the
+host-autotools-package+ macro.
Just like the generic infrastructure, the autotools infrastructure
works by defining a number of variables before calling the
+autotools-package+ macro.
All the package metadata information variables that exist in the
xref:generic-package-reference[generic package infrastructure] also
exist in the autotools infrastructure.
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_OPTS+, 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_OPTS+, 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_ENV+, to specify additional environment
variables to pass to the 'autoreconf' program if
+LIBFOO_AUTORECONF=YES+. These are passed in the environment of
the 'autoreconf' command. By default, empty.
* +LIBFOO_AUTORECONF_OPTS+ to specify additional options
passed to the 'autoreconf' program if
+LIBFOO_AUTORECONF=YES+. By default, empty.
* +LIBFOO_AUTOPOINT+, tells whether the package should be
autopointed or not (i.e. if the package needs I18N infrastructure
copied in.) Only valid when +LIBFOO_AUTORECONF=YES+. Valid
values are +YES+ and +NO+. The default is +NO+.
* +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_OPTS+ 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_OPTS+ 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.
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 xref:hooks[] 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.
Reference in New Issue View Git Blame Copy Permalink