From: Thomas De Schampheleire Date: Wed, 20 Aug 2014 19:39:54 +0000 (+0200) Subject: manual: file organization: rename files to match new section title X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=f21256b86adc88665f6fe1c16672ee7ebf76d6db;p=buildroot.git manual: file organization: rename files to match new section title After the renaming of some sections, rename the corresponding files for clarity. Signed-off-by: Thomas De Schampheleire Signed-off-by: Thomas Petazzoni --- diff --git a/docs/manual/get-involved.txt b/docs/manual/get-involved.txt deleted file mode 100644 index b11053ee1b..0000000000 --- a/docs/manual/get-involved.txt +++ /dev/null @@ -1,73 +0,0 @@ -// -*- mode:doc; -*- -// vim: set syntax=asciidoc: - -[[community-resources]] -== Community resources - -Like any open source project, Buildroot has different ways to share -information in its community and outside. - -Each of those ways may interest you if you are looking for some help, -want to understand Buildroot or contribute to the project. - -Mailing List:: -+ -Buildroot has a mailing list for discussion and development. It is the -main method of interaction for Buildroot users and developers. -+ -Only subscribers to the Buildroot mailing list are allowed to post to -this list. You can subscribe via the -http://lists.busybox.net/mailman/listinfo/buildroot[mailing list info -page]. -+ -Mails that are sent to the mailing list are also available in the -http://lists.busybox.net/pipermail/buildroot[mailing list archives] and -via http://gmane.org[Gmane], at -http://dir.gmane.org/gmane.comp.lib.uclibc.buildroot[+gmane.comp.lib.uclibc.buildroot+]. -Please search the mailing list archives before asking questions, since -there is a good chance someone else has asked the same question before. - -IRC:: -+ -The Buildroot IRC channel irc://freenode.net/#buildroot[#buildroot] is -hosted on http://webchat.freenode.net[Freenode]. It is a useful place to -ask quick questions or discuss on certain topics. -+ -When asking for help on IRC, share relevant logs or pieces of code -using a code sharing website, such as http://code.bulix.org. -+ -Note that for certain questions, posting to the mailing list may be -better as it will reach more people, both developers and users. - -Bug tracker:: -+ -Bugs in Buildroot can be reported via the mailing list or alternatively -via the https://bugs.busybox.net/buglist.cgi?product=buildroot[Buildroot -bugtracker]. Please refer to xref:reporting-bugs[] before creating a bug -report. - -Wiki:: -+ -http://elinux.org/Buildroot[The Buildroot wiki page] is hosted on -the http://elinux.org[eLinux] wiki. It contains some useful links, an -overview of past and upcoming events, and a TODO list. - -Patchwork:: -+ -Patchwork is a web-based patch tracking system designed to facilitate -the contribution and management of contributions to an open-source -project. Patches that have been sent to a mailing list are \'caught' by -the system, and appear on a web page. Any comments posted that -reference the patch are appended to the patch page too. For more -information on Patchwork see -http://jk.ozlabs.org/projects/patchwork[]. -+ -Buildroot's Patchwork website is mainly for use by Buildroot's -maintainer to ensure patches aren't missed. It is also used by Buildroot -patch reviewers (see also xref:apply-patches-patchwork[]). -However, since the website exposes patches and their corresponding -review comments in a clean and concise web interface, it can be useful -for all Buildroot developers. -+ -The Buildroot patch management interface is available at -http://patchwork.buildroot.org[]. diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt index 592becefe9..df34f014f2 100644 --- a/docs/manual/manual.txt +++ b/docs/manual/manual.txt @@ -24,9 +24,9 @@ include::prerequisite.txt[] include::getting.txt[] -include::using.txt[] +include::quickstart.txt[] -include::get-involved.txt[] +include::resources.txt[] = User guide diff --git a/docs/manual/quickstart.txt b/docs/manual/quickstart.txt new file mode 100644 index 0000000000..975fffc318 --- /dev/null +++ b/docs/manual/quickstart.txt @@ -0,0 +1,123 @@ +// -*- 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 +-------------------- + +You *should never* use +make -jN+ with Buildroot: top-level parallel +make is currently not supported. Instead, use the +BR2_JLEVEL+ option +to tell Buildroot to run the compilation of each individual package +with +make -jN+. + +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. + +* +staging/+ which contains a hierarchy similar to a root filesystem + hierarchy. This directory contains the headers and libraries of the + cross-compilation toolchain and all the userspace packages selected + for the target. 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. + +* +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. + +* +host/+ contains the installation of tools compiled for the host + that are needed for the proper execution of Buildroot, including the + cross-compilation toolchain. + +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[]. diff --git a/docs/manual/resources.txt b/docs/manual/resources.txt new file mode 100644 index 0000000000..b11053ee1b --- /dev/null +++ b/docs/manual/resources.txt @@ -0,0 +1,73 @@ +// -*- mode:doc; -*- +// vim: set syntax=asciidoc: + +[[community-resources]] +== Community resources + +Like any open source project, Buildroot has different ways to share +information in its community and outside. + +Each of those ways may interest you if you are looking for some help, +want to understand Buildroot or contribute to the project. + +Mailing List:: ++ +Buildroot has a mailing list for discussion and development. It is the +main method of interaction for Buildroot users and developers. ++ +Only subscribers to the Buildroot mailing list are allowed to post to +this list. You can subscribe via the +http://lists.busybox.net/mailman/listinfo/buildroot[mailing list info +page]. ++ +Mails that are sent to the mailing list are also available in the +http://lists.busybox.net/pipermail/buildroot[mailing list archives] and +via http://gmane.org[Gmane], at +http://dir.gmane.org/gmane.comp.lib.uclibc.buildroot[+gmane.comp.lib.uclibc.buildroot+]. +Please search the mailing list archives before asking questions, since +there is a good chance someone else has asked the same question before. + +IRC:: ++ +The Buildroot IRC channel irc://freenode.net/#buildroot[#buildroot] is +hosted on http://webchat.freenode.net[Freenode]. It is a useful place to +ask quick questions or discuss on certain topics. ++ +When asking for help on IRC, share relevant logs or pieces of code +using a code sharing website, such as http://code.bulix.org. ++ +Note that for certain questions, posting to the mailing list may be +better as it will reach more people, both developers and users. + +Bug tracker:: ++ +Bugs in Buildroot can be reported via the mailing list or alternatively +via the https://bugs.busybox.net/buglist.cgi?product=buildroot[Buildroot +bugtracker]. Please refer to xref:reporting-bugs[] before creating a bug +report. + +Wiki:: ++ +http://elinux.org/Buildroot[The Buildroot wiki page] is hosted on +the http://elinux.org[eLinux] wiki. It contains some useful links, an +overview of past and upcoming events, and a TODO list. + +Patchwork:: ++ +Patchwork is a web-based patch tracking system designed to facilitate +the contribution and management of contributions to an open-source +project. Patches that have been sent to a mailing list are \'caught' by +the system, and appear on a web page. Any comments posted that +reference the patch are appended to the patch page too. For more +information on Patchwork see +http://jk.ozlabs.org/projects/patchwork[]. ++ +Buildroot's Patchwork website is mainly for use by Buildroot's +maintainer to ensure patches aren't missed. It is also used by Buildroot +patch reviewers (see also xref:apply-patches-patchwork[]). +However, since the website exposes patches and their corresponding +review comments in a clean and concise web interface, it can be useful +for all Buildroot developers. ++ +The Buildroot patch management interface is available at +http://patchwork.buildroot.org[]. diff --git a/docs/manual/using.txt b/docs/manual/using.txt deleted file mode 100644 index 975fffc318..0000000000 --- a/docs/manual/using.txt +++ /dev/null @@ -1,123 +0,0 @@ -// -*- 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 --------------------- - -You *should never* use +make -jN+ with Buildroot: top-level parallel -make is currently not supported. Instead, use the +BR2_JLEVEL+ option -to tell Buildroot to run the compilation of each individual package -with +make -jN+. - -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. - -* +staging/+ which contains a hierarchy similar to a root filesystem - hierarchy. This directory contains the headers and libraries of the - cross-compilation toolchain and all the userspace packages selected - for the target. 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. - -* +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. - -* +host/+ contains the installation of tools compiled for the host - that are needed for the proper execution of Buildroot, including the - cross-compilation toolchain. - -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[].