diff --git a/Documentation/user/barebox.rst b/Documentation/user/barebox.rst index 70bdedc44..6a679c0b7 100644 --- a/Documentation/user/barebox.rst +++ b/Documentation/user/barebox.rst @@ -13,8 +13,8 @@ All releases can be downloaded from: http://www.barebox.org/download/ -Development versions of barebox are accessible via git. A local repository clone -can be created using git:: +Development versions of barebox are accessible via Git. A local repository clone +can be checked out as follows:: $ git clone git://git.pengutronix.de/git/barebox.git Cloning into 'barebox'... @@ -26,8 +26,9 @@ can be created using git:: Checking connectivity... done. Checking out files: 100% (5651/5651), done. -After this, make sure to check out needed branch. If you want to -develop for barebox, it's better to check the the next branch:: +After this, make sure to check out the appropriate branch. If you want to +develop for barebox, it's best to check out the ``next`` branch rather than +the ``master`` branch:: $ git checkout -b next origin/remotes/next @@ -39,11 +40,11 @@ http://git.pengutronix.de/?p=barebox.git. Configuration ------------- -barebox uses Kconfig from the Linux Kernel as a configuration tool. -All configuration is accessible via the 'make' command. Before running -it you have to specify your architecture with the ARCH environment -variable and the cross compiler with the CROSS_COMPILE environment -variable. ARCH has to be one of: +barebox uses Kconfig from the Linux kernel as a configuration tool, +where all configuration is done via the ``make`` command. Before running +it you have to specify your architecture with the ``ARCH`` environment +variable and the cross compiler with the ``CROSS_COMPILE`` environment +variable. ``ARCH`` has to be one of: * arm * blackfin @@ -54,17 +55,17 @@ variable. ARCH has to be one of: * sandbox * x86 -CROSS_COMPILE should be the prefix of your cross compiler. This can +``CROSS_COMPILE`` should be the prefix of your cross compiler. This can either contain the full path or, if the cross compiler binary is in your $PATH, just the prefix. -Either export ARCH and CROSS_COMPILE once before working on barebox:: +Either export ``ARCH`` and ``CROSS_COMPILE`` once before working on barebox:: export ARCH=arm export CROSS_COMPILE=/path/to/arm-cortexa8-linux-gnueabihf- make ... -or add them before each 'make' command:: +or add them to each invocation of the ``make`` command:: ARCH=arm CROSS_COMPILE=/path/to/arm-cortexa8-linux-gnueabihf- make ... @@ -73,11 +74,23 @@ For readability, ARCH/CROSS_COMPILE are skipped from the following examples. Configuring for a board ^^^^^^^^^^^^^^^^^^^^^^^ -All configuration files can be found under arch/$ARCH/configs/. For an -overview type:: +All configuration files can be found under the ``arch/${ARCH}/configs/`` +directory. For an overview of possible Make targets for your architecture, +type:: make help +Your output from ``make help`` will be based on the architecture you've +selected via the ``ARCH`` variable. So if, for example, you had selected:: + + export ARCH=mips + +your help output would represent all of the generic (architecture-independent) +targets, followed by the MIPS-specific ones:: + + make [ARCH=mips] help + ... + ... list of generic targets ... ... Architecture specific targets (mips): No architecture specific help defined for mips @@ -100,20 +113,51 @@ with the most popular being ``menuconfig``:: make menuconfig -barebox used the same configuration system as Linux, so you can use -all the things you know, e.g. ``make xconfig``, ``make allyesconfig`` etc. +barebox uses the same (Kbuild) configuration system as Linux, so you can use +all the kernel config targets you already know, e.g. ``make xconfig``, +``make allyesconfig`` etc. + +Configuring and compiling "out-of-tree" +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Before going any further, it's worth knowing how you can do all your barebox +configuration and compilation "out of tree"; that is, how you can keep your +source directory pristine and have all output from the various ``make`` commands +generated in a separate build directory. + +Once you check out your barebox source directory, and before you do any +configuration or building, set the environment variable ``KBUILD_OUTPUT`` +to point to your intended output directory, as in:: + + export KBUILD_OUTPUT=.../my_barebox_build_directory + +From that point on, all of the ``make`` commands you run in your source +directory will generate their output in your specified output directory. +Not only does this keep your source directory clean, but it allows several +developers to share the same source directory while doing all their own +configuration and building in their own individual build directories. + +.. note:: + + To do out-of-tree builds, your source tree must be absolutely clean + of all generated artifacts from previous configurations and builds. + In other words, if you had earlier done any configuration or building + in that source tree that dumped its results into the same source tree + directory, you need to do the equivalent of a ``make distclean`` before + using that source directory for any out-of-tree builds. Compilation ----------- -After barebox has been :ref:`configured ` it can be compiled:: +After barebox has been :ref:`configured ` it can be compiled +simply with:: make The resulting binary varies depending on the board barebox is compiled for. -Without :ref:`multi_image` support the 'barebox-flash-image' link will point +Without :ref:`multi_image` support the ``barebox-flash-image`` link will point to the binary for flashing/uploading to the board. With :ref:`multi_image` support -the compilation process will finish with a list of images built under images/:: +the compilation process will finish with a list of images built under ``images/``:: images built: barebox-freescale-imx51-babbage.img @@ -142,7 +186,7 @@ with U-Boot's 'go' command:: With barebox already running on your board, this can be used to chainload another barebox:: - bootm /mntf/tftp/barebox.bin + bootm /mnt/tftp/barebox.bin At least ``barebox.bin`` (with :ref:`pbl` support enabled ``arch/$ARCH/pbl/zbarebox.bin``) should be startable second stage. The flash binary (``barebox-flash-image``) may or may not @@ -177,9 +221,9 @@ This is a typical barebox startup log:: barebox@Genesi Efika MX Smartbook:/ Without intervention, barebox will continue booting after 3 seconds. If interrupted -by pressing a key, you will find yourself on the :ref:`shell `. +by pressing a key, you will find yourself at the :ref:`shell `. -On the shell type ``help`` for a list of supported commands. ``help `` shows +At the shell type ``help`` for a list of supported commands. ``help `` shows the usage for a particular command. barebox has tab completion which will complete your command. Arguments to commands are also completed depending on the command. If a command expects a file argument only files will be offered as completion. Other