Minor grammatical and spelling tweaks to the manual content.
Signed-off-by: Simon Dawson <spdawson@gmail.com>
Acked-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Acked-by: Samuel Martin <s.martin49@gmail.com>
Signed-off-by: Peter Korsgaard <jacmet@sunsite.dk>
~~~~~~~~~~
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
+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
Overall, for package library dependencies, +select+ should be
preferred.
-Note that such dependencies will make sure that the dependency option
+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 formating details: see xref:writing-rules-config-in[the
+Further formatting details: see xref:writing-rules-config-in[the
writing rules].
The +.mk+ file
* *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 requires a little more work from the
+ autotools-based packages, but require 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
Many packages that support internationalization use the gettext
library. Dependencies for this library are fairly complicated and
-therefore, deserves some explanation.
+therefore, deserve some explanation.
-The 'uClibc' C library doesn't implement gettext functionality,
+The 'uClibc' C library doesn't implement gettext functionality;
therefore with this C library, a separate gettext must be compiled. On
the other hand, the 'glibc' C library does integrate its own gettext,
-and in this case, the separate gettext library should not be compiled,
+and in this case the separate gettext library should not be compiled,
because it creates various kinds of build failures.
Additionally, some packages (such as +libglib2+) do require gettext
Package name, config entry name and makefile variable relationship
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-In Buildroot, there are some relation between:
+In Buildroot, there is some relationship between:
* the _package name_, which is the package directory name (and the
name of the +*.mk+ file);
* the makefile variable prefix.
-Thus, it is mandatory to keep consistency between all this stuff,
-matching the following rules:
+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.:
+foo-bar_boo+);
To achieve NFS-boot, enable _tar root filesystem_ in the _Filesystem
images_ menu.
-After complete build, just run the following commands to setup the
+After a complete build, just run the following commands to setup the
NFS-root directory:
-------------------
root of the Buildroot source tree. Move this file into the +configs/+
directory, and rename it +MYBOARD_defconfig+.
-It is recommended to use as much as possible upstream versions of the
-Linux kernel and bootloaders, and to use as much as possible default
-kernel and bootloader configurations. If they are incorrect for your
-platform, we encourage you to send fixes to the corresponding upstream
+It is recommended to use upstream versions of the Linux kernel and
+bootloaders where possible, and also to use default kernel and bootloader
+configurations if possible. If the defaults are incorrect for
+your platform, we encourage you to send fixes to the corresponding upstream
projects.
However, in the mean time, you may want to store kernel or bootloader
~~~~~~~~~~~~~~~~~~~~
As default, everything built by Buildroot is stored in the directory
-+output+ in the buildroot tree.
++output+ in the Buildroot tree.
Buildroot also supports building out of tree with a syntax similar to
the Linux kernel. To use it, add +O=<directory>+ to the make command
+
Note that the uClibc configuration file can also be set from the
configuration interface, so through the Buildroot .config file; this
- the actual recommended way of setting it.
+ is the recommended way of setting it.
+
* +BUSYBOX_CONFIG_FILE=<path/to/.config>+, path to
the Busybox configuration file.
+
Note that the Busybox configuration file can also be set from the
configuration interface, so through the Buildroot .config file; this
- the actual recommended way of setting it.
+ is the recommended way of setting it.
+
* +BUILDROOT_DL_DIR+ to override the directory in which
Buildroot stores/retrieves downloaded files
+
Note that the Buildroot download directory can also be set from the
configuration interface, so through the Buildroot .config file; this
- the actual recommended way of setting it.
+ is the recommended way of setting it.
An example that uses config files located in the toplevel directory and
in your $HOME:
Note that +git+ should be configured to use your mail account.
To configure +git+, see +man git-send-email+ or google it.
-Make sure posted *patches are not line-wrapped*, otherwise it cannot
+Make sure posted *patches are not line-wrapped*, otherwise they cannot
easily be applied. In such a case, fix your e-mail client, or better,
use +git send-email+ to send your patches.
Autobuild
---------
-The Buildroot community is currently setting up automatic build i
-order to test more and more configuration. All build results are
+The Buildroot community is currently setting up automatic builds in
+order to test more and more configurations. All build results are
available at http://autobuild.buildroot.org[]
-A way to contribute is fixing broken builds.
+A good way to contribute is by fixing broken builds.
In the commit message of a patch fixing an _autobuild_, add a
reference to the _build result directory_ (the +dir+ link in the _data
Reporting issues/bugs, get help
-------------------------------
-Before reporting some issues, please chek
-xref:mailing-list-subscribe[the mailing list archive] in case someone had
+Before reporting any issue, please check
+xref:mailing-list-subscribe[the mailing list archive] in case someone has
already reported and fixed a similar problem.
-Whatever the way you choose to report some bugs or get help,
+However you choose to report bugs or get help,
xref:bugtracker[opening a bug] or
-xref:mailing-list-subscribe[send a mail to the mailing list], there is
-a number of detail to provide in order to help people reproduce and
+xref:mailing-list-subscribe[send a mail to the mailing list], there are
+a number of details to provide in order to help people reproduce and
find a solution to the issue.
-Try to think as you would be the one who will help someone else; in
+Try to think as if you were trying to help someone else; in
that case, what would you need?
Here is a short list of details to provide in such case:
Additionnally, your can add the +.config+ file.
-If some of these details are too large, do not hesitate to use some
-pastebin service (see
-http://en.wikipedia.org/wiki/Comparison_of_pastebins[]).
+If some of these details are too large, do not hesitate to use a
+pastebin service (see http://www.similarsitesearch.com/alternatives-to/pastebin.com[]).
* Do an initial compilation of Buildroot without trying to customize
uClibc.
-* Invoke +make uclibc-menuconfig+. The nice configuration assistant,
+* Invoke +make uclibc-menuconfig+. The nice configuration assistant,
similar to the one used in the Linux kernel or Buildroot,
appears. Make your configuration changes as appropriate.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It might be useful to know that the various tarballs that are
-downloaded by the Makefiles are all stored in the +DL_DIR+ which by
-default is the +dl+ directory. It's useful, for example, if you want
+downloaded by the Makefiles are all stored in +DL_DIR+ which by
+default is the +dl+ directory. This is useful, for example, if you want
to keep a complete version of Buildroot which is known to be working
with the associated tarballs. This will allow you to regenerate the
toolchain and the target filesystem with exactly the same versions.
----------------------
When developing an embedded system, there are a number of choices to
-do:
+address:
* the cross-toolchain: target architecture/C library/...
* the bootloader
* the package selection (busybox vs. "real" programs, ...)
* ...
-Some of them may be influenced by the target hardware.
+Some of these may be influenced by the target hardware.
-Some of them may also add some constraints when you will develop the
-final application for what your target is designed (e.g. some
-functions may be provided by soem C libraries and missing in some
-others, ...). So, these choices should be carefully done.
+Some of the choices may also add some constraints when you develop the
+final application for which your target is designed (e.g. some
+functions may be provided by some C libraries and missing in some
+others, ...). So, these choices should be carefully made.
-Buildroot allows to set most of these options to fit your needs.
+Buildroot allows you to set most of these options to fit your needs.
Moreover, Buildroot provides an infrastructure for reproducing the
build process of your kernel, cross-toolchain, and embedded root
The boot hangs after 'Starting network...'
------------------------------------------
-If the boot process seems to hand after the following messages
+If the boot process seems to hang after the following messages
(messages not necessarily exactly similar, depending on the list of
packages selected):
then it means that your system is running, but didn't start a shell on
the serial console. In order to have the system start a shell on your
-serial console, you have to go in the Buildroot configuration, +System
+serial console, you have to go into the Buildroot configuration, +System
configuration+, and modify +Port to run a getty (login prompt) on+ and
+Baudrate to use+ as appropriate. This will automatically tune the
+/etc/inittab+ file of the generated system so that a shell starts on
C library.
[[faq-no-compiler-on-target]]
-Why there is no compiler on the target?
+Why is there no compiler on the target?
---------------------------------------
-It has been decided that the support of the _native compiler for the
-target_ would be stopped since the Buildroot-2012.11 release because:
+It has been decided that support for the _native compiler on the
+target_ would be stopped from the Buildroot-2012.11 release because:
-* this feature was not maintained nor tested and often broken;
+* this feature was neither maintained nor tested, and often broken;
* this feature was only available for Buildroot toolchains;
* Buildroot mostly targets _small_ or _very small_ target hardware
- with limited resource onboard (CPU, ram, mass-storage), on which
+ with limited resource onboard (CPU, ram, mass-storage), for which
compiling does not make much sense.
If you need a compiler on your target anyway, then Buildroot is not
suitable for your purpose. In such case, you need a _real
-distribution_ and you should for something like:
+distribution_ and you should opt for something like:
* http://www.openembedded.org[openembedded]
* https://www.yoctoproject.org[yocto]
* ...
[[faq-no-dev-files-on-target]]
-Why there is no development files on the target?
-------------------------------------------------
+Why are there no development files on the target?
+-------------------------------------------------
Since there is no compiler available on the target (see
xref:faq-no-compiler-on-target[]), it does not make sense to waste
Buildroot-2012.11 release.
[[faq-no-doc-on-target]]
-Why there is no documentation on the target?
+Why is there no documentation on the target?
--------------------------------------------
Because Buildroot mostly targets _small_ or _very small_ target
See xref:depends-on-vs-select[].
[[faq-why-not-visible-package]]
-Why some packages are not visible in the Buildroot config menu?
+Why are some packages not visible in the Buildroot config menu?
---------------------------------------------------------------
-If a package exists in the Buildroot tree and does not appears in the
+If a package exists in the Buildroot tree and does not appear in the
config menu, this most likely means that some of the package's
dependencies are not met.
-To know more about the dependencies of a package, search the package
-symbol using in teh config menu (see xref:make-tips[]).
+To know more about the dependencies of a package, search for the
+package symbol in the config menu (see xref:make-tips[]).
Then, you may have to recursively enable several options (which
-correspond to the unmeet dependencies) to finally be able to select
+correspond to the unmet dependencies) to finally be able to select
the package.
-If the package is not visible due to some unmeet toolchain options,
+If the package is not visible due to some unmet toolchain options,
then you should certainly run a full rebuild (see xref:make-tips[] for
more explanations).
Why not use the target directory as a chroot directory?
-------------------------------------------------------
-There are plenty of reason to *not* use the target directory a chroot
+There are plenty of reasons to *not* use the target directory a chroot
one, among these:
-* files' owners, modes and permissions are not correctly set in the
+* file ownerships, modes and permissions are not correctly set in the
target directory;
-* devices nodes are not created in the target directory.
+* device nodes are not created in the target directory.
-Because of that, commands run in through chroot, using the target
-directory as new root, will fail.
+For these reasons, commands run through chroot, using the target
+directory as the new root, would fail.
http://webchat.freenode.net[].
When asking for help on IRC, share relevant logs or pieces of code
-using a code sharing website (see
-http://en.wikipedia.org/wiki/Comparison_of_pastebins[], and pick one).
+using a code sharing website.
[[patchwork]]
Patchwork
About Buildroot
===============
-Buildroot provides a full featured environment for cross-development.
+Buildroot provides a full-featured environment for cross-development.
Buildroot is able to generate a cross-compilation toolchain, a root
filesystem, a Linux kernel image and a bootloader for your target.
-Buildroot can be used for any combinaison of these options,
+Buildroot can be used for any combination of these options,
independently.
Buildroot is useful mainly for people working with embedded systems.
processors, MIPS processors, ARM processors, etc.
Buildroot supports numerous processors and their variants; it also
-comes with default configuration for several boards available
-off-the-shelf. Besides, a number of third-party projects are based on
+comes with default configurations for several boards available
+off-the-shelf. Besides this, a number of third-party projects are based on,
or develop their BSP footnote:[BSP: Board Software Package] or
SDK footnote:[SDK: Standard Development Kit] on top of Buildroot.
bootloaders) contain opensource software, released under various licenses.
Using opensource software gives you the freedom to build rich embedded
-systems choosing from a wide range of packages, but also gives some
+systems, choosing from a wide range of packages, but also imposes some
obligations that you must know and honour.
Some licenses require you to publish the license text in the documentation of
-your product. Other require you to redistribute the source code of the
+your product. Others require you to redistribute the source code of the
software to those that receive your product.
-The exact requirements of each license is documented in each package, and it is
-your (or your legal office's) responsibility to comply with these requirements.
+The exact requirements of each license are documented in each package, and
+it is your responsibility (or that of your legal office) to comply with those
+requirements.
To make this easier for you, Buildroot can collect for you some material you
-will probably need. To produce this material, after you configured Buildroot
-with +make menuconfig+, +make xconfig+ or +make gconfig+, run:
+will probably need. To produce this material, after you have configured
+Buildroot with +make menuconfig+, +make xconfig+ or +make gconfig+, run:
--------------------
make legal-info
Buildroot sources and are not duplicated in the +sources/+ subdirectory.
* A manifest file listing the configured packages, their version, license and
related information.
- Some of these information might be not defined in Buildroot; in this case
- they are clearly marked as "unknown" or similar.
+ Some of this information might not be defined in Buildroot; such items are
+ clearly marked as "unknown" or similar.
* A +licenses/+ subdirectory, which contains the license text of packages.
If the license file(s) are not defined in Buildroot, the file is not produced
and a warning in the +README+ indicates this.
Please note that the aim of the +legal-info+ feature of Buildroot is to
produce all the material that is somehow relevant for legal compliance with the
package licenses. Buildroot does not try to produce the exact material that
-you must somehow make public. It does surely produce some more material than is
+you must somehow make public. Certainly, more material is produced than is
needed for a strict legal compliance. For example, it produces the source code
for packages released under BSD-like licenses, that you might not want to
redistribute in source form.
installation of the executable', and as such it is considered part of the
material that must be redistributed.
-Keep in mind this is only the Buildroot developers' opinion, and you should
-consult your legal department or lawyer in case of any doubt.
+Keep in mind that this is only the Buildroot developers' opinion, and you
+should consult your legal department or lawyer in case of any doubt.
'make' tips
-----------
-Because Buildroot is a set of Makefiles and patches, there are few
-things useful to know, such as:
+Because Buildroot is a set of Makefiles and patches, there are a few
+things that are useful to know, such as:
+make *config+ commands offer a search tool. Read the help message in
-the different frontend menu to know how to use it:
+the different frontend menus to know how to use it:
* in _menuconfig_, search tool is called by pressing +/+;
* in _xconfig_, search tool is called by pressing +ctrl+ + +f+.
-The result of the search show the help message of the matching items.
+The result of the search shows the help message of the matching items.
-Display all command executed by make:
+Display all commands executed by make:
--------------------
$ make V=0|1 <target>
--------------------
Note that if +ccache+ is enabled, running +make clean|distclean+ does
-not empty the cache of compiler used by Buildroot. To delete it, refer
+not empty the compiler cache used by Buildroot. To delete it, refer
to xref:ccache[].
Makedev syntax documentation
----------------------------
-The makedev syntax is used across several places in Buildroot to
-define changes to be made for permissions or which device files to
-create and how to create them, in order to avoid to call mkdnod every
-now and then.
+The makedev syntax is used in several places in Buildroot to
+define changes to be made for permissions, or which device files to
+create and how to create them, in order to avoid calls to mknod.
-This syntax is derived from the makedev utility, and a more complete
+This syntax is derived from the makedev utility, and more complete
documentation can be found in the +package/makedevs/README+ file.
It takes the form of a line for each file, with the following layout:
|name |type |mode |uid |gid |major |minor |start |inc |count
|===========================================================
-There is a few non-trivial blocks here:
+There are a few non-trivial blocks here:
- +name+ is the path to the file you want to create/modify
- +type+ is the type of the file, being one of :
* c: a character device file
* b: a block device file
* p: a named pipe
-- +mode+, +uid+ and +gid+ are the usual permissions stuff
+- +mode+, +uid+ and +gid+ are the usual permissions settings
- +major+ and +minor+ are here for device files
-- +start+, +inc+ and +count+ are when you want to create a whole batch
+- +start+, +inc+ and +count+ are for when you want to create a batch
of files, and can be reduced to a loop, beginning at +start+,
incrementing its counter by +inc+ until it reaches +count+
-Let's say you want to change the permissions of a given file, using
+Let's say you want to change the permissions of a given file; using
this syntax, you will need to put:
-------------------------------------------------------------------
/usr/bin/foobar f 644 0 0 - - - - -
| +rebuild+ | Rebuild only necessary binaries and install them
again
-| +reconfigure+ | Run again the configure command, then rebuild
+| +reconfigure+ | Re-run the configure command, then rebuild
only necessary binaries, and lastly install them again
|===================================================
Buildroot.
Buildroot offers an infrastructure to automatically handle this during
-the builds. It support several ways of applying patch sets:
+the builds. It supports several ways of applying patch sets:
-Provinding patches
-~~~~~~~~~~~~~~~~~~
+Providing patches
+~~~~~~~~~~~~~~~~~
-Additionnal tarball
-^^^^^^^^^^^^^^^^^^^
+Additional tarball
+^^^^^^^^^^^^^^^^^^
-If there needs to apply a patch set available as a tarball and
-
downloadable, then add the patch tarball to the +<packagename>_PATCH+
+If it is necessary to apply a patch set available as a downloadable
+
tarball, then add the patch tarball to the +<packagename>_PATCH+
variable.
Note that the patch tarballs are downloaded from the same site as the
Within Buildroot
^^^^^^^^^^^^^^^^
-Most of the patches are provided within Buildroot, in the package
-directory, because they aim to fix cross-compilation, +libc+ support,
-or whatever the reason is.
+Most patches are provided within Buildroot, in the package
+directory; these typically aim to fix cross-compilation, +libc+ support,
+or other such issues.
These patch files should have the extension +*.patch+.
-A +series+ file, like +quilt+ uses it, may also be added in the
+A +series+ file, as used by +quilt+, may also be added in the
package directory. In that case, the +series+ file defines the patch
application order.
. Run the +<packagename>_PRE_PATCH_HOOKS+ commands if defined;
-. Cleanup the build directory from any existing +*.rej+ files;
+. Cleanup the build directory, removing any existing +*.rej+ files;
. If +<packagename>_PATCH+ is defined, then patches from these
tarballs are applied;
Format and licensing of the package patches
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Patches are released under the same license the software that is
+Patches are released under the same license as the software that is
modified.
-A message explaining what does the patch and why should be add in the
-patch's header.
+A message explaining what the patch does, and why it is needed, should
+be added in the header commentary of the patch.
You should add a +signed-off-by+ statement in the header of the each
-patch to help keeping track of the changes.
+patch to help with keeping track of the changes.
-If the software is under versionning, it is recommended to use the SCM
-software to generate the patch set.
+If the software is under version control, it is recommended to use the
+SCM software to generate the patch set.
Otherwise, concatenate the header with the output of the
+diff -purN source.c.orig source.c+ command.
Integrating patches found on the Web
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-When integrating a patch whom you are not the author, you have to add
-few things in the header of the patch itself.
+When integrating a patch of which you are not the author, you have to
+add a few things in the header of the patch itself.
-Depending on whether the patch has been pick-up from the project
+Depending on whether the patch has been obtained from the project
repository itself, or from somewhere on the web, add one of the
following tags:
Fetch from: <some url>
---------------
-It is also possible to add few words about the changes that may have
-been necessary if any.
+It is also sensible to add a few words about any changes to the patch
+that may have been necessary.
System requirements
-------------------
-Buildroot is design to run on Linux system.
+Buildroot is designed to run on Linux systems.
Buildroot needs some software to be already installed on the host
-system; hereafter the lists of the mandatory and optional packages
+system; here are the lists of the mandatory and optional packages
(package names may vary between distributions).
-Take care of _installing both runtime and development data_, especially
+Take care to _install both runtime and development data_, especially
for the libraries that may be packaged in 2 distinct packages.
* Source fetching tools:
+
In the official tree, most of the package sources are retrieved
-using +wget+, few are only available through their +git+, +mercurial+,
+using +wget+; a few are only available through their +git+, +mercurial+,
or +svn+ repository.
+
All other source fetching methods are implemented and may be used in a
$ make clean all
---------------
-In what cases, a full rebuild is mandatory:
+In some cases, a full rebuild is mandatory:
* each time the toolchain properties are changed, this includes:
* after removing some libraries from the package selection.
-In what cases, a full rebuild is recommended:
+In some cases, a full rebuild is recommended:
* after adding some libraries to the package selection (otherwise,
some packages that can be optionally linked against those libraries
won't be rebuilt, so they won't support those new available
features).
-In other cases, it is up to you to decide if you should or not run a
+In other cases, it is up to you to decide if you should run a
full rebuild, but you should know what is impacted and understand what
you are doing anyway.
Buildroot infrastructures.
- Only toolchain packages remain using custom makefiles (i.e. do not
use any Buildroot infrastructure).
-- Most packages and toolchain packages, if not all, will progressively
+- Most, if not all, packages and toolchain packages will progressively
be ported over to the generic, autotools or CMake infrastructure,
making it much easier to rebuild individual packages.
* Download source files (as required)
* Configure, build and install the cross-compiling toolchain using the
- appropriate toolchain backend is used, or simply import a toolchain
- if an external toolchain
+ appropriate toolchain backend, or simply import an external toolchain
* Build/install selected target packages
* Build a kernel image, if selected
* Build a bootloader image, if selected
Writing rules
-------------
-Overall, those writing rules are here to help you add new files in
+Overall, these writing rules are here to help you add new files in
Buildroot or refactor existing ones.
If you slightly modify some existing file, the important thing is
projects / buildroot.git / commitdiff