From cc02514f954e8280c010044320790caed698174a Mon Sep 17 00:00:00 2001 From: Samuel Martin Date: Sun, 11 Nov 2012 03:14:50 +0000 Subject: manual: faq.txt: rework and update Also rename faq.txt -> faq-troubleshooting.txt Signed-off-by: Samuel Martin Signed-off-by: Peter Korsgaard --- docs/manual/faq-troubleshooting.txt | 134 ++++++++++++++++++++++++++++++++++++ docs/manual/faq.txt | 59 ---------------- docs/manual/manual.txt | 4 +- 3 files changed, 136 insertions(+), 61 deletions(-) create mode 100644 docs/manual/faq-troubleshooting.txt delete mode 100644 docs/manual/faq.txt diff --git a/docs/manual/faq-troubleshooting.txt b/docs/manual/faq-troubleshooting.txt new file mode 100644 index 000000000..6911c55e6 --- /dev/null +++ b/docs/manual/faq-troubleshooting.txt @@ -0,0 +1,134 @@ +// -*- 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. diff --git a/docs/manual/faq.txt b/docs/manual/faq.txt deleted file mode 100644 index 97a754bbf..000000000 --- a/docs/manual/faq.txt +++ /dev/null @@ -1,59 +0,0 @@ -Frequently Asked Questions -========================== - -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. - -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. - -How to add 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///tarball/ ------------------------- - -If the package version matches a tag, then this tag should be used to -identify the version: - ------------------------- -FOO_VERSION = v1.0 -FOO_SITE = http://github.com///tarball/$(FOO_VERSION) ------------------------- diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt index 00bd0372e..4df165734 100644 --- a/docs/manual/manual.txt +++ b/docs/manual/manual.txt @@ -17,10 +17,10 @@ include::starting-up.txt[] include::working-with.txt[] +include::faq-troubleshooting.txt[] + include::going-further.txt[] include::developer-guide.txt[] -include::faq.txt[] - include::appendix.txt[] -- cgit v1.2.3