Commit 65f66c17 authored by Arnout Vandecappelle (Essensium/Mind)'s avatar Arnout Vandecappelle (Essensium/Mind) Committed by Peter Korsgaard
Browse files

manual: various fixes 



Various consistency and correctness improvements.

Also removing some sentences that are not or no longer relevant.

Signed-off-by: default avatarArnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
Acked-by: default avatarSamuel Martin <s.martin49@gmail.com>
Signed-off-by: default avatarPeter Korsgaard <jacmet@sunsite.dk>
parent 1d989faf

docs/manual/adding-packages-conclusion.txt

+2 −1
Original line number Diff line number Diff line
@@ -8,5 +8,6 @@ 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 the Buildroot mailing list!

forget to send a patch to the Buildroot mailing list (see

xref:submitting-patches[])!

docs/manual/adding-packages-directory.txt

+7 −6
Original line number Diff line number Diff line
@@ -9,6 +9,7 @@ your software, for example +libfoo+. 
Some packages have been grouped by topic in a sub-directory:

+multimedia+, +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.in+ file
@@ -32,12 +33,12 @@ 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.



Of course, you can add other sub-options into a +if

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://lxr.free-electrons.com/source/Documentation/kbuild/kconfig-language.txt[]

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
@@ -68,9 +69,9 @@ rules: 
  dependency for dependencies on toolchain options (target

  architecture, MMU support, C library, C++ support, large file

  support, thread support, RPC support, IPV6 support, WCHAR support),

  or for dependencies on "big" things, such as the X.org system. In

  some cases, especially dependency on toolchain options, it is

  recommended to add a +comment+ displayed when the option is not

  or for dependencies on "big" things, such as the X.org system. For

  dependencies on toolchain options, there should be a +comment+ that

  is displayed when the option is not

  enabled, so that the user knows why the package is not available.

  The +depends on+ keyword express the dependency with a forward

  semantic.
@@ -160,7 +161,7 @@ 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

writing rules].

coding style].



The +.mk+ file

^^^^^^^^^^^^^^

docs/manual/adding-packages-generic.txt

+13 −12
Original line number Diff line number Diff line
@@ -151,11 +151,11 @@ information is (assuming the package name is +libfoo+) : 
* +LIBFOO_PATCH+ may contain the name of a patch, that will be

  downloaded from the same location as the tarball indicated in

  +LIBFOO_SOURCE+. If +HOST_LIBFOO_PATCH+ is not specified, it

  defaults to +LIBFOO_PATCH+. Also note that another mechanism is

  available to patch a package: all files of the form

  +packagename-packageversion-description.patch+ present in the

  package directory inside Buildroot will be applied to the package

  after extraction.

  defaults to +LIBFOO_PATCH+. Note that patches that are included

  in Buildroot itself use a different mechanism: all files of the

  form +<packagename>-*.patch+ present in the package directory inside

  Buildroot will be applied to the package after extraction (see

  xref:patch-policy[patching a package]).



* +LIBFOO_SITE+ provides the location of the package, which can be a

  URL or a local filesystem path. HTTP, FTP and SCP are supported URL
@@ -251,9 +251,6 @@ information is (assuming the package name is +libfoo+) : 
  use the same string to make the manifest file uniform.

  Otherwise, describe the license in a precise and concise way, avoiding

  ambiguous names such as +BSD+ which actually name a family of licenses.

  If the root filesystem you generate contains non-opensource packages, you

  can define their license as +PROPRIETARY+: Buildroot will not save any

  licensing info or source code for this package.

  This variable is optional. If it is not defined, +unknown+ will appear in

  the +license+ field of the manifest file for this package.
@@ -265,6 +262,11 @@ information is (assuming the package name is +libfoo+) : 
  to let you know, and +not saved+ will appear in the +license files+ field

  of the manifest file for this package.



* +LIBFOO_REDISTRIBUTE+ can be set to +YES+ (default) or +NO+ to indicate if

  the package source code is allowed to be redistributed. Set it to +NO+ for

  non-opensource packages: Buildroot will not save the source code for this

  package when collecting the +legal-info+.



