diff options
Diffstat (limited to 'docs/manual')
| -rw-r--r-- | docs/manual/adding-packages-directory.txt | 11 | ||||
| -rw-r--r-- | docs/manual/adding-packages-generic.txt | 2 | ||||
| -rw-r--r-- | docs/manual/advanced.txt | 2 | ||||
| -rw-r--r-- | docs/manual/common-usage.txt | 115 | ||||
| -rw-r--r-- | docs/manual/configure.txt | 77 | ||||
| -rw-r--r-- | docs/manual/contribute.txt | 2 | ||||
| -rw-r--r-- | docs/manual/customize-outside-br.txt | 10 | ||||
| -rw-r--r-- | docs/manual/faq-troubleshooting.txt | 100 | ||||
| -rw-r--r-- | docs/manual/make-tips.txt | 6 | ||||
| -rw-r--r-- | docs/manual/package-make-target.txt | 5 | ||||
| -rw-r--r-- | docs/manual/rebuilding-packages.txt | 132 | ||||
| -rw-r--r-- | docs/manual/using-buildroot-development.txt | 84 |
12 files changed, 442 insertions, 104 deletions
diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt index 3dc5395937..6145f54479 100644 --- a/docs/manual/adding-packages-directory.txt +++ b/docs/manual/adding-packages-directory.txt @@ -327,5 +327,16 @@ different way, using different infrastructures: CMake. We cover them through a xref:cmake-package-tutorial[tutorial] and xref:cmake-package-reference[reference]. +* *Makefiles for Python modules*: We have a dedicated infrastructure + for Python modules that use either the +distutils+ or the + +setuptools+ mechanism. We cover them through a + xref:python-package-tutorial[tutorial] and a + xref:python-package-reference[reference]. + +* *Makefiles for Lua modules*: We have a dedicated infrastructure for + Lua modules available through the LuaRocks web site. We cover them + through a xref:luarocks-package-tutorial[tutorial] and a + xref:luarocks-package-reference[reference]. + Further formatting details: see xref:writing-rules-mk[the writing rules]. diff --git a/docs/manual/adding-packages-generic.txt b/docs/manual/adding-packages-generic.txt index 14971b502b..04e589f9af 100644 --- a/docs/manual/adding-packages-generic.txt +++ b/docs/manual/adding-packages-generic.txt @@ -253,7 +253,7 @@ information is (assuming the package name is +libfoo+) : Buildroot should download from +LIBFOO_SITE+ in addition to the main +LIBFOO_SOURCE+ (which usually is a tarball). Buildroot will not do anything with those additional files, except download files: it will - be up to the package recipe to use them from +$(DL_DIR)+. + be up to the package recipe to use them from +$(BR2_DL_DIR)+. * +LIBFOO_SITE_METHOD+ determines the method used to fetch or copy the package source code. In many cases, Buildroot guesses the method diff --git a/docs/manual/advanced.txt b/docs/manual/advanced.txt index 764b71a5c7..fb337f5f71 100644 --- a/docs/manual/advanced.txt +++ b/docs/manual/advanced.txt @@ -11,3 +11,5 @@ include::ccache-support.txt[] include::download-location.txt[] include::package-make-target.txt[] + +include::using-buildroot-development.txt[] diff --git a/docs/manual/common-usage.txt b/docs/manual/common-usage.txt index 127060dc35..a16b887fb6 100644 --- a/docs/manual/common-usage.txt +++ b/docs/manual/common-usage.txt @@ -40,7 +40,13 @@ Or: $ cd /tmp/build; make O=$PWD -C path/to/buildroot -------------------- -All the output files will be located under +/tmp/build+. +All the output files will be located under +/tmp/build+. If the +O+ +path does not exist, Buildroot will create it. + +*Note:* the +O+ path can be either an absolute or a relative path, but if it's +passed as a relative path, it is important to note that it is interpreted +relative to the main Buildroot source directory, *not* the current working +directory. When using out-of-tree builds, the Buildroot +.config+ and temporary files are also stored in the output directory. This means that you can @@ -48,8 +54,8 @@ safely run multiple builds in parallel using the same source tree as long as they use unique output directories. For ease of use, Buildroot generates a Makefile wrapper in the output -directory - so after the first run, you no longer need to pass +O=..+ -and +-C ..+, simply run (in the output directory): +directory - so after the first run, you no longer need to pass +O=<...>+ +and +-C <...>+, simply run (in the output directory): -------------------- $ make <target> @@ -86,9 +92,9 @@ to +make+ or set in the environment: Note that the Buildroot download directory can also be set from the configuration interface, so through the Buildroot +.config+ file; this is the recommended way of setting it. -* +GRAPH_ALT+, if set and non-empty, to use an alternate color-scheme in +* +BR2_GRAPH_ALT+, if set and non-empty, to use an alternate color-scheme in build-time graphs -* +GRAPH_OUT+ to set the filetype of generated graphs, either +pdf+ (the +* +BR2_GRAPH_OUT+ to set the filetype of generated graphs, either +pdf+ (the default), or +png+. An example that uses config files located in the toplevel directory and @@ -143,3 +149,102 @@ of an ext2 filesystem may be corrupted; or, if you have sparse files in your filesystem, those parts may not be all-zeroes when read back). You should only use sparse files when handling files on the build machine, not when transferring them to an actual device that will be used on the target. + +Graphing the dependencies between packages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +[[graph-depends]] + +One of Buildroot's jobs is to know the dependencies between packages, +and make sure they are built in the right order. These dependencies +can sometimes be quite complicated, and for a given system, it is +often not easy to understand why such or such package was brought into +the build by Buildroot. + +In order to help understanding the dependencies, and therefore better +understand what is the role of the different components in your +embedded Linux system, Buildroot is capable of generating dependency +graphs. + +To generate a dependency graph of the full system you have compiled, +simply run: + +------------------------ +make graph-depends +------------------------ + +You will find the generated graph in ++output/graphs/graph-depends.pdf+. + +If your system is quite large, the dependency graph may be too complex +and difficult to read. It is therefore possible to generate the +dependency graph just for a given package: + +------------------------ +make <pkg>-graph-depends +------------------------ + +You will find the generated graph in ++output/graph/<pkg>-graph-depends.pdf+. + +Note that the dependency graphs are generated using the +dot+ tool +from the _Graphviz_ project, which you must have installed on your +system to use this feature. In most distributions, it is available as +the +graphviz+ package. + +By default, the dependency graphs are generated in the PDF +format. However, by passing the +BR2_GRAPH_OUT+ environment variable, you +can switch to other output formats, such as PNG, PostScript or +SVG. All formats supported by the +-T+ option of the +dot+ tool are +supported. + +-------------------------------- +BR2_GRAPH_OUT=svg make graph-depends +-------------------------------- + +Graphing the build duration +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +[[graph-duration]] + +When the build of a system takes a long time, it is sometimes useful +to be able to understand which packages are the longest to build, to +see if anything can be done to speed up the build. In order to help +such build time analysis, Buildroot collects the build time of each +step of each package, and allows to generate graphs from this data. + +To generate the build time graph after a build, run: + +---------------- +make graph-build +---------------- + +This will generate a set of files in +output/graphs+ : + +* +build.hist-build.pdf+, a histogram of the build time for each + package, ordered in the build order. + +* +build.hist-duration.pdf+, a histogram of the build time for each + package, ordered by duration (longest first) + +* +build.hist-name.pdf+, a histogram of the build time for each + package, order by package name. + +* +build.pie-packages.pdf+, a pie chart of the build time per package + +* +build.pie-steps.pdf+, a pie chart of the global time spent in each + step of the packages build process. + +This +graph-build+ target requires the Python Matplotlib and Numpy +libraries to be installed (+python-matplotlib+ and +python-numpy+ on +most distributions), and also the +argparse+ module if you're using a +Python version older than 2.7 (+python-argparse+ on most +distributions). + +By default, the output format for the graph is PDF, but a different +format can be selected using the +BR2_GRAPH_OUT+ environment variable. The +only other format supported is PNG: + +---------------- +BR2_GRAPH_OUT=png make graph-build +---------------- diff --git a/docs/manual/configure.txt b/docs/manual/configure.txt index 9b8135a6a4..badb6e473c 100644 --- a/docs/manual/configure.txt +++ b/docs/manual/configure.txt @@ -68,12 +68,10 @@ The _internal toolchain backend_ is the backend where Buildroot builds by itself a cross-compilation toolchain, before building the userspace applications and libraries for your target embedded system. -This backend is the historical backend of Buildroot, and has been -limited for a long time to the usage of the -http://www.uclibc.org[uClibc C library]. Support for the _eglibc_ C -library has been added in 2013 and is at this point considered -experimental. See the _External toolchain backend_ for another -solution to use _glibc_ or _eglibc_. +This backend supports several C libraries: +http://www.uclibc.org[uClibc], the +http://www.gnu.org/software/libc/libc.html[glibc] and +http://www.eglibc.org[eglibc]. Once you have selected this backend, a number of options appear. The most important ones allow to: @@ -96,18 +94,7 @@ most important ones allow to: the C library might be using interfaces that are not provided by your Linux kernel. - * Change the version and the configuration of the uClibc C library - (if uClibc is selected). The default options are usually - fine. However, if you really need to specifically customize the - configuration of your uClibc C library, you can pass a specific - configuration file here. Or alternatively, you can run the +make - uclibc-menuconfig+ command to get access to uClibc's configuration - interface. Note that all packages in Buildroot are tested against - the default uClibc configuration bundled in Buildroot: if you - deviate from this configuration by removing features from uClibc, - some packages may no longer build. - - * Change the version of the GCC compiler and binutils. + * Change the version of the GCC compiler, binutils and the C library. * Select a number of toolchain options (uClibc only): whether the toolchain should have largefile support (i.e support for files @@ -118,7 +105,12 @@ most important ones allow to: libraries visible in Buildroot menus will change: many applications and libraries require certain toolchain options to be enabled. Most packages show a comment when a certain toolchain option is required - to be able to enable those packages. + to be able to enable those packages. If needed, you can further + refine the uClibc configuration by running +make + uclibc-menuconfig+. Note however that all packages in Buildroot are + tested against the default uClibc configuration bundled in + Buildroot: if you deviate from this configuration by removing + features from uClibc, some packages may no longer build. It is worth noting that whenever one of those options is modified, then the entire toolchain and system must be rebuilt. See @@ -146,10 +138,9 @@ http://www.linaro.org[Linaro] for ARM, http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/[Sourcery CodeBench] for ARM, x86, x86-64, PowerPC, MIPS and SuperH, https://blackfin.uclinux.org/gf/project/toolchain[Blackfin toolchains -from ADI], http://git.xilinx.com/[Xilinx toolchains for Microblaze], -etc.) and is capable of downloading them automatically, or it can be -pointed to a custom toolchain, either available for download or -installed locally. +from Analog Devices], etc.) and is capable of downloading them +automatically, or it can be pointed to a custom toolchain, either +available for download or installed locally. Then, you have three solutions to use an external toolchain: @@ -168,14 +159,14 @@ Then, you have three solutions to use an external toolchain: toolchain. * Use a completely custom external toolchain. This is particularly - useful for toolchains generated using crosstool-NG. To do this, - select the +Custom toolchain+ solution in the +Toolchain+ list. You - need to fill the +Toolchain path+, +Toolchain prefix+ and +External - toolchain C library+ options. Then, you have to tell Buildroot what - your external toolchain supports. If your external toolchain uses - the 'glibc' library, you only have to tell whether your toolchain - supports C\+\+ or not and whether it has built-in RPC support. If - your external toolchain uses the 'uClibc' + useful for toolchains generated using crosstool-NG or with Buildroot + itself. To do this, select the +Custom toolchain+ solution in the + +Toolchain+ list. You need to fill the +Toolchain path+, +Toolchain + prefix+ and +External toolchain C library+ options. Then, you have + to tell Buildroot what your external toolchain supports. If your + external toolchain uses the 'glibc' library, you only have to tell + whether your toolchain supports C\+\+ or not and whether it has + built-in RPC support. If your external toolchain uses the 'uClibc' library, then you have to tell Buildroot if it supports largefile, IPv6, RPC, wide-char, locale, program invocation, threads and C++. At the beginning of the execution, Buildroot will tell you if @@ -188,23 +179,13 @@ Buildroot itself. In general, all toolchains that support the 'sysroot' feature should work. If not, do not hesitate to contact the developers. -We do not support toolchains from the -http://www.denx.de/wiki/DULG/ELDK[ELDK] of Denx, for two reasons: - -* The ELDK does not contain a pure toolchain (i.e just the compiler, - binutils, the C and C++ libraries), but a toolchain that comes with - a very large set of pre-compiled libraries and programs. Therefore, - Buildroot cannot import the 'sysroot' of the toolchain, as it would - contain hundreds of megabytes of pre-compiled libraries that are - normally built by Buildroot. - -* The ELDK toolchains have a completely non-standard custom mechanism - to handle multiple library variants. Instead of using the standard - GCC 'multilib' mechanism, the ARM ELDK uses different symbolic links - to the compiler to differentiate between library variants (for ARM - soft-float and ARM VFP), and the PowerPC ELDK compiler uses a - +CROSS_COMPILE+ environment variable. This non-standard behaviour - makes it difficult to support ELDK in Buildroot. +We do not support toolchains or SDK generated by OpenEmbedded or +Yocto, because these toolchains are not pure toolchains (i.e just the +compiler, binutils, the C and C++ libraries). Instead these toolchains +come with a very large set of pre-compiled libraries and +programs. Therefore, Buildroot cannot import the 'sysroot' of the +toolchain, as it would contain hundreds of megabytes of pre-compiled +libraries that are normally built by Buildroot. We also do not support using the distribution toolchain (i.e the gcc/binutils/C library installed by your distribution) as the diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt index 201685cc78..5602335044 100644 --- a/docs/manual/contribute.txt +++ b/docs/manual/contribute.txt @@ -48,7 +48,7 @@ before submitting them using your favorite text editor. Lastly, send/submit your patch set to the Buildroot mailing list: --------------------- -$ git send-email --to buildroot@busybox.net outgoing/* +$ git send-email --to buildroot@buildroot.org outgoing/* --------------------- Note that +git+ should be configured to use your mail account. diff --git a/docs/manual/customize-outside-br.txt b/docs/manual/customize-outside-br.txt index 585eedffef..7498940948 100644 --- a/docs/manual/customize-outside-br.txt +++ b/docs/manual/customize-outside-br.txt @@ -30,18 +30,18 @@ there is no need to pass +BR2_EXTERNAL+ at every +make+ invocation. It can however be changed at any time by passing a new value, and can be removed by passing an empty value. -The +BR2_EXTERNAL+ path can be either an absolute or a relative path, +*Note:* the +BR2_EXTERNAL+ path can be either an absolute or a relative path, but if it's passed as a relative path, it is important to note that it -is interpreted relatively to the main Buildroot source directory, not +is interpreted relative to the main Buildroot source directory, *not* the Buildroot output directory. Some examples: ----- - buildroot/ $ make BR2_EXTERNAL=../foobar menuconfig + buildroot/ $ make BR2_EXTERNAL=/path/to/foobar menuconfig ----- -Starting from now on, external definitions from the +../foobar+ +Starting from now on, external definitions from the +/path/to/foobar+ directory will be used: ----- @@ -52,7 +52,7 @@ directory will be used: We can switch to another external definitions directory at any time: ----- - buildroot/ $ make BR2_EXTERNAL=../barfoo xconfig + buildroot/ $ make BR2_EXTERNAL=/where/we/have/barfoo xconfig ----- Or disable the usage of external definitions: diff --git a/docs/manual/faq-troubleshooting.txt b/docs/manual/faq-troubleshooting.txt index 4e0612b8d7..4026e18ebd 100644 --- a/docs/manual/faq-troubleshooting.txt +++ b/docs/manual/faq-troubleshooting.txt @@ -111,3 +111,103 @@ directory as the new root, will most likely fail. If you want to run the target filesystem inside a chroot, or as an NFS root, then use the tarball image generated in +images/+ and extract it as root. + +[[faq-no-binary-packages]] +Why doesn't Buildroot generate binary packages (.deb, .ipkg...)? +---------------------------------------------------------------- + +One feature that is often discussed on the Buildroot list is the +the general topic of "package management". To summarize, the idea +would be to add some tracking of which Buildroot package installs +what files, with the goals of: + + * being able to remove files installed by a package when this package + gets unselected from the menuconfig; + + * being able to generate binary packages (ipk or other format) that + can be installed on the target without re-generating a new root + filesystem image. + +In general, most people think it is easy to do: just track which package +installed what and remove it when the package is unselected. However, it +is much more complicated than that: + + * It is not only about the +target/+ directory, but also the sysroot in + +host/usr/<tuple>/sysroot+ and the +host/+ directory itself. All files + installed in those directories by various packages must be tracked. + + * When a package is unselected from the configuration, it is not + sufficient to remove just the files it installed. One must also + remove all its reverse dependencies (i.e packages relying on it) + and rebuild all those packages. For example, package A depends + optionally on the OpenSSL library. Both are selected, and Buildroot + is built. Package A is built with crypto support using OpenSSL. + Later on, OpenSSL gets unselected from the configuration, but + package A remains (since OpenSSL is an optional dependency, this + is possible.) If only OpenSSL files are removed, then the files + installed by package A are broken: they use a library that is no + longer present on the target. Although this is technically doable, + it adds a lot of complexity to Buildroot, which goes against the + simplicity we try to stick to. + + * In addition to the previous problem, there is the case where the + optional dependency is not even known to Buildroot. For example, + package A in version 1.0 never used OpenSSL, but in version 2.0 it + automatically uses OpenSSL if available. If the Buildroot .mk file + hasn't been updated to take this into account, then package A will + not be part of the reverse dependencies of OpenSSL and will not be + removed and rebuilt when OpenSSL is removed. For sure, the .mk file + of package A should be fixed to mention this optional dependency, + but in the mean time, you can have non-reproducible behaviors. + + * The request is to also allow changes in the menuconfig to be + applied on the output directory without having to rebuild + everything from scratch. However, this is very difficult to achieve + in a reliable way: what happens when the suboptions of a package + are changed (we would have to detect this, and rebuild the package + from scratch and potentially all its reverse dependencies), what + happens if toolchain options are changed, etc. At the moment, what + Buildroot does is clear and simple so its behaviour is very + reliable and it is easy to support users. If configuration changes + done in menuconfig are applied after the next make, then it has to + work correctly and properly in all situations, and not have some + bizarre corner cases. The risk is to get bug reports like "I have + enabled package A, B and C, then ran make, then disabled package + C and enabled package D and ran make, then re-enabled package C + and enabled package E and then there is a build failure". Or worse + "I did some configuration, then built, then did some changes, + built, some more changes, built, some more changes, built, and now + it fails, but I don't remember all the changes I did and in which + order". This will be impossible to support. + +For all these reasons, the conclusion is that adding tracking of +installed files to remove them when the package is unselected, or to +generate a repository of binary packages, is something that is very +hard to achieve reliably and will add a lot of complexity. + +On this matter, the Buildroot developers make this position statement: + + * Buildroot strives to make it easy to generate a root filesystem (hence + the name, by the way.) That is what we want to make Buildroot good at: + building root filesystems. + + * Buildroot is not meant to be a distribution (or rather, a distribution + generator.) It is the opinion of most Buildroot developers that this + is not a goal we should pursue. We believe that there are other tools + better suited to generate a distro than Buildroot is. For example, + http://openembedded.org/[Open Embedded], or https://openwrt.org/[openWRT], + are such tools. + + * We prefer to push Buildroot in a direction that makes it easy (or even + easier) to generate complete root filesystems. This is what makes + Buildroot stands out in the crowd (among other things, of course!) + + * We believe that for most embedded Linux systems, binary packages are + not necessary, and potentially harmful. When binary packages are + used, it means that the system can be partially upgraded, which + creates an enormous number of possible combinations of package + versions that should be tested before doing the upgrade on the + embedded device. On the other hand, by doing complete system + upgrades by upgrading the entire root filesystem image at once, + the image deployed to the embedded system is guaranteed to really + be the one that has been tested and validated. diff --git a/docs/manual/make-tips.txt b/docs/manual/make-tips.txt index 0159ffe7ce..faf59f2c62 100644 --- a/docs/manual/make-tips.txt +++ b/docs/manual/make-tips.txt @@ -32,10 +32,12 @@ The result of the search shows the help message of the matching items. Not all targets are always available, some settings in the +.config+ file may hide some targets: +* +busybox-menuconfig+ and +busybox-savedefconfig+ ony work when + +busybox+ is enabled; * +linux-menuconfig+ and +linux-savedefconfig+ only work when +linux+ is enabled; -* +uclibc-menuconfig+ is only available when the - Buildroot internal toolchain backend is used; +* +uclibc-menuconfig+ is only available when the uClibc C library is + selected in the internal toolchain backend; * +barebox-menuconfig+ and +barebox-savedefconfig+ only work when the +barebox+ bootloader is enabled. diff --git a/docs/manual/package-make-target.txt b/docs/manual/package-make-target.txt index 9eefe680b0..bd514f40e8 100644 --- a/docs/manual/package-make-target.txt +++ b/docs/manual/package-make-target.txt @@ -63,6 +63,11 @@ Additionally, there are some other useful make targets: | +show-depends+ | Displays the dependencies required to build the package +| +graph-depends+ | Generate a dependency graph of the package, in the +context of the current Buildroot configuration. See +xref:graph-depends[this section] for more details about dependency +graphs. + | +dirclean+ | Remove the whole package build directory | +rebuild+ | Re-run the compilation commands - this only makes diff --git a/docs/manual/rebuilding-packages.txt b/docs/manual/rebuilding-packages.txt index 88d667015d..b2d10decc7 100644 --- a/docs/manual/rebuilding-packages.txt +++ b/docs/manual/rebuilding-packages.txt @@ -5,33 +5,82 @@ Understanding when a full rebuild is necessary ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A full rebuild is achieved by running: +Buildroot does not attempt to detect what parts of the system should +be rebuilt when the system configuration is changed through +make +menuconfig+, +make xconfig+ or one of the other configuration +tools. In some cases, Buildroot should rebuild the entire system, in +some cases, only a specific subset of packages. But detecting this in +a completely reliable manner is very difficult, and therefore the +Buildroot developers have decided to simply not attempt to do this. + +Instead, it is the responsibility of the user to know when a full +rebuild is necessary. As a hint, here are a few rules of thumb that +can help you understand how to work with Buildroot: + + * When the target architecture configuration is changed, a complete + rebuild is needed. Changing the architecture variant, the binary + format or the floating point strategy for example has an impact on + the entire system. + + * When the toolchain configuration is changed, a complete rebuild + generally is needed. Changing the toolchain configuration often + involves changing the compiler version, the type of C library or + its configuration, or some other fundamental configuration item, + and these changes have an impact on the entire system. + + * When an additional package is added to the configuration, a full + rebuild is not necessarily needed. Buildroot will detect that this + package has never been built, and will build it. However, if this + package is a library that can optionally be used by packages that + have already been built, Buildroot will not automatically rebuild + those. Either you know which packages should be rebuilt, and you + can rebuild them manually, or you should do a full rebuild. For + example, let's suppose you have built a system with the +ctorrent+ + package, but without +openssl+. Your system works, but you realize + you would like to have SSL support in +ctorrent+, so you enable the + +openssl+ package in Buildroot configuration and restart the + build. Buildroot will detect that +openssl+ should be built and + will be build it, but it will not detect that +ctorrent+ should be + rebuilt to benefit from +openssl+ to add OpenSSL support. You will + either have to do a full rebuild, or rebuild +ctorrent+ itself. + + * When a package is removed from the configuration, Buildroot does + not do anything special. It does not remove the files installed by + this package from the target root filesystem or from the toolchain + _sysroot_. A full rebuild is needed to get rid of this + package. However, generally you don't necessarily need this package + to be removed right now: you can wait for the next lunch break to + restart the build from scratch. + + * When the sub-options of a package are changed, the package is not + automatically rebuilt. After making such changes, rebuilding only + this package is often sufficient, unless enabling the package + sub-option adds some features to the package that are useful for + another package which has already been built. Again, Buildroot does + not track when a package should be rebuilt: once a package has been + built, it is never rebuilt unless explicitly told to do so. + + * When a change to the root filesystem skeleton is made, a full + rebuild is needed. However, when changes to the root filesystem + overlay, a post-build script or a post-image script are made, + there is no need for a full rebuild: a simple +make+ invocation + will take the changes into account. + +Generally speaking, when you're facing a build error and you're unsure +of the potential consequences of the configuration changes you've +made, do a full rebuild. If you get the same build error, then you are +sure that the error is not related to partial rebuilds of packages, +and if this error occurs with packages from the official Buildroot, do +not hesitate to report the problem! As your experience with Buildroot +progresses, you will progressively learn when a full rebuild is really +necessary, and you will save more and more time. + +For reference, a full rebuild is achieved by running: --------------- $ make clean all --------------- -In some cases, a full rebuild is mandatory: - -* each time the toolchain properties are changed, this includes: - -** after changing any toolchain option under the _Toolchain_ menu (if - the internal Buildroot backend is used); -** after running +make uclibc-menuconfig+. - -* after removing some libraries from the package selection. - -In some cases, a full rebuild is recommended: - -* after adding some libraries to the package selection (otherwise, - 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 run a -full rebuild, but you should know what is impacted and understand what -you are doing anyway. - [[rebuild-pkg]] Understanding how to rebuild packages ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -51,26 +100,25 @@ its build directory in +output/build+. Buildroot will then re-extract, re-configure, re-compile and re-install this package from scratch. You can ask buildroot to do this with the +make <package>-dirclean+ command. -For convenience, the special make targets -<package>-reconfigure and <package>-rebuild repeat the configure -resp. build steps. - -However, if you don't want to rebuild the package completely from -scratch, a better understanding of the Buildroot internals is -needed. Internally, to keep track of which steps have been done and -which steps remain to be done, Buildroot maintains stamp files (empty -files that just tell whether this or that action has been done): - -* +output/build/<package>-<version>/.stamp_configured+. If removed, - Buildroot will trigger the recompilation of the package from the - configuration step (execution of +./configure+). - -* +output/build/<package>-<version>/.stamp_built+. If removed, - Buildroot will trigger the recompilation of the package from the - compilation step (execution of +make+). - -Note: toolchain packages use custom makefiles. Their stamp files are named -differently. +On the other hand, if you only want to restart the build process of a +package from its compilation step, you can run +make +<package>-rebuild+, followed by +make+ or +make <package>+. It will +restart the compilation and installation of the package, but not from +scratch: it basically re-executes +make+ and +make install+ +inside the package, so it will only rebuild files that changed. + +If you want to restart the build process of a package from its +configuration step, you can run +make <package>-reconfigure+, followed +by +make+ or +make <package>+. It will restart the configuration, +compilation and installation of the package. + +Internally, Buildroot creates so-called _stamp files_ to keep track of +which build steps have been completed for each package. They are +stored in the package build directory, ++output/build/<package>-<version>/+ and are named ++.stamp_<step-name>+. The commands detailed above simply manipulate +these stamp files to force Buildroot to restart a specific set of +steps of a package build process. Further details about package special make targets are explained in xref:pkg-build-steps[]. diff --git a/docs/manual/using-buildroot-development.txt b/docs/manual/using-buildroot-development.txt new file mode 100644 index 0000000000..eaebeaf9fe --- /dev/null +++ b/docs/manual/using-buildroot-development.txt @@ -0,0 +1,84 @@ +// -*- mode:doc; -*- +// vim: set syntax=asciidoc: + +Using Buildroot during development +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The normal operation of Buildroot is to download a tarball, extract +it, configure, compile and install the software component found inside +this tarball. The source code is extracted in ++output/build/<package>-<version>+, which is a temporary directory: +whenever +make clean+ is used, this directory is entirely removed, and +re-recreated at the next +make+ invocation. Even when a Git or +Subversion repository is used as the input for the package source +code, Buildroot creates a tarball out of it, and then behaves as it +normally does with tarballs. + +This behavior is well-suited when Buildroot is used mainly as an +integration tool, to build and integrate all the components of an +embedded Linux system. However, if one uses Buildroot during the +development of certain components of the system, this behavior is not +very convenient: one would instead like to make a small change to the +source code of one package, and be able to quickly rebuild the system +with Buildroot. + +Making changes directly in +output/build/<package>-<version>+ is not +an appropriate solution, because this directory is removed on +make +clean+. + +Therefore, Buildroot provides a specific mechanism for this use case: +the +<pkg>_OVERRIDE_SRCDIR+ mechanism. Buildroot reads an _override_ +file, which allows the user to tell Buildroot the location of the +source for certain packages. By default this _override_ file is named ++local.mk+ and located in the top directory of the Buildroot source +tree, but a different location can be specified through the ++BR2_PACKAGE_OVERRIDE_FILE+ configuration option. + +In this _override_ file, Buildroot expects to find lines of the form: + +------------------ +<pkg1>_OVERRIDE_SRCDIR = /path/to/pkg1/sources +<pkg2>_OVERRIDE_SRCDIR = /path/to/pkg2/sources +------------------ + +For example: + +------------------ +LINUX_OVERRIDE_SRCDIR = /home/bob/linux/ +BUSYBOX_OVERRIDE_SRCDIR = /home/bob/busybox/ +------------------ + +When Buildroot finds that for a given package, an ++<pkg>_OVERRIDE_SRCDIR+ has been defined, it will no longer attempt to +download, extract and patch the package. Instead, it will directly use +the source code available in in the specified directory and +make +clean+ will not touch this directory. This allows to point Buildroot +to your own directories, that can be managed by Git, Subversion, or +any other version control system. To achieve this, Buildroot will use +_rsync_ to copy the source code of the component from the specified ++<pkg>_OVERRIDE_SRCDIR+ to +output/build/<package>-custom/+. + +This mechanism is best used in conjuction with the +make +<pkg>-rebuild+ and +make <pkg>-reconfigure+ targets. A +make +<pkg>-rebuild all+ sequence will _rsync_ the source code from ++<pkg>_OVERRIDE_SRCDIR+ to +output/build/<package>-custom+ (thanks to +_rsync_, only the modified files are copied), and restart the build +process of just this package. + +In the example of the +linux+ package above, the developer can then +make a source code change in +/home/bob/linux+ and then run: + +----------------------- +make linux-rebuild all +----------------------- + +and in a matter of seconds gets the updated Linux kernel image in ++output/images+. Similarly, a change can be made to the Busybox source +code in +/home/bob/busybox+, and after: + +----------------------- +make busybox-rebuild all +----------------------- + +the root filesystem image in +output/images+ contains the updated +Busybox. |
