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:
parent
42b936ba58
commit
009e5365d0
|
@ -13,8 +13,8 @@ All releases can be downloaded from:
|
||||||
|
|
||||||
http://www.barebox.org/download/
|
http://www.barebox.org/download/
|
||||||
|
|
||||||
Development versions of barebox are accessible via git. A local repository clone
|
Development versions of barebox are accessible via Git. A local repository clone
|
||||||
can be created using git::
|
can be checked out as follows::
|
||||||
|
|
||||||
$ git clone git://git.pengutronix.de/git/barebox.git
|
$ git clone git://git.pengutronix.de/git/barebox.git
|
||||||
Cloning into 'barebox'...
|
Cloning into 'barebox'...
|
||||||
|
@ -26,8 +26,9 @@ can be created using git::
|
||||||
Checking connectivity... done.
|
Checking connectivity... done.
|
||||||
Checking out files: 100% (5651/5651), done.
|
Checking out files: 100% (5651/5651), done.
|
||||||
|
|
||||||
After this, make sure to check out needed branch. If you want to
|
After this, make sure to check out the appropriate branch. If you want to
|
||||||
develop for barebox, it's better to check the the next branch::
|
develop for barebox, it's best to check out the ``next`` branch rather than
|
||||||
|
the ``master`` branch::
|
||||||
|
|
||||||
$ git checkout -b next origin/remotes/next
|
$ git checkout -b next origin/remotes/next
|
||||||
|
|
||||||
|
@ -39,11 +40,11 @@ http://git.pengutronix.de/?p=barebox.git.
|
||||||
Configuration
|
Configuration
|
||||||
-------------
|
-------------
|
||||||
|
|
||||||
barebox uses Kconfig from the Linux Kernel as a configuration tool.
|
barebox uses Kconfig from the Linux kernel as a configuration tool,
|
||||||
All configuration is accessible via the 'make' command. Before running
|
where all configuration is done via the ``make`` command. Before running
|
||||||
it you have to specify your architecture with the ARCH environment
|
it you have to specify your architecture with the ``ARCH`` environment
|
||||||
variable and the cross compiler with the CROSS_COMPILE environment
|
variable and the cross compiler with the ``CROSS_COMPILE`` environment
|
||||||
variable. ARCH has to be one of:
|
variable. ``ARCH`` has to be one of:
|
||||||
|
|
||||||
* arm
|
* arm
|
||||||
* blackfin
|
* blackfin
|
||||||
|
@ -54,17 +55,17 @@ variable. ARCH has to be one of:
|
||||||
* sandbox
|
* sandbox
|
||||||
* x86
|
* 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
|
either contain the full path or, if the cross compiler binary is
|
||||||
in your $PATH, just the prefix.
|
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 ARCH=arm
|
||||||
export CROSS_COMPILE=/path/to/arm-cortexa8-linux-gnueabihf-
|
export CROSS_COMPILE=/path/to/arm-cortexa8-linux-gnueabihf-
|
||||||
make ...
|
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 ...
|
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
|
Configuring for a board
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
All configuration files can be found under arch/$ARCH/configs/. For an
|
All configuration files can be found under the ``arch/${ARCH}/configs/``
|
||||||
overview type::
|
directory. For an overview of possible Make targets for your architecture,
|
||||||
|
type::
|
||||||
|
|
||||||
make help
|
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):
|
Architecture specific targets (mips):
|
||||||
No architecture specific help defined for mips
|
No architecture specific help defined for mips
|
||||||
|
@ -100,20 +113,51 @@ with the most popular being ``menuconfig``::
|
||||||
|
|
||||||
make menuconfig
|
make menuconfig
|
||||||
|
|
||||||
barebox used the same configuration system as Linux, so you can use
|
barebox uses the same (Kbuild) configuration system as Linux, so you can use
|
||||||
all the things you know, e.g. ``make xconfig``, ``make allyesconfig`` etc.
|
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
|
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
|
make
|
||||||
|
|
||||||
The resulting binary varies depending on the board barebox is compiled for.
|
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
|
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:
|
images built:
|
||||||
barebox-freescale-imx51-babbage.img
|
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::
|
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``)
|
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
|
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:/
|
barebox@Genesi Efika MX Smartbook:/
|
||||||
|
|
||||||
Without intervention, barebox will continue booting after 3 seconds. If interrupted
|
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
|
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
|
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
|
a command expects a file argument only files will be offered as completion. Other
|
||||||
|
|
Loading…
Reference in New Issue