X-Git-Url: https://review.fuel-infra.org/gitweb?a=blobdiff_plain;f=cirros-testvm%2Fsrc-cirros%2Fbuildroot-2015.05%2Fbuild%2Fdocs%2Fmanual%2Fcommon-usage.txt;fp=cirros-testvm%2Fsrc-cirros%2Fbuildroot-2015.05%2Fbuild%2Fdocs%2Fmanual%2Fcommon-usage.txt;h=5b27b1fa11b06347773d013e2cb90e3f8ef813cc;hb=b0a0f15dfaa205161a7fcb20cf1b8cd4948c2ef3;hp=0000000000000000000000000000000000000000;hpb=c6ac3cd55ee2da956195eee393b0882105dfad4e;p=packages%2Ftrusty%2Fcirros-testvm.git diff --git a/cirros-testvm/src-cirros/buildroot-2015.05/build/docs/manual/common-usage.txt b/cirros-testvm/src-cirros/buildroot-2015.05/build/docs/manual/common-usage.txt new file mode 100644 index 0000000..5b27b1f --- /dev/null +++ b/cirros-testvm/src-cirros/buildroot-2015.05/build/docs/manual/common-usage.txt @@ -0,0 +1,278 @@ +// -*- mode:doc; -*- +// vim: set syntax=asciidoc: + +== General Buildroot usage + +include::make-tips.txt[] + +include::rebuilding-packages.txt[] + +=== Offline builds + +If you intend to do an offline build and just want to download +all sources that you previously selected in the configurator +('menuconfig', 'nconfig', 'xconfig' or 'gconfig'), then issue: + +-------------------- + $ make source +-------------------- + +You can now disconnect or copy the content of your +dl+ +directory to the build-host. + +=== Building out-of-tree + +As default, everything built by Buildroot is stored in the directory ++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=+ to the make command +line: + +-------------------- + $ make O=/tmp/build +-------------------- + +Or: + +-------------------- + $ cd /tmp/build; make O=$PWD -C path/to/buildroot +-------------------- + +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 +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): + +-------------------- + $ make +-------------------- + +[[env-vars]] + +=== Environment variables + +Buildroot also honors some environment variables, when they are passed +to +make+ or set in the environment: + +* +HOSTCXX+, the host C++ compiler to use +* +HOSTCC+, the host C compiler to use +* +UCLIBC_CONFIG_FILE=+, path to + the uClibc configuration file, used to compile uClibc, if an + internal toolchain is being built. + + + Note that the uClibc configuration file can also be set from the + configuration interface, so through the Buildroot +.config+ file; this + is the recommended way of setting it. + + +* +BUSYBOX_CONFIG_FILE=+, 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 + is the recommended way of setting it. + + +* +BR2_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 + is the recommended way of setting it. +* +BR2_GRAPH_ALT+, if set and non-empty, to use an alternate color-scheme in + build-time graphs +* +BR2_GRAPH_OUT+ to set the filetype of generated graphs, either +pdf+ (the + default), or +png+. +* +BR2_GRAPH_DEPS_OPTS+ to pass extra options to the dependency graph; see + xref:graph-depends[] for the accepted options +* +BR2_GRAPH_DOT_OPTS+ is passed verbatim as options to the +dot+ utility to + draw the dependency graph. + +An example that uses config files located in the toplevel directory and +in your $HOME: + +-------------------- + $ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config +-------------------- + +If you want to use a compiler other than the default +gcc+ +or +g+++ for building helper-binaries on your host, then do + +-------------------- + $ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD +-------------------- + +=== Dealing efficiently with filesystem images + +Filesystem images can get pretty big, depending on the filesystem you choose, +the number of packages, whether you provisioned free space... Yet, some +locations in the filesystems images may just be _empty_ (e.g. a long run of +'zeroes'); such a file is called a _sparse_ file. + +Most tools can handle sparse files efficiently, and will only store or write +those parts of a sparse file that are not empty. + +For example: + +* +tar+ accepts the +-S+ option to tell it to only store non-zero blocks + of sparse files: +** +tar cf archive.tar -S [files...]+ will efficiently store sparse files + in a tarball +** +tar xf archive.tar -S+ will efficiently store sparse files extracted + from a tarball + +* +cp+ accepts the +--sparse=WHEN+ option (+WHEN+ is one of +auto+, + +never+ or +always+): +** +cp --sparse=always source.file dest.file+ will make +dest.file+ a + sparse file if +source.file+ has long runs of zeroes + +Other tools may have similar options. Please consult their respective man +pages. + +You can use sparse files if you need to store the filesystem images (e.g. +to transfer from one machine to another), or if you need to send them (e.g. +to the Q&A team). + +Note however that flashing a filesystem image to a device while using the +sparse mode of +dd+ may result in a broken filesystem (e.g. the block bitmap +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 -graph-depends +------------------------ + +You will find the generated graph in ++output/graph/-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 +-------------------------------- + +The +graph-depends+ behaviour can be controlled by setting options in the ++BR2_GRAPH_DEPS_OPTS+ environment variable. The accepted options are: + +* +--depth N+, +-d N+, to limit the dependency depth to +N+ levels. The + default, +0+, means no limit. + +* +--stop-on PKG+, +-s PKG+, to stop the graph on the package +PKG+. + +PKG+ can be an actual package name, a glob, or the keyword 'virtual' + (to stop on virtual packages). The package is still present on the + graph, but its dependencies are not. + +* +--exclude PKG+, +-x PKG+, like +--stop-on+, but also omits +PKG+ from + the graph. + +* +--transitive+, +--no-transitive+, to draw (or not) the transitive + dependencies. The default is to not draw transitive dependencies. + +* +--colours R,T,H+, the comma-separated list of colours to draw the + root package (+R+), the target packages (+T+) and the host packages + (+H+). Defaults to: +lightblue,grey,gainsboro+ + +-------------------------------- +BR2_GRAPH_DEPS_OPTS='-d 3 --no-transitive --colours=red,green,blue' 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 +---------------- + +include::eclipse-integration.txt[] + +include::advanced.txt[]