1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc: 3 4== Frequently Asked Questions & Troubleshooting 5 6[[faq-boot-hang-after-starting]] 7=== The boot hangs after 'Starting network...' 8 9If the boot process seems to hang after the following messages 10(messages not necessarily exactly similar, depending on the list of 11packages selected): 12 13------------------------ 14Freeing init memory: 3972K 15Initializing random number generator... done. 16Starting network... 17Starting dropbear sshd: generating rsa key... generating dsa key... OK 18------------------------ 19 20then it means that your system is running, but didn't start a shell on 21the serial console. In order to have the system start a shell on your 22serial console, you have to go into the Buildroot configuration, in 23+System configuration+, modify +Run a getty (login prompt) after boot+ 24and set the appropriate port and baud rate in the +getty options+ 25submenu. This will automatically tune the +/etc/inittab+ file of the 26generated system so that a shell starts on the correct serial port. 27 28[[faq-no-compiler-on-target]] 29=== Why is there no compiler on the target? 30 31It has been decided that support for the _native compiler on the 32target_ would be stopped from the Buildroot-2012.11 release because: 33 34* this feature was neither maintained nor tested, and often broken; 35* this feature was only available for Buildroot toolchains; 36* Buildroot mostly targets _small_ or _very small_ target hardware 37 with limited resource onboard (CPU, ram, mass-storage), for which 38 compiling on the target does not make much sense; 39* Buildroot aims at easing the cross-compilation, making native 40 compilation on the target unnecessary. 41 42If you need a compiler on your target anyway, then Buildroot is not 43suitable for your purpose. In such case, you need a _real 44distribution_ and you should opt for something like: 45 46* http://www.openembedded.org[openembedded] 47* https://www.yoctoproject.org[yocto] 48* http://www.emdebian.org[emdebian] 49* https://fedoraproject.org/wiki/Architectures[Fedora] 50* http://en.opensuse.org/Portal:ARM[openSUSE ARM] 51* http://archlinuxarm.org[Arch Linux ARM] 52* ... 53 54[[faq-no-dev-files-on-target]] 55=== Why are there no development files on the target? 56 57Since there is no compiler available on the target (see 58xref:faq-no-compiler-on-target[]), it does not make sense to waste 59space with headers or static libraries. 60 61Therefore, those files are always removed from the target since the 62Buildroot-2012.11 release. 63 64[[faq-no-doc-on-target]] 65=== Why is there no documentation on the target? 66 67Because Buildroot mostly targets _small_ or _very small_ target 68hardware with limited resource onboard (CPU, ram, mass-storage), it 69does not make sense to waste space with the documentation data. 70 71If you need documentation data on your target anyway, then Buildroot 72is not suitable for your purpose, and you should look for a _real 73distribution_ (see: xref:faq-no-compiler-on-target[]). 74 75[[faq-why-not-visible-package]] 76=== Why are some packages not visible in the Buildroot config menu? 77 78If a package exists in the Buildroot tree and does not appear in the 79config menu, this most likely means that some of the package's 80dependencies are not met. 81 82To know more about the dependencies of a package, search for the 83package symbol in the config menu (see xref:make-tips[]). 84 85Then, you may have to recursively enable several options (which 86correspond to the unmet dependencies) to finally be able to select 87the package. 88 89If the package is not visible due to some unmet toolchain options, 90then you should certainly run a full rebuild (see xref:make-tips[] for 91more explanations). 92 93[[faq-why-not-use-target-as-chroot]] 94=== Why not use the target directory as a chroot directory? 95 96There are plenty of reasons to *not* use the target directory a chroot 97one, among these: 98 99* file ownerships, modes and permissions are not correctly set in the 100 target directory; 101* device nodes are not created in the target directory. 102 103For these reasons, commands run through chroot, using the target 104directory as the new root, will most likely fail. 105 106If you want to run the target filesystem inside a chroot, or as an NFS 107root, then use the tarball image generated in +images/+ and extract it 108as root. 109 110[[faq-no-binary-packages]] 111=== Why doesn't Buildroot generate binary packages (.deb, .ipkg...)? 112 113One feature that is often discussed on the Buildroot list is the 114general topic of "package management". To summarize, the idea 115would be to add some tracking of which Buildroot package installs 116what files, with the goals of: 117 118 * being able to remove files installed by a package when this package 119 gets unselected from the menuconfig; 120 121 * being able to generate binary packages (ipk or other format) that 122 can be installed on the target without re-generating a new root 123 filesystem image. 124 125In general, most people think it is easy to do: just track which package 126installed what and remove it when the package is unselected. However, it 127is much more complicated than that: 128 129 * It is not only about the +target/+ directory, but also the sysroot in 130 +host/<tuple>/sysroot+ and the +host/+ directory itself. All files 131 installed in those directories by various packages must be tracked. 132 133 * When a package is unselected from the configuration, it is not 134 sufficient to remove just the files it installed. One must also 135 remove all its reverse dependencies (i.e. packages relying on it) 136 and rebuild all those packages. For example, package A depends 137 optionally on the OpenSSL library. Both are selected, and Buildroot 138 is built. Package A is built with crypto support using OpenSSL. 139 Later on, OpenSSL gets unselected from the configuration, but 140 package A remains (since OpenSSL is an optional dependency, this 141 is possible.) If only OpenSSL files are removed, then the files 142 installed by package A are broken: they use a library that is no 143 longer present on the target. Although this is technically doable, 144 it adds a lot of complexity to Buildroot, which goes against the 145 simplicity we try to stick to. 146 147 * In addition to the previous problem, there is the case where the 148 optional dependency is not even known to Buildroot. For example, 149 package A in version 1.0 never used OpenSSL, but in version 2.0 it 150 automatically uses OpenSSL if available. If the Buildroot .mk file 151 hasn't been updated to take this into account, then package A will 152 not be part of the reverse dependencies of OpenSSL and will not be 153 removed and rebuilt when OpenSSL is removed. For sure, the .mk file 154 of package A should be fixed to mention this optional dependency, 155 but in the mean time, you can have non-reproducible behaviors. 156 157 * The request is to also allow changes in the menuconfig to be 158 applied on the output directory without having to rebuild 159 everything from scratch. However, this is very difficult to achieve 160 in a reliable way: what happens when the suboptions of a package 161 are changed (we would have to detect this, and rebuild the package 162 from scratch and potentially all its reverse dependencies), what 163 happens if toolchain options are changed, etc. At the moment, what 164 Buildroot does is clear and simple so its behaviour is very 165 reliable and it is easy to support users. If configuration changes 166 done in menuconfig are applied after the next make, then it has to 167 work correctly and properly in all situations, and not have some 168 bizarre corner cases. The risk is to get bug reports like "I have 169 enabled package A, B and C, then ran make, then disabled package 170 C and enabled package D and ran make, then re-enabled package C 171 and enabled package E and then there is a build failure". Or worse 172 "I did some configuration, then built, then did some changes, 173 built, some more changes, built, some more changes, built, and now 174 it fails, but I don't remember all the changes I did and in which 175 order". This will be impossible to support. 176 177For all these reasons, the conclusion is that adding tracking of 178installed files to remove them when the package is unselected, or to 179generate a repository of binary packages, is something that is very 180hard to achieve reliably and will add a lot of complexity. 181 182On this matter, the Buildroot developers make this position statement: 183 184 * Buildroot strives to make it easy to generate a root filesystem (hence 185 the name, by the way.) That is what we want to make Buildroot good at: 186 building root filesystems. 187 188 * Buildroot is not meant to be a distribution (or rather, a distribution 189 generator.) It is the opinion of most Buildroot developers that this 190 is not a goal we should pursue. We believe that there are other tools 191 better suited to generate a distro than Buildroot is. For example, 192 http://openembedded.org/[Open Embedded], or https://openwrt.org/[openWRT], 193 are such tools. 194 195 * We prefer to push Buildroot in a direction that makes it easy (or even 196 easier) to generate complete root filesystems. This is what makes 197 Buildroot stands out in the crowd (among other things, of course!) 198 199 * We believe that for most embedded Linux systems, binary packages are 200 not necessary, and potentially harmful. When binary packages are 201 used, it means that the system can be partially upgraded, which 202 creates an enormous number of possible combinations of package 203 versions that should be tested before doing the upgrade on the 204 embedded device. On the other hand, by doing complete system 205 upgrades by upgrading the entire root filesystem image at once, 206 the image deployed to the embedded system is guaranteed to really 207 be the one that has been tested and validated. 208 209[[faq-speeding-up-build]] 210=== How to speed-up the build process? 211 212Since Buildroot often involves doing full rebuilds of the entire 213system that can be quite long, we provide below a number of tips to 214help reduce the build time: 215 216 * Use a pre-built external toolchain instead of the default Buildroot 217 internal toolchain. By using a pre-built Linaro toolchain (on ARM) 218 or a Sourcery CodeBench toolchain (for ARM, x86, x86-64, MIPS, 219 etc.), you will save the build time of the toolchain at each 220 complete rebuild, approximately 15 to 20 minutes. Note that 221 temporarily using an external toolchain does not prevent you to 222 switch back to an internal toolchain (that may provide a higher 223 level of customization) once the rest of your system is working; 224 225 * Use the +ccache+ compiler cache (see: xref:ccache[]); 226 227 * Learn about rebuilding only the few packages you actually care 228 about (see xref:rebuild-pkg[]), but beware that sometimes full 229 rebuilds are anyway necessary (see xref:full-rebuild[]); 230 231 * Make sure you are not using a virtual machine for the Linux system 232 used to run Buildroot. Most of the virtual machine technologies are 233 known to cause a significant performance impact on I/O, which is 234 really important for building source code; 235 236 * Make sure that you're using only local files: do not attempt to do 237 a build over NFS, which significantly slows down the build. Having 238 the Buildroot download folder available locally also helps a bit. 239 240 * Buy new hardware. SSDs and lots of RAM are key to speeding up the 241 builds. 242 243 * Experiment with top-level parallel build, see 244 xref:top-level-parallel-build[]. 245