quickstart.txt 4.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125
  1. // -*- mode:doc; -*-
  2. // vim: set syntax=asciidoc:
  3. == Buildroot quick start
  4. *Important*: you can and should *build everything as a normal user*. There
  5. is no need to be root to configure and use Buildroot. By running all
  6. commands as a regular user, you protect your system against packages
  7. behaving badly during compilation and installation.
  8. The first step when using Buildroot is to create a configuration.
  9. Buildroot has a nice configuration tool similar to the one you can
  10. find in the http://www.kernel.org/[Linux kernel] or in
  11. http://www.busybox.net/[BusyBox].
  12. From the buildroot directory, run
  13. --------------------
  14. $ make menuconfig
  15. --------------------
  16. for the original curses-based configurator, or
  17. --------------------
  18. $ make nconfig
  19. --------------------
  20. for the new curses-based configurator, or
  21. --------------------
  22. $ make xconfig
  23. --------------------
  24. for the Qt-based configurator, or
  25. --------------------
  26. $ make gconfig
  27. --------------------
  28. for the GTK-based configurator.
  29. All of these "make" commands will need to build a configuration
  30. utility (including the interface), so you may need to install
  31. "development" packages for relevant libraries used by the
  32. configuration utilities. Refer to xref:requirement[] for more details,
  33. specifically the xref:requirement-optional[optional requirements]
  34. to get the dependencies of your favorite interface.
  35. For each menu entry in the configuration tool, you can find associated
  36. help that describes the purpose of the entry. Refer to xref:configure[]
  37. for details on some specific configuration aspects.
  38. Once everything is configured, the configuration tool generates a
  39. +.config+ file that contains the entire configuration. This file will be
  40. read by the top-level Makefile.
  41. To start the build process, simply run:
  42. --------------------
  43. $ make
  44. --------------------
  45. By default, Buildroot does not support top-level parallel build, so
  46. running +make -jN+ is not necessary. There is however experimental
  47. support for top-level parallel build, see
  48. xref:top-level-parallel-build[].
  49. The `make` command will generally perform the following steps:
  50. * download source files (as required);
  51. * configure, build and install the cross-compilation toolchain, or
  52. simply import an external toolchain;
  53. * configure, build and install selected target packages;
  54. * build a kernel image, if selected;
  55. * build a bootloader image, if selected;
  56. * create a root filesystem in selected formats.
  57. Buildroot output is stored in a single directory, +output/+.
  58. This directory contains several subdirectories:
  59. * +images/+ where all the images (kernel image, bootloader and root
  60. filesystem images) are stored. These are the files you need to put
  61. on your target system.
  62. * +build/+ where all the components are built (this includes tools
  63. needed by Buildroot on the host and packages compiled for the
  64. target). This directory contains one subdirectory for each of these
  65. components.
  66. * +host/+ contains both the tools built for the host, and the sysroot
  67. of the target toolchain. The former is an installation of tools
  68. compiled for the host that are needed for the proper execution of
  69. Buildroot, including the cross-compilation toolchain. The latter
  70. is a hierarchy similar to a root filesystem hierarchy. It contains
  71. the headers and libraries of all user-space packages that provide
  72. and install libraries used by other packages. However, this
  73. directory is 'not' intended to be the root filesystem for the target:
  74. it contains a lot of development files, unstripped binaries and
  75. libraries that make it far too big for an embedded system. These
  76. development files are used to compile libraries and applications for
  77. the target that depend on other libraries.
  78. * +staging/+ is a symlink to the target toolchain sysroot inside
  79. +host/+, which exists for backwards compatibility.
  80. * +target/+ which contains 'almost' the complete root filesystem for
  81. the target: everything needed is present except the device files in
  82. +/dev/+ (Buildroot can't create them because Buildroot doesn't run
  83. as root and doesn't want to run as root). Also, it doesn't have the correct
  84. permissions (e.g. setuid for the busybox binary). Therefore, this directory
  85. *should not be used on your target*. Instead, you should use one of
  86. the images built in the +images/+ directory. If you need an
  87. extracted image of the root filesystem for booting over NFS, then
  88. use the tarball image generated in +images/+ and extract it as
  89. root. Compared to +staging/+, +target/+ contains only the files and
  90. libraries needed to run the selected target applications: the
  91. development files (headers, etc.) are not present, the binaries are
  92. stripped.
  93. These commands, +make menuconfig|nconfig|gconfig|xconfig+ and +make+, are the
  94. basic ones that allow to easily and quickly generate images fitting
  95. your needs, with all the features and applications you enabled.
  96. More details about the "make" command usage are given in
  97. xref:make-tips[].