// -*- mode:doc; -*-

Frequently Asked Questions & Troubleshooting
============================================

[[faq-boot-hang-after-starting]]
The boot hangs after 'Starting network...'
------------------------------------------

If the boot process seems to hand after the following messages
(messages not necessarily exactly similar, depending on the list of
packages selected):

------------------------
Freeing init memory: 3972K
Initializing random number generator... done.
Starting network...
Starting dropbear sshd: generating rsa key... generating dsa key... OK
------------------------

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
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
the correct serial port.

[[faq-module-init-tool-build-failure]]
module-init-tools fails to build with 'cannot find -lc'
-------------------------------------------------------

If the build of +module-init-tools+ for the host fails with:

------------------------
/usr/bin/ld: cannot find -lc
------------------------

then probably you are running a Fedora (or similar) distribution, and
you should install the +glibc-static+ package. This is because the
+module-init-tools+ build process wants to link statically against the
C library.

[[faq-no-compiler-on-target]]
Why there is 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:

* this feature was not 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
  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:

* http://www.openembedded.org[openembedded]
* https://www.yoctoproject.org[yocto]
* http://www.emdebian.org[emdebian]
* https://fedoraproject.org/wiki/Architectures[Fedora]
* http://en.opensuse.org/Portal:ARM[openSUSE ARM]
* http://archlinuxarm.org[Arch Linux ARM]
* ...

[[faq-no-dev-files-on-target]]
Why there is 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
space with headers or static libraries.

Therefore, those files are always removed from the target since the
Buildroot-2012.11 release.

[[faq-no-doc-on-target]]
Why there is no documentation on the target?
--------------------------------------------

Because Buildroot mostly targets _small_ or _very small_ target
hardware with limited resource onboard (CPU, ram, mass-storage), it
does not make sense to waste space with the documentation data.

If you need documentation data on your target anyway, then Buildroot
is not suitable for your purpose, and you should look for a _real
distribution_ (see: xref:faq-no-compiler-on-target[]).

[[faq-depends-on-vs-select]]
+Config.in+: _depends on_ vs _select_
-------------------------------------

When adding a new package to Buildroot, you will most likely have to
deal with expressing the dependencies of this package.

In the +Config.in+ file, dependencies may be expressed following two
semantics.
See xref:depends-on-vs-select[].

[[faq-why-not-visible-package]]
Why some packages are not visible in the Buildroot config menu?
---------------------------------------------------------------

If a package exists in the Buildroot tree and does not appears 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[]).

Then, you may have to recursively enable several options (which
correspond to the unmeet dependencies) to finally be able to select
the package.

If the package is not visible due to some unmeet toolchain options,
then you should certainly run a full rebuild (see xref:make-tips[] for
more explanations).

[[faq-why-not-use-target-as-chroot]]
Why not use the target directory as a chroot directory?
-------------------------------------------------------

There are plenty of reason to *not* use the target directory a chroot
one, among these:

* files' owners, modes and permissions are not correctly set in the
  target directory;
* devices 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.