@@ -1,33 +1,169 @@
// -*- mode:doc; -*-
// vim: set syntax=asciidoc:
-Boot the generated images
+After having run Buildroot, you will have a brand new filesystem for
+your target exported in the 'output/images' directory. The content of
+this folder depends of the option you chose during buildroot
+configuration in the +Filesystem images+ submenu.
+So what's next? You will probably want to :
-To achieve NFS-boot, enable _tar root filesystem_ in the _Filesystem
+* deploy and/or install the freshly built images on the target to test
-After a complete build, just run the following commands to setup the
+* test the images in emulators (http://wiki.qemu.org/Main_Page[Qemu],
+ --- a AArch64 emulator, ...).
+ By default, Buildroot comes with a set of configurations for vairous
+ architectures running in 'Qemu'.
+ These configurations are stored under the 'board/qemu' directory.
+ Each of these configurations comes with a +readme.txt+ file providing
+ details to use the built images with 'Qemu'. They are regularly tested
+ and maintained by the Buildroot core developers;
+* generate a virtual disk to dump to real system or to use in
+ virtualisation systems (http://wiki.qemu.org/Main_Page[Qemu],
+ https://www.virtualbox.org/[VirtualBox], ...).
+ This mostly useful for 'x86' and 'x86_64' targets.
+This stuff is really depending on each project and hardware, so we
+cannot describe every solution here. This is where Buildroot's work
+The following section aims at guiding new user on what to do next to
+avoid staying in the dark.
+This is *not* an exact guide on how to precisely do what is described.
+Please take the time to have a look to refered projets to get those
+Prepare a bootable raw disk file for virtualisation
+If you plan to use virtual machines, or to copy a binary bootable image
+to your target, you may need to create an _disk image_.
+To create a bootable raw disk file you will need to:
+* create an empty file with the +dd+ command;
+* edit the partition table of this _disk image_ file using some tools
+ like +fdisk+;
+* install the MBR;
+* create virtual devices in +/dev+ pointing to your virtual disk
+ partitions (as you will have with +/dev/sda+, +/dev/sda1+, +/dev/sda2+,
+ etc) with
+* mount one or several partitions of your virtual disk with the +mount+
+* populate the root partition by extracting into it the rootfs tarball
+ generated by Buildroot;
+Some device does not have external memory and need to be booted to be
+able to install the rootfs.
+A nice way of doing this is booting from network. If the device allows
+you to do that, you will be able to:
+* test the *in-progress* rootfs without installing it on your system
+ (it prevents from premature wear of the flash memories);
+* create a second Buildroot project with a minimalist installer that
+ will install your production rootfs on the target.
+Network bootloaders (PXE,iPXE)
+To fully boot on the network you need a network bootloader. This is
+optionnal and you could use your classic bootloader to mount a NFS
+is a specification that has been implemented at least by
+The main idea is to have a DHCP server that provide a link to a generic
+boot ROM that is accessible from a simple FTP server (TFTP).
+Then your target boots with it and come back to the TFTP server to get
+the specific stuff (for instance it's boot menu).
+Here is some hints on how to setup this:
+NFS rootfs mount on +/+
+The idea is to mount +/+ using a network shared folder from a
+(usually on the host development machine).
+To enable the NFS-boot, you should select the _tar root filesystem_
+option in the _Filesystem images_ submenu.
+The embedded kernel needs at least the following option:
+* NFS filesystem support (CONFIG_NFS_FS);
+* Root file system on NFS (CONFIG_ROOT_NFS);
+* Ethernet (CONFIG_NET_ETHERNET);
+* The ethernet driver for the embedded network card;
+* IP: kernel level autoconfiguration. This includes:
+ * CONFIG_IP_PNP;
+ * CONFIG_IP_PNP_BOOTTP;
+ * CONFIG_IP_PNP_DHCP.
+After a complete build, just run the following command to setup the
+NFS-root directory on the server:
sudo tar -xavf /path/to/output_dir/rootfs.tar -C /path/to/nfs_root_dir
-Remember to add this path to +/etc/exports+.
+Make sure this location appears in the +/etc/exports+ file, and a _nfs_
+daemon is running onthe server.
+After editing +/etc/exports+, you should run:
+Then, you can execute a NFS-boot from your target. Here is a documentation hints:
+// - sort links
-Then, you can execute a NFS-boot from your target.
+Chroot into generated image
-If you want to chroot in a generated image, then there are few thing
+If you want to 'chroot' in a generated image, then there are few thing
you should be aware of:
* you should setup the new root from the _tar root filesystem_ image;
@@ -67,7 +67,8 @@ 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.
+ filesystem images) are stored. For further details for uisng/booting
+ the images, refer to the xref:beyond-buildroot.
* +build/+ where all the components except for the cross-compilation
toolchain are built (this includes tools needed to run Buildroot on
@@ -27,3 +27,8 @@ interested in hacking it to add:
* new board support: refer to the
+Using/Booting Buildroot images
+Refer to the xref:beyond-buildroot.