Documentation: User manual, "barebox" section
Various grammar/font fixes to that section, including adding an additional section describing how to properly do "out of tree" configuration and building. Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca> Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>
This commit is contained in:
Robert P. J. Day
Sascha Hauer
parent
42b936ba58
commit
009e5365d0
|
|
@ -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 <configuration>` it can be compiled::
|
||||
After barebox has been :ref:`configured <configuration>` 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 <hush>`.
|
||||
by pressing a key, you will find yourself at the :ref:`shell <hush>`.
|
||||
|
||||
On the shell type ``help`` for a list of supported commands. ``help <command>`` shows
|
||||
At the shell type ``help`` for a list of supported commands. ``help <command>`` 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
|
||||
|
|
|
|||
Loading…
Reference in New Issue