The recommended way to define these variables is to use the following

syntax:
@@ -292,10 +294,9 @@ different steps of the build process. 
  performed to install the package to the target directory, when the

  package is a target package. The package must install its files to

  the directory given by +$(TARGET_DIR)+. Only the files required for

  'documentation' and 'execution' of the package should be

  installed. Header files should not be installed, they will be copied

  to the target, if the +development files in target filesystem+

  option is selected.

  'execution' of the package have to be

  installed. Header files, static libraries and documentation will be

  removed again when the target filesystem is finalized.



* +LIBFOO_INSTALL_STAGING_CMDS+ lists the actions to be

  performed to install the package to the staging directory, when the

docs/manual/adding-packages-gettext.txt

+12 −8
Original line number Diff line number Diff line
@@ -27,16 +27,20 @@ Therefore, Buildroot defines two configuration options: 
  doesn't provide its own gettext implementation and if locale support

  is enabled



Therefore, packages that unconditionally need gettext should:

Packages that need gettext only when locale support is enabled should:



* Use +select BR2_PACKAGE_GETTEXT if BR2_NEEDS_GETTEXT+

* use +select BR2_PACKAGE_GETTEXT if BR2_NEEDS_GETTEXT_IF_LOCALE+ in the

  +Config.in+ file;



* Use +$(if $(BR2_NEEDS_GETTEXT),gettext)+ in the package

  +DEPENDENCIES+ variable

* use +$(if $(BR2_NEEDS_GETTEXT_IF_LOCALE),gettext)+ in the package

  +DEPENDENCIES+ variable in the +.mk+ file.



Packages that need gettext only when locale support is enabled should:

Packages that unconditionally need gettext (which should be very rare)

should:



* use +select BR2_PACKAGE_GETTEXT if BR2_NEEDS_GETTEXT+ in the +Config.in+

  file;



* Use +select BR2_PACKAGE_GETTEXT if BR2_NEEDS_GETTEXT_IF_LOCALE+

* use +$(if $(BR2_NEEDS_GETTEXT),gettext)+ in the package

  +DEPENDENCIES+ variable in the +.mk+ file.

* Use +$(if $(BR2_NEEDS_GETTEXT_IF_LOCALE),gettext)+ in the package

  +DEPENDENCIES+ variable

docs/manual/adding-packages-tips.txt

+20 −10
Original line number Diff line number Diff line
@@ -19,7 +19,10 @@ In Buildroot, there is some relationship between: 
It is mandatory to maintain consistency between these elements,

using the following rules:



* the _make_ target name will be the _package name_ itself (e.g.:

* the package directory and the +*.mk+ name are the _package name_

  itself (e.g.: +package/foo-bar_boo/foo-bar_boo.mk+);



* the _make_ target name is the _package name_ itself (e.g.:

  +foo-bar_boo+);



* the config entry is the upper case _package name_ with `.` and `-`
@@ -35,15 +38,9 @@ using the following rules: 
How to add a package from github

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^



If the package has no release version, or its version cannot be

identified using tag, then the sha1 of the particular commit should be

used to identify the version (the first 7 characters of the sha1 are

enough):



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

FOO_VERSION = 1234567

FOO_SITE = http://github.com/<user>/<package>/tarball/<branch>

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

Packages on github often don't have a download area with release tarballs.

However, it is possible to download tarballs directly from the repository

on github.



If the package version matches a tag, then this tag should be used to

identify the version:
@@ -52,3 +49,16 @@ identify the version: 
FOO_VERSION = v1.0

FOO_SITE = http://github.com/<user>/<package>/tarball/$(FOO_VERSION)

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



If the package has no release version, or its version cannot be

identified using tag, then the SHA1 of the particular commit should be

used to identify the version (the first 7 characters of the SHA1 are

enough):



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

FOO_VERSION = 1234567

FOO_SITE = http://github.com/<user>/<package>/tarball/<branch>

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



Note that the name of the tarball is the default +foo-1234567.tar.gz+

so it is not necessary to specify it in the +.mk+ file.