X-Git-Url: https://review.fuel-infra.org/gitweb?a=blobdiff_plain;f=cirros-testvm%2Fsrc-cirros%2Fbuildroot-2015.05%2Fbuild%2Fdocs%2Fmanual%2Fadding-packages-directory.txt;fp=cirros-testvm%2Fsrc-cirros%2Fbuildroot-2015.05%2Fbuild%2Fdocs%2Fmanual%2Fadding-packages-directory.txt;h=3d0982feed02ae4c7be68a9aa3c4855aa877b530;hb=b0a0f15dfaa205161a7fcb20cf1b8cd4948c2ef3;hp=0000000000000000000000000000000000000000;hpb=c6ac3cd55ee2da956195eee393b0882105dfad4e;p=packages%2Ftrusty%2Fcirros-testvm.git diff --git a/cirros-testvm/src-cirros/buildroot-2015.05/build/docs/manual/adding-packages-directory.txt b/cirros-testvm/src-cirros/buildroot-2015.05/build/docs/manual/adding-packages-directory.txt new file mode 100644 index 0000000..3d0982f --- /dev/null +++ b/cirros-testvm/src-cirros/buildroot-2015.05/build/docs/manual/adding-packages-directory.txt @@ -0,0 +1,498 @@ +// -*- mode:doc; -*- +// vim: set syntax=asciidoc: + +=== 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: ++x11r7+, +efl+ and +matchbox+. If your package fits in +one of these categories, then create your package directory in these. +New subdirectories are discouraged, however. + +=== Config files + +For the package to be displayed in the configuration tool, you need to +create a Config file in your package directory. There are two types: ++Config.in+ and +Config.in.host+. + +==== +Config.in+ file + +For packages used on the target, 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/ +--------------------------- + +The +bool+ line, +help+ line and other metadata information about the +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. + +You can add other sub-options into a +if +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 +http://kernel.org/doc/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" +-------------------------- + + +==== +Config.in.host+ file + +Some packages also need to be built for the host system. There are two +options here: + +* The host package is only required to satisfy build-time + dependencies of one or more target packages. In this case, add + +host-foo+ to the target package's +BAR_DEPENDENCIES+ variable. No + +Config.in.host+ file should be created. + +* The host package should be explicitly selectable by the user from + the configuration menu. In this case, create a +Config.in.host+ file + for that host package: ++ +--------------------------- +config BR2_PACKAGE_HOST_FOO + bool "host foo" + help + This is a comment that explains what foo for the host is. + + http://foosoftware.org/foo/ +--------------------------- ++ +The same coding style and options as for the +Config.in+ file are valid. ++ +Finally you have to add your new +libfoo/Config.in.host+ to ++package/Config.in.host+. The files included there are 'sorted alphabetically' +and are 'NOT' supposed to contain anything but the 'bare' name of the package. ++ +-------------------------- +source "package/foo/Config.in.host" +-------------------------- ++ +The host package will then be available from the +Host utilities+ menu. + +[[depends-on-vs-select]] +==== Choosing +depends on+ or +select+ + +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. + The +select+ keyword expresses the dependency with a backward + semantic. + +* Use a +depends on+ type of dependency when the user really needs to + be aware of the dependency. Typically, Buildroot uses this type of + 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. + The +depends on+ keyword expresses the dependency with a forward + 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. + +An example illustrates both the usage of +select+ and +depends on+. + +-------------------------- +config BR2_PACKAGE_RRDTOOL + bool "rrdtool" + depends on BR2_USE_WCHAR + select BR2_PACKAGE_FREETYPE + select BR2_PACKAGE_LIBART + select BR2_PACKAGE_LIBPNG + select BR2_PACKAGE_ZLIB + help + RRDtool is the OpenSource industry standard, high performance + data logging and graphing system for time series data. + + http://oss.oetiker.ch/rrdtool/ + +comment "rrdtool needs a toolchain w/ wchar" + depends on !BR2_USE_WCHAR +-------------------------- + + +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. + +Note that such dependencies will ensure that the dependency option +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. + +Further formatting details: see xref:writing-rules-config-in[the +coding style]. + +[[dependencies-target-toolchain-options]] +==== Dependencies on target and toolchain options + +Many packages depend on certain options of the toolchain: the choice of +C library, C++ support, thread support, RPC 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. + +These dependencies have to be expressed with the appropriate 'depends +on' statements in the Config.in file. Additionally, for dependencies on +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. + +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. + +The general format of a dependency +comment+ for package foo is: + +-------------------------- +foo needs a toolchain w/ featA, featB, featC +-------------------------- + +for example: + +-------------------------- +mpd needs a toolchain w/ C++, threads, wchar +-------------------------- + +or + +-------------------------- +crda needs a toolchain w/ threads +-------------------------- + +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 + +* Atomic instructions (whereby the architecture has instructions to + perform some operations atomically, like LOCKCMPXCHG on x86) +** Dependency symbol: +BR2_ARCH_HAS_ATOMICS+ +** Comment string: no comment to be added + +* 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+ and/or `headers <= X.Y` (replace + +X.Y+ with the proper version) + +* C library +** Dependency symbol: +BR2_TOOLCHAIN_USES_GLIBC+, + +BR2_TOOLCHAIN_USES_MUSL+, +BR2_TOOLCHAIN_USES_UCLIBC+ +** 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 + toolchain w/ C++` + +* C++ support +** Dependency symbol: +BR2_INSTALL_LIBSTDCPP+ +** Comment string: `C++` + +* thread support +** Dependency symbol: +BR2_TOOLCHAIN_HAS_THREADS+ +** 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+ + +* RPC support +** Dependency symbol: +BR2_TOOLCHAIN_HAS_NATIVE_RPC+ +** Comment string: +RPC+ + +* wchar support +** Dependency symbol: +BR2_USE_WCHAR+ +** Comment string: +wchar+ + +* dynamic library +** Dependency symbol: +!BR2_STATIC_LIBS+ +** Comment string: +dynamic library+ + +==== Dependencies on a Linux kernel built by buildroot + +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 +-------------------------- + +==== Dependencies on udev /dev management + +If a package needs udev /dev management, it should depend on symbol ++BR2_PACKAGE_HAS_UDEV+, and the following comment should be added: + +-------------------------- +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 +-------------------------- + +==== 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. + +=== The +.mk+ file + +[[adding-packages-mk]] + +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 or CMake): + These are based on an infrastructure similar to the one used for + autotools-based packages, but require a little more work from the + developer. They specify what should be done for the configuration, + compilation and installation 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:generic-package-tutorial[tutorial] and a + xref:generic-package-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:autotools-package-tutorial[tutorial] + and xref:autotools-package-reference[reference]. + +* *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 + CMake. We cover them through a xref:cmake-package-tutorial[tutorial] + and xref:cmake-package-reference[reference]. + +* *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]. + +Further formatting details: see xref:writing-rules-mk[the writing +rules]. + +[[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: +** +md5+, +sha1+, +sha224+, +sha256+, +sha384+, +sha512+, +none+ +* the hash of the file: +** for +none+, one or more non-space chars, usually just the string +xxx+ +** for +md5+, 32 hexadecimal characters +** 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. + +.Note +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 (e.g. +sha1+ and +sha512+), then it is +best to add all those hashes in the +.hash+ file. If upstream does not +provide any hash, or only provides an +md5+ hash, then compute at least one +strong hash yourself (preferably +sha256+, but not +md5+), and mention +this in a comment line above the hashes. + +.Note +If +libfoo+ is from GitHub (see xref:github-download-url[] for details), we +can only accept a +.hash+ file if the package is a released (e.g. uploaded +by the maintainer) tarball. Otherwise, the automatically generated tarball +may change over time, and thus its hashes may be different each time it is +downloaded, causing a +.hash+ mismatch for that tarball. + +.Note +The number of spaces does not matter, so one can use spaces (or tabs) to +properly align the different fields. + +The +none+ hash type is reserved to those archives downloaded from a +repository, like a 'git clone', a 'subversion checkout'... or archives +downloaded with the xref:github-download-url[github helper]. + +The example below defines a +sha1+ and a +sha256+ published by upstream for +the main +libfoo-1.2.3.tar.bz2+ tarball, an +md5+ from upstream and a +locally-computed +sha256+ hashes for a binary blob, a +sha256+ for a +downloaded patch, and an archive with no hash: + +---- +# 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 + +# md5 from: http://www.foosoftware.org/download/libfoo-1.2.3.tar.bz2.md5, sha256 locally computed: +md5 2d608f3c318c6b7557d551a5a09314f03452f1a1 libfoo-data.bin +sha256 01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b libfoo-data.bin + +# Locally computed: +sha256 ff52101fb90bbfc3fe9475e425688c660f46216d7e751c4bbdb1dc85cdccacb9 libfoo-fix-blabla.patch + +# No hash for 1234, comes from the github-helper: +none xxx libfoo-1234.tar.gz +---- + +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, Buildroot considers this an error and aborts. However, +the downloaded file is left in the download directory since this +typically indicates that the +.hash+ file is wrong but the downloaded +file is probably OK. + +Sources that are downloaded from a version control system (git, subversion, +etc...) can not have a hash, because the version control system and tar +may not create exactly the same file (dates, files ordering...), so the +hash could be wrong even for a valid download. Therefore, the hash check +is entirely skipped for such sources. + +If the +.hash+ file is missing, then no check is done at all.