[Mod] First commit

docs/manual/quickstart.txt

@@ -0,0 +1,125 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+== Buildroot quick start
+
+*Important*: you can and should *build everything as a normal user*. There
+is no need to be root to configure and use Buildroot. By running all
+commands as a regular user, you protect your system against packages
+behaving badly during compilation and installation.
+
+The first step when using Buildroot is to create a configuration.
+Buildroot has a nice configuration tool similar to the one you can
+find in the http://www.kernel.org/[Linux kernel] or in
+http://www.busybox.net/[BusyBox].
+
+From the buildroot directory, run
+
+--------------------
+ $ make menuconfig
+--------------------
+
+for the original curses-based configurator, or
+
+--------------------
+ $ make nconfig
+--------------------
+
+for the new curses-based configurator, or
+
+--------------------
+ $ make xconfig
+--------------------
+
+for the Qt-based configurator, or
+
+--------------------
+ $ make gconfig
+--------------------
+
+for the GTK-based configurator.
+
+All of these "make" commands will need to build a configuration
+utility (including the interface), so you may need to install
+"development" packages for relevant libraries used by the
+configuration utilities. Refer to xref:requirement[] for more details,
+specifically the xref:requirement-optional[optional requirements]
+to get the dependencies of your favorite interface.
+
+For each menu entry in the configuration tool, you can find associated
+help that describes the purpose of the entry. Refer to xref:configure[]
+for details on some specific configuration aspects.
+
+Once everything is configured, the configuration tool generates a
++.config+ file that contains the entire configuration. This file will be
+read by the top-level Makefile.
+
+To start the build process, simply run:
+
+--------------------
+ $ make
+--------------------
+
+By default, Buildroot does not support top-level parallel build, so
+running +make -jN+ is not necessary. There is however experimental
+support for top-level parallel build, see
+xref:top-level-parallel-build[].
+
+The `make` command will generally perform the following steps:
+
+* download source files (as required);
+* configure, build and install the cross-compilation toolchain, or
+  simply import an external toolchain;
+* configure, build and install selected target packages;
+* build a kernel image, if selected;
+* build a bootloader image, if selected;
+* create a root filesystem in selected formats.
+
+Buildroot output is stored in a single directory, +output/+.
+This directory contains several subdirectories:
+
+* +images/+ where all the images (kernel image, bootloader and root
+  filesystem images) are stored. These are the files you need to put
+  on your target system.
+
+* +build/+ where all the components are built (this includes tools
+  needed by Buildroot on the host and packages compiled for the
+  target). This directory contains one subdirectory for each of these
+  components.
+
+* +host/+ contains both the tools built for the host, and the sysroot
+  of the target toolchain. The former is an installation of tools
+  compiled for the host that are needed for the proper execution of
+  Buildroot, including the cross-compilation toolchain. The latter
+  is a hierarchy similar to a root filesystem hierarchy. It contains
+  the headers and libraries of all user-space packages that provide
+  and install libraries used by other packages. However, this
+  directory is 'not' intended to be the root filesystem for the target:
+  it contains a lot of development files, unstripped binaries and
+  libraries that make it far too big for an embedded system. These
+  development files are used to compile libraries and applications for
+  the target that depend on other libraries.
+
+* +staging/+ is a symlink to the target toolchain sysroot inside
+  +host/+, which exists for backwards compatibility.
+
+* +target/+ which contains 'almost' the complete root filesystem for
+  the target: everything needed is present except the device files in
+  +/dev/+ (Buildroot can't create them because Buildroot doesn't run
+  as root and doesn't want to run as root). Also, it doesn't have the correct
+  permissions (e.g. setuid for the busybox binary). Therefore, this directory
+  *should not be used on your target*. Instead, you should use one of
+  the images built in the +images/+ directory. If you need an
+  extracted image of the root filesystem for booting over NFS, then
+  use the tarball image generated in +images/+ and extract it as
+  root. Compared to +staging/+, +target/+ contains only the files and
+  libraries needed to run the selected target applications: the
+  development files (headers, etc.) are not present, the binaries are
+  stripped.
+
+These commands, +make menuconfig|nconfig|gconfig|xconfig+ and +make+, are the
+basic ones that allow to easily and quickly generate images fitting
+your needs, with all the features and applications you enabled.
+
+More details about the "make" command usage are given in
+xref:make-tips[].