* [Buildroot] [PATCH 01/11] manual: rework the whole documentation stub
2012-03-20 23:09 [Buildroot] [PATCH 00/11] RFC: Manual content reorganization Samuel MARTIN
@ 2012-03-20 23:09 ` Samuel MARTIN
2012-03-20 23:09 ` [Buildroot] [PATCH 02/11] manual: rework introduction.txt and update embedded-basics.txt Samuel MARTIN
` (13 subsequent siblings)
14 siblings, 0 replies; 53+ messages in thread
From: Samuel MARTIN @ 2012-03-20 23:09 UTC (permalink / raw)
To: buildroot
The new skeleton of the manual as it has been thought:
1. About Buildroot:
Presentation of Buildroot
2. Starting up:
Everything to quickly and easily start working with Buildroot
3. Working with Buildroot
Basics to make your work fitting your needs
4. Troubleshooting
5. Going further in Buildroot's innards
Explaination of how buildroot is organised, how it works, etc
6. Developer Guidelines
7. Getting involved
8. Contibuting to Buildroot
9. Legal notice
10. Appendix
It is easy to distinguish two parts in this plan:
- Sections 1 to 4 mainly address people starting with Buildroot
- Sections 5 to 10 are more focused on how to develop Buildroot itself
Most of the existing sections have just been moved in the hierarchy,
few were split and dispatch in, what i think was the relevant section,
and numerous others have been created.
Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>
---
docs/manual/adding-packages-autotargets.txt | 6 +++---
docs/manual/adding-packages-cmaketargets.txt | 6 +++---
docs/manual/adding-packages-conclusion.txt | 2 +-
docs/manual/adding-packages-directory.txt | 6 +++---
docs/manual/adding-packages-gentargets.txt | 6 +++---
docs/manual/adding-packages-gettext.txt | 2 +-
docs/manual/adding-packages-handwritten.txt | 4 +---
docs/manual/adding-packages.txt | 3 ++-
docs/manual/advanced.txt | 10 ++++++++++
docs/manual/board-support.txt | 3 ++-
docs/manual/ccache-support.txt | 3 ++-
docs/manual/common-usage.txt | 4 ++++
docs/manual/contribute.txt | 2 ++
docs/manual/customize-busybox-config.txt | 6 +++---
docs/manual/customize-kernel-config.txt | 3 ++-
docs/manual/customize-rootfs.txt | 3 ++-
docs/manual/customize-toolchain.txt | 10 +++++-----
docs/manual/customize-uclibc-config.txt | 4 ++--
docs/manual/customize.txt | 2 +-
docs/manual/developer-guide.txt | 8 ++++++++
docs/manual/download-location.txt | 2 +-
docs/manual/embedded-basics.txt | 2 ++
docs/manual/external-toolchain.txt | 4 ++--
docs/manual/get-involved.txt | 2 ++
docs/manual/getting.txt | 3 ++-
docs/manual/going-further.txt | 8 ++++++++
docs/manual/how-buildroot-works.txt | 2 +-
docs/manual/legal-notice.txt | 4 ++++
docs/manual/make-tips.txt | 2 ++
docs/manual/manual.txt | 21 +++++++++++----------
docs/manual/prerequisite.txt | 2 ++
docs/manual/rebuilding-packages.txt | 2 +-
docs/manual/starting-up.txt | 9 +++++++++
docs/manual/troubleshooting.txt | 2 ++
docs/manual/using-buildroot-toolchain.txt | 2 +-
docs/manual/working-with.txt | 12 ++++++++++++
docs/manual/writing-rules.txt | 11 +++++++++++
37 files changed, 133 insertions(+), 50 deletions(-)
create mode 100644 docs/manual/advanced.txt
create mode 100644 docs/manual/common-usage.txt
create mode 100644 docs/manual/contribute.txt
create mode 100644 docs/manual/developer-guide.txt
create mode 100644 docs/manual/embedded-basics.txt
create mode 100644 docs/manual/get-involved.txt
create mode 100644 docs/manual/going-further.txt
create mode 100644 docs/manual/legal-notice.txt
create mode 100644 docs/manual/make-tips.txt
create mode 100644 docs/manual/prerequisite.txt
create mode 100644 docs/manual/starting-up.txt
create mode 100644 docs/manual/troubleshooting.txt
create mode 100644 docs/manual/working-with.txt
create mode 100644 docs/manual/writing-rules.txt
diff --git a/docs/manual/adding-packages-autotargets.txt b/docs/manual/adding-packages-autotargets.txt
index 428a182..dcc7a24 100644
--- a/docs/manual/adding-packages-autotargets.txt
+++ b/docs/manual/adding-packages-autotargets.txt
@@ -1,10 +1,10 @@
Infrastructure for autotools-based packages
--------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[[autotargets-tutorial]]
+AUTOTARGETS+ tutorial
-~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^
First, let's see how to write a +.mk+ file for an autotools-based
package, with an example :
@@ -64,7 +64,7 @@ package to be built.
[[autotargets-reference]]
+AUTOTARGETS+ reference
-~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^
The main macro of the autotools package infrastructure is
+AUTOTARGETS+. It has the same number of arguments and the
diff --git a/docs/manual/adding-packages-cmaketargets.txt b/docs/manual/adding-packages-cmaketargets.txt
index 3e400ec..a6b2273 100644
--- a/docs/manual/adding-packages-cmaketargets.txt
+++ b/docs/manual/adding-packages-cmaketargets.txt
@@ -1,10 +1,10 @@
Infrastructure for CMake-based packages
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[[cmaketargets-tutorial]]
+CMAKETARGETS+ tutorial
-~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^
First, let's see how to write a +.mk+ file for a CMake-based package,
with an example :
@@ -63,7 +63,7 @@ package to be built.
[[cmaketargets-reference]]
+CMAKETARGETS+ reference
-~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^
The main macro of the CMake package infrastructure is
+CMAKETARGETS+. It has the same number of arguments and the same
diff --git a/docs/manual/adding-packages-conclusion.txt b/docs/manual/adding-packages-conclusion.txt
index 3475827..d03dc4e 100644
--- a/docs/manual/adding-packages-conclusion.txt
+++ b/docs/manual/adding-packages-conclusion.txt
@@ -1,5 +1,5 @@
Conclusion
-----------
+~~~~~~~~~~
As you can see, adding a software package to Buildroot is simply a
matter of writing a Makefile using an existing example and modifying it
diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
index 2670f2f..1428f37 100644
--- a/docs/manual/adding-packages-directory.txt
+++ b/docs/manual/adding-packages-directory.txt
@@ -1,5 +1,5 @@
Package directory
------------------
+~~~~~~~~~~~~~~~~~
First of all, create a directory under the +package+ directory for
your software, for example +libfoo+.
@@ -10,7 +10,7 @@ one of these categories, then create your package directory in these.
+Config.in+ file
-~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^
Then, create a file named +Config.in+. This file will contain the
option descriptions related to our +libfoo+ software that will be used
@@ -146,7 +146,7 @@ so, the dependency also needs to be expressed in the +.mk+ file of the
package.
The +.mk+ file
-~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^
Finally, here's the hardest part. Create a file named +libfoo.mk+. It
describes how the package should be downloaded, configured, built,
diff --git a/docs/manual/adding-packages-gentargets.txt b/docs/manual/adding-packages-gentargets.txt
index cfcee8c..c0ad89d 100644
--- a/docs/manual/adding-packages-gentargets.txt
+++ b/docs/manual/adding-packages-gentargets.txt
@@ -1,5 +1,5 @@
Infrastructure for packages with specific build systems
--------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By 'packages with specific build systems' we mean all the packages
whose build system is not one of the standard ones, such as
@@ -9,7 +9,7 @@ system is based on hand-written Makefiles or shell scripts.
[[gentargets-tutorial]]
+GENTARGETS+ Tutorial
-~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^
------------------------------
01: #############################################################
@@ -90,7 +90,7 @@ Makefile code necessary to make your package working.
[[gentargets-reference]]
+GENTARGETS+ Reference
-~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^
The +GENTARGETS+ macro takes one optional argument. This argument can
be used to tell if the package is a target package (cross-compiled for
diff --git a/docs/manual/adding-packages-gettext.txt b/docs/manual/adding-packages-gettext.txt
index 1ed834e..7eced86 100644
--- a/docs/manual/adding-packages-gettext.txt
+++ b/docs/manual/adding-packages-gettext.txt
@@ -1,5 +1,5 @@
Gettext integration and interaction with packages
--------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Many packages that support internationalization use the gettext
library. Dependencies for this library are fairly complicated and
diff --git a/docs/manual/adding-packages-handwritten.txt b/docs/manual/adding-packages-handwritten.txt
index beb25f6..25fa93c 100644
--- a/docs/manual/adding-packages-handwritten.txt
+++ b/docs/manual/adding-packages-handwritten.txt
@@ -1,7 +1,5 @@
-[[handwritten-tutorial]]
-
Manual Makefile
----------------
+~~~~~~~~~~~~~~~
*NOTE: new manual makefiles should not be created, and existing manual
makefiles should be converted either to the generic, autotools or
diff --git a/docs/manual/adding-packages.txt b/docs/manual/adding-packages.txt
index 0217e9f..91649d4 100644
--- a/docs/manual/adding-packages.txt
+++ b/docs/manual/adding-packages.txt
@@ -1,5 +1,6 @@
+[[adding-packages]]
Adding new packages to Buildroot
-================================
+--------------------------------
This section covers how new packages (userspace libraries or
applications) can be integrated into Buildroot. It also shows how
diff --git a/docs/manual/advanced.txt b/docs/manual/advanced.txt
new file mode 100644
index 0000000..f433c13
--- /dev/null
+++ b/docs/manual/advanced.txt
@@ -0,0 +1,10 @@
+Advanced usage
+--------------
+
+include::using-buildroot-toolchain.txt[]
+
+include::external-toolchain.txt[]
+
+include::ccache-support.txt[]
+
+include::download-location.txt[]
diff --git a/docs/manual/board-support.txt b/docs/manual/board-support.txt
index d1d9d63..e8142ab 100644
--- a/docs/manual/board-support.txt
+++ b/docs/manual/board-support.txt
@@ -1,5 +1,6 @@
+[[board-support]]
Creating your own board support
-===============================
+-------------------------------
Creating your own board support in Buildroot allows users of a
particular hardware platform to easily build a system that is known to
diff --git a/docs/manual/ccache-support.txt b/docs/manual/ccache-support.txt
index ab8cbad..37a9f92 100644
--- a/docs/manual/ccache-support.txt
+++ b/docs/manual/ccache-support.txt
@@ -1,5 +1,6 @@
+[[ccache]]
Using +ccache+ in Buildroot
-===========================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
http://ccache.samba.org[ccache] is a compiler cache. It stores the
object files resulting from each compilation process, and is able to
diff --git a/docs/manual/common-usage.txt b/docs/manual/common-usage.txt
new file mode 100644
index 0000000..ff8543f
--- /dev/null
+++ b/docs/manual/common-usage.txt
@@ -0,0 +1,4 @@
+Daily use
+---------
+
+include::rebuilding-packages.txt[]
diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
new file mode 100644
index 0000000..30ae800
--- /dev/null
+++ b/docs/manual/contribute.txt
@@ -0,0 +1,2 @@
+Contibuting to Buildroot
+========================
diff --git a/docs/manual/customize-busybox-config.txt b/docs/manual/customize-busybox-config.txt
index 60e6a55..880fe3a 100644
--- a/docs/manual/customize-busybox-config.txt
+++ b/docs/manual/customize-busybox-config.txt
@@ -1,6 +1,6 @@
-Customizing the Busybox configuration
--------------------------------------
[[busybox-custom]]
+Customizing the Busybox configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
http://www.busybox.net/[Busybox] is very configurable, and you may
want to customize it. You can follow these simple steps to do so. This
@@ -20,5 +20,5 @@ Otherwise, you can simply change the
options you want to change, without using the configuration tool.
If you want to use an existing config file for busybox, then see
-section xref:env-vars[].
+xref:env-vars[].
diff --git a/docs/manual/customize-kernel-config.txt b/docs/manual/customize-kernel-config.txt
index 6bafe46..93470be 100644
--- a/docs/manual/customize-kernel-config.txt
+++ b/docs/manual/customize-kernel-config.txt
@@ -1,5 +1,6 @@
+[[kernel-custom]]
Customizing the Linux kernel configuration
-------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Linux kernel configuration can be customized just like
xref:busybox-custom[BusyBox] and xref:uclibc-custom[uClibc] using
diff --git a/docs/manual/customize-rootfs.txt b/docs/manual/customize-rootfs.txt
index 8c3ea82..123c97f 100644
--- a/docs/manual/customize-rootfs.txt
+++ b/docs/manual/customize-rootfs.txt
@@ -1,5 +1,6 @@
+[[rootfs-custom]]
Customizing the generated target filesystem
--------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are a few ways to customize the resulting target filesystem:
diff --git a/docs/manual/customize-toolchain.txt b/docs/manual/customize-toolchain.txt
index 08b60a2..b4ac4a4 100644
--- a/docs/manual/customize-toolchain.txt
+++ b/docs/manual/customize-toolchain.txt
@@ -1,12 +1,12 @@
-Customizing the toolchain
--------------------------
[[toolchain-custom]]
+Customizing the toolchain
+~~~~~~~~~~~~~~~~~~~~~~~~~
There are three distinct types of toolchain backend supported in Buildroot,
available under the menu +Toolchain+, invoking +make menuconfig+.
Using the external toolchain backend
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There is no way of tuning an external toolchain since Buildroot does not
generate it.
@@ -15,7 +15,7 @@ It also requires to set the Buildroot settings according to the toolchain ones
(see xref:external-toolchain[]).
Using the internal Buildroot toolchain backend
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The internal Buildroot toolchain backend *only* allows to generate
*http://www.uclibc.org/[uClibc]-based toolchains*.
@@ -32,7 +32,7 @@ This is directly available after selecting the +Buildroot toolchain+ type in
the menu +Toolchain+.
Using the Crosstool-NG backend
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The http://crosstool-ng.org[crosstool-NG] toolchain backend enables a rather
limited set of settings under the Buildroot +Toolchain+ menu (ie. when invoking
diff --git a/docs/manual/customize-uclibc-config.txt b/docs/manual/customize-uclibc-config.txt
index e2e6799..6db4e41 100644
--- a/docs/manual/customize-uclibc-config.txt
+++ b/docs/manual/customize-uclibc-config.txt
@@ -1,6 +1,6 @@
-Customizing the uClibc configuration
-------------------------------------
[[uclibc-custom]]
+Customizing the uClibc configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Just like xref:busybox-custom[BusyBox], http://www.uclibc.org/[uClibc]
offers a lot of configuration options. They allow you to select
diff --git a/docs/manual/customize.txt b/docs/manual/customize.txt
index e8235de..8778fdd 100644
--- a/docs/manual/customize.txt
+++ b/docs/manual/customize.txt
@@ -1,5 +1,5 @@
Customization
-=============
+-------------
include::customize-rootfs.txt[]
diff --git a/docs/manual/developer-guide.txt b/docs/manual/developer-guide.txt
new file mode 100644
index 0000000..14589c2
--- /dev/null
+++ b/docs/manual/developer-guide.txt
@@ -0,0 +1,8 @@
+Developer Guidelines
+====================
+
+include::writing-rules.txt[]
+
+include::adding-packages.txt[]
+
+include::board-support.txt[]
diff --git a/docs/manual/download-location.txt b/docs/manual/download-location.txt
index cb6147f..7ac98c0 100644
--- a/docs/manual/download-location.txt
+++ b/docs/manual/download-location.txt
@@ -1,5 +1,5 @@
Location of downloaded packages
-===============================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It might be useful to know that the various tarballs that are
downloaded by the Makefiles are all stored in the +DL_DIR+ which by
diff --git a/docs/manual/embedded-basics.txt b/docs/manual/embedded-basics.txt
new file mode 100644
index 0000000..e1c66e3
--- /dev/null
+++ b/docs/manual/embedded-basics.txt
@@ -0,0 +1,2 @@
+Embedded system basics & Reasons to use Buildroot
+-------------------------------------------------
diff --git a/docs/manual/external-toolchain.txt b/docs/manual/external-toolchain.txt
index 62eb0a3..30efe42 100644
--- a/docs/manual/external-toolchain.txt
+++ b/docs/manual/external-toolchain.txt
@@ -1,6 +1,6 @@
-Using an external toolchain
-===========================
[[external-toolchain]]
+Using an external toolchain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
Using an already existing toolchain is useful for different
reasons:
diff --git a/docs/manual/get-involved.txt b/docs/manual/get-involved.txt
new file mode 100644
index 0000000..df3b055
--- /dev/null
+++ b/docs/manual/get-involved.txt
@@ -0,0 +1,2 @@
+Getting involved
+================
diff --git a/docs/manual/getting.txt b/docs/manual/getting.txt
index 42ca009..6cfdefb 100644
--- a/docs/manual/getting.txt
+++ b/docs/manual/getting.txt
@@ -1,5 +1,6 @@
+[[getting-buildroot]]
Getting Buildroot
-=================
+-----------------
Buildroot releases are made approximately every 3 months. Direct Git
access and daily snapshots are also available, if you want more
diff --git a/docs/manual/going-further.txt b/docs/manual/going-further.txt
new file mode 100644
index 0000000..67162a6
--- /dev/null
+++ b/docs/manual/going-further.txt
@@ -0,0 +1,8 @@
+Going further in Buildroot's innards
+====================================
+
+include::embedded-basics.txt[]
+
+include::how-buildroot-works.txt[]
+
+include::advanced.txt[]
diff --git a/docs/manual/how-buildroot-works.txt b/docs/manual/how-buildroot-works.txt
index 481e5a4..1e86ca3 100644
--- a/docs/manual/how-buildroot-works.txt
+++ b/docs/manual/how-buildroot-works.txt
@@ -1,5 +1,5 @@
How Buildroot works
-===================
+-------------------
As mentioned above, Buildroot is basically a set of Makefiles that
download, configure, and compile software with the correct options. It
diff --git a/docs/manual/legal-notice.txt b/docs/manual/legal-notice.txt
new file mode 100644
index 0000000..3d741a9
--- /dev/null
+++ b/docs/manual/legal-notice.txt
@@ -0,0 +1,4 @@
+Legal notice
+============
+
+TODO
diff --git a/docs/manual/make-tips.txt b/docs/manual/make-tips.txt
new file mode 100644
index 0000000..646efdf
--- /dev/null
+++ b/docs/manual/make-tips.txt
@@ -0,0 +1,2 @@
+'make' tips
+-----------
diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
index 732b50c..3e7a7ef 100644
--- a/docs/manual/manual.txt
+++ b/docs/manual/manual.txt
@@ -11,24 +11,25 @@ image::logo.png[]
include::introduction.txt[]
-include::getting.txt[]
+include::starting-up.txt[]
-include::using.txt[]
-include::customize.txt[]
-include::rebuilding-packages.txt[]
+include::working-with.txt[]
-include::how-buildroot-works.txt[]
+include::troubleshooting.txt[]
-include::using-buildroot-toolchain.txt[]
-include::external-toolchain.txt[]
-include::ccache-support.txt[]
+include::going-further.txt[]
-include::download-location.txt[]
+include::developer-guide.txt[]
+
+include::get-involved.txt[]
+
+include::contribute.txt[]
+
+include::legal-notice.txt[]
-include::adding-packages.txt[]
include::appendix.txt[]
diff --git a/docs/manual/prerequisite.txt b/docs/manual/prerequisite.txt
new file mode 100644
index 0000000..f50672b
--- /dev/null
+++ b/docs/manual/prerequisite.txt
@@ -0,0 +1,2 @@
+System requirements
+-------------------
diff --git a/docs/manual/rebuilding-packages.txt b/docs/manual/rebuilding-packages.txt
index 9a41a88..6e4ee2f 100644
--- a/docs/manual/rebuilding-packages.txt
+++ b/docs/manual/rebuilding-packages.txt
@@ -1,5 +1,5 @@
Understanding how to rebuild packages
-=====================================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
One of the most common questions asked by Buildroot users is how to
rebuild a given package or how to remove a package without rebuilding
diff --git a/docs/manual/starting-up.txt b/docs/manual/starting-up.txt
new file mode 100644
index 0000000..3a74ea6
--- /dev/null
+++ b/docs/manual/starting-up.txt
@@ -0,0 +1,9 @@
+Starting up
+===========
+
+include::prerequisite.txt[]
+
+include::getting.txt[]
+
+include::using.txt[]
+
diff --git a/docs/manual/troubleshooting.txt b/docs/manual/troubleshooting.txt
new file mode 100644
index 0000000..4eddddd
--- /dev/null
+++ b/docs/manual/troubleshooting.txt
@@ -0,0 +1,2 @@
+Troubleshooting
+===============
diff --git a/docs/manual/using-buildroot-toolchain.txt b/docs/manual/using-buildroot-toolchain.txt
index 712e9a8..24e797f 100644
--- a/docs/manual/using-buildroot-toolchain.txt
+++ b/docs/manual/using-buildroot-toolchain.txt
@@ -1,5 +1,5 @@
Using the generated toolchain outside Buildroot
-===============================================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You may want to compile, for your target, your own programs or other
software that are not packaged in Buildroot. In order to do this you
diff --git a/docs/manual/working-with.txt b/docs/manual/working-with.txt
new file mode 100644
index 0000000..01f1041
--- /dev/null
+++ b/docs/manual/working-with.txt
@@ -0,0 +1,12 @@
+Working with Buildroot
+======================
+[[working-with-br]]
+
+include::make-tips.txt[]
+
+include::customize.txt[]
+
+include::common-usage.txt[]
+
+Tweaking Buildroot
+------------------
diff --git a/docs/manual/writing-rules.txt b/docs/manual/writing-rules.txt
new file mode 100644
index 0000000..284cee2
--- /dev/null
+++ b/docs/manual/writing-rules.txt
@@ -0,0 +1,11 @@
+Writing rules
+-------------
+
++Config.in+ file
+~~~~~~~~~~~~~~~~
+
+The +.mk+ file
+~~~~~~~~~~~~~~
+
+The documentation
+~~~~~~~~~~~~~~~~~
--
1.7.9.4
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH 02/11] manual: rework introduction.txt and update embedded-basics.txt
2012-03-20 23:09 [Buildroot] [PATCH 00/11] RFC: Manual content reorganization Samuel MARTIN
2012-03-20 23:09 ` [Buildroot] [PATCH 01/11] manual: rework the whole documentation stub Samuel MARTIN
@ 2012-03-20 23:09 ` Samuel MARTIN
2012-03-20 23:09 ` [Buildroot] [PATCH 03/11] manual: update prerequisite.txt Samuel MARTIN
` (12 subsequent siblings)
14 siblings, 0 replies; 53+ messages in thread
From: Samuel MARTIN @ 2012-03-20 23:09 UTC (permalink / raw)
To: buildroot
Split and rephrasing of introduction.txt.
Cross-toolchain and pro-Buildroot explainations moved from introduction.txt
into embedded-basics.txt.
Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>
---
docs/manual/embedded-basics.txt | 65 ++++++++++++++++++++++++++++++++++
docs/manual/introduction.txt | 74 +++++++--------------------------------
2 files changed, 78 insertions(+), 61 deletions(-)
diff --git a/docs/manual/embedded-basics.txt b/docs/manual/embedded-basics.txt
index e1c66e3..bf14d7c 100644
--- a/docs/manual/embedded-basics.txt
+++ b/docs/manual/embedded-basics.txt
@@ -1,2 +1,67 @@
Embedded system basics & Reasons to use Buildroot
-------------------------------------------------
+
+Cross-compilation & cross-toolchain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A compilation toolchain is the set of tools that allows you to compile
+code for your system. It consists of a compiler (in our case, +gcc+),
+binary utils like assembler and linker (in our case, +binutils+) and a
+C standard library (for example
+http://www.gnu.org/software/libc/libc.html[GNU Libc],
+http://www.uclibc.org/[uClibc] or
+http://www.fefe.de/dietlibc/[dietlibc]). The system installed on your
+development station certainly already has a compilation toolchain that
+you can use to compile an application that runs on your system. If
+you're using a PC, your compilation toolchain runs on an x86 processor
+and generates code for an x86 processor. Under most Linux systems, the
+compilation toolchain uses the GNU libc (glibc) as the C standard
+library. This compilation toolchain is called the "host compilation
+toolchain". The machine on which it is running, and on which you're
+working, is called the "host system". The compilation toolchain is
+provided by your distribution, and Buildroot has nothing to do with it
+(other than using it to build a cross-compilation toolchain and other
+tools that are run on the development host).
+
+As said above, the compilation toolchain that comes with your system
+runs on and generates code for the processor in your host system. As
+your embedded system has a different processor, you need a
+cross-compilation toolchain - a compilation toolchain that runs on
+your host system but generates code for your target system (and target
+processor). For example, if your host system uses x86 and your target
+system uses ARM, the regular compilation toolchain on your host runs on
+x86 and generates code for x86, while the cross-compilation toolchain
+runs on x86 and generates code for ARM.
+
+[[pros-buildroot]]
+
+Why choose Buildroot
+~~~~~~~~~~~~~~~~~~~~
+
+Even if your embedded system uses an x86 processor, you might be
+interested in Buildroot for two reasons:
+
+* The compilation toolchain on your host certainly uses the GNU Libc
+ which is a complete but huge C standard library. Instead of using
+ GNU Libc on your target system, you can use uClibc which is a tiny C
+ standard library. If you want to use this C library, then you need a
+ compilation toolchain to generate binaries linked with it. Buildroot
+ can do that for you.
+
+* Buildroot automates the building of a root filesystem with all
+ needed tools like busybox. That makes it much easier than doing it
+ by hand.
+
+You might wonder why such a tool is needed when you can compile +gcc+,
++binutils+, +uClibc+ and all the other tools by hand. Of course doing
+so is possible but, dealing with all of the configure options and
+problems of every +gcc+ or +binutils+ version is very time-consuming
+and uninteresting. Buildroot automates this process through the use
+of Makefiles and has a collection of patches for each +gcc+ and
++binutils+ version to make them work on most architectures.
+
+Moreover, Buildroot provides an infrastructure for reproducing the
+build process of your kernel, cross-toolchain, and embedded root
+filesystem. Being able to reproduce the build process will be useful
+when a component needs to be patched or updated or when another person
+is supposed to take over the project.
diff --git a/docs/manual/introduction.txt b/docs/manual/introduction.txt
index 476ce25..e330674 100644
--- a/docs/manual/introduction.txt
+++ b/docs/manual/introduction.txt
@@ -1,69 +1,21 @@
About Buildroot
===============
-Buildroot is a set of Makefiles and patches that allows you to easily
-generate a cross-compilation toolchain, a root filesystem and a Linux
-kernel image for your target. Buildroot can be used for one, two or
-all of these options, independently.
-
-Buildroot is useful mainly for people working with embedded systems.
+Buildroot provides a full featured environment for cross-development.
+Buildroot is able to generate a cross-compilation toolchain, a root
+filesystem, a Linux kernel image and a bootloader for your target.
+Buildroot can be used for any combinaison of these options,
+independently.
+
+Buildroot is useful mainly for people working with embedded systems
+for a number of good reasons (see xref:pros-buildroot[]).
Embedded systems often use processors that are not the regular x86
processors everyone is used to having in his PC. They can be PowerPC
processors, MIPS processors, ARM processors, etc.
-A compilation toolchain is the set of tools that allows you to compile
-code for your system. It consists of a compiler (in our case, +gcc+),
-binary utils like assembler and linker (in our case, +binutils+) and a
-C standard library (for example
-http://www.gnu.org/software/libc/libc.html[GNU Libc],
-http://www.uclibc.org/[uClibc] or
-http://www.fefe.de/dietlibc/[dietlibc]). The system installed on your
-development station certainly already has a compilation toolchain that
-you can use to compile an application that runs on your system. If
-you're using a PC, your compilation toolchain runs on an x86 processor
-and generates code for an x86 processor. Under most Linux systems, the
-compilation toolchain uses the GNU libc (glibc) as the C standard
-library. This compilation toolchain is called the "host compilation
-toolchain". The machine on which it is running, and on which you're
-working, is called the "host system". The compilation toolchain is
-provided by your distribution, and Buildroot has nothing to do with it
-(other than using it to build a cross-compilation toolchain and other
-tools that are run on the development host).
-
-As said above, the compilation toolchain that comes with your system
-runs on and generates code for the processor in your host system. As
-your embedded system has a different processor, you need a
-cross-compilation toolchain - a compilation toolchain that runs on
-your host system but generates code for your target system (and target
-processor). For example, if your host system uses x86 and your target
-system uses ARM, the regular compilation toolchain on your host runs on
-x86 and generates code for x86, while the cross-compilation toolchain
-runs on x86 and generates code for ARM.
-
-Even if your embedded system uses an x86 processor, you might be
-interested in Buildroot for two reasons:
-
-* The compilation toolchain on your host certainly uses the GNU Libc
- which is a complete but huge C standard library. Instead of using
- GNU Libc on your target system, you can use uClibc which is a tiny C
- standard library. If you want to use this C library, then you need a
- compilation toolchain to generate binaries linked with it. Buildroot
- can do that for you.
-
-* Buildroot automates the building of a root filesystem with all
- needed tools like busybox. That makes it much easier than doing it
- by hand.
-
-You might wonder why such a tool is needed when you can compile +gcc+,
-+binutils+, +uClibc+ and all the other tools by hand. Of course doing
-so is possible but, dealing with all of the configure options and
-problems of every +gcc+ or +binutils+ version is very time-consuming
-and uninteresting. Buildroot automates this process through the use
-of Makefiles and has a collection of patches for each +gcc+ and
-+binutils+ version to make them work on most architectures.
+Buildroot supports numerous processors and their variants; it also
+comes with default configuration for several boards available
+off-the-shelf. Besides, a number of third-party projects are based on
+or develop their BSP footnote:[BSP: Board Software Package] or
+SDK footnote:[SDK: Standard Development Kit] on top of Buildroot.
-Moreover, Buildroot provides an infrastructure for reproducing the
-build process of your kernel, cross-toolchain, and embedded root
-filesystem. Being able to reproduce the build process will be useful
-when a component needs to be patched or updated or when another person
-is supposed to take over the project.
--
1.7.9.4
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH 03/11] manual: update prerequisite.txt
2012-03-20 23:09 [Buildroot] [PATCH 00/11] RFC: Manual content reorganization Samuel MARTIN
2012-03-20 23:09 ` [Buildroot] [PATCH 01/11] manual: rework the whole documentation stub Samuel MARTIN
2012-03-20 23:09 ` [Buildroot] [PATCH 02/11] manual: rework introduction.txt and update embedded-basics.txt Samuel MARTIN
@ 2012-03-20 23:09 ` Samuel MARTIN
2012-03-20 23:29 ` Thomas Petazzoni
2012-03-20 23:09 ` [Buildroot] [PATCH 04/11] manual: rework using.txt and update common-usage.txt Samuel MARTIN
` (11 subsequent siblings)
14 siblings, 1 reply; 53+ messages in thread
From: Samuel MARTIN @ 2012-03-20 23:09 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>
---
docs/manual/prerequisite.txt | 67 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 67 insertions(+)
diff --git a/docs/manual/prerequisite.txt b/docs/manual/prerequisite.txt
index f50672b..df1e6a8 100644
--- a/docs/manual/prerequisite.txt
+++ b/docs/manual/prerequisite.txt
@@ -1,2 +1,69 @@
+[[requirement]]
System requirements
-------------------
+
+Buildroot is design to run on Linux system.
+
+Buildroot needs some software to be already installed on the host
+system; hereafter the lists of the mandatory and optional packages
+(packages' name may vary between distribution).
+
+Take care of _installing both runtime and development data_, especially
+for the libraries that may be packaged in 2 distinct packages.
+
+
+[[requirement-mandatory]]
+
+Mandatory packages
+~~~~~~~~~~~~~~~~~~
+
+* Build tools:
+** +build-essential+ (only for Debian based system)
+** +gcc+
+** +g+++
+** +autoconf+
+** +automake+
+** +libtool+
+** +bison+
+** +flex+
+** +gettext+
+** +patch+
+** +gawk+
+
+* Source fetching tools:
+** +curl+
+** +wget+
+** +cvs+
+** +git+
+** +mercurial+
+** +subversion+
+
+* Development libraries:
+** +ncurses5+
+** +lzo2+
+** +lzma+
+** +zlib1+
+** +acl1+
+** +uuid+
+
+* Documentation generation tools:
+** +asciidoc+
+** +texinfo+
+
+[[requirement-optional]]
+
+Optional packages
+~~~~~~~~~~~~~~~~~
+
+* Interface dependencies (requires development libraries):
+** +ncurses5+ to use the 'menuconfig' interface
+** +qt4+ to use the 'xconfig' interface
+** +glib2+, +gtk2+ and +glade2+ to use the 'gconfig' interface
+
+* Development libraries:
+** +glib2+
+** +netpbm10+ (for +fbtest+)
+** +python-xcbgen+ (for +Matchbox+ on Debian based system)
+** +jdk+ and and depending on the host system +gcj-compat+ for Java
+development (for +java+, +jamvm+ and +gnu-classpath+)
+
--
1.7.9.4
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH 03/11] manual: update prerequisite.txt
2012-03-20 23:09 ` [Buildroot] [PATCH 03/11] manual: update prerequisite.txt Samuel MARTIN
@ 2012-03-20 23:29 ` Thomas Petazzoni
0 siblings, 0 replies; 53+ messages in thread
From: Thomas Petazzoni @ 2012-03-20 23:29 UTC (permalink / raw)
To: buildroot
Hello Samuel,
Good work. I'll try to reply to your introduction e-mail soon with
general comments. Below some specific comments on this patch.
Le Wed, 21 Mar 2012 00:09:53 +0100,
Samuel MARTIN <s.martin49@gmail.com> a ?crit :
> +Mandatory packages
> +~~~~~~~~~~~~~~~~~~
> +
> +* Build tools:
> +** +build-essential+ (only for Debian based system)
> +** +gcc+
> +** +g+++
> +** +autoconf+
> +** +automake+
> +** +libtool+
autoconf/automake/libtool are not needed.
> +** +bison+
> +** +flex+
> +** +gettext+
> +** +patch+
> +** +gawk+
gawk is not in the list of mandatory dependencies. For example, the
crosstool-ng package builds host-gawk because it needs gawk. So this
tool is not current part of the mandatory dependencies.
> +* Source fetching tools:
> +** +curl+
curl is not needed.
> +** +wget+
> +** +cvs+
> +** +git+
> +** +mercurial+
> +** +subversion+
None of the version control systems are part of the mandatory
dependencies. They will only be needed if the user has selected only
one package that needs to be fetched from one of those version control
system.
I know it's nitpicking, but I think that one of the good thing with
Buildroot is that the amount of mandatory dependencies on the host is
relatively small, so it would be a shame to mark all those tools are
mandatory even though they are not.
> +* Development libraries:
> +** +ncurses5+
> +** +lzo2+
> +** +lzma+
> +** +zlib1+
> +** +acl1+
> +** +uuid+
Except ncurses5, none of these libraries should be needed, I think. We
build host-zlib when needed, and I don't see where the other libraries
are coming from.
> +* Documentation generation tools:
> +** +asciidoc+
This one should be part of the optional dependencies, people /using/
Buildroot will not need to re-generate the documentation.
> +** +texinfo+
> +
> +[[requirement-optional]]
> +
> +Optional packages
> +~~~~~~~~~~~~~~~~~
> +
> +* Interface dependencies (requires development libraries):
s/Interface/Configuration interface/
> +** +ncurses5+ to use the 'menuconfig' interface
This one is already listed above as a mandatory dependency.
> +** +qt4+ to use the 'xconfig' interface
> +** +glib2+, +gtk2+ and +glade2+ to use the 'gconfig' interface
> +
> +* Development libraries:
> +** +glib2+
> +** +netpbm10+ (for +fbtest+)
> +** +python-xcbgen+ (for +Matchbox+ on Debian based system)
Huh, why?!? We build host-libglib2 when needed, and the other ones
should be fixed if they don't build correctly without those host
components installed.
> +** +jdk+ and and depending on the host system +gcj-compat+ for Java
> +development (for +java+, +jamvm+ and +gnu-classpath+)
We don't have Java packages anymore in Buildroot, at least at the
moment.
Best regards,
Thomas
--
Thomas Petazzoni, Free Electrons
Kernel, drivers, real-time and embedded Linux
development, consulting, training and support.
http://free-electrons.com
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH 04/11] manual: rework using.txt and update common-usage.txt
2012-03-20 23:09 [Buildroot] [PATCH 00/11] RFC: Manual content reorganization Samuel MARTIN
` (2 preceding siblings ...)
2012-03-20 23:09 ` [Buildroot] [PATCH 03/11] manual: update prerequisite.txt Samuel MARTIN
@ 2012-03-20 23:09 ` Samuel MARTIN
2012-03-20 23:09 ` [Buildroot] [PATCH 05/11] manual: update make-tips.txt Samuel MARTIN
` (10 subsequent siblings)
14 siblings, 0 replies; 53+ messages in thread
From: Samuel MARTIN @ 2012-03-20 23:09 UTC (permalink / raw)
To: buildroot
Consider the second chapter: "starting-up", as a tutorial.
Assuming that, using.txt only contains the very first commands used to get
configure and build its very first target system.
So, the following subsection from using.txt have been to common-usage.txt:
- Offline builds
- Building out-of-tree
- Environment variables
Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>
---
docs/manual/common-usage.txt | 77 +++++++++++++++++++++++++++++++
docs/manual/using.txt | 105 +++++++-----------------------------------
2 files changed, 93 insertions(+), 89 deletions(-)
diff --git a/docs/manual/common-usage.txt b/docs/manual/common-usage.txt
index ff8543f..dde1ab0 100644
--- a/docs/manual/common-usage.txt
+++ b/docs/manual/common-usage.txt
@@ -2,3 +2,80 @@ Daily use
---------
include::rebuilding-packages.txt[]
+
+Offline builds
+~~~~~~~~~~~~~~
+
+If you intend to do an offline build and just want to download
+all sources that you previously selected in the configurator
+('menuconfig', 'xconfig' or 'gconfig'), then issue:
+
+--------------------
+ $ make source
+--------------------
+
+You can now disconnect or copy the content of your +dl+
+directory to the build-host.
+
+Building out-of-tree
+~~~~~~~~~~~~~~~~~~~~
+
+Buildroot supports building out of tree with a syntax similar to the
+Linux kernel. To use it, add +O=<directory>+ to the make command line:
+
+--------------------
+ $ make O=/tmp/build
+--------------------
+
+Or:
+
+--------------------
+ $ cd /tmp/build; make O=$PWD -C path/to/buildroot
+--------------------
+
+All the output files will be located under +/tmp/build+.
+
+When using out-of-tree builds, the Buildroot +.config+ and temporary
+files are also stored in the output directory. This means that you can
+safely run multiple builds in parallel using the same source tree as
+long as they use unique output directories.
+
+For ease of use, Buildroot generates a Makefile wrapper in the output
+directory - So after the first run, you no longer need to pass +O=..+
+and +-C ..+, simply run (in the output directory):
+
+--------------------
+ $ make <target>
+--------------------
+
+[[env-vars]]
+
+Environment variables
+~~~~~~~~~~~~~~~~~~~~~
+
+Buildroot also honors some environment variables, when they are passed
+to +make+ or set in the environment:
+
+* +HOSTCXX+, the host C++ compiler to use
+* +HOSTCC+, the host C compiler to use
+* +UCLIBC_CONFIG_FILE=<path/to/.config>+, path to
+ the uClibc configuration file, used to compile uClibc, if an
+ internal toolchain is being built
+* +BUSYBOX_CONFIG_FILE=<path/to/.config>+, path to
+ the Busybox configuration file
+* +BUILDROOT_DL_DIR+ to override the directory in which
+ Buildroot stores/retrieves downloaded files
+
+An example that uses config files located in the toplevel directory and
+in your $HOME:
+
+--------------------
+ $ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config
+--------------------
+
+If you want to use a compiler other than the default +gcc+
+or +g+++ for building helper-binaries on your host, then do
+
+--------------------
+ $ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD
+--------------------
diff --git a/docs/manual/using.txt b/docs/manual/using.txt
index a5dc9e1..2945098 100644
--- a/docs/manual/using.txt
+++ b/docs/manual/using.txt
@@ -1,13 +1,10 @@
Using Buildroot
-===============
-
-Configuration and general usage
--------------------------------
+---------------
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]. Note that you can (and should) build
-everything as a normal user. There is no need to be root to configure
+http://www.busybox.net/[Busybox]. Note that you can *and should build
+everything as a normal user*. There is no need to be root to configure
and use Buildroot. The first step is to run the configuration
assistant:
@@ -30,12 +27,11 @@ or
to run the Qt or GTK-based configurators.
All of these "make" commands will need to build a configuration
-utility, so you may need to install "development" packages for
-relevant libraries used by the configuration utilities. On Debian-like
-systems, the +libncurses5-dev+ package is required to use the
-'menuconfig' interface, +libqt4-dev+ is required to use the 'xconfig'
-interface, and +libglib2.0-dev, libgtk2.0-dev and libglade2-dev+ are
-needed to use the 'gconfig' interface.
+utility (including the interface), so you may need to install
+"development" packages for relevant libraries used by the
+configuration utilities. Check the xref:requirement[] to know what
+Buildroot needs, and specifically the xref:requirement-optional[system requirements]
+to get the dependencies of favourite interface.
For each menu entry in the configuration tool, you can find associated
help that describes the purpose of the entry.
@@ -57,9 +53,9 @@ tell Buildroot to run each package compilation with +make -jN+.
This command will generally perform the following steps:
* Download source files (as required)
-* Configure, build and install the cross-compiling toolchain if an
- internal toolchain is used, or import a toolchain if an external
- toolchain is used
+* Configure, build and install the cross-compiling toolchain using the
+ appropiate toolchain backend is used, or simply import a toolchain
+ if an external toolchain is used
* Build/install selected target packages
* Build a kernel image, if selected
* Build a bootloader image, if selected
@@ -106,78 +102,9 @@ This directory contains several subdirectories:
* +toolchain/+ contains the build directories for the various
components of the cross-compilation toolchain.
-Offline builds
---------------
-
-If you intend to do an offline build and just want to download
-all sources that you previously selected in the configurator
-('menuconfig', 'xconfig' or 'gconfig'), then issue:
-
---------------------
- $ make source
---------------------
-
-You can now disconnect or copy the content of your +dl+
-directory to the build-host.
-
-Building out-of-tree
---------------------
-
-Buildroot supports building out of tree with a syntax similar to the
-Linux kernel. To use it, add +O=<directory>+ to the make command line:
-
---------------------
- $ make O=/tmp/build
---------------------
-
-Or:
-
---------------------
- $ cd /tmp/build; make O=$PWD -C path/to/buildroot
---------------------
-
-All the output files will be located under +/tmp/build+.
-
-When using out-of-tree builds, the Buildroot +.config+ and temporary
-files are also stored in the output directory. This means that you can
-safely run multiple builds in parallel using the same source tree as
-long as they use unique output directories.
-
-For ease of use, Buildroot generates a Makefile wrapper in the output
-directory - So after the first run, you no longer need to pass +O=..+
-and +-C ..+, simply run (in the output directory):
-
---------------------
- $ make <target>
---------------------
-
-Environment variables
----------------------
-[[env-vars]]
-
-Buildroot also honors some environment variables, when they are passed
-to +make+ or set in the environment:
+These commands, +make menuconfig|gconfig|xconfig+ and +make+, are the
+basic ones that allow to easily and quickly generate images fitting
+your needs, with all the supports and applications you enabled.
-* +HOSTCXX+, the host C++ compiler to use
-* +HOSTCC+, the host C compiler to use
-* +UCLIBC_CONFIG_FILE=<path/to/.config>+, path to
- the uClibc configuration file, used to compile uClibc, if an
- internal toolchain is being built
-* +BUSYBOX_CONFIG_FILE=<path/to/.config>+, path to
- the Busybox configuration file
-* +BUILDROOT_DL_DIR+ to override the directory in which
- Buildroot stores/retrieves downloaded files
-
-An example that uses config files located in the toplevel directory and
-in your $HOME:
-
---------------------
- $ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config
---------------------
-
-If you want to use a compiler other than the default +gcc+
-or +g+++ for building helper-binaries on your host, then do
-
---------------------
- $ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD
---------------------
+More details about the "make" command usages are given in
+xref:make-tips[].
--
1.7.9.4
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH 05/11] manual: update make-tips.txt
2012-03-20 23:09 [Buildroot] [PATCH 00/11] RFC: Manual content reorganization Samuel MARTIN
` (3 preceding siblings ...)
2012-03-20 23:09 ` [Buildroot] [PATCH 04/11] manual: rework using.txt and update common-usage.txt Samuel MARTIN
@ 2012-03-20 23:09 ` Samuel MARTIN
2012-03-20 23:09 ` [Buildroot] [PATCH 06/11] manual: update working-with.txt Samuel MARTIN
` (9 subsequent siblings)
14 siblings, 0 replies; 53+ messages in thread
From: Samuel MARTIN @ 2012-03-20 23:09 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>
---
docs/manual/make-tips.txt | 46 +++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 46 insertions(+)
diff --git a/docs/manual/make-tips.txt b/docs/manual/make-tips.txt
index 646efdf..a512689 100644
--- a/docs/manual/make-tips.txt
+++ b/docs/manual/make-tips.txt
@@ -1,2 +1,48 @@
+[[make-tips]]
'make' tips
-----------
+
+Because Buildroot is a set of Makefiles and patches, there are few
+things useful to know, such as:
+
+Display all command executed by make:
+
+--------------------
+ $ make V=0|1 <target>
+--------------------
+
+Display all available targets:
+
+--------------------
+ $ make help
+--------------------
+
+Note that, some settings in the +.config+ file may hide some targets
+like:
+
+* +busybox-menuconfig+ depends whether +busybox+ is enabled or not in
+ the +Package selection+ menu
+* +linux-menuconfig+ and +linux-savedefconfig+ depends on whether
+ +linux+ is enabled or not
+* +uclibc-menuconfig+ depends on whether the toolchain uses the
+ Buildroot internal toolchain backend or not
+* +ctng-menuconfig+ depends on whether the toolchain uses the
+ crosstool-NG backend or not
+* +barebox-menuconfig+ and +barebox-savedefconfig+ depends on whether
+ +barebox+ bootloader is enabled or not
+
+Delete all build products (including build directories, host, staging
+and target trees, the images and the toolchain):
+
+--------------------
+ $ make clean
+--------------------
+
+Delete all build products as well as the configuration:
+
+--------------------
+ $ make distclean
+--------------------
+
+Note that if +ccache+ is enabled, running +make clean|distclean+ does
+not empty the Buildroot's cache. To delete it, refer to xref:ccache[].
--
1.7.9.4
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH 06/11] manual: update working-with.txt
2012-03-20 23:09 [Buildroot] [PATCH 00/11] RFC: Manual content reorganization Samuel MARTIN
` (4 preceding siblings ...)
2012-03-20 23:09 ` [Buildroot] [PATCH 05/11] manual: update make-tips.txt Samuel MARTIN
@ 2012-03-20 23:09 ` Samuel MARTIN
2012-03-20 23:09 ` [Buildroot] [PATCH 07/11] manual: update troubleshooting.txt Samuel MARTIN
` (8 subsequent siblings)
14 siblings, 0 replies; 53+ messages in thread
From: Samuel MARTIN @ 2012-03-20 23:09 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>
---
docs/manual/rebuilding-packages.txt | 4 ++--
docs/manual/working-with.txt | 12 +++++++++++-
2 files changed, 13 insertions(+), 3 deletions(-)
diff --git a/docs/manual/rebuilding-packages.txt b/docs/manual/rebuilding-packages.txt
index 6e4ee2f..b0f53f6 100644
--- a/docs/manual/rebuilding-packages.txt
+++ b/docs/manual/rebuilding-packages.txt
@@ -25,8 +25,8 @@ by the different packages, so some understanding of the particular
package is needed.
For packages relying on Buildroot packages infrastructures (see
-xref:add-packages[this section] for details), the following stamp
-files are relevant:
+xref:adding-packages[] for details), the following stamp files are
+relevant:
* +output/build/packagename-version/.stamp_configured+. If removed,
Buildroot will trigger the recompilation of the package from the
diff --git a/docs/manual/working-with.txt b/docs/manual/working-with.txt
index 01f1041..b9d915c 100644
--- a/docs/manual/working-with.txt
+++ b/docs/manual/working-with.txt
@@ -1,6 +1,9 @@
Working with Buildroot
======================
-[[working-with-br]]
+
+This section aims to explain how Buildroot allows you to tune,
+customize almost everthing... making your configuration fitting your
+needs.
include::make-tips.txt[]
@@ -10,3 +13,10 @@ include::common-usage.txt[]
Tweaking Buildroot
------------------
+
+Because Buildroot does not yet fit all your requirements, you may be
+intrested in tweaking it to add:
+
+* new packages: refer to the xref:adding-packages[Developer guide]
+
+* new board support: refer to the xref:board-support[Developer guide]
--
1.7.9.4
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH 07/11] manual: update troubleshooting.txt
2012-03-20 23:09 [Buildroot] [PATCH 00/11] RFC: Manual content reorganization Samuel MARTIN
` (5 preceding siblings ...)
2012-03-20 23:09 ` [Buildroot] [PATCH 06/11] manual: update working-with.txt Samuel MARTIN
@ 2012-03-20 23:09 ` Samuel MARTIN
2012-03-20 23:09 ` [Buildroot] [PATCH 08/11] manual: rework the intro of customize-rootfs.txt Samuel MARTIN
` (7 subsequent siblings)
14 siblings, 0 replies; 53+ messages in thread
From: Samuel MARTIN @ 2012-03-20 23:09 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>
---
docs/manual/troubleshooting.txt | 44 +++++++++++++++++++++++++++++++++++++++
1 file changed, 44 insertions(+)
diff --git a/docs/manual/troubleshooting.txt b/docs/manual/troubleshooting.txt
index 4eddddd..db9277d 100644
--- a/docs/manual/troubleshooting.txt
+++ b/docs/manual/troubleshooting.txt
@@ -1,2 +1,46 @@
Troubleshooting
===============
+
+LZO package configuration failure due to incorrect host architecture detection
+------------------------------------------------------------------------------
+
+Typical error output
+~~~~~~~~~~~~~~~~~~~~
+
+------------------------
+configure: Configuring LZO 2.03
+checking build system type... Invalid configuration `x86_64-unknown-linux-': machine `x86_64-unknown-linux' not recognized
+configure: error: /bin/sh autoconf/config.sub x86_64-unknown-linux- failed
+------------------------
+
+Actually this is a known ccache/zlib issue (see
+https://bugs.busybox.net/show_bug.cgi?id=4808) that occurs when the
+zlib version of the host system is more recent that the one provided
+by Buildroot. This misleads the Buildroot host binary +ccache+.
+
+This bug has been spotted, then fixed shortly after the Buildroot
+2012.02 release.
+
+If you are using the release 2012.02 or elder and got this issue, then
+applying this patch
+http://git.buildroot.net/buildroot/patch/package/ccache/ccache.mk?id=7ea11dafff37c5403432f691cf3c46d1d5566e46
+should fix it.
+
+Solution
+~~~~~~~~
+
+* Get the upstream patch:
++
+-----------------------
+ $ wget -O /tmp/ccache-Force-ccache-to-use-its-internal-zlib.patch \
+ "http://git.buildroot.net/buildroot/patch/package/ccache/ccache.mk?id=7ea11dafff37c5403432f691cf3c46d1d5566e46"
+------------------------
+
+* Apply this patch and rebuild ccache:
++
+------------------------
+ $ cd buildroot
+ $ patch -p1 < /tmp/ccache-Force-ccache-to-use-its-internal-zlib.patch
+ $ make host-ccache-dirclean
+ $ make
+------------------------
--
1.7.9.4
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH 08/11] manual: rework the intro of customize-rootfs.txt
2012-03-20 23:09 [Buildroot] [PATCH 00/11] RFC: Manual content reorganization Samuel MARTIN
` (6 preceding siblings ...)
2012-03-20 23:09 ` [Buildroot] [PATCH 07/11] manual: update troubleshooting.txt Samuel MARTIN
@ 2012-03-20 23:09 ` Samuel MARTIN
2012-03-20 23:09 ` [Buildroot] [PATCH 09/11] manual: update writing-rules.txt Samuel MARTIN
` (6 subsequent siblings)
14 siblings, 0 replies; 53+ messages in thread
From: Samuel MARTIN @ 2012-03-20 23:09 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>
---
docs/manual/customize-rootfs.txt | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/docs/manual/customize-rootfs.txt b/docs/manual/customize-rootfs.txt
index 123c97f..d067e31 100644
--- a/docs/manual/customize-rootfs.txt
+++ b/docs/manual/customize-rootfs.txt
@@ -2,7 +2,9 @@
Customizing the generated target filesystem
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-There are a few ways to customize the resulting target filesystem:
+Apart changing one or another configuration through +make
+*-menuconfig+, there are a few ways to customize the resulting target
+filesystem:
* Customize the target filesystem directly and rebuild the image. The
target filesystem is available under +output/target/+. You can
--
1.7.9.4
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH 09/11] manual: update writing-rules.txt
2012-03-20 23:09 [Buildroot] [PATCH 00/11] RFC: Manual content reorganization Samuel MARTIN
` (7 preceding siblings ...)
2012-03-20 23:09 ` [Buildroot] [PATCH 08/11] manual: rework the intro of customize-rootfs.txt Samuel MARTIN
@ 2012-03-20 23:09 ` Samuel MARTIN
2012-03-20 23:10 ` [Buildroot] [PATCH 10/11] manual: update get-involved.txt Samuel MARTIN
` (5 subsequent siblings)
14 siblings, 0 replies; 53+ messages in thread
From: Samuel MARTIN @ 2012-03-20 23:09 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>
---
docs/manual/adding-packages-directory.txt | 5 ++
docs/manual/writing-rules.txt | 108 +++++++++++++++++++++++++++++
2 files changed, 113 insertions(+)
diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
index 1428f37..e36eafc 100644
--- a/docs/manual/adding-packages-directory.txt
+++ b/docs/manual/adding-packages-directory.txt
@@ -145,6 +145,9 @@ is also enabled, but not necessarily built before your package. To do
so, the dependency also needs to be expressed in the +.mk+ file of the
package.
+Further formating details: see xref:writing-rules-config-in[the
+writing rules].
+
The +.mk+ file
^^^^^^^^^^^^^^
@@ -185,3 +188,5 @@ different way, using different infrastructures:
many of them in the tree, we keep them documented in a
xref:handwritten-tutorial[tutorial].
+Further formating details: see xref:writing-rules-mk[the writing
+rules].
diff --git a/docs/manual/writing-rules.txt b/docs/manual/writing-rules.txt
index 284cee2..b18f30b 100644
--- a/docs/manual/writing-rules.txt
+++ b/docs/manual/writing-rules.txt
@@ -1,11 +1,119 @@
Writing rules
-------------
+Overall, those writing rules are here to help you adding new files in
+Buildroot or refactoring existing ones. In these cases, should be followed.
+
+If you slightly modify some existing file, the important thing is
+keeping th consistency of the whole file, so you can:
+* either follow the potentially deprecated rules used all over this
+file
+* or entirely rework it in order to make it comply with those rules.
+
+[[writing-rules-config-in]]
+
+Config.in+ file
~~~~~~~~~~~~~~~~
++Config.in+ files contain entry for almost anything configurable in
+buildroot.
+
+Entry has the following pattern:
+
+---------------------
+config BR2_PACKAGE_LIBFOO
+ bool "libfoo"
+ depends on BR2_PACKAGE_LIBBAZ
+ select BR2_PACKAGE_LIBBAR
+ help
+ This is a comment that explains what libfoo is.
+
+ http://foosoftware.org/libfoo/
+---------------------
+
+* The +bool+, +depends on+, +select+ and +help+ lines are indented
+ with one tab.
+
+* The help text itself should be indented with one tab and two
+ spaces.
+
+
+[[writing-rules-mk]]
+
The +.mk+ file
~~~~~~~~~~~~~~
+* Affectation: use +=+ preceeded and followed by one space:
++
+---------------------
+LIBFOO_VERSION = 1.0
+LIBFOO_CONF_OPT += --without-python-support
+---------------------
+
+* Indentation: use tab only:
++
+---------------------
+define LIBFOO_REMOVE_DOC
+$(RM) -fr $(TARGET_DIR)/usr/share/libfoo/doc \
+ $(TARGET_DIR)/usr/share/man/man3/libfoo*
+endef
+---------------------
+
+* Optional dependency:
+
+** Prefer multi-line syntax.
++
+YES:
++
+---------------------
+ifeq ($(BR2_PACKAGE_PYTHON),y)
+LIBFOO_CONF_OPT += --with-python-support
+LIBFOO_DEPENDENCIES += python
+else
+LIBFOO_CONF_OPT += --without-python-support
+endif
+---------------------
++
+NO:
++
+---------------------
+LIBFOO_CONF_OPT += --with$(if $(BR2_PACKAGE_PYTHON),,out)-python-support
+LIBFOO_DEPENDENCIES += $(if $(BR2_PACKAGE_PYTHON),python,)
+---------------------
+
+** Keep configure options and dependencies close together.
+
+* Optional hook: Keep hook function definition close hooks variable
+ affection nested in the +if+ block:
++
+YES:
++
+---------------------
+ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
+define LIBFOO_REMOVE_DATA
+ $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
+endef
+LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
+endif
+---------------------
++
+NO:
++
+---------------------
+define LIBFOO_REMOVE_DATA
+ $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
+endef
+
+ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
+LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
+endif
+---------------------
+
The documentation
~~~~~~~~~~~~~~~~~
+
+The documentation uses the
+http://www.methods.co.nz/asciidoc/[asciidoc] format.
+
+Further details about the http://www.methods.co.nz/asciidoc/[asciidoc]
+syntax: refer to http://www.methods.co.nz/asciidoc/userguide.html[].
--
1.7.9.4
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH 10/11] manual: update get-involved.txt
2012-03-20 23:09 [Buildroot] [PATCH 00/11] RFC: Manual content reorganization Samuel MARTIN
` (8 preceding siblings ...)
2012-03-20 23:09 ` [Buildroot] [PATCH 09/11] manual: update writing-rules.txt Samuel MARTIN
@ 2012-03-20 23:10 ` Samuel MARTIN
2012-03-20 23:10 ` [Buildroot] [PATCH 11/11] manual: update contribute.txt Samuel MARTIN
` (4 subsequent siblings)
14 siblings, 0 replies; 53+ messages in thread
From: Samuel MARTIN @ 2012-03-20 23:10 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>
---
docs/manual/get-involved.txt | 65 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 65 insertions(+)
diff --git a/docs/manual/get-involved.txt b/docs/manual/get-involved.txt
index df3b055..9b6e843 100644
--- a/docs/manual/get-involved.txt
+++ b/docs/manual/get-involved.txt
@@ -1,2 +1,67 @@
Getting involved
================
+
+Like any open source projects, Buildroot has different ways to share
+information in its community and outside.
+
+One piece of it is the document you are currently reading ;-).
+
+Each of those ways may interest you if you are look for some help,
+want to understand Buildroot or contribute to the project.
+
+Mailing List
+------------
+
+Buildroot has a mailing list
+http://lists.busybox.net/pipermail/buildroot[] for discussion and
+development.
+
+[[mailing-list-subscribe]]
+
+Subscribing to the mailing list
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can subscribe by visiting
+http://lists.busybox.net/mailman/listinfo/buildroot[].
+Only subscribers to the Buildroot mailing list are allowed to post to
+this list.
+
+The list is also available through _Gmane_ http://gmane.org[], at
++gmane.comp.lib.uclibc.buildroot+
+http://dir.gmane.org/gmane.comp.lib.uclibc.buildroot[].
+
+Searching the List Archives
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Please search the mailing list archives before asking questions on the
+mailing list, since there is a good chance someone else has asked the
+same question before. Checking the archives is a great way to avoid
+annoying everyone on the list with frequently asked questions...
+
+IRC
+---
+
+The Buildroot IRC is irc://freenode.net/#buildroot[].
+The channel +#buildroot+ is hosted on Freenode
+http://webchat.freenode.net[].
+
+When asking for help on the IRC, share relevant logs or piece of code
+using a code sharing website (see
+http://en.wikipedia.org/wiki/Comparison_of_pastebins[], and pick up
+one).
+
+Bugtracker
+----------
+
+The Buildroot bugtracker is at https://bugs.uclibc.org[].
+
+Buildroot wikipage
+------------------
+
+Consecutively to the Buildroot developer day February 3, 2012,
+a page dedicated to Buildroot has been created on
+http://elinux.org[elinux.org].
+
+This page is reachable at http://elinux.org/Buildroot[].
+
+Currently, this page is mainly used as a _todo-list_.
--
1.7.9.4
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH 11/11] manual: update contribute.txt
2012-03-20 23:09 [Buildroot] [PATCH 00/11] RFC: Manual content reorganization Samuel MARTIN
` (9 preceding siblings ...)
2012-03-20 23:10 ` [Buildroot] [PATCH 10/11] manual: update get-involved.txt Samuel MARTIN
@ 2012-03-20 23:10 ` Samuel MARTIN
2012-03-25 21:50 ` [Buildroot] [PATCH 00/11] RFC: Manual content reorganization Arnout Vandecappelle
` (3 subsequent siblings)
14 siblings, 0 replies; 53+ messages in thread
From: Samuel MARTIN @ 2012-03-20 23:10 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>
---
docs/manual/contribute.txt | 61 ++++++++++++++++++++++++++++++++++++++++++++
docs/manual/getting.txt | 1 +
2 files changed, 62 insertions(+)
diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
index 30ae800..d80e79a 100644
--- a/docs/manual/contribute.txt
+++ b/docs/manual/contribute.txt
@@ -1,2 +1,63 @@
Contibuting to Buildroot
========================
+
+If you want to contribute to Buildroot, you will need a git view of
+the project. Refer to xref:getting-buildroot[] to get it.
+
+Currently, the mailing list is the central place for contribution.
+If you have not already subscribe to it, then refer to
+xref:mailing-list-subscribe[].
+
+Submiting patches
+-----------------
+
+When your changes are done, and commited in your local git view,
+_rebase_ your development branch on top of the upstream tree before
+generating the patch set. To do so, run:
+
+---------------------
+ $ git fetch --all --tags
+ $ git rebase origin/master
+---------------------
+
+Here, your are ready to generate then submit your patch set.
+
+To generate it, run:
+
+---------------------
+ $ git format-patch -M -n -s -o outgoing origin/master
+---------------------
+
+This will generate patch files in the +outgoing+ subdirectory,
+automatically adding the +signed-of-by+ line.
+
+If you want to present the whole patch set in a separate mail, add
++--cover-letter --summary+ to the previous command line (+man
+git-format-patch+ for further information).
+
+Once patch files are generated, you can review/edit the commit message
+before submitting them using your favourite text editor.
+
+Lastly, send/submit your patch set to the Buildroot mailing list:
+
+---------------------
+ $ git send-email --to buildroot at busybox.net outgoing/*
+---------------------
+
+Note that +git+ should be configured to use your mail account.
+To configure +git+, see +man git-send-email+ or google it.
+
+Reviewing/Testing patches
+-------------------------
+
+In the review process, do not hesitate to respond to patch submissions
+for remarks, suggestions or anything that will help everyone to
+understand the patches and make them better.
+
+Some tags are used to help following the state of any patch posted on
+the mailing-list:
+
+Acked-by:: Indicates that the patch can be committed.
+
+Tested-by:: Indicates that the patch has been tested. It is useful
+ but not necessary to add a comment about what has been tested.
diff --git a/docs/manual/getting.txt b/docs/manual/getting.txt
index 6cfdefb..8ad544a 100644
--- a/docs/manual/getting.txt
+++ b/docs/manual/getting.txt
@@ -1,6 +1,7 @@
[[getting-buildroot]]
Getting Buildroot
-----------------
+[[getting-buildroot]]
Buildroot releases are made approximately every 3 months. Direct Git
access and daily snapshots are also available, if you want more
--
1.7.9.4
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH 00/11] RFC: Manual content reorganization
2012-03-20 23:09 [Buildroot] [PATCH 00/11] RFC: Manual content reorganization Samuel MARTIN
` (10 preceding siblings ...)
2012-03-20 23:10 ` [Buildroot] [PATCH 11/11] manual: update contribute.txt Samuel MARTIN
@ 2012-03-25 21:50 ` Arnout Vandecappelle
2012-04-15 10:56 ` Samuel Martin
` (2 subsequent siblings)
14 siblings, 0 replies; 53+ messages in thread
From: Arnout Vandecappelle @ 2012-03-25 21:50 UTC (permalink / raw)
To: buildroot
On Wednesday 21 March 2012 00:09:50 Samuel MARTIN wrote:
> Right now, I'm not happy with everything I did.
> For example, now I use a deeper toc (4 title levels in this patch set vs. 3 on
> the current git master). This has a side effect on the html manual, indeed the
> toc only shows the first two level, this reduce the readability, IOW the fact
> that one can quickly find the relevant piece of information he/she is looking
> for.
I don't think it reduces readability. The table of contents is much
clearer than it was before and more levels would just add clutter. The
lack of hyperlinks to levels 3 and 4 also doesn't hurt because the
deepest levels are pretty short. As you can see in the PDF: all level-2
sections fit on two pages, except for "Adding new packages to Buildroot".
Regards,
Arnout
--
Arnout Vandecappelle arnout at mind be
Senior Embedded Software Architect +32-16-286540
Essensium/Mind http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint: 7CB5 E4CC 6C2E EFD4 6E3D A754 F963 ECAB 2450 2F1F
^ permalink raw reply [flat|nested] 53+ messages in thread* [Buildroot] [PATCH 00/11] RFC: Manual content reorganization
2012-03-20 23:09 [Buildroot] [PATCH 00/11] RFC: Manual content reorganization Samuel MARTIN
` (11 preceding siblings ...)
2012-03-25 21:50 ` [Buildroot] [PATCH 00/11] RFC: Manual content reorganization Arnout Vandecappelle
@ 2012-04-15 10:56 ` Samuel Martin
2012-04-25 20:23 ` Samuel Martin
2012-08-01 20:43 ` [Buildroot] [PATCH 00/11] RFC: Manual content reorganization Thomas Petazzoni
2012-11-09 21:25 ` Arnout Vandecappelle
14 siblings, 1 reply; 53+ messages in thread
From: Samuel Martin @ 2012-04-15 10:56 UTC (permalink / raw)
To: buildroot
Hi all,
No more comments about this set of patches?
Some of you already gave me feedback about it, or told me they will.
For anyone who is interested in improving the documentation, hereafter
is the original patch submission in the ML archive:
http://lists.busybox.net/pipermail/buildroot/2012-March/051952.html
http://lists.busybox.net/pipermail/buildroot/2012-March/051953.html
http://lists.busybox.net/pipermail/buildroot/2012-March/051954.html
http://lists.busybox.net/pipermail/buildroot/2012-March/051955.html
http://lists.busybox.net/pipermail/buildroot/2012-March/051956.html
http://lists.busybox.net/pipermail/buildroot/2012-March/051957.html
http://lists.busybox.net/pipermail/buildroot/2012-March/051958.html
http://lists.busybox.net/pipermail/buildroot/2012-March/051959.html
http://lists.busybox.net/pipermail/buildroot/2012-March/051960.html
http://lists.busybox.net/pipermail/buildroot/2012-March/051961.html
http://lists.busybox.net/pipermail/buildroot/2012-March/051962.html
http://lists.busybox.net/pipermail/buildroot/2012-March/051963.html
Cheers,
Sam
^ permalink raw reply [flat|nested] 53+ messages in thread* [Buildroot] [PATCH 00/11] RFC: Manual content reorganization
2012-04-15 10:56 ` Samuel Martin
@ 2012-04-25 20:23 ` Samuel Martin
2012-04-28 14:41 ` Arnout Vandecappelle
0 siblings, 1 reply; 53+ messages in thread
From: Samuel Martin @ 2012-04-25 20:23 UTC (permalink / raw)
To: buildroot
ping?
2012/4/15 Samuel Martin <s.martin49@gmail.com>:
> Hi all,
>
> No more comments about this set of patches?
>
> Some of you already gave me feedback about it, or told me they will.
>
> For anyone who is interested in improving the documentation, hereafter
> is the original patch submission in the ML archive:
> http://lists.busybox.net/pipermail/buildroot/2012-March/051952.html
> http://lists.busybox.net/pipermail/buildroot/2012-March/051953.html
> http://lists.busybox.net/pipermail/buildroot/2012-March/051954.html
> http://lists.busybox.net/pipermail/buildroot/2012-March/051955.html
> http://lists.busybox.net/pipermail/buildroot/2012-March/051956.html
> http://lists.busybox.net/pipermail/buildroot/2012-March/051957.html
> http://lists.busybox.net/pipermail/buildroot/2012-March/051958.html
> http://lists.busybox.net/pipermail/buildroot/2012-March/051959.html
> http://lists.busybox.net/pipermail/buildroot/2012-March/051960.html
> http://lists.busybox.net/pipermail/buildroot/2012-March/051961.html
> http://lists.busybox.net/pipermail/buildroot/2012-March/051962.html
> http://lists.busybox.net/pipermail/buildroot/2012-March/051963.html
>
>
> Cheers,
>
> Sam
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH 00/11] RFC: Manual content reorganization
2012-04-25 20:23 ` Samuel Martin
@ 2012-04-28 14:41 ` Arnout Vandecappelle
2012-05-06 21:04 ` Peter Korsgaard
0 siblings, 1 reply; 53+ messages in thread
From: Arnout Vandecappelle @ 2012-04-28 14:41 UTC (permalink / raw)
To: buildroot
On Wednesday 25 April 2012 22:23:30 Samuel Martin wrote:
> ping?
>
> 2012/4/15 Samuel Martin <s.martin49@gmail.com>:
> > Hi all,
> >
> > No more comments about this set of patches?
> >
> > Some of you already gave me feedback about it, or told me they will.
> >
> > For anyone who is interested in improving the documentation, hereafter
> > is the original patch submission in the ML archive:
> > http://lists.busybox.net/pipermail/buildroot/2012-March/051952.html
> > http://lists.busybox.net/pipermail/buildroot/2012-March/051953.html
> > http://lists.busybox.net/pipermail/buildroot/2012-March/051954.html
> > http://lists.busybox.net/pipermail/buildroot/2012-March/051955.html
> > http://lists.busybox.net/pipermail/buildroot/2012-March/051956.html
> > http://lists.busybox.net/pipermail/buildroot/2012-March/051957.html
> > http://lists.busybox.net/pipermail/buildroot/2012-March/051958.html
> > http://lists.busybox.net/pipermail/buildroot/2012-March/051959.html
> > http://lists.busybox.net/pipermail/buildroot/2012-March/051960.html
> > http://lists.busybox.net/pipermail/buildroot/2012-March/051961.html
> > http://lists.busybox.net/pipermail/buildroot/2012-March/051962.html
> > http://lists.busybox.net/pipermail/buildroot/2012-March/051963.html
I'm very much in favour of this reorganisation. I've started a
review of the documentation based on your final version (but it
got stalled a bit due to holidays).
Peter, would it expedite things if Samuel reposted the patches?
Regards,
Arnout
--
Arnout Vandecappelle arnout at mind be
Senior Embedded Software Architect +32-16-286540
Essensium/Mind http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint: 7CB5 E4CC 6C2E EFD4 6E3D A754 F963 ECAB 2450 2F1F
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH 00/11] RFC: Manual content reorganization
2012-04-28 14:41 ` Arnout Vandecappelle
@ 2012-05-06 21:04 ` Peter Korsgaard
2012-05-07 15:39 ` Samuel Martin
0 siblings, 1 reply; 53+ messages in thread
From: Peter Korsgaard @ 2012-05-06 21:04 UTC (permalink / raw)
To: buildroot
>>>>> "Arnout" == Arnout Vandecappelle <arnout@mind.be> writes:
Hi,
Arnout> I'm very much in favour of this reorganisation. I've started a
Arnout> review of the documentation based on your final version (but it
Arnout> got stalled a bit due to holidays).
Arnout> Peter, would it expedite things if Samuel reposted the patches?
Yes I think so (after fixing the things Thomas pointed out).
--
Bye, Peter Korsgaard
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH 00/11] RFC: Manual content reorganization
2012-05-06 21:04 ` Peter Korsgaard
@ 2012-05-07 15:39 ` Samuel Martin
2012-05-12 23:18 ` Arnout Vandecappelle
0 siblings, 1 reply; 53+ messages in thread
From: Samuel Martin @ 2012-05-07 15:39 UTC (permalink / raw)
To: buildroot
Hi Arnout, Peter, all,
2012/5/6 Peter Korsgaard <jacmet@uclibc.org>:
>>>>>> "Arnout" == Arnout Vandecappelle <arnout@mind.be> writes:
>
> Hi,
>
> ?Arnout> ?I'm very much in favour of this reorganisation. ?I've started a
> ?Arnout> review of the documentation based on your final version (but it
> ?Arnout> got stalled a bit due to holidays).
>
> ?Arnout> ?Peter, would it expedite things if Samuel reposted the patches?
>
> Yes I think so (after fixing the things Thomas pointed out).
I have not reposted the patches yet, I slightly reworked them
according to the already sent comments though.
I'm still waiting for some comments from Thomas... or perhaps I've
missed them...
Anyway, I've already updated the series and sometime I rebase it on
top of the master.
You can get these patches checking out the branch sma/docs from
git://github.com/tSed/buildroot.git
Cheers,
Sam
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH 00/11] RFC: Manual content reorganization
2012-05-07 15:39 ` Samuel Martin
@ 2012-05-12 23:18 ` Arnout Vandecappelle
2012-05-13 10:38 ` [Buildroot] [PATCH v2 " Samuel Martin
0 siblings, 1 reply; 53+ messages in thread
From: Arnout Vandecappelle @ 2012-05-12 23:18 UTC (permalink / raw)
To: buildroot
On 05/07/12 17:39, Samuel Martin wrote:
>> > Arnout> Peter, would it expedite things if Samuel reposted the patches?
>> >
>> > Yes I think so (after fixing the things Thomas pointed out).
> I have not reposted the patches yet, I slightly reworked them
> according to the already sent comments though.
> I'm still waiting for some comments from Thomas... or perhaps I've
> missed them...
Sam, I think you should go ahead and repost the patches. The
comments from Thomas don't seem to be coming :-)
Regards,
Arnout
--
Arnout Vandecappelle arnout at mind be
Senior Embedded Software Architect +32-16-286540
Essensium/Mind http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint: 7CB5 E4CC 6C2E EFD4 6E3D A754 F963 ECAB 2450 2F1F
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH v2 00/11] RFC: Manual content reorganization
2012-05-12 23:18 ` Arnout Vandecappelle
@ 2012-05-13 10:38 ` Samuel Martin
2012-05-13 10:38 ` [Buildroot] [PATCH v2 01/11] manual: rework the whole documentation stub Samuel Martin
` (10 more replies)
0 siblings, 11 replies; 53+ messages in thread
From: Samuel Martin @ 2012-05-13 10:38 UTC (permalink / raw)
To: buildroot
Hi all,
Here is the second round of the patch series about the manual content.
For further information about the reasons, the objectives and the
new manual organization, please refer to:
http://lists.busybox.net/pipermail/buildroot/2012-March/051952.html
Happy review!
Looking forward to read your comments, suggestions, critics, blames...
Regards,
Sam
Change since v1:
* Cleanup/fix the prerequesite section
Samuel MARTIN (11):
manual: rework the whole documentation stub
manual: rework introduction.txt and add embedded-basics.txt
manual: add prerequisite.txt
manual: rework using.txt and update common-usage.txt
manual: add make-tips.txt
manual: update working-with.txt
manual: rework the intro of customize-rootfs.txt
manual: add troubleshooting.txt
manual: add writing-rules.txt
manual: add get-involved.txt
manual: add contribute.txt
docs/manual/adding-packages-autotargets.txt | 6 +-
docs/manual/adding-packages-cmaketargets.txt | 6 +-
docs/manual/adding-packages-conclusion.txt | 2 +-
docs/manual/adding-packages-directory.txt | 11 ++-
docs/manual/adding-packages-gentargets.txt | 6 +-
docs/manual/adding-packages-gettext.txt | 2 +-
docs/manual/adding-packages-handwritten.txt | 4 +-
docs/manual/adding-packages.txt | 3 +-
docs/manual/advanced.txt | 10 +++
docs/manual/board-support.txt | 3 +-
docs/manual/ccache-support.txt | 3 +-
docs/manual/common-usage.txt | 81 ++++++++++++++++++
docs/manual/contribute.txt | 63 ++++++++++++++
docs/manual/customize-busybox-config.txt | 6 +-
docs/manual/customize-kernel-config.txt | 3 +-
docs/manual/customize-rootfs.txt | 7 +-
docs/manual/customize-toolchain.txt | 10 +--
docs/manual/customize-uclibc-config.txt | 4 +-
docs/manual/customize.txt | 2 +-
docs/manual/developer-guide.txt | 8 ++
docs/manual/download-location.txt | 2 +-
docs/manual/embedded-basics.txt | 67 +++++++++++++++
docs/manual/external-toolchain.txt | 4 +-
docs/manual/get-involved.txt | 67 +++++++++++++++
docs/manual/getting.txt | 3 +-
docs/manual/going-further.txt | 8 ++
docs/manual/how-buildroot-works.txt | 2 +-
docs/manual/introduction.txt | 74 +++-------------
docs/manual/legal-notice.txt | 4 +
docs/manual/make-tips.txt | 48 +++++++++++
docs/manual/manual.txt | 21 ++---
docs/manual/prerequisite.txt | 62 ++++++++++++++
docs/manual/rebuilding-packages.txt | 6 +-
docs/manual/starting-up.txt | 9 ++
docs/manual/troubleshooting.txt | 46 ++++++++++
docs/manual/using-buildroot-toolchain.txt | 2 +-
docs/manual/using.txt | 105 ++++-------------------
docs/manual/working-with.txt | 22 +++++
docs/manual/writing-rules.txt | 119 ++++++++++++++++++++++++++
39 files changed, 708 insertions(+), 203 deletions(-)
create mode 100644 docs/manual/advanced.txt
create mode 100644 docs/manual/common-usage.txt
create mode 100644 docs/manual/contribute.txt
create mode 100644 docs/manual/developer-guide.txt
create mode 100644 docs/manual/embedded-basics.txt
create mode 100644 docs/manual/get-involved.txt
create mode 100644 docs/manual/going-further.txt
create mode 100644 docs/manual/legal-notice.txt
create mode 100644 docs/manual/make-tips.txt
create mode 100644 docs/manual/prerequisite.txt
create mode 100644 docs/manual/starting-up.txt
create mode 100644 docs/manual/troubleshooting.txt
create mode 100644 docs/manual/working-with.txt
create mode 100644 docs/manual/writing-rules.txt
--
1.7.10.2
^ permalink raw reply [flat|nested] 53+ messages in thread* [Buildroot] [PATCH v2 01/11] manual: rework the whole documentation stub
2012-05-13 10:38 ` [Buildroot] [PATCH v2 " Samuel Martin
@ 2012-05-13 10:38 ` Samuel Martin
2012-05-16 11:45 ` Thomas De Schampheleire
2012-05-13 10:38 ` [Buildroot] [PATCH v2 02/11] manual: rework introduction.txt and add embedded-basics.txt Samuel Martin
` (9 subsequent siblings)
10 siblings, 1 reply; 53+ messages in thread
From: Samuel Martin @ 2012-05-13 10:38 UTC (permalink / raw)
To: buildroot
From: Samuel MARTIN <s.martin49@gmail.com>
The new skeleton of the manual as it has been thought:
1. About Buildroot:
Presentation of Buildroot
2. Starting up:
Everything to quickly and easily start working with Buildroot
3. Working with Buildroot
Basics to make your work fitting your needs
4. Troubleshooting
5. Going further in Buildroot's innards
Explaination of how buildroot is organised, how it works, etc
6. Developer Guidelines
7. Getting involved
8. Contibuting to Buildroot
9. Legal notice
10. Appendix
It is easy to distinguish two parts in this plan:
- Sections 1 to 4 mainly address people starting with Buildroot
- Sections 5 to 10 are more focused on how to develop Buildroot itself
Most of the existing sections have just been moved in the hierarchy,
few were split and dispatch in, what i think was the relevant section,
and numerous others have been created.
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
create mode 100644 docs/manual/advanced.txt
create mode 100644 docs/manual/common-usage.txt
create mode 100644 docs/manual/developer-guide.txt
create mode 100644 docs/manual/going-further.txt
create mode 100644 docs/manual/legal-notice.txt
create mode 100644 docs/manual/starting-up.txt
create mode 100644 docs/manual/working-with.txt
diff --git a/docs/manual/adding-packages-autotargets.txt b/docs/manual/adding-packages-autotargets.txt
index 428a182..dcc7a24 100644
--- a/docs/manual/adding-packages-autotargets.txt
+++ b/docs/manual/adding-packages-autotargets.txt
@@ -1,10 +1,10 @@
Infrastructure for autotools-based packages
--------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[[autotargets-tutorial]]
+AUTOTARGETS+ tutorial
-~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^
First, let's see how to write a +.mk+ file for an autotools-based
package, with an example :
@@ -64,7 +64,7 @@ package to be built.
[[autotargets-reference]]
+AUTOTARGETS+ reference
-~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^
The main macro of the autotools package infrastructure is
+AUTOTARGETS+. It has the same number of arguments and the
diff --git a/docs/manual/adding-packages-cmaketargets.txt b/docs/manual/adding-packages-cmaketargets.txt
index 3e400ec..a6b2273 100644
--- a/docs/manual/adding-packages-cmaketargets.txt
+++ b/docs/manual/adding-packages-cmaketargets.txt
@@ -1,10 +1,10 @@
Infrastructure for CMake-based packages
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[[cmaketargets-tutorial]]
+CMAKETARGETS+ tutorial
-~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^
First, let's see how to write a +.mk+ file for a CMake-based package,
with an example :
@@ -63,7 +63,7 @@ package to be built.
[[cmaketargets-reference]]
+CMAKETARGETS+ reference
-~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^
The main macro of the CMake package infrastructure is
+CMAKETARGETS+. It has the same number of arguments and the same
diff --git a/docs/manual/adding-packages-conclusion.txt b/docs/manual/adding-packages-conclusion.txt
index 3475827..d03dc4e 100644
--- a/docs/manual/adding-packages-conclusion.txt
+++ b/docs/manual/adding-packages-conclusion.txt
@@ -1,5 +1,5 @@
Conclusion
-----------
+~~~~~~~~~~
As you can see, adding a software package to Buildroot is simply a
matter of writing a Makefile using an existing example and modifying it
diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
index 2670f2f..1428f37 100644
--- a/docs/manual/adding-packages-directory.txt
+++ b/docs/manual/adding-packages-directory.txt
@@ -1,5 +1,5 @@
Package directory
------------------
+~~~~~~~~~~~~~~~~~
First of all, create a directory under the +package+ directory for
your software, for example +libfoo+.
@@ -10,7 +10,7 @@ one of these categories, then create your package directory in these.
+Config.in+ file
-~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^
Then, create a file named +Config.in+. This file will contain the
option descriptions related to our +libfoo+ software that will be used
@@ -146,7 +146,7 @@ so, the dependency also needs to be expressed in the +.mk+ file of the
package.
The +.mk+ file
-~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^
Finally, here's the hardest part. Create a file named +libfoo.mk+. It
describes how the package should be downloaded, configured, built,
diff --git a/docs/manual/adding-packages-gentargets.txt b/docs/manual/adding-packages-gentargets.txt
index cfcee8c..c0ad89d 100644
--- a/docs/manual/adding-packages-gentargets.txt
+++ b/docs/manual/adding-packages-gentargets.txt
@@ -1,5 +1,5 @@
Infrastructure for packages with specific build systems
--------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By 'packages with specific build systems' we mean all the packages
whose build system is not one of the standard ones, such as
@@ -9,7 +9,7 @@ system is based on hand-written Makefiles or shell scripts.
[[gentargets-tutorial]]
+GENTARGETS+ Tutorial
-~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^
------------------------------
01: #############################################################
@@ -90,7 +90,7 @@ Makefile code necessary to make your package working.
[[gentargets-reference]]
+GENTARGETS+ Reference
-~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^
The +GENTARGETS+ macro takes one optional argument. This argument can
be used to tell if the package is a target package (cross-compiled for
diff --git a/docs/manual/adding-packages-gettext.txt b/docs/manual/adding-packages-gettext.txt
index 1ed834e..7eced86 100644
--- a/docs/manual/adding-packages-gettext.txt
+++ b/docs/manual/adding-packages-gettext.txt
@@ -1,5 +1,5 @@
Gettext integration and interaction with packages
--------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Many packages that support internationalization use the gettext
library. Dependencies for this library are fairly complicated and
diff --git a/docs/manual/adding-packages-handwritten.txt b/docs/manual/adding-packages-handwritten.txt
index beb25f6..25fa93c 100644
--- a/docs/manual/adding-packages-handwritten.txt
+++ b/docs/manual/adding-packages-handwritten.txt
@@ -1,7 +1,5 @@
-[[handwritten-tutorial]]
-
Manual Makefile
----------------
+~~~~~~~~~~~~~~~
*NOTE: new manual makefiles should not be created, and existing manual
makefiles should be converted either to the generic, autotools or
diff --git a/docs/manual/adding-packages.txt b/docs/manual/adding-packages.txt
index 0217e9f..91649d4 100644
--- a/docs/manual/adding-packages.txt
+++ b/docs/manual/adding-packages.txt
@@ -1,5 +1,6 @@
+[[adding-packages]]
Adding new packages to Buildroot
-================================
+--------------------------------
This section covers how new packages (userspace libraries or
applications) can be integrated into Buildroot. It also shows how
diff --git a/docs/manual/advanced.txt b/docs/manual/advanced.txt
new file mode 100644
index 0000000..f433c13
--- /dev/null
+++ b/docs/manual/advanced.txt
@@ -0,0 +1,10 @@
+Advanced usage
+--------------
+
+include::using-buildroot-toolchain.txt[]
+
+include::external-toolchain.txt[]
+
+include::ccache-support.txt[]
+
+include::download-location.txt[]
diff --git a/docs/manual/board-support.txt b/docs/manual/board-support.txt
index d1d9d63..e8142ab 100644
--- a/docs/manual/board-support.txt
+++ b/docs/manual/board-support.txt
@@ -1,5 +1,6 @@
+[[board-support]]
Creating your own board support
-===============================
+-------------------------------
Creating your own board support in Buildroot allows users of a
particular hardware platform to easily build a system that is known to
diff --git a/docs/manual/ccache-support.txt b/docs/manual/ccache-support.txt
index ab8cbad..37a9f92 100644
--- a/docs/manual/ccache-support.txt
+++ b/docs/manual/ccache-support.txt
@@ -1,5 +1,6 @@
+[[ccache]]
Using +ccache+ in Buildroot
-===========================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
http://ccache.samba.org[ccache] is a compiler cache. It stores the
object files resulting from each compilation process, and is able to
diff --git a/docs/manual/common-usage.txt b/docs/manual/common-usage.txt
new file mode 100644
index 0000000..ff8543f
--- /dev/null
+++ b/docs/manual/common-usage.txt
@@ -0,0 +1,4 @@
+Daily use
+---------
+
+include::rebuilding-packages.txt[]
diff --git a/docs/manual/customize-busybox-config.txt b/docs/manual/customize-busybox-config.txt
index 60e6a55..880fe3a 100644
--- a/docs/manual/customize-busybox-config.txt
+++ b/docs/manual/customize-busybox-config.txt
@@ -1,6 +1,6 @@
-Customizing the Busybox configuration
--------------------------------------
[[busybox-custom]]
+Customizing the Busybox configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
http://www.busybox.net/[Busybox] is very configurable, and you may
want to customize it. You can follow these simple steps to do so. This
@@ -20,5 +20,5 @@ Otherwise, you can simply change the
options you want to change, without using the configuration tool.
If you want to use an existing config file for busybox, then see
-section xref:env-vars[].
+xref:env-vars[].
diff --git a/docs/manual/customize-kernel-config.txt b/docs/manual/customize-kernel-config.txt
index 6bafe46..93470be 100644
--- a/docs/manual/customize-kernel-config.txt
+++ b/docs/manual/customize-kernel-config.txt
@@ -1,5 +1,6 @@
+[[kernel-custom]]
Customizing the Linux kernel configuration
-------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Linux kernel configuration can be customized just like
xref:busybox-custom[BusyBox] and xref:uclibc-custom[uClibc] using
diff --git a/docs/manual/customize-rootfs.txt b/docs/manual/customize-rootfs.txt
index 8c3ea82..123c97f 100644
--- a/docs/manual/customize-rootfs.txt
+++ b/docs/manual/customize-rootfs.txt
@@ -1,5 +1,6 @@
+[[rootfs-custom]]
Customizing the generated target filesystem
--------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are a few ways to customize the resulting target filesystem:
diff --git a/docs/manual/customize-toolchain.txt b/docs/manual/customize-toolchain.txt
index 08b60a2..b4ac4a4 100644
--- a/docs/manual/customize-toolchain.txt
+++ b/docs/manual/customize-toolchain.txt
@@ -1,12 +1,12 @@
-Customizing the toolchain
--------------------------
[[toolchain-custom]]
+Customizing the toolchain
+~~~~~~~~~~~~~~~~~~~~~~~~~
There are three distinct types of toolchain backend supported in Buildroot,
available under the menu +Toolchain+, invoking +make menuconfig+.
Using the external toolchain backend
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There is no way of tuning an external toolchain since Buildroot does not
generate it.
@@ -15,7 +15,7 @@ It also requires to set the Buildroot settings according to the toolchain ones
(see xref:external-toolchain[]).
Using the internal Buildroot toolchain backend
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The internal Buildroot toolchain backend *only* allows to generate
*http://www.uclibc.org/[uClibc]-based toolchains*.
@@ -32,7 +32,7 @@ This is directly available after selecting the +Buildroot toolchain+ type in
the menu +Toolchain+.
Using the Crosstool-NG backend
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The http://crosstool-ng.org[crosstool-NG] toolchain backend enables a rather
limited set of settings under the Buildroot +Toolchain+ menu (ie. when invoking
diff --git a/docs/manual/customize-uclibc-config.txt b/docs/manual/customize-uclibc-config.txt
index e2e6799..6db4e41 100644
--- a/docs/manual/customize-uclibc-config.txt
+++ b/docs/manual/customize-uclibc-config.txt
@@ -1,6 +1,6 @@
-Customizing the uClibc configuration
-------------------------------------
[[uclibc-custom]]
+Customizing the uClibc configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Just like xref:busybox-custom[BusyBox], http://www.uclibc.org/[uClibc]
offers a lot of configuration options. They allow you to select
diff --git a/docs/manual/customize.txt b/docs/manual/customize.txt
index e8235de..8778fdd 100644
--- a/docs/manual/customize.txt
+++ b/docs/manual/customize.txt
@@ -1,5 +1,5 @@
Customization
-=============
+-------------
include::customize-rootfs.txt[]
diff --git a/docs/manual/developer-guide.txt b/docs/manual/developer-guide.txt
new file mode 100644
index 0000000..69f3632
--- /dev/null
+++ b/docs/manual/developer-guide.txt
@@ -0,0 +1,6 @@
+Developer Guidelines
+====================
+
+include::adding-packages.txt[]
+
+include::board-support.txt[]
diff --git a/docs/manual/download-location.txt b/docs/manual/download-location.txt
index cb6147f..7ac98c0 100644
--- a/docs/manual/download-location.txt
+++ b/docs/manual/download-location.txt
@@ -1,5 +1,5 @@
Location of downloaded packages
-===============================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It might be useful to know that the various tarballs that are
downloaded by the Makefiles are all stored in the +DL_DIR+ which by
diff --git a/docs/manual/external-toolchain.txt b/docs/manual/external-toolchain.txt
index 62eb0a3..30efe42 100644
--- a/docs/manual/external-toolchain.txt
+++ b/docs/manual/external-toolchain.txt
@@ -1,6 +1,6 @@
-Using an external toolchain
-===========================
[[external-toolchain]]
+Using an external toolchain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
Using an already existing toolchain is useful for different
reasons:
diff --git a/docs/manual/getting.txt b/docs/manual/getting.txt
index 42ca009..6cfdefb 100644
--- a/docs/manual/getting.txt
+++ b/docs/manual/getting.txt
@@ -1,5 +1,6 @@
+[[getting-buildroot]]
Getting Buildroot
-=================
+-----------------
Buildroot releases are made approximately every 3 months. Direct Git
access and daily snapshots are also available, if you want more
diff --git a/docs/manual/going-further.txt b/docs/manual/going-further.txt
new file mode 100644
index 0000000..6f3cd6e
--- /dev/null
+++ b/docs/manual/going-further.txt
@@ -0,0 +1,6 @@
+Going further in Buildroot's innards
+====================================
+
+include::how-buildroot-works.txt[]
+
+include::advanced.txt[]
diff --git a/docs/manual/how-buildroot-works.txt b/docs/manual/how-buildroot-works.txt
index 481e5a4..1e86ca3 100644
--- a/docs/manual/how-buildroot-works.txt
+++ b/docs/manual/how-buildroot-works.txt
@@ -1,5 +1,5 @@
How Buildroot works
-===================
+-------------------
As mentioned above, Buildroot is basically a set of Makefiles that
download, configure, and compile software with the correct options. It
diff --git a/docs/manual/legal-notice.txt b/docs/manual/legal-notice.txt
new file mode 100644
index 0000000..3d741a9
--- /dev/null
+++ b/docs/manual/legal-notice.txt
@@ -0,0 +1,4 @@
+Legal notice
+============
+
+TODO
diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
index 732b50c..b35b5f6 100644
--- a/docs/manual/manual.txt
+++ b/docs/manual/manual.txt
@@ -11,24 +11,20 @@ image::logo.png[]
include::introduction.txt[]
-include::getting.txt[]
+include::starting-up.txt[]
-include::using.txt[]
-include::customize.txt[]
-include::rebuilding-packages.txt[]
+include::working-with.txt[]
-include::how-buildroot-works.txt[]
-include::using-buildroot-toolchain.txt[]
-include::external-toolchain.txt[]
-include::ccache-support.txt[]
+include::going-further.txt[]
-include::download-location.txt[]
+include::developer-guide.txt[]
+
+include::legal-notice.txt[]
-include::adding-packages.txt[]
include::appendix.txt[]
diff --git a/docs/manual/rebuilding-packages.txt b/docs/manual/rebuilding-packages.txt
index f247dd0..717121a 100644
--- a/docs/manual/rebuilding-packages.txt
+++ b/docs/manual/rebuilding-packages.txt
@@ -1,5 +1,5 @@
Understanding how to rebuild packages
-=====================================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
One of the most common questions asked by Buildroot users is how to
rebuild a given package or how to remove a package without rebuilding
diff --git a/docs/manual/starting-up.txt b/docs/manual/starting-up.txt
new file mode 100644
index 0000000..4f567f0
--- /dev/null
+++ b/docs/manual/starting-up.txt
@@ -0,0 +1,7 @@
+Starting up
+===========
+
+include::getting.txt[]
+
+include::using.txt[]
+
diff --git a/docs/manual/using-buildroot-toolchain.txt b/docs/manual/using-buildroot-toolchain.txt
index 712e9a8..24e797f 100644
--- a/docs/manual/using-buildroot-toolchain.txt
+++ b/docs/manual/using-buildroot-toolchain.txt
@@ -1,5 +1,5 @@
Using the generated toolchain outside Buildroot
-===============================================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You may want to compile, for your target, your own programs or other
software that are not packaged in Buildroot. In order to do this you
diff --git a/docs/manual/using.txt b/docs/manual/using.txt
index a5dc9e1..88dc58c 100644
--- a/docs/manual/using.txt
+++ b/docs/manual/using.txt
@@ -1,8 +1,5 @@
Using Buildroot
-===============
-
-Configuration and general usage
--------------------------------
+---------------
Buildroot has a nice configuration tool similar to the one you can
find in the http://www.kernel.org/[Linux kernel] or in
diff --git a/docs/manual/working-with.txt b/docs/manual/working-with.txt
new file mode 100644
index 0000000..e444204
--- /dev/null
+++ b/docs/manual/working-with.txt
@@ -0,0 +1,10 @@
+Working with Buildroot
+======================
+[[working-with-br]]
+
+include::customize.txt[]
+
+include::common-usage.txt[]
+
+Tweaking Buildroot
+------------------
--
1.7.10.2
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH v2 01/11] manual: rework the whole documentation stub
2012-05-13 10:38 ` [Buildroot] [PATCH v2 01/11] manual: rework the whole documentation stub Samuel Martin
@ 2012-05-16 11:45 ` Thomas De Schampheleire
0 siblings, 0 replies; 53+ messages in thread
From: Thomas De Schampheleire @ 2012-05-16 11:45 UTC (permalink / raw)
To: buildroot
On Sun, May 13, 2012 at 12:38 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> From: Samuel MARTIN <s.martin49@gmail.com>
>
> The new skeleton of the manual as it has been thought:
> 1. ?About Buildroot:
> ? ? Presentation of Buildroot
> 2. ?Starting up:
> ? ? Everything to quickly and easily start working with Buildroot
> 3. ?Working with Buildroot
> ? ? Basics to make your work fitting your needs
> 4. ?Troubleshooting
> 5. ?Going further in Buildroot's innards
> ? ? Explaination of how buildroot is organised, how it works, etc
> 6. ?Developer Guidelines
> 7. ?Getting involved
> 8. ?Contibuting to Buildroot
> 9. ?Legal notice
> 10. Appendix
>
> It is easy to distinguish two parts in this plan:
> - Sections 1 to 4 mainly address people starting with Buildroot
> - Sections 5 to 10 are more focused on how to develop Buildroot itself
>
> Most of the existing sections have just been moved in the hierarchy,
> few were split and dispatch in, what i think was the relevant section,
> and numerous others have been created.
>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
>
> ?create mode 100644 docs/manual/advanced.txt
> ?create mode 100644 docs/manual/common-usage.txt
> ?create mode 100644 docs/manual/developer-guide.txt
> ?create mode 100644 docs/manual/going-further.txt
> ?create mode 100644 docs/manual/legal-notice.txt
> ?create mode 100644 docs/manual/starting-up.txt
> ?create mode 100644 docs/manual/working-with.txt
>
> diff --git a/docs/manual/adding-packages-autotargets.txt b/docs/manual/adding-packages-autotargets.txt
> index 428a182..dcc7a24 100644
> --- a/docs/manual/adding-packages-autotargets.txt
> +++ b/docs/manual/adding-packages-autotargets.txt
> @@ -1,10 +1,10 @@
> ?Infrastructure for autotools-based packages
> --------------------------------------------
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> ?[[autotargets-tutorial]]
>
> ?+AUTOTARGETS+ tutorial
> -~~~~~~~~~~~~~~~~~~~~~~
> +^^^^^^^^^^^^^^^^^^^^^^
>
> ?First, let's see how to write a +.mk+ file for an autotools-based
> ?package, with an example :
> @@ -64,7 +64,7 @@ package to be built.
> ?[[autotargets-reference]]
>
> ?+AUTOTARGETS+ reference
> -~~~~~~~~~~~~~~~~~~~~~~~
> +^^^^^^^^^^^^^^^^^^^^^^^
>
> ?The main macro of the autotools package infrastructure is
> ?+AUTOTARGETS+. It has the same number of arguments and the
> diff --git a/docs/manual/adding-packages-cmaketargets.txt b/docs/manual/adding-packages-cmaketargets.txt
> index 3e400ec..a6b2273 100644
> --- a/docs/manual/adding-packages-cmaketargets.txt
> +++ b/docs/manual/adding-packages-cmaketargets.txt
> @@ -1,10 +1,10 @@
> ?Infrastructure for CMake-based packages
> ----------------------------------------
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> ?[[cmaketargets-tutorial]]
>
> ?+CMAKETARGETS+ tutorial
> -~~~~~~~~~~~~~~~~~~~~~~~
> +^^^^^^^^^^^^^^^^^^^^^^^
>
> ?First, let's see how to write a +.mk+ file for a CMake-based package,
> ?with an example :
> @@ -63,7 +63,7 @@ package to be built.
> ?[[cmaketargets-reference]]
>
> ?+CMAKETARGETS+ reference
> -~~~~~~~~~~~~~~~~~~~~~~~~
> +^^^^^^^^^^^^^^^^^^^^^^^^
>
> ?The main macro of the CMake package infrastructure is
> ?+CMAKETARGETS+. It has the same number of arguments and the same
> diff --git a/docs/manual/adding-packages-conclusion.txt b/docs/manual/adding-packages-conclusion.txt
> index 3475827..d03dc4e 100644
> --- a/docs/manual/adding-packages-conclusion.txt
> +++ b/docs/manual/adding-packages-conclusion.txt
> @@ -1,5 +1,5 @@
> ?Conclusion
> -----------
> +~~~~~~~~~~
>
> ?As you can see, adding a software package to Buildroot is simply a
> ?matter of writing a Makefile using an ?existing example and modifying it
> diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
> index 2670f2f..1428f37 100644
> --- a/docs/manual/adding-packages-directory.txt
> +++ b/docs/manual/adding-packages-directory.txt
> @@ -1,5 +1,5 @@
> ?Package directory
> ------------------
> +~~~~~~~~~~~~~~~~~
>
> ?First of all, create a directory under the +package+ directory for
> ?your software, for example +libfoo+.
> @@ -10,7 +10,7 @@ one of these categories, then create your package directory in these.
>
>
> ?+Config.in+ file
> -~~~~~~~~~~~~~~~~
> +^^^^^^^^^^^^^^^^
>
> ?Then, create a file named +Config.in+. This file will contain the
> ?option descriptions related to our +libfoo+ software that will be used
> @@ -146,7 +146,7 @@ so, the dependency also needs to be expressed in the +.mk+ file of the
> ?package.
>
> ?The +.mk+ file
> -~~~~~~~~~~~~~~
> +^^^^^^^^^^^^^^
>
> ?Finally, here's the hardest part. Create a file named +libfoo.mk+. It
> ?describes how the package should be downloaded, configured, built,
> diff --git a/docs/manual/adding-packages-gentargets.txt b/docs/manual/adding-packages-gentargets.txt
> index cfcee8c..c0ad89d 100644
> --- a/docs/manual/adding-packages-gentargets.txt
> +++ b/docs/manual/adding-packages-gentargets.txt
> @@ -1,5 +1,5 @@
> ?Infrastructure for packages with specific build systems
> --------------------------------------------------------
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> ?By 'packages with specific build systems' we mean all the packages
> ?whose build system is not one of the standard ones, such as
> @@ -9,7 +9,7 @@ system is based on hand-written Makefiles or shell scripts.
> ?[[gentargets-tutorial]]
>
> ?+GENTARGETS+ Tutorial
> -~~~~~~~~~~~~~~~~~~~~~
> +^^^^^^^^^^^^^^^^^^^^^
>
> ?------------------------------
> ?01: #############################################################
> @@ -90,7 +90,7 @@ Makefile code necessary to make your package working.
> ?[[gentargets-reference]]
>
> ?+GENTARGETS+ Reference
> -~~~~~~~~~~~~~~~~~~~~~~
> +^^^^^^^^^^^^^^^^^^^^^^
>
> ?The +GENTARGETS+ macro takes one optional argument. This argument can
> ?be used to tell if the package is a target package (cross-compiled for
> diff --git a/docs/manual/adding-packages-gettext.txt b/docs/manual/adding-packages-gettext.txt
> index 1ed834e..7eced86 100644
> --- a/docs/manual/adding-packages-gettext.txt
> +++ b/docs/manual/adding-packages-gettext.txt
> @@ -1,5 +1,5 @@
> ?Gettext integration and interaction with packages
> --------------------------------------------------
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> ?Many packages that support internationalization use the gettext
> ?library. Dependencies for this library are fairly complicated and
> diff --git a/docs/manual/adding-packages-handwritten.txt b/docs/manual/adding-packages-handwritten.txt
> index beb25f6..25fa93c 100644
> --- a/docs/manual/adding-packages-handwritten.txt
> +++ b/docs/manual/adding-packages-handwritten.txt
> @@ -1,7 +1,5 @@
> -[[handwritten-tutorial]]
> -
Why is this removed? I still see a reference to it in
adding-packages-directory.txt.
> ?Manual Makefile
> ----------------
> +~~~~~~~~~~~~~~~
>
> ?*NOTE: new manual makefiles should not be created, and existing manual
> ?makefiles should be converted either to the generic, autotools or
> diff --git a/docs/manual/adding-packages.txt b/docs/manual/adding-packages.txt
> index 0217e9f..91649d4 100644
> --- a/docs/manual/adding-packages.txt
> +++ b/docs/manual/adding-packages.txt
> @@ -1,5 +1,6 @@
> +[[adding-packages]]
> ?Adding new packages to Buildroot
> -================================
> +--------------------------------
>
> ?This section covers how new packages (userspace libraries or
> ?applications) can be integrated into Buildroot. It also shows how
> diff --git a/docs/manual/advanced.txt b/docs/manual/advanced.txt
> new file mode 100644
> index 0000000..f433c13
> --- /dev/null
> +++ b/docs/manual/advanced.txt
> @@ -0,0 +1,10 @@
> +Advanced usage
> +--------------
> +
> +include::using-buildroot-toolchain.txt[]
> +
> +include::external-toolchain.txt[]
> +
> +include::ccache-support.txt[]
> +
> +include::download-location.txt[]
> diff --git a/docs/manual/board-support.txt b/docs/manual/board-support.txt
> index d1d9d63..e8142ab 100644
> --- a/docs/manual/board-support.txt
> +++ b/docs/manual/board-support.txt
> @@ -1,5 +1,6 @@
> +[[board-support]]
> ?Creating your own board support
> -===============================
> +-------------------------------
>
> ?Creating your own board support in Buildroot allows users of a
> ?particular hardware platform to easily build a system that is known to
> diff --git a/docs/manual/ccache-support.txt b/docs/manual/ccache-support.txt
> index ab8cbad..37a9f92 100644
> --- a/docs/manual/ccache-support.txt
> +++ b/docs/manual/ccache-support.txt
> @@ -1,5 +1,6 @@
> +[[ccache]]
> ?Using +ccache+ in Buildroot
> -===========================
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> ?http://ccache.samba.org[ccache] is a compiler cache. It stores the
> ?object files resulting from each compilation process, and is able to
> diff --git a/docs/manual/common-usage.txt b/docs/manual/common-usage.txt
> new file mode 100644
> index 0000000..ff8543f
> --- /dev/null
> +++ b/docs/manual/common-usage.txt
> @@ -0,0 +1,4 @@
> +Daily use
> +---------
> +
> +include::rebuilding-packages.txt[]
> diff --git a/docs/manual/customize-busybox-config.txt b/docs/manual/customize-busybox-config.txt
> index 60e6a55..880fe3a 100644
> --- a/docs/manual/customize-busybox-config.txt
> +++ b/docs/manual/customize-busybox-config.txt
> @@ -1,6 +1,6 @@
> -Customizing the Busybox configuration
> --------------------------------------
> ?[[busybox-custom]]
> +Customizing the Busybox configuration
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> ?http://www.busybox.net/[Busybox] is very configurable, and you may
> ?want to customize it. You can follow these simple steps to do so. This
> @@ -20,5 +20,5 @@ Otherwise, you can simply change the
> ?options you want to change, without using the configuration tool.
>
> ?If you want to use an existing config file for busybox, then see
> -section xref:env-vars[].
> +xref:env-vars[].
>
> diff --git a/docs/manual/customize-kernel-config.txt b/docs/manual/customize-kernel-config.txt
> index 6bafe46..93470be 100644
> --- a/docs/manual/customize-kernel-config.txt
> +++ b/docs/manual/customize-kernel-config.txt
> @@ -1,5 +1,6 @@
> +[[kernel-custom]]
> ?Customizing the Linux kernel configuration
> -------------------------------------------
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> ?The Linux kernel configuration can be customized just like
> ?xref:busybox-custom[BusyBox] and xref:uclibc-custom[uClibc] using
> diff --git a/docs/manual/customize-rootfs.txt b/docs/manual/customize-rootfs.txt
> index 8c3ea82..123c97f 100644
> --- a/docs/manual/customize-rootfs.txt
> +++ b/docs/manual/customize-rootfs.txt
> @@ -1,5 +1,6 @@
> +[[rootfs-custom]]
> ?Customizing the generated target filesystem
> --------------------------------------------
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> ?There are a few ways to customize the resulting target filesystem:
>
> diff --git a/docs/manual/customize-toolchain.txt b/docs/manual/customize-toolchain.txt
> index 08b60a2..b4ac4a4 100644
> --- a/docs/manual/customize-toolchain.txt
> +++ b/docs/manual/customize-toolchain.txt
> @@ -1,12 +1,12 @@
> -Customizing the toolchain
> --------------------------
> ?[[toolchain-custom]]
> +Customizing the toolchain
> +~~~~~~~~~~~~~~~~~~~~~~~~~
>
> ?There are three distinct types of toolchain backend supported in Buildroot,
> ?available under the menu +Toolchain+, invoking +make menuconfig+.
>
> ?Using the external toolchain backend
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> ?There is no way of tuning an external toolchain since Buildroot does not
> ?generate it.
> @@ -15,7 +15,7 @@ It also requires to set the Buildroot settings according to the toolchain ones
> ?(see xref:external-toolchain[]).
>
> ?Using the internal Buildroot toolchain backend
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> ?The internal Buildroot toolchain backend *only* allows to generate
> ?*http://www.uclibc.org/[uClibc]-based toolchains*.
> @@ -32,7 +32,7 @@ This is directly available after selecting the +Buildroot toolchain+ type in
> ?the menu +Toolchain+.
>
> ?Using the Crosstool-NG backend
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> ?The http://crosstool-ng.org[crosstool-NG] toolchain backend enables a rather
> ?limited set of settings under the Buildroot +Toolchain+ menu (ie. when invoking
> diff --git a/docs/manual/customize-uclibc-config.txt b/docs/manual/customize-uclibc-config.txt
> index e2e6799..6db4e41 100644
> --- a/docs/manual/customize-uclibc-config.txt
> +++ b/docs/manual/customize-uclibc-config.txt
> @@ -1,6 +1,6 @@
> -Customizing the uClibc configuration
> -------------------------------------
> ?[[uclibc-custom]]
> +Customizing the uClibc configuration
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> ?Just like xref:busybox-custom[BusyBox], http://www.uclibc.org/[uClibc]
> ?offers a lot of configuration options. They allow you to select
> diff --git a/docs/manual/customize.txt b/docs/manual/customize.txt
> index e8235de..8778fdd 100644
> --- a/docs/manual/customize.txt
> +++ b/docs/manual/customize.txt
> @@ -1,5 +1,5 @@
> ?Customization
> -=============
> +-------------
>
> ?include::customize-rootfs.txt[]
>
> diff --git a/docs/manual/developer-guide.txt b/docs/manual/developer-guide.txt
> new file mode 100644
> index 0000000..69f3632
> --- /dev/null
> +++ b/docs/manual/developer-guide.txt
> @@ -0,0 +1,6 @@
> +Developer Guidelines
> +====================
> +
> +include::adding-packages.txt[]
> +
> +include::board-support.txt[]
> diff --git a/docs/manual/download-location.txt b/docs/manual/download-location.txt
> index cb6147f..7ac98c0 100644
> --- a/docs/manual/download-location.txt
> +++ b/docs/manual/download-location.txt
> @@ -1,5 +1,5 @@
> ?Location of downloaded packages
> -===============================
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> ?It might be useful to know that the various tarballs that are
> ?downloaded by the Makefiles are all stored in the +DL_DIR+ which by
> diff --git a/docs/manual/external-toolchain.txt b/docs/manual/external-toolchain.txt
> index 62eb0a3..30efe42 100644
> --- a/docs/manual/external-toolchain.txt
> +++ b/docs/manual/external-toolchain.txt
> @@ -1,6 +1,6 @@
> -Using an external toolchain
> -===========================
> ?[[external-toolchain]]
> +Using an external toolchain
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> ?Using an already existing toolchain is useful for different
> ?reasons:
> diff --git a/docs/manual/getting.txt b/docs/manual/getting.txt
> index 42ca009..6cfdefb 100644
> --- a/docs/manual/getting.txt
> +++ b/docs/manual/getting.txt
> @@ -1,5 +1,6 @@
> +[[getting-buildroot]]
> ?Getting Buildroot
> -=================
> +-----------------
>
> ?Buildroot releases are made approximately every 3 months. Direct Git
> ?access and daily snapshots are also available, if you want more
> diff --git a/docs/manual/going-further.txt b/docs/manual/going-further.txt
> new file mode 100644
> index 0000000..6f3cd6e
> --- /dev/null
> +++ b/docs/manual/going-further.txt
> @@ -0,0 +1,6 @@
> +Going further in Buildroot's innards
> +====================================
> +
> +include::how-buildroot-works.txt[]
> +
> +include::advanced.txt[]
> diff --git a/docs/manual/how-buildroot-works.txt b/docs/manual/how-buildroot-works.txt
> index 481e5a4..1e86ca3 100644
> --- a/docs/manual/how-buildroot-works.txt
> +++ b/docs/manual/how-buildroot-works.txt
> @@ -1,5 +1,5 @@
> ?How Buildroot works
> -===================
> +-------------------
>
> ?As mentioned above, Buildroot is basically a set of Makefiles that
> ?download, configure, and compile software with the correct options. It
> diff --git a/docs/manual/legal-notice.txt b/docs/manual/legal-notice.txt
> new file mode 100644
> index 0000000..3d741a9
> --- /dev/null
> +++ b/docs/manual/legal-notice.txt
> @@ -0,0 +1,4 @@
> +Legal notice
> +============
> +
> +TODO
> diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
> index 732b50c..b35b5f6 100644
> --- a/docs/manual/manual.txt
> +++ b/docs/manual/manual.txt
> @@ -11,24 +11,20 @@ image::logo.png[]
>
> ?include::introduction.txt[]
>
> -include::getting.txt[]
> +include::starting-up.txt[]
>
> -include::using.txt[]
>
> -include::customize.txt[]
>
> -include::rebuilding-packages.txt[]
> +include::working-with.txt[]
>
> -include::how-buildroot-works.txt[]
>
> -include::using-buildroot-toolchain.txt[]
>
> -include::external-toolchain.txt[]
>
> -include::ccache-support.txt[]
> +include::going-further.txt[]
>
> -include::download-location.txt[]
> +include::developer-guide.txt[]
> +
> +include::legal-notice.txt[]
>
> -include::adding-packages.txt[]
>
> ?include::appendix.txt[]
> diff --git a/docs/manual/rebuilding-packages.txt b/docs/manual/rebuilding-packages.txt
> index f247dd0..717121a 100644
> --- a/docs/manual/rebuilding-packages.txt
> +++ b/docs/manual/rebuilding-packages.txt
> @@ -1,5 +1,5 @@
> ?Understanding how to rebuild packages
> -=====================================
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> ?One of the most common questions asked by Buildroot users is how to
> ?rebuild a given package or how to remove a package without rebuilding
> diff --git a/docs/manual/starting-up.txt b/docs/manual/starting-up.txt
> new file mode 100644
> index 0000000..4f567f0
> --- /dev/null
> +++ b/docs/manual/starting-up.txt
> @@ -0,0 +1,7 @@
> +Starting up
> +===========
> +
> +include::getting.txt[]
> +
> +include::using.txt[]
> +
> diff --git a/docs/manual/using-buildroot-toolchain.txt b/docs/manual/using-buildroot-toolchain.txt
> index 712e9a8..24e797f 100644
> --- a/docs/manual/using-buildroot-toolchain.txt
> +++ b/docs/manual/using-buildroot-toolchain.txt
> @@ -1,5 +1,5 @@
> ?Using the generated toolchain outside Buildroot
> -===============================================
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> ?You may want to compile, for your target, your own programs or other
> ?software that are not packaged in Buildroot. In order to do this you
> diff --git a/docs/manual/using.txt b/docs/manual/using.txt
> index a5dc9e1..88dc58c 100644
> --- a/docs/manual/using.txt
> +++ b/docs/manual/using.txt
> @@ -1,8 +1,5 @@
> ?Using Buildroot
> -===============
> -
> -Configuration and general usage
> --------------------------------
> +---------------
>
> ?Buildroot has a nice configuration tool similar to the one you can
> ?find in the http://www.kernel.org/[Linux kernel] or in
> diff --git a/docs/manual/working-with.txt b/docs/manual/working-with.txt
> new file mode 100644
> index 0000000..e444204
> --- /dev/null
> +++ b/docs/manual/working-with.txt
> @@ -0,0 +1,10 @@
> +Working with Buildroot
> +======================
> +[[working-with-br]]
> +
> +include::customize.txt[]
> +
> +include::common-usage.txt[]
> +
> +Tweaking Buildroot
> +------------------
> --
> 1.7.10.2
>
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH v2 02/11] manual: rework introduction.txt and add embedded-basics.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 " Samuel Martin
2012-05-13 10:38 ` [Buildroot] [PATCH v2 01/11] manual: rework the whole documentation stub Samuel Martin
@ 2012-05-13 10:38 ` Samuel Martin
2012-05-16 11:50 ` Thomas De Schampheleire
2012-05-13 10:38 ` [Buildroot] [PATCH v2 03/11] manual: add prerequisite.txt Samuel Martin
` (8 subsequent siblings)
10 siblings, 1 reply; 53+ messages in thread
From: Samuel Martin @ 2012-05-13 10:38 UTC (permalink / raw)
To: buildroot
From: Samuel MARTIN <s.martin49@gmail.com>
Split and rephrasing of introduction.txt.
Cross-toolchain and pro-Buildroot explainations moved from introduction.txt
into embedded-basics.txt.
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
create mode 100644 docs/manual/embedded-basics.txt
diff --git a/docs/manual/embedded-basics.txt b/docs/manual/embedded-basics.txt
new file mode 100644
index 0000000..bf14d7c
--- /dev/null
+++ b/docs/manual/embedded-basics.txt
@@ -0,0 +1,67 @@
+Embedded system basics & Reasons to use Buildroot
+-------------------------------------------------
+
+Cross-compilation & cross-toolchain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A compilation toolchain is the set of tools that allows you to compile
+code for your system. It consists of a compiler (in our case, +gcc+),
+binary utils like assembler and linker (in our case, +binutils+) and a
+C standard library (for example
+http://www.gnu.org/software/libc/libc.html[GNU Libc],
+http://www.uclibc.org/[uClibc] or
+http://www.fefe.de/dietlibc/[dietlibc]). The system installed on your
+development station certainly already has a compilation toolchain that
+you can use to compile an application that runs on your system. If
+you're using a PC, your compilation toolchain runs on an x86 processor
+and generates code for an x86 processor. Under most Linux systems, the
+compilation toolchain uses the GNU libc (glibc) as the C standard
+library. This compilation toolchain is called the "host compilation
+toolchain". The machine on which it is running, and on which you're
+working, is called the "host system". The compilation toolchain is
+provided by your distribution, and Buildroot has nothing to do with it
+(other than using it to build a cross-compilation toolchain and other
+tools that are run on the development host).
+
+As said above, the compilation toolchain that comes with your system
+runs on and generates code for the processor in your host system. As
+your embedded system has a different processor, you need a
+cross-compilation toolchain - a compilation toolchain that runs on
+your host system but generates code for your target system (and target
+processor). For example, if your host system uses x86 and your target
+system uses ARM, the regular compilation toolchain on your host runs on
+x86 and generates code for x86, while the cross-compilation toolchain
+runs on x86 and generates code for ARM.
+
+[[pros-buildroot]]
+
+Why choose Buildroot
+~~~~~~~~~~~~~~~~~~~~
+
+Even if your embedded system uses an x86 processor, you might be
+interested in Buildroot for two reasons:
+
+* The compilation toolchain on your host certainly uses the GNU Libc
+ which is a complete but huge C standard library. Instead of using
+ GNU Libc on your target system, you can use uClibc which is a tiny C
+ standard library. If you want to use this C library, then you need a
+ compilation toolchain to generate binaries linked with it. Buildroot
+ can do that for you.
+
+* Buildroot automates the building of a root filesystem with all
+ needed tools like busybox. That makes it much easier than doing it
+ by hand.
+
+You might wonder why such a tool is needed when you can compile +gcc+,
++binutils+, +uClibc+ and all the other tools by hand. Of course doing
+so is possible but, dealing with all of the configure options and
+problems of every +gcc+ or +binutils+ version is very time-consuming
+and uninteresting. Buildroot automates this process through the use
+of Makefiles and has a collection of patches for each +gcc+ and
++binutils+ version to make them work on most architectures.
+
+Moreover, Buildroot provides an infrastructure for reproducing the
+build process of your kernel, cross-toolchain, and embedded root
+filesystem. Being able to reproduce the build process will be useful
+when a component needs to be patched or updated or when another person
+is supposed to take over the project.
diff --git a/docs/manual/going-further.txt b/docs/manual/going-further.txt
index 6f3cd6e..67162a6 100644
--- a/docs/manual/going-further.txt
+++ b/docs/manual/going-further.txt
@@ -1,6 +1,8 @@
Going further in Buildroot's innards
====================================
+include::embedded-basics.txt[]
+
include::how-buildroot-works.txt[]
include::advanced.txt[]
diff --git a/docs/manual/introduction.txt b/docs/manual/introduction.txt
index 476ce25..e330674 100644
--- a/docs/manual/introduction.txt
+++ b/docs/manual/introduction.txt
@@ -1,69 +1,21 @@
About Buildroot
===============
-Buildroot is a set of Makefiles and patches that allows you to easily
-generate a cross-compilation toolchain, a root filesystem and a Linux
-kernel image for your target. Buildroot can be used for one, two or
-all of these options, independently.
-
-Buildroot is useful mainly for people working with embedded systems.
+Buildroot provides a full featured environment for cross-development.
+Buildroot is able to generate a cross-compilation toolchain, a root
+filesystem, a Linux kernel image and a bootloader for your target.
+Buildroot can be used for any combinaison of these options,
+independently.
+
+Buildroot is useful mainly for people working with embedded systems
+for a number of good reasons (see xref:pros-buildroot[]).
Embedded systems often use processors that are not the regular x86
processors everyone is used to having in his PC. They can be PowerPC
processors, MIPS processors, ARM processors, etc.
-A compilation toolchain is the set of tools that allows you to compile
-code for your system. It consists of a compiler (in our case, +gcc+),
-binary utils like assembler and linker (in our case, +binutils+) and a
-C standard library (for example
-http://www.gnu.org/software/libc/libc.html[GNU Libc],
-http://www.uclibc.org/[uClibc] or
-http://www.fefe.de/dietlibc/[dietlibc]). The system installed on your
-development station certainly already has a compilation toolchain that
-you can use to compile an application that runs on your system. If
-you're using a PC, your compilation toolchain runs on an x86 processor
-and generates code for an x86 processor. Under most Linux systems, the
-compilation toolchain uses the GNU libc (glibc) as the C standard
-library. This compilation toolchain is called the "host compilation
-toolchain". The machine on which it is running, and on which you're
-working, is called the "host system". The compilation toolchain is
-provided by your distribution, and Buildroot has nothing to do with it
-(other than using it to build a cross-compilation toolchain and other
-tools that are run on the development host).
-
-As said above, the compilation toolchain that comes with your system
-runs on and generates code for the processor in your host system. As
-your embedded system has a different processor, you need a
-cross-compilation toolchain - a compilation toolchain that runs on
-your host system but generates code for your target system (and target
-processor). For example, if your host system uses x86 and your target
-system uses ARM, the regular compilation toolchain on your host runs on
-x86 and generates code for x86, while the cross-compilation toolchain
-runs on x86 and generates code for ARM.
-
-Even if your embedded system uses an x86 processor, you might be
-interested in Buildroot for two reasons:
-
-* The compilation toolchain on your host certainly uses the GNU Libc
- which is a complete but huge C standard library. Instead of using
- GNU Libc on your target system, you can use uClibc which is a tiny C
- standard library. If you want to use this C library, then you need a
- compilation toolchain to generate binaries linked with it. Buildroot
- can do that for you.
-
-* Buildroot automates the building of a root filesystem with all
- needed tools like busybox. That makes it much easier than doing it
- by hand.
-
-You might wonder why such a tool is needed when you can compile +gcc+,
-+binutils+, +uClibc+ and all the other tools by hand. Of course doing
-so is possible but, dealing with all of the configure options and
-problems of every +gcc+ or +binutils+ version is very time-consuming
-and uninteresting. Buildroot automates this process through the use
-of Makefiles and has a collection of patches for each +gcc+ and
-+binutils+ version to make them work on most architectures.
+Buildroot supports numerous processors and their variants; it also
+comes with default configuration for several boards available
+off-the-shelf. Besides, a number of third-party projects are based on
+or develop their BSP footnote:[BSP: Board Software Package] or
+SDK footnote:[SDK: Standard Development Kit] on top of Buildroot.
-Moreover, Buildroot provides an infrastructure for reproducing the
-build process of your kernel, cross-toolchain, and embedded root
-filesystem. Being able to reproduce the build process will be useful
-when a component needs to be patched or updated or when another person
-is supposed to take over the project.
--
1.7.10.2
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH v2 02/11] manual: rework introduction.txt and add embedded-basics.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 02/11] manual: rework introduction.txt and add embedded-basics.txt Samuel Martin
@ 2012-05-16 11:50 ` Thomas De Schampheleire
0 siblings, 0 replies; 53+ messages in thread
From: Thomas De Schampheleire @ 2012-05-16 11:50 UTC (permalink / raw)
To: buildroot
On Sun, May 13, 2012 at 12:38 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> From: Samuel MARTIN <s.martin49@gmail.com>
>
> Split and rephrasing of introduction.txt.
>
> Cross-toolchain and pro-Buildroot explainations moved from introduction.txt
> into embedded-basics.txt.
>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
>
> ?create mode 100644 docs/manual/embedded-basics.txt
>
> diff --git a/docs/manual/embedded-basics.txt b/docs/manual/embedded-basics.txt
> new file mode 100644
> index 0000000..bf14d7c
> --- /dev/null
> +++ b/docs/manual/embedded-basics.txt
> @@ -0,0 +1,67 @@
> +Embedded system basics & Reasons to use Buildroot
> +-------------------------------------------------
> +
> +Cross-compilation & cross-toolchain
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +A compilation toolchain is the set of tools that allows you to compile
> +code for your system. It consists of a compiler (in our case, +gcc+),
> +binary utils like assembler and linker (in our case, +binutils+) and a
> +C standard library (for example
> +http://www.gnu.org/software/libc/libc.html[GNU Libc],
> +http://www.uclibc.org/[uClibc] or
> +http://www.fefe.de/dietlibc/[dietlibc]). The system installed on your
> +development station certainly already has a compilation toolchain that
> +you can use to compile an application that runs on your system. If
> +you're using a PC, your compilation toolchain runs on an x86 processor
> +and generates code for an x86 processor. Under most Linux systems, the
> +compilation toolchain uses the GNU libc (glibc) as the C standard
> +library. ?This compilation toolchain is called the "host compilation
> +toolchain". The machine on which it is running, and on which you're
> +working, is called the "host system". The compilation toolchain is
> +provided by your distribution, and Buildroot has nothing to do with it
> +(other than using it to build a cross-compilation toolchain and other
> +tools that are run on the development host).
> +
> +As said above, the compilation toolchain that comes with your system
> +runs on and generates code for the processor in your host system. As
> +your embedded system has a different processor, you need a
> +cross-compilation toolchain - a compilation toolchain that runs on
> +your host system but generates code for your target system (and target
> +processor). For example, if your host system uses x86 and your target
> +system uses ARM, the regular compilation toolchain on your host runs on
> +x86 and generates code for x86, while the cross-compilation toolchain
> +runs on x86 and generates code for ARM.
> +
> +[[pros-buildroot]]
> +
> +Why choose Buildroot
> +~~~~~~~~~~~~~~~~~~~~
> +
> +Even if your embedded system uses an x86 processor, you might be
> +interested in Buildroot for two reasons:
> +
> +* The compilation toolchain on your host certainly uses the GNU Libc
> + ?which is a complete but huge C standard library. Instead of using
> + ?GNU Libc on your target system, you can use uClibc which is a tiny C
> + ?standard library. If you want to use this C library, then you need a
> + ?compilation toolchain to generate binaries linked with it. Buildroot
> + ?can do that for you.
> +
> +* Buildroot automates the building of a root filesystem with all
> + ?needed tools like busybox. That makes it much easier than doing it
> + ?by hand.
> +
> +You might wonder why such a tool is needed when you can compile +gcc+,
> ++binutils+, +uClibc+ and all the other tools by hand. Of course doing
> +so is possible but, dealing with all of the configure options and
> +problems of every +gcc+ or +binutils+ version is very time-consuming
> +and uninteresting. ?Buildroot automates this process through the use
> +of Makefiles and has a collection of patches for each +gcc+ and
> ++binutils+ version to make them work on most architectures.
> +
> +Moreover, Buildroot provides an infrastructure for reproducing the
> +build process of your kernel, cross-toolchain, and embedded root
> +filesystem. Being able to reproduce the build process will be useful
> +when a component needs to be patched or updated or when another person
> +is supposed to take over the project.
> diff --git a/docs/manual/going-further.txt b/docs/manual/going-further.txt
> index 6f3cd6e..67162a6 100644
> --- a/docs/manual/going-further.txt
> +++ b/docs/manual/going-further.txt
> @@ -1,6 +1,8 @@
> ?Going further in Buildroot's innards
> ?====================================
>
> +include::embedded-basics.txt[]
> +
> ?include::how-buildroot-works.txt[]
>
> ?include::advanced.txt[]
> diff --git a/docs/manual/introduction.txt b/docs/manual/introduction.txt
> index 476ce25..e330674 100644
> --- a/docs/manual/introduction.txt
> +++ b/docs/manual/introduction.txt
> @@ -1,69 +1,21 @@
> ?About Buildroot
> ?===============
>
> -Buildroot is a set of Makefiles and patches that allows you to easily
> -generate a cross-compilation toolchain, a root filesystem and a Linux
> -kernel image for your target. Buildroot can be used for one, two or
> -all of these options, independently.
> -
> -Buildroot is useful mainly for people working with embedded systems.
> +Buildroot provides a full featured environment for cross-development.
> +Buildroot is able to generate a cross-compilation toolchain, a root
> +filesystem, a Linux kernel image and a bootloader for your target.
> +Buildroot can be used for any combinaison of these options,
s/combinaison/combination/
> +independently.
> +
> +Buildroot is useful mainly for people working with embedded systems
> +for a number of good reasons (see xref:pros-buildroot[]).
> ?Embedded systems often use processors that are not the regular x86
> ?processors everyone is used to having in his PC. They can be PowerPC
> ?processors, MIPS processors, ARM processors, etc.
>
> -A compilation toolchain is the set of tools that allows you to compile
> -code for your system. It consists of a compiler (in our case, +gcc+),
> -binary utils like assembler and linker (in our case, +binutils+) and a
> -C standard library (for example
> -http://www.gnu.org/software/libc/libc.html[GNU Libc],
> -http://www.uclibc.org/[uClibc] or
> -http://www.fefe.de/dietlibc/[dietlibc]). The system installed on your
> -development station certainly already has a compilation toolchain that
> -you can use to compile an application that runs on your system. If
> -you're using a PC, your compilation toolchain runs on an x86 processor
> -and generates code for an x86 processor. Under most Linux systems, the
> -compilation toolchain uses the GNU libc (glibc) as the C standard
> -library. ?This compilation toolchain is called the "host compilation
> -toolchain". The machine on which it is running, and on which you're
> -working, is called the "host system". The compilation toolchain is
> -provided by your distribution, and Buildroot has nothing to do with it
> -(other than using it to build a cross-compilation toolchain and other
> -tools that are run on the development host).
> -
> -As said above, the compilation toolchain that comes with your system
> -runs on and generates code for the processor in your host system. As
> -your embedded system has a different processor, you need a
> -cross-compilation toolchain - a compilation toolchain that runs on
> -your host system but generates code for your target system (and target
> -processor). For example, if your host system uses x86 and your target
> -system uses ARM, the regular compilation toolchain on your host runs on
> -x86 and generates code for x86, while the cross-compilation toolchain
> -runs on x86 and generates code for ARM.
> -
> -Even if your embedded system uses an x86 processor, you might be
> -interested in Buildroot for two reasons:
> -
> -* The compilation toolchain on your host certainly uses the GNU Libc
> - ?which is a complete but huge C standard library. Instead of using
> - ?GNU Libc on your target system, you can use uClibc which is a tiny C
> - ?standard library. If you want to use this C library, then you need a
> - ?compilation toolchain to generate binaries linked with it. Buildroot
> - ?can do that for you.
> -
> -* Buildroot automates the building of a root filesystem with all
> - ?needed tools like busybox. That makes it much easier than doing it
> - ?by hand.
> -
> -You might wonder why such a tool is needed when you can compile +gcc+,
> -+binutils+, +uClibc+ and all the other tools by hand. Of course doing
> -so is possible but, dealing with all of the configure options and
> -problems of every +gcc+ or +binutils+ version is very time-consuming
> -and uninteresting. ?Buildroot automates this process through the use
> -of Makefiles and has a collection of patches for each +gcc+ and
> -+binutils+ version to make them work on most architectures.
> +Buildroot supports numerous processors and their variants; it also
> +comes with default configuration for several boards available
> +off-the-shelf. Besides, a number of third-party projects are based on
> +or develop their BSP footnote:[BSP: Board Software Package] or
> +SDK footnote:[SDK: Standard Development Kit] on top of Buildroot.
>
> -Moreover, Buildroot provides an infrastructure for reproducing the
> -build process of your kernel, cross-toolchain, and embedded root
> -filesystem. Being able to reproduce the build process will be useful
> -when a component needs to be patched or updated or when another person
> -is supposed to take over the project.
> --
> 1.7.10.2
>
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH v2 03/11] manual: add prerequisite.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 " Samuel Martin
2012-05-13 10:38 ` [Buildroot] [PATCH v2 01/11] manual: rework the whole documentation stub Samuel Martin
2012-05-13 10:38 ` [Buildroot] [PATCH v2 02/11] manual: rework introduction.txt and add embedded-basics.txt Samuel Martin
@ 2012-05-13 10:38 ` Samuel Martin
2012-05-16 16:32 ` Thomas De Schampheleire
2012-05-13 10:38 ` [Buildroot] [PATCH v2 04/11] manual: rework using.txt and update common-usage.txt Samuel Martin
` (7 subsequent siblings)
10 siblings, 1 reply; 53+ messages in thread
From: Samuel Martin @ 2012-05-13 10:38 UTC (permalink / raw)
To: buildroot
From: Samuel MARTIN <s.martin49@gmail.com>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
create mode 100644 docs/manual/prerequisite.txt
diff --git a/docs/manual/prerequisite.txt b/docs/manual/prerequisite.txt
new file mode 100644
index 0000000..6ed3072
--- /dev/null
+++ b/docs/manual/prerequisite.txt
@@ -0,0 +1,62 @@
+[[requirement]]
+System requirements
+-------------------
+
+Buildroot is design to run on Linux system.
+
+Buildroot needs some software to be already installed on the host
+system; hereafter the lists of the mandatory and optional packages
+(packages' name may vary between distribution).
+
+Take care of _installing both runtime and development data_, especially
+for the libraries that may be packaged in 2 distinct packages.
+
+
+[[requirement-mandatory]]
+
+Mandatory packages
+~~~~~~~~~~~~~~~~~~
+
+* Build tools:
+** +build-essential+ (only for Debian based system)
+** +gcc+
+** +g+++
+** +bison+
+** +flex+
+** +gettext+
+** +patch+
+
+* Source fetching tools:
+** +wget+
+
+* Development libraries:
+** +ncurses5+
+
+[[requirement-optional]]
+
+Optional packages
+~~~~~~~~~~~~~~~~~
+
+* Build tools:
+** +gawk+
+
+* Source fetching tools:
+** +cvs+
+** +git+
+** +mercurial+
+** +subversion+
+
+* Configuration interface dependencies (requires development libraries):
+** +qt4+ to use the 'xconfig' interface
+** +glib2+, +gtk2+ and +glade2+ to use the 'gconfig' interface
+
+* Development libraries:
+** +zlib1+
+** +netpbm10+ (for +fbtest+)
+** +python-xcbgen+ (for +Matchbox+ on Debian based system)
+// ** +jdk+ and and depending on the host system +gcj-compat+ for Java
+// development (for +java+, +jamvm+ and +gnu-classpath+)
+
+* Documentation generation tools:
+** +asciidoc+
+** +texinfo+
diff --git a/docs/manual/starting-up.txt b/docs/manual/starting-up.txt
index 4f567f0..3a74ea6 100644
--- a/docs/manual/starting-up.txt
+++ b/docs/manual/starting-up.txt
@@ -1,6 +1,8 @@
Starting up
===========
+include::prerequisite.txt[]
+
include::getting.txt[]
include::using.txt[]
--
1.7.10.2
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH v2 03/11] manual: add prerequisite.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 03/11] manual: add prerequisite.txt Samuel Martin
@ 2012-05-16 16:32 ` Thomas De Schampheleire
2012-05-16 21:45 ` Samuel Martin
0 siblings, 1 reply; 53+ messages in thread
From: Thomas De Schampheleire @ 2012-05-16 16:32 UTC (permalink / raw)
To: buildroot
On Sun, May 13, 2012 at 12:38 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> From: Samuel MARTIN <s.martin49@gmail.com>
>
>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
>
> ?create mode 100644 docs/manual/prerequisite.txt
>
> diff --git a/docs/manual/prerequisite.txt b/docs/manual/prerequisite.txt
> new file mode 100644
> index 0000000..6ed3072
> --- /dev/null
> +++ b/docs/manual/prerequisite.txt
> @@ -0,0 +1,62 @@
> +[[requirement]]
> +System requirements
> +-------------------
> +
> +Buildroot is design to run on Linux system.
> +
> +Buildroot needs some software to be already installed on the host
> +system; hereafter the lists of the mandatory and optional packages
> +(packages' name may vary between distribution).
I'm not a native English speaker, but I think "packages' name" is not correct.
I'd say "packages' names" or simply "package names".
s/distribution/distributions/
> +
> +Take care of _installing both runtime and development data_, especially
> +for the libraries that may be packaged in 2 distinct packages.
> +
> +
> +[[requirement-mandatory]]
> +
> +Mandatory packages
> +~~~~~~~~~~~~~~~~~~
> +
> +* Build tools:
> +** +build-essential+ (only for Debian based system)
s/system/systems/
> +** +gcc+
> +** +g+++
> +** +bison+
> +** +flex+
> +** +gettext+
> +** +patch+
> +
> +* Source fetching tools:
> +** +wget+
> +
> +* Development libraries:
> +** +ncurses5+
Isn't ncurses only needed for menuconfig, and so belongs in the list
'Configuration interface dependencies' ?
> +
> +[[requirement-optional]]
> +
> +Optional packages
> +~~~~~~~~~~~~~~~~~
> +
> +* Build tools:
> +** +gawk+
> +
> +* Source fetching tools:
> +** +cvs+
> +** +git+
> +** +mercurial+
> +** +subversion+
What's the reasoning behind these 'optional requirements' ?
People that are new to buildroot may simply install all 'requirements'
and hence install tools like cvs or one of the other version control
systems, while it won't actually be used, unless they select a package
that downloads using that method.
Moreover, some tools that could fit in this category are missing, like
bazaar or scp.
> +
> +* Configuration interface dependencies (requires development libraries):
> +** +qt4+ to use the 'xconfig' interface
> +** +glib2+, +gtk2+ and +glade2+ to use the 'gconfig' interface
> +
> +* Development libraries:
> +** +zlib1+
> +** +netpbm10+ (for +fbtest+)
> +** +python-xcbgen+ (for +Matchbox+ on Debian based system)
> +// ** +jdk+ and and depending on the host system +gcj-compat+ for Java
> +// development (for +java+, +jamvm+ and +gnu-classpath+)
> +
I would think that the intention of buildroot is that most
non-standard dependencies are handled within buildroot.
One can safely expect make and gcc to be present, but is it currently
so that such things like netpbm10 are needed? If so, shouldn't they be
built as host-netpbm10 etc ?
If we can do that, the above section can be removed.
Otherwise:
s/and and/and/
> +* Documentation generation tools:
> +** +asciidoc+
> +** +texinfo+
> diff --git a/docs/manual/starting-up.txt b/docs/manual/starting-up.txt
> index 4f567f0..3a74ea6 100644
> --- a/docs/manual/starting-up.txt
> +++ b/docs/manual/starting-up.txt
> @@ -1,6 +1,8 @@
> ?Starting up
> ?===========
>
> +include::prerequisite.txt[]
> +
> ?include::getting.txt[]
>
> ?include::using.txt[]
> --
> 1.7.10.2
>
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH v2 03/11] manual: add prerequisite.txt
2012-05-16 16:32 ` Thomas De Schampheleire
@ 2012-05-16 21:45 ` Samuel Martin
2012-05-17 6:53 ` Thomas De Schampheleire
0 siblings, 1 reply; 53+ messages in thread
From: Samuel Martin @ 2012-05-16 21:45 UTC (permalink / raw)
To: buildroot
Hi Thomas,
Thx for the review.
2012/5/16 Thomas De Schampheleire <patrickdepinguin+buildroot@gmail.com>:
>> +
>> +[[requirement-optional]]
>> +
>> +Optional packages
>> +~~~~~~~~~~~~~~~~~
>> +
>> +* Build tools:
>> +** +gawk+
>> +
>> +* Source fetching tools:
>> +** +cvs+
>> +** +git+
>> +** +mercurial+
>> +** +subversion+
>
> What's the reasoning behind these 'optional requirements' ?
Actually, I followed the comments from Thomas P. on the first post, see:
http://lists.busybox.net/pipermail/buildroot/2012-March/051972.html
> People that are new to buildroot may simply install all 'requirements'
> and hence install tools like cvs or one of the other version control
> systems, while it won't actually be used, unless they select a package
> that downloads using that method.
> Moreover, some tools that could fit in this category are missing, like
> bazaar or scp.
You're right, I've omitted them and others...
>
>> +
>> +* Configuration interface dependencies (requires development libraries):
>> +** +qt4+ to use the 'xconfig' interface
>> +** +glib2+, +gtk2+ and +glade2+ to use the 'gconfig' interface
>> +
>> +* Development libraries:
>> +** +zlib1+
>> +** +netpbm10+ (for +fbtest+)
>> +** +python-xcbgen+ (for +Matchbox+ on Debian based system)
>> +// ** +jdk+ and and depending on the host system +gcj-compat+ for Java
>> +// development (for +java+, +jamvm+ and +gnu-classpath+)
>> +
>
> I would think that the intention of buildroot is that most
> non-standard dependencies are handled within buildroot.
So am I.
> One can safely expect make and gcc to be present, but is it currently
> so that such things like netpbm10 are needed? If so, shouldn't they be
> built as host-netpbm10 etc ?
Sure. A new item on the todo list ;-)
To write this page, I got inspired from:
http://www.armadeus.com/wiki/index.php?title=Ubuntu/Debian_installation_prerequisites
BR moves fast and the Armadeus Project is not based on the latest release, so...
> If we can do that, the above section can be removed.
I agree.
> Otherwise:
> s/and and/and/
>
Cheers,
Sam
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH v2 03/11] manual: add prerequisite.txt
2012-05-16 21:45 ` Samuel Martin
@ 2012-05-17 6:53 ` Thomas De Schampheleire
0 siblings, 0 replies; 53+ messages in thread
From: Thomas De Schampheleire @ 2012-05-17 6:53 UTC (permalink / raw)
To: buildroot
Op 16 mei 2012 23:46 schreef "Samuel Martin" <s.martin49@gmail.com> het
volgende:
>
> Hi Thomas,
>
> Thx for the review.
>
> 2012/5/16 Thomas De Schampheleire <patrickdepinguin+buildroot@gmail.com>:
> >> +
> >> +[[requirement-optional]]
> >> +
> >> +Optional packages
> >> +~~~~~~~~~~~~~~~~~
> >> +
> >> +* Build tools:
> >> +** +gawk+
Based on Thomas' post, is gawk really needed? As he says, host-gawk will be
built when required by a package.
> >> +
> >> +* Source fetching tools:
> >> +** +cvs+
> >> +** +git+
> >> +** +mercurial+
> >> +** +subversion+
> >
> > What's the reasoning behind these 'optional requirements' ?
> Actually, I followed the comments from Thomas P. on the first post, see:
> http://lists.busybox.net/pipermail/buildroot/2012-March/051972.html
>
> > People that are new to buildroot may simply install all 'requirements'
> > and hence install tools like cvs or one of the other version control
> > systems, while it won't actually be used, unless they select a package
> > that downloads using that method.
> > Moreover, some tools that could fit in this category are missing, like
> > bazaar or scp.
> You're right, I've omitted them and others...
>
> >
> >> +
> >> +* Configuration interface dependencies (requires development
libraries):
> >> +** +qt4+ to use the 'xconfig' interface
> >> +** +glib2+, +gtk2+ and +glade2+ to use the 'gconfig' interface
> >> +
> >> +* Development libraries:
> >> +** +zlib1+
> >> +** +netpbm10+ (for +fbtest+)
> >> +** +python-xcbgen+ (for +Matchbox+ on Debian based system)
> >> +// ** +jdk+ and and depending on the host system +gcj-compat+ for Java
> >> +// development (for +java+, +jamvm+ and +gnu-classpath+)
> >> +
> >
> > I would think that the intention of buildroot is that most
> > non-standard dependencies are handled within buildroot.
> So am I.
>
> > One can safely expect make and gcc to be present, but is it currently
> > so that such things like netpbm10 are needed? If so, shouldn't they be
> > built as host-netpbm10 etc ?
> Sure. A new item on the todo list ;-)
>
> To write this page, I got inspired from:
>
http://www.armadeus.com/wiki/index.php?title=Ubuntu/Debian_installation_prerequisites
> BR moves fast and the Armadeus Project is not based on the latest
release, so...
>
> > If we can do that, the above section can be removed.
> I agree.
>
> > Otherwise:
> > s/and and/and/
> >
>
>
> Cheers,
>
> Sam
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.busybox.net/pipermail/buildroot/attachments/20120517/77a307ef/attachment.html>
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH v2 04/11] manual: rework using.txt and update common-usage.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 " Samuel Martin
` (2 preceding siblings ...)
2012-05-13 10:38 ` [Buildroot] [PATCH v2 03/11] manual: add prerequisite.txt Samuel Martin
@ 2012-05-13 10:38 ` Samuel Martin
2012-05-16 16:47 ` Thomas De Schampheleire
2012-05-13 10:38 ` [Buildroot] [PATCH v2 05/11] manual: add make-tips.txt Samuel Martin
` (6 subsequent siblings)
10 siblings, 1 reply; 53+ messages in thread
From: Samuel Martin @ 2012-05-13 10:38 UTC (permalink / raw)
To: buildroot
From: Samuel MARTIN <s.martin49@gmail.com>
Consider the second chapter: "starting-up", as a tutorial.
Assuming that, using.txt only contains the very first commands used to get
configure and build its very first target system.
So, the following subsection from using.txt have been to common-usage.txt:
- Offline builds
- Building out-of-tree
- Environment variables
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
diff --git a/docs/manual/common-usage.txt b/docs/manual/common-usage.txt
index ff8543f..dde1ab0 100644
--- a/docs/manual/common-usage.txt
+++ b/docs/manual/common-usage.txt
@@ -2,3 +2,80 @@ Daily use
---------
include::rebuilding-packages.txt[]
+
+Offline builds
+~~~~~~~~~~~~~~
+
+If you intend to do an offline build and just want to download
+all sources that you previously selected in the configurator
+('menuconfig', 'xconfig' or 'gconfig'), then issue:
+
+--------------------
+ $ make source
+--------------------
+
+You can now disconnect or copy the content of your +dl+
+directory to the build-host.
+
+Building out-of-tree
+~~~~~~~~~~~~~~~~~~~~
+
+Buildroot supports building out of tree with a syntax similar to the
+Linux kernel. To use it, add +O=<directory>+ to the make command line:
+
+--------------------
+ $ make O=/tmp/build
+--------------------
+
+Or:
+
+--------------------
+ $ cd /tmp/build; make O=$PWD -C path/to/buildroot
+--------------------
+
+All the output files will be located under +/tmp/build+.
+
+When using out-of-tree builds, the Buildroot +.config+ and temporary
+files are also stored in the output directory. This means that you can
+safely run multiple builds in parallel using the same source tree as
+long as they use unique output directories.
+
+For ease of use, Buildroot generates a Makefile wrapper in the output
+directory - So after the first run, you no longer need to pass +O=..+
+and +-C ..+, simply run (in the output directory):
+
+--------------------
+ $ make <target>
+--------------------
+
+[[env-vars]]
+
+Environment variables
+~~~~~~~~~~~~~~~~~~~~~
+
+Buildroot also honors some environment variables, when they are passed
+to +make+ or set in the environment:
+
+* +HOSTCXX+, the host C++ compiler to use
+* +HOSTCC+, the host C compiler to use
+* +UCLIBC_CONFIG_FILE=<path/to/.config>+, path to
+ the uClibc configuration file, used to compile uClibc, if an
+ internal toolchain is being built
+* +BUSYBOX_CONFIG_FILE=<path/to/.config>+, path to
+ the Busybox configuration file
+* +BUILDROOT_DL_DIR+ to override the directory in which
+ Buildroot stores/retrieves downloaded files
+
+An example that uses config files located in the toplevel directory and
+in your $HOME:
+
+--------------------
+ $ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config
+--------------------
+
+If you want to use a compiler other than the default +gcc+
+or +g+++ for building helper-binaries on your host, then do
+
+--------------------
+ $ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD
+--------------------
diff --git a/docs/manual/using.txt b/docs/manual/using.txt
index 88dc58c..2945098 100644
--- a/docs/manual/using.txt
+++ b/docs/manual/using.txt
@@ -3,8 +3,8 @@ Using Buildroot
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]. Note that you can (and should) build
-everything as a normal user. There is no need to be root to configure
+http://www.busybox.net/[Busybox]. Note that you can *and should build
+everything as a normal user*. There is no need to be root to configure
and use Buildroot. The first step is to run the configuration
assistant:
@@ -27,12 +27,11 @@ or
to run the Qt or GTK-based configurators.
All of these "make" commands will need to build a configuration
-utility, so you may need to install "development" packages for
-relevant libraries used by the configuration utilities. On Debian-like
-systems, the +libncurses5-dev+ package is required to use the
-'menuconfig' interface, +libqt4-dev+ is required to use the 'xconfig'
-interface, and +libglib2.0-dev, libgtk2.0-dev and libglade2-dev+ are
-needed to use the 'gconfig' interface.
+utility (including the interface), so you may need to install
+"development" packages for relevant libraries used by the
+configuration utilities. Check the xref:requirement[] to know what
+Buildroot needs, and specifically the xref:requirement-optional[system requirements]
+to get the dependencies of favourite interface.
For each menu entry in the configuration tool, you can find associated
help that describes the purpose of the entry.
@@ -54,9 +53,9 @@ tell Buildroot to run each package compilation with +make -jN+.
This command will generally perform the following steps:
* Download source files (as required)
-* Configure, build and install the cross-compiling toolchain if an
- internal toolchain is used, or import a toolchain if an external
- toolchain is used
+* Configure, build and install the cross-compiling toolchain using the
+ appropiate toolchain backend is used, or simply import a toolchain
+ if an external toolchain is used
* Build/install selected target packages
* Build a kernel image, if selected
* Build a bootloader image, if selected
@@ -103,78 +102,9 @@ This directory contains several subdirectories:
* +toolchain/+ contains the build directories for the various
components of the cross-compilation toolchain.
-Offline builds
---------------
+These commands, +make menuconfig|gconfig|xconfig+ and +make+, are the
+basic ones that allow to easily and quickly generate images fitting
+your needs, with all the supports and applications you enabled.
-If you intend to do an offline build and just want to download
-all sources that you previously selected in the configurator
-('menuconfig', 'xconfig' or 'gconfig'), then issue:
-
---------------------
- $ make source
---------------------
-
-You can now disconnect or copy the content of your +dl+
-directory to the build-host.
-
-Building out-of-tree
---------------------
-
-Buildroot supports building out of tree with a syntax similar to the
-Linux kernel. To use it, add +O=<directory>+ to the make command line:
-
---------------------
- $ make O=/tmp/build
---------------------
-
-Or:
-
---------------------
- $ cd /tmp/build; make O=$PWD -C path/to/buildroot
---------------------
-
-All the output files will be located under +/tmp/build+.
-
-When using out-of-tree builds, the Buildroot +.config+ and temporary
-files are also stored in the output directory. This means that you can
-safely run multiple builds in parallel using the same source tree as
-long as they use unique output directories.
-
-For ease of use, Buildroot generates a Makefile wrapper in the output
-directory - So after the first run, you no longer need to pass +O=..+
-and +-C ..+, simply run (in the output directory):
-
---------------------
- $ make <target>
---------------------
-
-Environment variables
----------------------
-[[env-vars]]
-
-Buildroot also honors some environment variables, when they are passed
-to +make+ or set in the environment:
-
-* +HOSTCXX+, the host C++ compiler to use
-* +HOSTCC+, the host C compiler to use
-* +UCLIBC_CONFIG_FILE=<path/to/.config>+, path to
- the uClibc configuration file, used to compile uClibc, if an
- internal toolchain is being built
-* +BUSYBOX_CONFIG_FILE=<path/to/.config>+, path to
- the Busybox configuration file
-* +BUILDROOT_DL_DIR+ to override the directory in which
- Buildroot stores/retrieves downloaded files
-
-An example that uses config files located in the toplevel directory and
-in your $HOME:
-
---------------------
- $ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config
---------------------
-
-If you want to use a compiler other than the default +gcc+
-or +g+++ for building helper-binaries on your host, then do
-
---------------------
- $ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD
---------------------
+More details about the "make" command usages are given in
+xref:make-tips[].
--
1.7.10.2
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH v2 04/11] manual: rework using.txt and update common-usage.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 04/11] manual: rework using.txt and update common-usage.txt Samuel Martin
@ 2012-05-16 16:47 ` Thomas De Schampheleire
0 siblings, 0 replies; 53+ messages in thread
From: Thomas De Schampheleire @ 2012-05-16 16:47 UTC (permalink / raw)
To: buildroot
On Sun, May 13, 2012 at 12:38 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> From: Samuel MARTIN <s.martin49@gmail.com>
>
> Consider the second chapter: "starting-up", as a tutorial.
> Assuming that, using.txt only contains the very first commands used to get
> configure and build its very first target system.
>
> So, the following subsection from using.txt have been to common-usage.txt:
> - Offline builds
> - Building out-of-tree
> - Environment variables
>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
>
> diff --git a/docs/manual/common-usage.txt b/docs/manual/common-usage.txt
> index ff8543f..dde1ab0 100644
> --- a/docs/manual/common-usage.txt
> +++ b/docs/manual/common-usage.txt
> @@ -2,3 +2,80 @@ Daily use
> ?---------
>
> ?include::rebuilding-packages.txt[]
> +
> +Offline builds
> +~~~~~~~~~~~~~~
> +
> +If you intend to do an offline build and just want to download
> +all sources that you previously selected in the configurator
> +('menuconfig', 'xconfig' or 'gconfig'), then issue:
> +
> +--------------------
> + $ make source
> +--------------------
> +
> +You can now disconnect or copy the content of your +dl+
> +directory to the build-host.
> +
> +Building out-of-tree
> +~~~~~~~~~~~~~~~~~~~~
> +
> +Buildroot supports building out of tree with a syntax similar to the
> +Linux kernel. To use it, add +O=<directory>+ to the make command line:
> +
> +--------------------
> + $ make O=/tmp/build
> +--------------------
> +
> +Or:
> +
> +--------------------
> + $ cd /tmp/build; make O=$PWD -C path/to/buildroot
> +--------------------
> +
> +All the output files will be located under +/tmp/build+.
I would mention in this section that the default output directory is
'output' in the buildroot tree.
> +
> +When using out-of-tree builds, the Buildroot +.config+ and temporary
> +files are also stored in the output directory. This means that you can
> +safely run multiple builds in parallel using the same source tree as
> +long as they use unique output directories.
> +
> +For ease of use, Buildroot generates a Makefile wrapper in the output
> +directory - So after the first run, you no longer need to pass +O=..+
> +and +-C ..+, simply run (in the output directory):
> +
> +--------------------
> + $ make <target>
> +--------------------
> +
> +[[env-vars]]
> +
> +Environment variables
> +~~~~~~~~~~~~~~~~~~~~~
> +
> +Buildroot also honors some environment variables, when they are passed
> +to +make+ or set in the environment:
> +
> +* +HOSTCXX+, the host C++ compiler to use
> +* +HOSTCC+, the host C compiler to use
> +* +UCLIBC_CONFIG_FILE=<path/to/.config>+, path to
> + ?the uClibc configuration file, used to compile uClibc, if an
> + ?internal toolchain is being built
> +* +BUSYBOX_CONFIG_FILE=<path/to/.config>+, path to
> + ?the Busybox configuration file
> +* +BUILDROOT_DL_DIR+ to override the directory in which
> + ?Buildroot stores/retrieves downloaded files
> +
> +An example that uses config files located in the toplevel directory and
> +in your $HOME:
> +
> +--------------------
> + $ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config
> +--------------------
I would mention here that the recommended usage is to specify these
config files in the buildroot .config file instead.
> +
> +If you want to use a compiler other than the default +gcc+
> +or +g+++ for building helper-binaries on your host, then do
> +
> +--------------------
> + $ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD
> +--------------------
> diff --git a/docs/manual/using.txt b/docs/manual/using.txt
> index 88dc58c..2945098 100644
> --- a/docs/manual/using.txt
> +++ b/docs/manual/using.txt
> @@ -3,8 +3,8 @@ Using Buildroot
>
> ?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]. Note that you can (and should) build
> -everything as a normal user. There is no need to be root to configure
> +http://www.busybox.net/[Busybox]. Note that you can *and should build
> +everything as a normal user*. There is no need to be root to configure
> ?and use Buildroot. The first step is to run the configuration
> ?assistant:
>
> @@ -27,12 +27,11 @@ or
> ?to run the Qt or GTK-based configurators.
>
> ?All of these "make" commands will need to build a configuration
> -utility, so you may need to install "development" packages for
> -relevant libraries used by the configuration utilities. On Debian-like
> -systems, the +libncurses5-dev+ package is required to use the
> -'menuconfig' interface, +libqt4-dev+ is required to use the 'xconfig'
> -interface, and +libglib2.0-dev, libgtk2.0-dev and libglade2-dev+ are
> -needed to use the 'gconfig' interface.
> +utility (including the interface), so you may need to install
> +"development" packages for relevant libraries used by the
> +configuration utilities. Check the xref:requirement[] to know what
> +Buildroot needs, and specifically the xref:requirement-optional[system requirements]
> +to get the dependencies of favourite interface.
s/favourite/favorite/
as we generally use American style words (as you did before with honor, ...)
>
> ?For each menu entry in the configuration tool, you can find associated
> ?help that describes the purpose of the entry.
> @@ -54,9 +53,9 @@ tell Buildroot to run each package compilation with +make -jN+.
> ?This command will generally perform the following steps:
>
> ?* Download source files (as required)
> -* Configure, build and install the cross-compiling toolchain if an
> - ?internal toolchain is used, or import a toolchain if an external
> - ?toolchain is used
> +* Configure, build and install the cross-compiling toolchain using the
> + ?appropiate toolchain backend is used, or simply import a toolchain
> + ?if an external toolchain is used
s/appropiate/appropriate/
s/is used//
> ?* Build/install selected target packages
> ?* Build a kernel image, if selected
> ?* Build a bootloader image, if selected
> @@ -103,78 +102,9 @@ This directory contains several subdirectories:
> ?* +toolchain/+ contains the build directories for the various
> ? components of the cross-compilation toolchain.
>
> -Offline builds
> ---------------
> +These commands, +make menuconfig|gconfig|xconfig+ and +make+, are the
> +basic ones that allow to easily and quickly generate images fitting
> +your needs, with all the supports and applications you enabled.
>
> -If you intend to do an offline build and just want to download
> -all sources that you previously selected in the configurator
> -('menuconfig', 'xconfig' or 'gconfig'), then issue:
> -
> ---------------------
> - $ make source
> ---------------------
> -
> -You can now disconnect or copy the content of your +dl+
> -directory to the build-host.
> -
> -Building out-of-tree
> ---------------------
> -
> -Buildroot supports building out of tree with a syntax similar to the
> -Linux kernel. To use it, add +O=<directory>+ to the make command line:
> -
> ---------------------
> - $ make O=/tmp/build
> ---------------------
> -
> -Or:
> -
> ---------------------
> - $ cd /tmp/build; make O=$PWD -C path/to/buildroot
> ---------------------
> -
> -All the output files will be located under +/tmp/build+.
> -
> -When using out-of-tree builds, the Buildroot +.config+ and temporary
> -files are also stored in the output directory. This means that you can
> -safely run multiple builds in parallel using the same source tree as
> -long as they use unique output directories.
> -
> -For ease of use, Buildroot generates a Makefile wrapper in the output
> -directory - So after the first run, you no longer need to pass +O=..+
> -and +-C ..+, simply run (in the output directory):
> -
> ---------------------
> - $ make <target>
> ---------------------
> -
> -Environment variables
> ----------------------
> -[[env-vars]]
> -
> -Buildroot also honors some environment variables, when they are passed
> -to +make+ or set in the environment:
> -
> -* +HOSTCXX+, the host C++ compiler to use
> -* +HOSTCC+, the host C compiler to use
> -* +UCLIBC_CONFIG_FILE=<path/to/.config>+, path to
> - ?the uClibc configuration file, used to compile uClibc, if an
> - ?internal toolchain is being built
> -* +BUSYBOX_CONFIG_FILE=<path/to/.config>+, path to
> - ?the Busybox configuration file
> -* +BUILDROOT_DL_DIR+ to override the directory in which
> - ?Buildroot stores/retrieves downloaded files
> -
> -An example that uses config files located in the toplevel directory and
> -in your $HOME:
> -
> ---------------------
> - $ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config
> ---------------------
> -
> -If you want to use a compiler other than the default +gcc+
> -or +g+++ for building helper-binaries on your host, then do
> -
> ---------------------
> - $ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD
> ---------------------
> +More details about the "make" command usages are given in
> +xref:make-tips[].
Is it common to talk about 'command usages' ? I would have put 'command usage'.
> --
> 1.7.10.2
>
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH v2 05/11] manual: add make-tips.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 " Samuel Martin
` (3 preceding siblings ...)
2012-05-13 10:38 ` [Buildroot] [PATCH v2 04/11] manual: rework using.txt and update common-usage.txt Samuel Martin
@ 2012-05-13 10:38 ` Samuel Martin
2012-05-16 16:55 ` Thomas De Schampheleire
2012-05-13 10:38 ` [Buildroot] [PATCH v2 06/11] manual: update working-with.txt Samuel Martin
` (5 subsequent siblings)
10 siblings, 1 reply; 53+ messages in thread
From: Samuel Martin @ 2012-05-13 10:38 UTC (permalink / raw)
To: buildroot
From: Samuel MARTIN <s.martin49@gmail.com>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
create mode 100644 docs/manual/make-tips.txt
diff --git a/docs/manual/make-tips.txt b/docs/manual/make-tips.txt
new file mode 100644
index 0000000..a512689
--- /dev/null
+++ b/docs/manual/make-tips.txt
@@ -0,0 +1,48 @@
+[[make-tips]]
+'make' tips
+-----------
+
+Because Buildroot is a set of Makefiles and patches, there are few
+things useful to know, such as:
+
+Display all command executed by make:
+
+--------------------
+ $ make V=0|1 <target>
+--------------------
+
+Display all available targets:
+
+--------------------
+ $ make help
+--------------------
+
+Note that, some settings in the +.config+ file may hide some targets
+like:
+
+* +busybox-menuconfig+ depends whether +busybox+ is enabled or not in
+ the +Package selection+ menu
+* +linux-menuconfig+ and +linux-savedefconfig+ depends on whether
+ +linux+ is enabled or not
+* +uclibc-menuconfig+ depends on whether the toolchain uses the
+ Buildroot internal toolchain backend or not
+* +ctng-menuconfig+ depends on whether the toolchain uses the
+ crosstool-NG backend or not
+* +barebox-menuconfig+ and +barebox-savedefconfig+ depends on whether
+ +barebox+ bootloader is enabled or not
+
+Delete all build products (including build directories, host, staging
+and target trees, the images and the toolchain):
+
+--------------------
+ $ make clean
+--------------------
+
+Delete all build products as well as the configuration:
+
+--------------------
+ $ make distclean
+--------------------
+
+Note that if +ccache+ is enabled, running +make clean|distclean+ does
+not empty the Buildroot's cache. To delete it, refer to xref:ccache[].
diff --git a/docs/manual/working-with.txt b/docs/manual/working-with.txt
index e444204..01f1041 100644
--- a/docs/manual/working-with.txt
+++ b/docs/manual/working-with.txt
@@ -2,6 +2,8 @@ Working with Buildroot
======================
[[working-with-br]]
+include::make-tips.txt[]
+
include::customize.txt[]
include::common-usage.txt[]
--
1.7.10.2
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH v2 05/11] manual: add make-tips.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 05/11] manual: add make-tips.txt Samuel Martin
@ 2012-05-16 16:55 ` Thomas De Schampheleire
0 siblings, 0 replies; 53+ messages in thread
From: Thomas De Schampheleire @ 2012-05-16 16:55 UTC (permalink / raw)
To: buildroot
On Sun, May 13, 2012 at 12:38 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> From: Samuel MARTIN <s.martin49@gmail.com>
>
>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
>
> ?create mode 100644 docs/manual/make-tips.txt
>
> diff --git a/docs/manual/make-tips.txt b/docs/manual/make-tips.txt
> new file mode 100644
> index 0000000..a512689
> --- /dev/null
> +++ b/docs/manual/make-tips.txt
> @@ -0,0 +1,48 @@
> +[[make-tips]]
> +'make' tips
> +-----------
> +
> +Because Buildroot is a set of Makefiles and patches, there are few
> +things useful to know, such as:
> +
> +Display all command executed by make:
> +
> +--------------------
> + $ make V=0|1 <target>
> +--------------------
> +
> +Display all available targets:
> +
> +--------------------
> + $ make help
> +--------------------
> +
> +Note that, some settings in the +.config+ file may hide some targets
> +like:
> +
In combination with the below, this is not a fluent sentence: 'some
settings may hide some targets like ...menuconfig depends on ...'.
This problem can be solved by removing 'like'.
Additionally I'd remove the comma after 'note that'.
> +* +busybox-menuconfig+ depends whether +busybox+ is enabled or not in
> + ?the +Package selection+ menu
s/depends/depends on/
> +* +linux-menuconfig+ and +linux-savedefconfig+ depends on whether
> + ?+linux+ is enabled or not
s/depends/depend/ (plural)
> +* +uclibc-menuconfig+ depends on whether the toolchain uses the
> + ?Buildroot internal toolchain backend or not
> +* +ctng-menuconfig+ depends on whether the toolchain uses the
> + ?crosstool-NG backend or not
> +* +barebox-menuconfig+ and +barebox-savedefconfig+ depends on whether
> + ?+barebox+ bootloader is enabled or not
s/depends/depend/ (plural)
> +
> +Delete all build products (including build directories, host, staging
> +and target trees, the images and the toolchain):
> +
> +--------------------
> + $ make clean
> +--------------------
> +
> +Delete all build products as well as the configuration:
> +
> +--------------------
> + $ make distclean
> +--------------------
> +
> +Note that if +ccache+ is enabled, running +make clean|distclean+ does
> +not empty the Buildroot's cache. To delete it, refer to xref:ccache[].
"the Buildroot's cache" is not correct grammatically, but in fact it
is more the compiler cache. Buildroot doesn't have a lot to do with
it.
> diff --git a/docs/manual/working-with.txt b/docs/manual/working-with.txt
> index e444204..01f1041 100644
> --- a/docs/manual/working-with.txt
> +++ b/docs/manual/working-with.txt
> @@ -2,6 +2,8 @@ Working with Buildroot
> ?======================
> ?[[working-with-br]]
>
> +include::make-tips.txt[]
> +
> ?include::customize.txt[]
>
> ?include::common-usage.txt[]
> --
> 1.7.10.2
>
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH v2 06/11] manual: update working-with.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 " Samuel Martin
` (4 preceding siblings ...)
2012-05-13 10:38 ` [Buildroot] [PATCH v2 05/11] manual: add make-tips.txt Samuel Martin
@ 2012-05-13 10:38 ` Samuel Martin
2012-05-16 17:00 ` Thomas De Schampheleire
2012-05-13 10:38 ` [Buildroot] [PATCH v2 07/11] manual: rework the intro of customize-rootfs.txt Samuel Martin
` (4 subsequent siblings)
10 siblings, 1 reply; 53+ messages in thread
From: Samuel Martin @ 2012-05-13 10:38 UTC (permalink / raw)
To: buildroot
From: Samuel MARTIN <s.martin49@gmail.com>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
diff --git a/docs/manual/rebuilding-packages.txt b/docs/manual/rebuilding-packages.txt
index 717121a..6b486cf 100644
--- a/docs/manual/rebuilding-packages.txt
+++ b/docs/manual/rebuilding-packages.txt
@@ -29,8 +29,8 @@ by the different packages, so some understanding of the particular
package is needed.
For packages relying on Buildroot packages infrastructures (see
-xref:add-packages[this section] for details), the following stamp
-files are relevant:
+xref:adding-packages[] for details), the following stamp files are
+relevant:
* +output/build/packagename-version/.stamp_configured+. If removed,
Buildroot will trigger the recompilation of the package from the
diff --git a/docs/manual/working-with.txt b/docs/manual/working-with.txt
index 01f1041..b9d915c 100644
--- a/docs/manual/working-with.txt
+++ b/docs/manual/working-with.txt
@@ -1,6 +1,9 @@
Working with Buildroot
======================
-[[working-with-br]]
+
+This section aims to explain how Buildroot allows you to tune,
+customize almost everthing... making your configuration fitting your
+needs.
include::make-tips.txt[]
@@ -10,3 +13,10 @@ include::common-usage.txt[]
Tweaking Buildroot
------------------
+
+Because Buildroot does not yet fit all your requirements, you may be
+intrested in tweaking it to add:
+
+* new packages: refer to the xref:adding-packages[Developer guide]
+
+* new board support: refer to the xref:board-support[Developer guide]
--
1.7.10.2
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH v2 06/11] manual: update working-with.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 06/11] manual: update working-with.txt Samuel Martin
@ 2012-05-16 17:00 ` Thomas De Schampheleire
2012-05-17 10:02 ` Samuel Martin
0 siblings, 1 reply; 53+ messages in thread
From: Thomas De Schampheleire @ 2012-05-16 17:00 UTC (permalink / raw)
To: buildroot
On Sun, May 13, 2012 at 12:38 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> From: Samuel MARTIN <s.martin49@gmail.com>
>
>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
>
> diff --git a/docs/manual/rebuilding-packages.txt b/docs/manual/rebuilding-packages.txt
> index 717121a..6b486cf 100644
> --- a/docs/manual/rebuilding-packages.txt
> +++ b/docs/manual/rebuilding-packages.txt
> @@ -29,8 +29,8 @@ by the different packages, so some understanding of the particular
> ?package is needed.
>
> ?For packages relying on Buildroot packages infrastructures (see
I know that you didn't change this here, but I'd change the second
'packages' to singular:
... on Buildroot package infrastructures.
> -xref:add-packages[this section] for details), the following stamp
> -files are relevant:
> +xref:adding-packages[] for details), the following stamp files are
> +relevant:
>
> ?* +output/build/packagename-version/.stamp_configured+. If removed,
> ? Buildroot will trigger the recompilation of the package from the
> diff --git a/docs/manual/working-with.txt b/docs/manual/working-with.txt
> index 01f1041..b9d915c 100644
> --- a/docs/manual/working-with.txt
> +++ b/docs/manual/working-with.txt
> @@ -1,6 +1,9 @@
> ?Working with Buildroot
> ?======================
> -[[working-with-br]]
> +
> +This section aims to explain how Buildroot allows you to tune,
> +customize almost everthing... making your configuration fitting your
> +needs.
What is the difference between tune and customize? Later you also use
'tweaking'.
s/everthing/everything/
s/fitting/fit/
But, rephrasing suggestion:
This section explains how you can customize Buildroot to fit your needs.
>
> ?include::make-tips.txt[]
>
> @@ -10,3 +13,10 @@ include::common-usage.txt[]
>
> ?Tweaking Buildroot
> ?------------------
> +
> +Because Buildroot does not yet fit all your requirements, you may be
> +intrested in tweaking it to add:
s/Because/If/
s/intrested/interested/
> +
> +* new packages: refer to the xref:adding-packages[Developer guide]
> +
> +* new board support: refer to the xref:board-support[Developer guide]
> --
> 1.7.10.2
>
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH v2 06/11] manual: update working-with.txt
2012-05-16 17:00 ` Thomas De Schampheleire
@ 2012-05-17 10:02 ` Samuel Martin
0 siblings, 0 replies; 53+ messages in thread
From: Samuel Martin @ 2012-05-17 10:02 UTC (permalink / raw)
To: buildroot
2012/5/16 Thomas De Schampheleire <patrickdepinguin+buildroot@gmail.com>:
> On Sun, May 13, 2012 at 12:38 PM, Samuel Martin <s.martin49@gmail.com> wrote:
>> From: Samuel MARTIN <s.martin49@gmail.com>
>>
[...]
>> diff --git a/docs/manual/working-with.txt b/docs/manual/working-with.txt
>> index 01f1041..b9d915c 100644
>> --- a/docs/manual/working-with.txt
>> +++ b/docs/manual/working-with.txt
>> @@ -1,6 +1,9 @@
>> ?Working with Buildroot
>> ?======================
>> -[[working-with-br]]
>> +
>> +This section aims to explain how Buildroot allows you to tune,
>> +customize almost everthing... making your configuration fitting your
>> +needs.
>
> What is the difference between tune and customize? Later you also use
> 'tweaking'.
My first thoughts were: tuning or customizing BR means "making changes
through the configuration interface (i.e. adjusting toolchain
features, package selection and so on), whereas tweaking was more
likely hacking BR itself (i.e adding new packages, support for new
boards/architectures/...).
But, I admit the difference between these 3 words is not so obvious.
Let's put 'hacking' in instead of 'tweaking'.
> s/everthing/everything/
> s/fitting/fit/
>
> But, rephrasing suggestion:
> This section explains how you can customize Buildroot to fit your needs.
Fair enough.
The simpler, the better!
>
>>
>> ?include::make-tips.txt[]
>>
>> @@ -10,3 +13,10 @@ include::common-usage.txt[]
>>
>> ?Tweaking Buildroot
>> ?------------------
>> +
>> +Because Buildroot does not yet fit all your requirements, you may be
>> +intrested in tweaking it to add:
>
> s/Because/If/
> s/intrested/interested/
>
>> +
>> +* new packages: refer to the xref:adding-packages[Developer guide]
>> +
>> +* new board support: refer to the xref:board-support[Developer guide]
>> --
>> 1.7.10.2
>>
>> _______________________________________________
>> buildroot mailing list
>> buildroot at busybox.net
>> http://lists.busybox.net/mailman/listinfo/buildroot
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH v2 07/11] manual: rework the intro of customize-rootfs.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 " Samuel Martin
` (5 preceding siblings ...)
2012-05-13 10:38 ` [Buildroot] [PATCH v2 06/11] manual: update working-with.txt Samuel Martin
@ 2012-05-13 10:38 ` Samuel Martin
2012-05-16 17:02 ` Thomas De Schampheleire
2012-05-13 10:38 ` [Buildroot] [PATCH v2 08/11] manual: add troubleshooting.txt Samuel Martin
` (3 subsequent siblings)
10 siblings, 1 reply; 53+ messages in thread
From: Samuel Martin @ 2012-05-13 10:38 UTC (permalink / raw)
To: buildroot
From: Samuel MARTIN <s.martin49@gmail.com>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
diff --git a/docs/manual/customize-rootfs.txt b/docs/manual/customize-rootfs.txt
index 123c97f..d067e31 100644
--- a/docs/manual/customize-rootfs.txt
+++ b/docs/manual/customize-rootfs.txt
@@ -2,7 +2,9 @@
Customizing the generated target filesystem
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-There are a few ways to customize the resulting target filesystem:
+Apart changing one or another configuration through +make
+*-menuconfig+, there are a few ways to customize the resulting target
+filesystem:
* Customize the target filesystem directly and rebuild the image. The
target filesystem is available under +output/target/+. You can
--
1.7.10.2
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH v2 07/11] manual: rework the intro of customize-rootfs.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 07/11] manual: rework the intro of customize-rootfs.txt Samuel Martin
@ 2012-05-16 17:02 ` Thomas De Schampheleire
0 siblings, 0 replies; 53+ messages in thread
From: Thomas De Schampheleire @ 2012-05-16 17:02 UTC (permalink / raw)
To: buildroot
On Sun, May 13, 2012 at 12:38 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> From: Samuel MARTIN <s.martin49@gmail.com>
>
>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
>
> diff --git a/docs/manual/customize-rootfs.txt b/docs/manual/customize-rootfs.txt
> index 123c97f..d067e31 100644
> --- a/docs/manual/customize-rootfs.txt
> +++ b/docs/manual/customize-rootfs.txt
> @@ -2,7 +2,9 @@
> ?Customizing the generated target filesystem
> ?~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> -There are a few ways to customize the resulting target filesystem:
> +Apart changing one or another configuration through +make
> +*-menuconfig+, there are a few ways to customize the resulting target
> +filesystem:
s/Apart/Apart from/
or
s/Apart/Besides/
I also don't think you can 'change one or another configuration'. You
could 'change configuration' or 'change one or more configuration
options'.
>
> ?* Customize the target filesystem directly and rebuild the image. ?The
> ? target filesystem is available under +output/target/+. ?You can
> --
> 1.7.10.2
>
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH v2 08/11] manual: add troubleshooting.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 " Samuel Martin
` (6 preceding siblings ...)
2012-05-13 10:38 ` [Buildroot] [PATCH v2 07/11] manual: rework the intro of customize-rootfs.txt Samuel Martin
@ 2012-05-13 10:38 ` Samuel Martin
2012-05-16 17:04 ` Thomas De Schampheleire
2012-05-13 10:38 ` [Buildroot] [PATCH v2 09/11] manual: add writing-rules.txt Samuel Martin
` (2 subsequent siblings)
10 siblings, 1 reply; 53+ messages in thread
From: Samuel Martin @ 2012-05-13 10:38 UTC (permalink / raw)
To: buildroot
From: Samuel MARTIN <s.martin49@gmail.com>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
create mode 100644 docs/manual/troubleshooting.txt
diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
index b35b5f6..aa0952e 100644
--- a/docs/manual/manual.txt
+++ b/docs/manual/manual.txt
@@ -17,6 +17,7 @@ include::starting-up.txt[]
include::working-with.txt[]
+include::troubleshooting.txt[]
diff --git a/docs/manual/troubleshooting.txt b/docs/manual/troubleshooting.txt
new file mode 100644
index 0000000..db9277d
--- /dev/null
+++ b/docs/manual/troubleshooting.txt
@@ -0,0 +1,46 @@
+Troubleshooting
+===============
+
+LZO package configuration failure due to incorrect host architecture detection
+------------------------------------------------------------------------------
+
+Typical error output
+~~~~~~~~~~~~~~~~~~~~
+
+------------------------
+configure: Configuring LZO 2.03
+checking build system type... Invalid configuration `x86_64-unknown-linux-': machine `x86_64-unknown-linux' not recognized
+configure: error: /bin/sh autoconf/config.sub x86_64-unknown-linux- failed
+------------------------
+
+Actually this is a known ccache/zlib issue (see
+https://bugs.busybox.net/show_bug.cgi?id=4808) that occurs when the
+zlib version of the host system is more recent that the one provided
+by Buildroot. This misleads the Buildroot host binary +ccache+.
+
+This bug has been spotted, then fixed shortly after the Buildroot
+2012.02 release.
+
+If you are using the release 2012.02 or elder and got this issue, then
+applying this patch
+http://git.buildroot.net/buildroot/patch/package/ccache/ccache.mk?id=7ea11dafff37c5403432f691cf3c46d1d5566e46
+should fix it.
+
+Solution
+~~~~~~~~
+
+* Get the upstream patch:
++
+-----------------------
+ $ wget -O /tmp/ccache-Force-ccache-to-use-its-internal-zlib.patch \
+ "http://git.buildroot.net/buildroot/patch/package/ccache/ccache.mk?id=7ea11dafff37c5403432f691cf3c46d1d5566e46"
+------------------------
+
+* Apply this patch and rebuild ccache:
++
+------------------------
+ $ cd buildroot
+ $ patch -p1 < /tmp/ccache-Force-ccache-to-use-its-internal-zlib.patch
+ $ make host-ccache-dirclean
+ $ make
+------------------------
--
1.7.10.2
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH v2 08/11] manual: add troubleshooting.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 08/11] manual: add troubleshooting.txt Samuel Martin
@ 2012-05-16 17:04 ` Thomas De Schampheleire
0 siblings, 0 replies; 53+ messages in thread
From: Thomas De Schampheleire @ 2012-05-16 17:04 UTC (permalink / raw)
To: buildroot
On Sun, May 13, 2012 at 12:38 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> From: Samuel MARTIN <s.martin49@gmail.com>
>
>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
>
> ?create mode 100644 docs/manual/troubleshooting.txt
>
> diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
> index b35b5f6..aa0952e 100644
> --- a/docs/manual/manual.txt
> +++ b/docs/manual/manual.txt
> @@ -17,6 +17,7 @@ include::starting-up.txt[]
>
> ?include::working-with.txt[]
>
> +include::troubleshooting.txt[]
>
>
>
> diff --git a/docs/manual/troubleshooting.txt b/docs/manual/troubleshooting.txt
> new file mode 100644
> index 0000000..db9277d
> --- /dev/null
> +++ b/docs/manual/troubleshooting.txt
> @@ -0,0 +1,46 @@
> +Troubleshooting
> +===============
> +
> +LZO package configuration failure due to incorrect host architecture detection
> +------------------------------------------------------------------------------
> +
> +Typical error output
> +~~~~~~~~~~~~~~~~~~~~
> +
> +------------------------
> +configure: Configuring LZO 2.03
> +checking build system type... Invalid configuration `x86_64-unknown-linux-': machine `x86_64-unknown-linux' not recognized
> +configure: error: /bin/sh autoconf/config.sub x86_64-unknown-linux- failed
> +------------------------
> +
> +Actually this is a known ccache/zlib issue (see
> +https://bugs.busybox.net/show_bug.cgi?id=4808) that occurs when the
> +zlib version of the host system is more recent that the one provided
> +by Buildroot. This misleads the Buildroot host binary +ccache+.
> +
> +This bug has been spotted, then fixed shortly after the Buildroot
> +2012.02 release.
> +
> +If you are using the release 2012.02 or elder and got this issue, then
> +applying this patch
> +http://git.buildroot.net/buildroot/patch/package/ccache/ccache.mk?id=7ea11dafff37c5403432f691cf3c46d1d5566e46
> +should fix it.
s/elder/older/
> +
> +Solution
> +~~~~~~~~
> +
> +* Get the upstream patch:
> ++
> +-----------------------
> + $ wget -O /tmp/ccache-Force-ccache-to-use-its-internal-zlib.patch \
> + ? ?"http://git.buildroot.net/buildroot/patch/package/ccache/ccache.mk?id=7ea11dafff37c5403432f691cf3c46d1d5566e46"
> +------------------------
> +
> +* Apply this patch and rebuild ccache:
> ++
> +------------------------
> + $ cd buildroot
> + $ patch -p1 < /tmp/ccache-Force-ccache-to-use-its-internal-zlib.patch
> + $ make host-ccache-dirclean
> + $ make
> +------------------------
> --
> 1.7.10.2
>
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH v2 09/11] manual: add writing-rules.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 " Samuel Martin
` (7 preceding siblings ...)
2012-05-13 10:38 ` [Buildroot] [PATCH v2 08/11] manual: add troubleshooting.txt Samuel Martin
@ 2012-05-13 10:38 ` Samuel Martin
2012-05-13 14:12 ` Yegor Yefremov
2012-05-16 17:15 ` Thomas De Schampheleire
2012-05-13 10:38 ` [Buildroot] [PATCH v2 10/11] manual: add get-involved.txt Samuel Martin
2012-05-13 10:38 ` [Buildroot] [PATCH v2 11/11] manual: add contribute.txt Samuel Martin
10 siblings, 2 replies; 53+ messages in thread
From: Samuel Martin @ 2012-05-13 10:38 UTC (permalink / raw)
To: buildroot
From: Samuel MARTIN <s.martin49@gmail.com>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
create mode 100644 docs/manual/writing-rules.txt
diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
index 1428f37..e36eafc 100644
--- a/docs/manual/adding-packages-directory.txt
+++ b/docs/manual/adding-packages-directory.txt
@@ -145,6 +145,9 @@ is also enabled, but not necessarily built before your package. To do
so, the dependency also needs to be expressed in the +.mk+ file of the
package.
+Further formating details: see xref:writing-rules-config-in[the
+writing rules].
+
The +.mk+ file
^^^^^^^^^^^^^^
@@ -185,3 +188,5 @@ different way, using different infrastructures:
many of them in the tree, we keep them documented in a
xref:handwritten-tutorial[tutorial].
+Further formating details: see xref:writing-rules-mk[the writing
+rules].
diff --git a/docs/manual/developer-guide.txt b/docs/manual/developer-guide.txt
index 69f3632..14589c2 100644
--- a/docs/manual/developer-guide.txt
+++ b/docs/manual/developer-guide.txt
@@ -1,6 +1,8 @@
Developer Guidelines
====================
+include::writing-rules.txt[]
+
include::adding-packages.txt[]
include::board-support.txt[]
diff --git a/docs/manual/writing-rules.txt b/docs/manual/writing-rules.txt
new file mode 100644
index 0000000..b18f30b
--- /dev/null
+++ b/docs/manual/writing-rules.txt
@@ -0,0 +1,119 @@
+Writing rules
+-------------
+
+Overall, those writing rules are here to help you adding new files in
+Buildroot or refactoring existing ones. In these cases, should be followed.
+
+If you slightly modify some existing file, the important thing is
+keeping th consistency of the whole file, so you can:
+* either follow the potentially deprecated rules used all over this
+file
+* or entirely rework it in order to make it comply with those rules.
+
+[[writing-rules-config-in]]
+
++Config.in+ file
+~~~~~~~~~~~~~~~~
+
++Config.in+ files contain entry for almost anything configurable in
+buildroot.
+
+Entry has the following pattern:
+
+---------------------
+config BR2_PACKAGE_LIBFOO
+ bool "libfoo"
+ depends on BR2_PACKAGE_LIBBAZ
+ select BR2_PACKAGE_LIBBAR
+ help
+ This is a comment that explains what libfoo is.
+
+ http://foosoftware.org/libfoo/
+---------------------
+
+* The +bool+, +depends on+, +select+ and +help+ lines are indented
+ with one tab.
+
+* The help text itself should be indented with one tab and two
+ spaces.
+
+
+[[writing-rules-mk]]
+
+The +.mk+ file
+~~~~~~~~~~~~~~
+
+* Affectation: use +=+ preceeded and followed by one space:
++
+---------------------
+LIBFOO_VERSION = 1.0
+LIBFOO_CONF_OPT += --without-python-support
+---------------------
+
+* Indentation: use tab only:
++
+---------------------
+define LIBFOO_REMOVE_DOC
+$(RM) -fr $(TARGET_DIR)/usr/share/libfoo/doc \
+ $(TARGET_DIR)/usr/share/man/man3/libfoo*
+endef
+---------------------
+
+* Optional dependency:
+
+** Prefer multi-line syntax.
++
+YES:
++
+---------------------
+ifeq ($(BR2_PACKAGE_PYTHON),y)
+LIBFOO_CONF_OPT += --with-python-support
+LIBFOO_DEPENDENCIES += python
+else
+LIBFOO_CONF_OPT += --without-python-support
+endif
+---------------------
++
+NO:
++
+---------------------
+LIBFOO_CONF_OPT += --with$(if $(BR2_PACKAGE_PYTHON),,out)-python-support
+LIBFOO_DEPENDENCIES += $(if $(BR2_PACKAGE_PYTHON),python,)
+---------------------
+
+** Keep configure options and dependencies close together.
+
+* Optional hook: Keep hook function definition close hooks variable
+ affection nested in the +if+ block:
++
+YES:
++
+---------------------
+ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
+define LIBFOO_REMOVE_DATA
+ $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
+endef
+LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
+endif
+---------------------
++
+NO:
++
+---------------------
+define LIBFOO_REMOVE_DATA
+ $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
+endef
+
+ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
+LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
+endif
+---------------------
+
+The documentation
+~~~~~~~~~~~~~~~~~
+
+The documentation uses the
+http://www.methods.co.nz/asciidoc/[asciidoc] format.
+
+Further details about the http://www.methods.co.nz/asciidoc/[asciidoc]
+syntax: refer to http://www.methods.co.nz/asciidoc/userguide.html[].
--
1.7.10.2
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH v2 09/11] manual: add writing-rules.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 09/11] manual: add writing-rules.txt Samuel Martin
@ 2012-05-13 14:12 ` Yegor Yefremov
2012-05-16 17:15 ` Thomas De Schampheleire
1 sibling, 0 replies; 53+ messages in thread
From: Yegor Yefremov @ 2012-05-13 14:12 UTC (permalink / raw)
To: buildroot
On Sun, May 13, 2012 at 12:38 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> From: Samuel MARTIN <s.martin49@gmail.com>
>
>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
>
> ?create mode 100644 docs/manual/writing-rules.txt
>
> diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
> index 1428f37..e36eafc 100644
> --- a/docs/manual/adding-packages-directory.txt
> +++ b/docs/manual/adding-packages-directory.txt
> @@ -145,6 +145,9 @@ is also enabled, but not necessarily built before your package. To do
> ?so, the dependency also needs to be expressed in the +.mk+ file of the
> ?package.
>
> +Further formating details: see xref:writing-rules-config-in[the
> +writing rules].
> +
> ?The +.mk+ file
> ?^^^^^^^^^^^^^^
>
> @@ -185,3 +188,5 @@ different way, using different infrastructures:
> ? many of them in the tree, we keep them documented in a
> ? xref:handwritten-tutorial[tutorial].
>
> +Further formating details: see xref:writing-rules-mk[the writing
> +rules].
> diff --git a/docs/manual/developer-guide.txt b/docs/manual/developer-guide.txt
> index 69f3632..14589c2 100644
> --- a/docs/manual/developer-guide.txt
> +++ b/docs/manual/developer-guide.txt
> @@ -1,6 +1,8 @@
> ?Developer Guidelines
> ?====================
>
> +include::writing-rules.txt[]
> +
> ?include::adding-packages.txt[]
>
> ?include::board-support.txt[]
> diff --git a/docs/manual/writing-rules.txt b/docs/manual/writing-rules.txt
> new file mode 100644
> index 0000000..b18f30b
> --- /dev/null
> +++ b/docs/manual/writing-rules.txt
> @@ -0,0 +1,119 @@
> +Writing rules
> +-------------
> +
> +Overall, those writing rules are here to help you adding new files in
> +Buildroot or refactoring existing ones. In these cases, should be followed.
> +
> +If you slightly modify some existing file, the important thing is
> +keeping th consistency of the whole file, so you can:
s/th/the
> +* either follow the potentially deprecated rules used all over this
> +file
> +* or entirely rework it in order to make it comply with those rules.
> +
> +[[writing-rules-config-in]]
> +
> ++Config.in+ file
> +~~~~~~~~~~~~~~~~
> +
> ++Config.in+ files contain entry for almost anything configurable in
> +buildroot.
s/buildroot/Buildroot
> +
> +Entry has the following pattern:
> +
> +---------------------
> +config BR2_PACKAGE_LIBFOO
> + ? ? ? bool "libfoo"
> + ? ? ? depends on BR2_PACKAGE_LIBBAZ
> + ? ? ? select BR2_PACKAGE_LIBBAR
> + ? ? ? help
> + ? ? ? ? This is a comment that explains what libfoo is.
> +
> + ? ? ? ? http://foosoftware.org/libfoo/
> +---------------------
> +
> +* The +bool+, +depends on+, +select+ and +help+ lines are indented
> + ?with one tab.
> +
> +* The help text itself should be indented with one tab and two
> + ?spaces.
> +
> +
> +[[writing-rules-mk]]
> +
> +The +.mk+ file
> +~~~~~~~~~~~~~~
> +
> +* Affectation: use +=+ preceeded and followed by one space:
> ++
> +---------------------
> +LIBFOO_VERSION = 1.0
> +LIBFOO_CONF_OPT += --without-python-support
> +---------------------
> +
> +* Indentation: use tab only:
> ++
> +---------------------
> +define LIBFOO_REMOVE_DOC
> +$(RM) -fr $(TARGET_DIR)/usr/share/libfoo/doc \
> + ? ? ? $(TARGET_DIR)/usr/share/man/man3/libfoo*
> +endef
> +---------------------
> +
> +* Optional dependency:
> +
> +** Prefer multi-line syntax.
> ++
> +YES:
> ++
> +---------------------
> +ifeq ($(BR2_PACKAGE_PYTHON),y)
> +LIBFOO_CONF_OPT += --with-python-support
> +LIBFOO_DEPENDENCIES += python
> +else
> +LIBFOO_CONF_OPT += --without-python-support
> +endif
> +---------------------
> ++
> +NO:
> ++
> +---------------------
> +LIBFOO_CONF_OPT += --with$(if $(BR2_PACKAGE_PYTHON),,out)-python-support
> +LIBFOO_DEPENDENCIES += $(if $(BR2_PACKAGE_PYTHON),python,)
> +---------------------
> +
> +** Keep configure options and dependencies close together.
> +
> +* Optional hook: Keep hook function definition close hooks variable
> + ?affection nested in the +if+ block:
> ++
> +YES:
> ++
> +---------------------
> +ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
> +define LIBFOO_REMOVE_DATA
> + ? ? ? $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
> +endef
> +LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
> +endif
> +---------------------
> ++
> +NO:
> ++
> +---------------------
> +define LIBFOO_REMOVE_DATA
> + ? ? ? $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
> +endef
> +
> +ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
> +LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
> +endif
> +---------------------
> +
> +The documentation
> +~~~~~~~~~~~~~~~~~
> +
> +The documentation uses the
> +http://www.methods.co.nz/asciidoc/[asciidoc] format.
> +
> +Further details about the http://www.methods.co.nz/asciidoc/[asciidoc]
> +syntax: refer to http://www.methods.co.nz/asciidoc/userguide.html[].
> --
> 1.7.10.2
>
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH v2 09/11] manual: add writing-rules.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 09/11] manual: add writing-rules.txt Samuel Martin
2012-05-13 14:12 ` Yegor Yefremov
@ 2012-05-16 17:15 ` Thomas De Schampheleire
1 sibling, 0 replies; 53+ messages in thread
From: Thomas De Schampheleire @ 2012-05-16 17:15 UTC (permalink / raw)
To: buildroot
On Sun, May 13, 2012 at 12:38 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> From: Samuel MARTIN <s.martin49@gmail.com>
>
>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
>
> ?create mode 100644 docs/manual/writing-rules.txt
>
> diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
> index 1428f37..e36eafc 100644
> --- a/docs/manual/adding-packages-directory.txt
> +++ b/docs/manual/adding-packages-directory.txt
> @@ -145,6 +145,9 @@ is also enabled, but not necessarily built before your package. To do
> ?so, the dependency also needs to be expressed in the +.mk+ file of the
> ?package.
>
> +Further formating details: see xref:writing-rules-config-in[the
> +writing rules].
s/formating/formatting/
> +
> ?The +.mk+ file
> ?^^^^^^^^^^^^^^
>
> @@ -185,3 +188,5 @@ different way, using different infrastructures:
> ? many of them in the tree, we keep them documented in a
> ? xref:handwritten-tutorial[tutorial].
>
> +Further formating details: see xref:writing-rules-mk[the writing
> +rules].
idem, formatting
> diff --git a/docs/manual/developer-guide.txt b/docs/manual/developer-guide.txt
> index 69f3632..14589c2 100644
> --- a/docs/manual/developer-guide.txt
> +++ b/docs/manual/developer-guide.txt
> @@ -1,6 +1,8 @@
> ?Developer Guidelines
> ?====================
>
> +include::writing-rules.txt[]
> +
> ?include::adding-packages.txt[]
>
> ?include::board-support.txt[]
> diff --git a/docs/manual/writing-rules.txt b/docs/manual/writing-rules.txt
> new file mode 100644
> index 0000000..b18f30b
> --- /dev/null
> +++ b/docs/manual/writing-rules.txt
> @@ -0,0 +1,119 @@
> +Writing rules
> +-------------
> +
> +Overall, those writing rules are here to help you adding new files in
> +Buildroot or refactoring existing ones. In these cases, should be followed.
Again, I'm not a native English speaker, but I think that you can either say:
... to help you add new files or refactor existing ones.
or
... to help you in adding new files or refactoring existing ones.
There is something missing in the sentence 'In these cases, should be followed.'
> +
> +If you slightly modify some existing file, the important thing is
> +keeping th consistency of the whole file, so you can:
> +* either follow the potentially deprecated rules used all over this
> +file
> +* or entirely rework it in order to make it comply with those rules.
s/th/the/
> +
> +[[writing-rules-config-in]]
> +
> ++Config.in+ file
> +~~~~~~~~~~~~~~~~
> +
> ++Config.in+ files contain entry for almost anything configurable in
> +buildroot.
s/entry/entries/
> +
> +Entry has the following pattern:
s/Entry/An entry/
> +
> +---------------------
> +config BR2_PACKAGE_LIBFOO
> + ? ? ? bool "libfoo"
> + ? ? ? depends on BR2_PACKAGE_LIBBAZ
> + ? ? ? select BR2_PACKAGE_LIBBAR
> + ? ? ? help
> + ? ? ? ? This is a comment that explains what libfoo is.
> +
> + ? ? ? ? http://foosoftware.org/libfoo/
> +---------------------
> +
> +* The +bool+, +depends on+, +select+ and +help+ lines are indented
> + ?with one tab.
> +
> +* The help text itself should be indented with one tab and two
> + ?spaces.
I'd refer to the fact that this is regular Kconfig, and a reference to
the syntax description, for example in the Linux kernel documentation.
> +
> +
> +[[writing-rules-mk]]
> +
> +The +.mk+ file
> +~~~~~~~~~~~~~~
> +
> +* Affectation: use +=+ preceeded and followed by one space:
What is 'affectation' ? Do you mean assignment?
s/preceeded/preceded/
> ++
> +---------------------
> +LIBFOO_VERSION = 1.0
> +LIBFOO_CONF_OPT += --without-python-support
> +---------------------
> +
> +* Indentation: use tab only:
> ++
> +---------------------
> +define LIBFOO_REMOVE_DOC
> +$(RM) -fr $(TARGET_DIR)/usr/share/libfoo/doc \
> + ? ? ? $(TARGET_DIR)/usr/share/man/man3/libfoo*
> +endef
> +---------------------
> +
> +* Optional dependency:
> +
> +** Prefer multi-line syntax.
> ++
> +YES:
> ++
> +---------------------
> +ifeq ($(BR2_PACKAGE_PYTHON),y)
> +LIBFOO_CONF_OPT += --with-python-support
> +LIBFOO_DEPENDENCIES += python
> +else
> +LIBFOO_CONF_OPT += --without-python-support
> +endif
> +---------------------
> ++
> +NO:
> ++
> +---------------------
> +LIBFOO_CONF_OPT += --with$(if $(BR2_PACKAGE_PYTHON),,out)-python-support
> +LIBFOO_DEPENDENCIES += $(if $(BR2_PACKAGE_PYTHON),python,)
> +---------------------
> +
> +** Keep configure options and dependencies close together.
> +
> +* Optional hook: Keep hook function definition close hooks variable
> + ?affection nested in the +if+ block:
Suggestion:
Optional hooks: keep hook definition and assignment together in one if block.
> ++
> +YES:
> ++
> +---------------------
> +ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
> +define LIBFOO_REMOVE_DATA
> + ? ? ? $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/datas/Optional hook/Optional hooks/
> +endef
> +LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
> +endif
> +---------------------
> ++
> +NO:
> ++
> +---------------------
> +define LIBFOO_REMOVE_DATA
> + ? ? ? $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
> +endef
> +
> +ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
> +LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
> +endif
> +---------------------
> +
> +The documentation
> +~~~~~~~~~~~~~~~~~
> +
> +The documentation uses the
> +http://www.methods.co.nz/asciidoc/[asciidoc] format.
> +
> +Further details about the http://www.methods.co.nz/asciidoc/[asciidoc]
> +syntax: refer to http://www.methods.co.nz/asciidoc/userguide.html[].
> --
> 1.7.10.2
>
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH v2 10/11] manual: add get-involved.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 " Samuel Martin
` (8 preceding siblings ...)
2012-05-13 10:38 ` [Buildroot] [PATCH v2 09/11] manual: add writing-rules.txt Samuel Martin
@ 2012-05-13 10:38 ` Samuel Martin
2012-05-13 11:25 ` Yegor Yefremov
2012-05-16 17:21 ` Thomas De Schampheleire
2012-05-13 10:38 ` [Buildroot] [PATCH v2 11/11] manual: add contribute.txt Samuel Martin
10 siblings, 2 replies; 53+ messages in thread
From: Samuel Martin @ 2012-05-13 10:38 UTC (permalink / raw)
To: buildroot
From: Samuel MARTIN <s.martin49@gmail.com>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
create mode 100644 docs/manual/get-involved.txt
diff --git a/docs/manual/get-involved.txt b/docs/manual/get-involved.txt
new file mode 100644
index 0000000..9b6e843
--- /dev/null
+++ b/docs/manual/get-involved.txt
@@ -0,0 +1,67 @@
+Getting involved
+================
+
+Like any open source projects, Buildroot has different ways to share
+information in its community and outside.
+
+One piece of it is the document you are currently reading ;-).
+
+Each of those ways may interest you if you are look for some help,
+want to understand Buildroot or contribute to the project.
+
+Mailing List
+------------
+
+Buildroot has a mailing list
+http://lists.busybox.net/pipermail/buildroot[] for discussion and
+development.
+
+[[mailing-list-subscribe]]
+
+Subscribing to the mailing list
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can subscribe by visiting
+http://lists.busybox.net/mailman/listinfo/buildroot[].
+Only subscribers to the Buildroot mailing list are allowed to post to
+this list.
+
+The list is also available through _Gmane_ http://gmane.org[], at
++gmane.comp.lib.uclibc.buildroot+
+http://dir.gmane.org/gmane.comp.lib.uclibc.buildroot[].
+
+Searching the List Archives
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Please search the mailing list archives before asking questions on the
+mailing list, since there is a good chance someone else has asked the
+same question before. Checking the archives is a great way to avoid
+annoying everyone on the list with frequently asked questions...
+
+IRC
+---
+
+The Buildroot IRC is irc://freenode.net/#buildroot[].
+The channel +#buildroot+ is hosted on Freenode
+http://webchat.freenode.net[].
+
+When asking for help on the IRC, share relevant logs or piece of code
+using a code sharing website (see
+http://en.wikipedia.org/wiki/Comparison_of_pastebins[], and pick up
+one).
+
+Bugtracker
+----------
+
+The Buildroot bugtracker is at https://bugs.uclibc.org[].
+
+Buildroot wikipage
+------------------
+
+Consecutively to the Buildroot developer day February 3, 2012,
+a page dedicated to Buildroot has been created on
+http://elinux.org[elinux.org].
+
+This page is reachable at http://elinux.org/Buildroot[].
+
+Currently, this page is mainly used as a _todo-list_.
diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
index aa0952e..b23e9c1 100644
--- a/docs/manual/manual.txt
+++ b/docs/manual/manual.txt
@@ -25,6 +25,8 @@ include::going-further.txt[]
include::developer-guide.txt[]
+include::get-involved.txt[]
+
include::legal-notice.txt[]
--
1.7.10.2
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH v2 10/11] manual: add get-involved.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 10/11] manual: add get-involved.txt Samuel Martin
@ 2012-05-13 11:25 ` Yegor Yefremov
2012-05-16 17:21 ` Thomas De Schampheleire
1 sibling, 0 replies; 53+ messages in thread
From: Yegor Yefremov @ 2012-05-13 11:25 UTC (permalink / raw)
To: buildroot
On Sun, May 13, 2012 at 12:38 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> From: Samuel MARTIN <s.martin49@gmail.com>
>
>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
>
> ?create mode 100644 docs/manual/get-involved.txt
>
> diff --git a/docs/manual/get-involved.txt b/docs/manual/get-involved.txt
> new file mode 100644
> index 0000000..9b6e843
> --- /dev/null
> +++ b/docs/manual/get-involved.txt
> @@ -0,0 +1,67 @@
> +Getting involved
> +================
> +
> +Like any open source projects, Buildroot has different ways to share
> +information in its community and outside.
> +
> +One piece of it is the document you are currently reading ;-).
> +
> +Each of those ways may interest you if you are look for some help,
s/look/looking
> +want to understand Buildroot or contribute to the project.
> +
> +Mailing List
> +------------
> +
> +Buildroot has a mailing list
> +http://lists.busybox.net/pipermail/buildroot[] for discussion and
> +development.
> +
> +[[mailing-list-subscribe]]
> +
> +Subscribing to the mailing list
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +You can subscribe by visiting
> +http://lists.busybox.net/mailman/listinfo/buildroot[].
> +Only subscribers to the Buildroot mailing list are allowed to post to
> +this list.
> +
> +The list is also available through _Gmane_ http://gmane.org[], at
> ++gmane.comp.lib.uclibc.buildroot+
> +http://dir.gmane.org/gmane.comp.lib.uclibc.buildroot[].
> +
> +Searching the List Archives
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Please search the mailing list archives before asking questions on the
> +mailing list, since there is a good chance someone else has asked the
> +same question before. Checking the archives is a great way to avoid
> +annoying everyone on the list with frequently asked questions...
> +
> +IRC
> +---
> +
> +The Buildroot IRC is irc://freenode.net/#buildroot[].
> +The channel +#buildroot+ is hosted on Freenode
> +http://webchat.freenode.net[].
> +
> +When asking for help on the IRC, share relevant logs or piece of code
> +using a code sharing website (see
> +http://en.wikipedia.org/wiki/Comparison_of_pastebins[], and pick up
> +one).
> +
> +Bugtracker
> +----------
> +
> +The Buildroot bugtracker is at https://bugs.uclibc.org[].
> +
patchwork will be used to keep an eye on patches/bugs, so bugtracker
can be abandoned (require further discussion)
> +Buildroot wikipage
> +------------------
> +
> +Consecutively to the Buildroot developer day February 3, 2012,
> +a page dedicated to Buildroot has been created on
> +http://elinux.org[elinux.org].
> +
> +This page is reachable at http://elinux.org/Buildroot[].
> +
> +Currently, this page is mainly used as a _todo-list_.
> diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
> index aa0952e..b23e9c1 100644
> --- a/docs/manual/manual.txt
> +++ b/docs/manual/manual.txt
> @@ -25,6 +25,8 @@ include::going-further.txt[]
>
> ?include::developer-guide.txt[]
>
> +include::get-involved.txt[]
> +
> ?include::legal-notice.txt[]
>
>
> --
> 1.7.10.2
>
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH v2 10/11] manual: add get-involved.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 10/11] manual: add get-involved.txt Samuel Martin
2012-05-13 11:25 ` Yegor Yefremov
@ 2012-05-16 17:21 ` Thomas De Schampheleire
1 sibling, 0 replies; 53+ messages in thread
From: Thomas De Schampheleire @ 2012-05-16 17:21 UTC (permalink / raw)
To: buildroot
On Sun, May 13, 2012 at 12:38 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> From: Samuel MARTIN <s.martin49@gmail.com>
>
>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
>
> ?create mode 100644 docs/manual/get-involved.txt
>
> diff --git a/docs/manual/get-involved.txt b/docs/manual/get-involved.txt
> new file mode 100644
> index 0000000..9b6e843
> --- /dev/null
> +++ b/docs/manual/get-involved.txt
> @@ -0,0 +1,67 @@
> +Getting involved
> +================
> +
> +Like any open source projects, Buildroot has different ways to share
> +information in its community and outside.
s/projects/project/
> +
> +One piece of it is the document you are currently reading ;-).
> +
> +Each of those ways may interest you if you are look for some help,
> +want to understand Buildroot or contribute to the project.
> +
> +Mailing List
> +------------
> +
> +Buildroot has a mailing list
> +http://lists.busybox.net/pipermail/buildroot[] for discussion and
> +development.
> +
> +[[mailing-list-subscribe]]
> +
> +Subscribing to the mailing list
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +You can subscribe by visiting
> +http://lists.busybox.net/mailman/listinfo/buildroot[].
> +Only subscribers to the Buildroot mailing list are allowed to post to
> +this list.
> +
> +The list is also available through _Gmane_ http://gmane.org[], at
> ++gmane.comp.lib.uclibc.buildroot+
> +http://dir.gmane.org/gmane.comp.lib.uclibc.buildroot[].
> +
> +Searching the List Archives
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Please search the mailing list archives before asking questions on the
> +mailing list, since there is a good chance someone else has asked the
> +same question before. Checking the archives is a great way to avoid
> +annoying everyone on the list with frequently asked questions...
> +
> +IRC
> +---
> +
> +The Buildroot IRC is irc://freenode.net/#buildroot[].
> +The channel +#buildroot+ is hosted on Freenode
> +http://webchat.freenode.net[].
> +
> +When asking for help on the IRC, share relevant logs or piece of code
> +using a code sharing website (see
> +http://en.wikipedia.org/wiki/Comparison_of_pastebins[], and pick up
> +one).
s/the IRC/IRC/
s/piece of code/pieces of code/
s/pick up/pick/
> +
> +Bugtracker
> +----------
> +
> +The Buildroot bugtracker is at https://bugs.uclibc.org[].
It is also reachable through bugs.buildroot.org, so I think we should
use that URL in the documentation.
> +
> +Buildroot wikipage
> +------------------
> +
> +Consecutively to the Buildroot developer day February 3, 2012,
> +a page dedicated to Buildroot has been created on
> +http://elinux.org[elinux.org].
'Consecutively to' feels strange to me. I'd write 'After'
I think you should put 'on' before February.
> +
> +This page is reachable at http://elinux.org/Buildroot[].
> +
> +Currently, this page is mainly used as a _todo-list_.
> diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
> index aa0952e..b23e9c1 100644
> --- a/docs/manual/manual.txt
> +++ b/docs/manual/manual.txt
> @@ -25,6 +25,8 @@ include::going-further.txt[]
>
> ?include::developer-guide.txt[]
>
> +include::get-involved.txt[]
> +
> ?include::legal-notice.txt[]
>
>
> --
> 1.7.10.2
>
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH v2 11/11] manual: add contribute.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 " Samuel Martin
` (9 preceding siblings ...)
2012-05-13 10:38 ` [Buildroot] [PATCH v2 10/11] manual: add get-involved.txt Samuel Martin
@ 2012-05-13 10:38 ` Samuel Martin
2012-05-13 12:16 ` Yegor Yefremov
2012-05-16 17:24 ` Thomas De Schampheleire
10 siblings, 2 replies; 53+ messages in thread
From: Samuel Martin @ 2012-05-13 10:38 UTC (permalink / raw)
To: buildroot
From: Samuel MARTIN <s.martin49@gmail.com>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
create mode 100644 docs/manual/contribute.txt
diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
new file mode 100644
index 0000000..d80e79a
--- /dev/null
+++ b/docs/manual/contribute.txt
@@ -0,0 +1,63 @@
+Contibuting to Buildroot
+========================
+
+If you want to contribute to Buildroot, you will need a git view of
+the project. Refer to xref:getting-buildroot[] to get it.
+
+Currently, the mailing list is the central place for contribution.
+If you have not already subscribe to it, then refer to
+xref:mailing-list-subscribe[].
+
+Submiting patches
+-----------------
+
+When your changes are done, and commited in your local git view,
+_rebase_ your development branch on top of the upstream tree before
+generating the patch set. To do so, run:
+
+---------------------
+ $ git fetch --all --tags
+ $ git rebase origin/master
+---------------------
+
+Here, your are ready to generate then submit your patch set.
+
+To generate it, run:
+
+---------------------
+ $ git format-patch -M -n -s -o outgoing origin/master
+---------------------
+
+This will generate patch files in the +outgoing+ subdirectory,
+automatically adding the +signed-of-by+ line.
+
+If you want to present the whole patch set in a separate mail, add
++--cover-letter --summary+ to the previous command line (+man
+git-format-patch+ for further information).
+
+Once patch files are generated, you can review/edit the commit message
+before submitting them using your favourite text editor.
+
+Lastly, send/submit your patch set to the Buildroot mailing list:
+
+---------------------
+ $ git send-email --to buildroot at busybox.net outgoing/*
+---------------------
+
+Note that +git+ should be configured to use your mail account.
+To configure +git+, see +man git-send-email+ or google it.
+
+Reviewing/Testing patches
+-------------------------
+
+In the review process, do not hesitate to respond to patch submissions
+for remarks, suggestions or anything that will help everyone to
+understand the patches and make them better.
+
+Some tags are used to help following the state of any patch posted on
+the mailing-list:
+
+Acked-by:: Indicates that the patch can be committed.
+
+Tested-by:: Indicates that the patch has been tested. It is useful
+ but not necessary to add a comment about what has been tested.
diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
index b23e9c1..3e7a7ef 100644
--- a/docs/manual/manual.txt
+++ b/docs/manual/manual.txt
@@ -27,6 +27,8 @@ include::developer-guide.txt[]
include::get-involved.txt[]
+include::contribute.txt[]
+
include::legal-notice.txt[]
--
1.7.10.2
^ permalink raw reply related [flat|nested] 53+ messages in thread* [Buildroot] [PATCH v2 11/11] manual: add contribute.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 11/11] manual: add contribute.txt Samuel Martin
@ 2012-05-13 12:16 ` Yegor Yefremov
2012-05-16 17:24 ` Thomas De Schampheleire
1 sibling, 0 replies; 53+ messages in thread
From: Yegor Yefremov @ 2012-05-13 12:16 UTC (permalink / raw)
To: buildroot
On Sun, May 13, 2012 at 12:38 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> From: Samuel MARTIN <s.martin49@gmail.com>
>
>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
>
> ?create mode 100644 docs/manual/contribute.txt
>
> diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
> new file mode 100644
> index 0000000..d80e79a
> --- /dev/null
> +++ b/docs/manual/contribute.txt
> @@ -0,0 +1,63 @@
> +Contibuting to Buildroot
> +========================
> +
> +If you want to contribute to Buildroot, you will need a git view of
> +the project. Refer to xref:getting-buildroot[] to get it.
> +
> +Currently, the mailing list is the central place for contribution.
> +If you have not already subscribe to it, then refer to
s/subscribe/subscribed
> +xref:mailing-list-subscribe[].
> +
> +Submiting patches
> +-----------------
> +
> +When your changes are done, and commited in your local git view,
> +_rebase_ your development branch on top of the upstream tree before
> +generating the patch set. To do so, run:
> +
> +---------------------
> + $ git fetch --all --tags
> + $ git rebase origin/master
> +---------------------
> +
> +Here, your are ready to generate then submit your patch set.
s/your are ready/you are ready
> +
> +To generate it, run:
> +
> +---------------------
> + $ git format-patch -M -n -s -o outgoing origin/master
> +---------------------
> +
> +This will generate patch files in the +outgoing+ subdirectory,
> +automatically adding the +signed-of-by+ line.
> +
> +If you want to present the whole patch set in a separate mail, add
> ++--cover-letter --summary+ to the previous command line (+man
> +git-format-patch+ for further information).
> +
> +Once patch files are generated, you can review/edit the commit message
> +before submitting them using your favourite text editor.
> +
> +Lastly, send/submit your patch set to the Buildroot mailing list:
> +
> +---------------------
> + $ git send-email --to buildroot at busybox.net outgoing/*
> +---------------------
> +
> +Note that +git+ should be configured to use your mail account.
> +To configure +git+, see +man git-send-email+ or google it.
> +
> +Reviewing/Testing patches
> +-------------------------
> +
> +In the review process, do not hesitate to respond to patch submissions
> +for remarks, suggestions or anything that will help everyone to
> +understand the patches and make them better.
> +
> +Some tags are used to help following the state of any patch posted on
> +the mailing-list:
> +
> +Acked-by:: Indicates that the patch can be committed.
> +
> +Tested-by:: Indicates that the patch has been tested. It is useful
> + ?but not necessary to add a comment about what has been tested.
> diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
> index b23e9c1..3e7a7ef 100644
> --- a/docs/manual/manual.txt
> +++ b/docs/manual/manual.txt
> @@ -27,6 +27,8 @@ include::developer-guide.txt[]
>
> ?include::get-involved.txt[]
>
> +include::contribute.txt[]
> +
> ?include::legal-notice.txt[]
>
>
> --
> 1.7.10.2
>
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH v2 11/11] manual: add contribute.txt
2012-05-13 10:38 ` [Buildroot] [PATCH v2 11/11] manual: add contribute.txt Samuel Martin
2012-05-13 12:16 ` Yegor Yefremov
@ 2012-05-16 17:24 ` Thomas De Schampheleire
1 sibling, 0 replies; 53+ messages in thread
From: Thomas De Schampheleire @ 2012-05-16 17:24 UTC (permalink / raw)
To: buildroot
On Sun, May 13, 2012 at 12:38 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> From: Samuel MARTIN <s.martin49@gmail.com>
>
>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
>
> ?create mode 100644 docs/manual/contribute.txt
>
> diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
> new file mode 100644
> index 0000000..d80e79a
> --- /dev/null
> +++ b/docs/manual/contribute.txt
> @@ -0,0 +1,63 @@
> +Contibuting to Buildroot
> +========================
> +
> +If you want to contribute to Buildroot, you will need a git view of
> +the project. Refer to xref:getting-buildroot[] to get it.
> +
> +Currently, the mailing list is the central place for contribution.
> +If you have not already subscribe to it, then refer to
> +xref:mailing-list-subscribe[].
> +
> +Submiting patches
s/Submiting/Submitting/
> +-----------------
> +
> +When your changes are done, and commited in your local git view,
> +_rebase_ your development branch on top of the upstream tree before
> +generating the patch set. To do so, run:
> +
s/commited/committed/
> +---------------------
> + $ git fetch --all --tags
> + $ git rebase origin/master
> +---------------------
> +
> +Here, your are ready to generate then submit your patch set.
> +
> +To generate it, run:
> +
> +---------------------
> + $ git format-patch -M -n -s -o outgoing origin/master
> +---------------------
> +
> +This will generate patch files in the +outgoing+ subdirectory,
> +automatically adding the +signed-of-by+ line.
s/of/off/
> +
> +If you want to present the whole patch set in a separate mail, add
> ++--cover-letter --summary+ to the previous command line (+man
> +git-format-patch+ for further information).
> +
> +Once patch files are generated, you can review/edit the commit message
> +before submitting them using your favourite text editor.
s/favourite/favorite/
> +
> +Lastly, send/submit your patch set to the Buildroot mailing list:
> +
> +---------------------
> + $ git send-email --to buildroot at busybox.net outgoing/*
> +---------------------
> +
> +Note that +git+ should be configured to use your mail account.
> +To configure +git+, see +man git-send-email+ or google it.
> +
> +Reviewing/Testing patches
> +-------------------------
> +
> +In the review process, do not hesitate to respond to patch submissions
> +for remarks, suggestions or anything that will help everyone to
> +understand the patches and make them better.
> +
> +Some tags are used to help following the state of any patch posted on
> +the mailing-list:
> +
> +Acked-by:: Indicates that the patch can be committed.
> +
> +Tested-by:: Indicates that the patch has been tested. It is useful
> + ?but not necessary to add a comment about what has been tested.
> diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
> index b23e9c1..3e7a7ef 100644
> --- a/docs/manual/manual.txt
> +++ b/docs/manual/manual.txt
> @@ -27,6 +27,8 @@ include::developer-guide.txt[]
>
> ?include::get-involved.txt[]
>
> +include::contribute.txt[]
> +
> ?include::legal-notice.txt[]
>
>
> --
> 1.7.10.2
>
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH 00/11] RFC: Manual content reorganization
2012-03-20 23:09 [Buildroot] [PATCH 00/11] RFC: Manual content reorganization Samuel MARTIN
` (12 preceding siblings ...)
2012-04-15 10:56 ` Samuel Martin
@ 2012-08-01 20:43 ` Thomas Petazzoni
2012-08-05 14:59 ` Samuel Martin
2012-11-09 21:25 ` Arnout Vandecappelle
14 siblings, 1 reply; 53+ messages in thread
From: Thomas Petazzoni @ 2012-08-01 20:43 UTC (permalink / raw)
To: buildroot
Hello,
Le Wed, 21 Mar 2012 00:09:50 +0100,
Samuel MARTIN <s.martin49@gmail.com> a ?crit :
> This patch series aims to reorganize the manual content, as well as
> complete it... thought there are still lacks here and there after that ;-)
>
> This work intends to make the manual:
> - understable and clear for new comers, even if they are not familiar with
> embedded development;
> - useful for developers, contributors, even people that may want to redistribute
> third-party SDK/BSP based on Buildroot
> - as the entry point (anyone discovering/needing/using Buildroot should find
> its way out straight forward reading the manual)
Those are good objectives that I fully agree with.
> Although I am well aware that these are ambitious goals and this patch series
> does not acheive nor address all these points, at least, it is a starting point.
>
> Let's talk about the new organization.
>
> Overview of the new table of content:
> 1. About Buildroot
> 2. Starting up
> Think this chapter like a tutorial.
> Includes system requirements, how to get Buildroot and the first steps
> using it.
> 3. Working with Buildroot
> Intends to present basics to make Buildroot fitting your needs using
> the available customization knobs.
Is this where we would put details like what's the difference between
the three toolchain backends? Where we would explain how Buildroot
reacts when one removes package from menuconfig and runs 'make'?
> 4. Troubleshooting
What do you intend to put here? Our FAQ?
> 5. Going further in Buildroot's innards
> Explains some topics like about embedded development, cross-compilation,
> etc, and gives more advanced tips about Buildroot usages.
I am not sure it is a good idea to mix topics not directly related to
Buildroot (embedded development, cross-compilation) with recommendation
on using Buildroot itself.
For example, is this where you would recommend to use post-build
scripts instead of custom target skeleton? How to have a custom
additional device table?
I am not sure to see clearly where's the boundary between (3) and (5).
For example, in (3) you will probably want to explain the
different /dev management mechanism, which will lead you to explain
device table concepts and so on.
> 6. Developer Guidelines
> Intends to provide all relevant information for anyone wanting to hack in
> Buildroot.
> 7. Getting involved
> Provides all the way to keep informed about the Buildroot development.
> 8. Contibuting to Buildroot
> Gives tips about patch submission.
I am not sure to understand where's the boundary between 6, 7 and 8
here.
I think we also need to differentiate two developer levels maybe:
* The new developer, which generally needs a tutorial and reference on
how to add packages
* The hardcore developer, for which we will maybe want to provide
details about Buildroot internals (even though I'm not sure those
will ever be documented).
> 9. Legal notice
> Intends to give legal/license details about Buildroot itself, software
> used/built by Buildroot, how to redistribute SDK based on, etc.
> 10. Appendix
> BTW, over the last days, some other topics came out of my mind, but I have
> intentionally omitted them, letting their respective authors writing
> documentation about them. For example:
> - patches policy/howto, for which some great changes are on their way to be
> integrated;
Good point. Should be added to the "new package reference", that should
be more clearly defined above.
> - init system, maybe a paragraph about systemd (that is in the queue) and/or a
> comparative between the others available init systems could be added:
> - package's license explaination;
> - ... anything else i missed ;-)
>
>
> Right now, I'm not happy with everything I did.
> For example, now I use a deeper toc (4 title levels in this patch set vs. 3 on
> the current git master). This has a side effect on the html manual, indeed the
> toc only shows the first two level, this reduce the readability, IOW the fact
> that one can quickly find the relevant piece of information he/she is looking
> for.
>
> So, IOW, I'd like to know whether I'm on right path, the one the Buildroot
> community want to take.
I think it's a good strategy to first defined the organization of the
manual before diving into the implementation of such organization. I
would suggest to work on the Wiki page at
http://elinux.org/Buildroot:ManualOrganization. First by listing, in
random order and without any organization, the topics we think should
be discussed in the manual. And then, work on a proposed organization.
Most likely, it'll be similar to what you're proposing, but I think
that listing beforehand all the topics is a good idea.
Best regards,
Thomas
--
Thomas Petazzoni, Free Electrons
Kernel, drivers, real-time and embedded Linux
development, consulting, training and support.
http://free-electrons.com
^ permalink raw reply [flat|nested] 53+ messages in thread* [Buildroot] [PATCH 00/11] RFC: Manual content reorganization
2012-08-01 20:43 ` [Buildroot] [PATCH 00/11] RFC: Manual content reorganization Thomas Petazzoni
@ 2012-08-05 14:59 ` Samuel Martin
0 siblings, 0 replies; 53+ messages in thread
From: Samuel Martin @ 2012-08-05 14:59 UTC (permalink / raw)
To: buildroot
Hi Thomas, all,
2012/8/1 Thomas Petazzoni <thomas.petazzoni@free-electrons.com>:
> Hello,
>
> Le Wed, 21 Mar 2012 00:09:50 +0100,
> Samuel MARTIN <s.martin49@gmail.com> a ?crit :
>
>> This patch series aims to reorganize the manual content, as well as
>> complete it... thought there are still lacks here and there after that ;-)
>>
>> This work intends to make the manual:
>> - understable and clear for new comers, even if they are not familiar with
>> embedded development;
>> - useful for developers, contributors, even people that may want to redistribute
>> third-party SDK/BSP based on Buildroot
>> - as the entry point (anyone discovering/needing/using Buildroot should find
>> its way out straight forward reading the manual)
>
> Those are good objectives that I fully agree with.
>
>> Although I am well aware that these are ambitious goals and this patch series
>> does not acheive nor address all these points, at least, it is a starting point.
>>
>> Let's talk about the new organization.
>>
>> Overview of the new table of content:
>> 1. About Buildroot
>> 2. Starting up
>> Think this chapter like a tutorial.
>> Includes system requirements, how to get Buildroot and the first steps
>> using it.
>> 3. Working with Buildroot
>> Intends to present basics to make Buildroot fitting your needs using
>> the available customization knobs.
>
> Is this where we would put details like what's the difference between
> the three toolchain backends?
Yes.
> Where we would explain how Buildroot
> reacts when one removes package from menuconfig and runs 'make'?
Hum... not sure if this point is documented right now; but yes, I
think this is the place where I would add it.
>
>> 4. Troubleshooting
>
> What do you intend to put here? Our FAQ?
The FAQ has its place here.
>
>> 5. Going further in Buildroot's innards
>> Explains some topics like about embedded development, cross-compilation,
>> etc, and gives more advanced tips about Buildroot usages.
>
> I am not sure it is a good idea to mix topics not directly related to
> Buildroot (embedded development, cross-compilation) with recommendation
> on using Buildroot itself.
In fact, most of this section come from from the current introduction.
The truth is this chapter is part of what I'm not happy with. So, it
certainly need some more rework.
>
> For example, is this where you would recommend to use post-build
> scripts instead of custom target skeleton? How to have a custom
> additional device table?
Definitely yes.
>
> I am not sure to see clearly where's the boundary between (3) and (5).
> For example, in (3) you will probably want to explain the
> different /dev management mechanism, which will lead you to explain
> device table concepts and so on.
Having to write some code (*.mk, scripts, etc) is (more or less) the
boundary that lead me putting each section in chapter 3 or 5.
IOW, anything explained in chapter 3 should be available from the
menuconfig or is direct buildroot (make) invocation tips.
New comers should just have to read chapter 1 to 3 (maybe 4), and
after that they should be able to use buildroot, though some options,
like /dev management mechanism, may require some deeper knowledge or
understanding of what it is.
In such a case, I would add a section in chapter 5, or add a new chapter.
>
>> 6. Developer Guidelines
>> Intends to provide all relevant information for anyone wanting to hack in
>> Buildroot.
Anything you want to know to add new software in BR, to hack in a way
or another BR; whatever your will to push the patches upstream or not.
>> 7. Getting involved
>> Provides all the way to keep informed about the Buildroot development.
All places where BR is on the www, all places where you should look to
get information.
>> 8. Contibuting to Buildroot
>> Gives tips about patch submission.
How to push your patch upstream, making them available for all BR users.
Hope, this is clearer.
>
> I am not sure to understand where's the boundary between 6, 7 and 8
> here.
>
> I think we also need to differentiate two developer levels maybe:
>
> * The new developer, which generally needs a tutorial and reference on
> how to add packages
>
> * The hardcore developer, for which we will maybe want to provide
> details about Buildroot internals (even though I'm not sure those
> will ever be documented).
>
So, you would recommend to split chapter 6 in 2, one for new
developers, the other for "hardcore developer"?
I disagree with not documenting BR internals.
I've been following BR and hacking in it for 3 years now, and I still
discover features that are in BR for a while, but I've never noticed
or known (certainly because I haven't need them for far), the latest
one is the <pkg>_PERMISSIONS infrastructure!
>> 9. Legal notice
>> Intends to give legal/license details about Buildroot itself, software
>> used/built by Buildroot, how to redistribute SDK based on, etc.
>> 10. Appendix
>
>
>> BTW, over the last days, some other topics came out of my mind, but I have
>> intentionally omitted them, letting their respective authors writing
>> documentation about them. For example:
>> - patches policy/howto, for which some great changes are on their way to be
>> integrated;
>
> Good point. Should be added to the "new package reference", that should
> be more clearly defined above.
>
>> - init system, maybe a paragraph about systemd (that is in the queue) and/or a
>> comparative between the others available init systems could be added:
>> - package's license explaination;
>> - ... anything else i missed ;-)
- /dev management (as you suggest above :P)
>>
>>
>> Right now, I'm not happy with everything I did.
>> For example, now I use a deeper toc (4 title levels in this patch set vs. 3 on
>> the current git master). This has a side effect on the html manual, indeed the
>> toc only shows the first two level, this reduce the readability, IOW the fact
>> that one can quickly find the relevant piece of information he/she is looking
>> for.
>>
>> So, IOW, I'd like to know whether I'm on right path, the one the Buildroot
>> community want to take.
>
> I think it's a good strategy to first defined the organization of the
> manual before diving into the implementation of such organization. I
> would suggest to work on the Wiki page at
> http://elinux.org/Buildroot:ManualOrganization. First by listing, in
> random order and without any organization, the topics we think should
> be discussed in the manual. And then, work on a proposed organization.
> Most likely, it'll be similar to what you're proposing, but I think
> that listing beforehand all the topics is a good idea.
Definitely I agree.
This way, I'd really like to see more people involved in or touched by
this doc work.
So, to all:
Grab your keyboard and fill the documentation wish list!
If you are hanging around BR world for a long while, try to remember
what was missing in the doc when you started out;
or if you've just discovered BR, tell us what is disappointing for you
because of the lack of documentation.
Though I make this call using some humorous tone, I really mean it.
Some people have the knowledge, so don't really need the doc; some
others want to learn.
So, tell us what is missing, we'll fill the gaps.
Yours,
--
Sam
^ permalink raw reply [flat|nested] 53+ messages in thread
* [Buildroot] [PATCH 00/11] RFC: Manual content reorganization
2012-03-20 23:09 [Buildroot] [PATCH 00/11] RFC: Manual content reorganization Samuel MARTIN
` (13 preceding siblings ...)
2012-08-01 20:43 ` [Buildroot] [PATCH 00/11] RFC: Manual content reorganization Thomas Petazzoni
@ 2012-11-09 21:25 ` Arnout Vandecappelle
2012-11-09 22:45 ` Samuel Martin
14 siblings, 1 reply; 53+ messages in thread
From: Arnout Vandecappelle @ 2012-11-09 21:25 UTC (permalink / raw)
To: buildroot
On 03/21/12 00:09, Samuel MARTIN wrote:
> This patch series aims to reorganize the manual content, as well as
> complete it... thought there are still lacks here and there after that
Sam,
Do you think we could still get this into 2012.11?
Regards,
Arnout
--
Arnout Vandecappelle arnout at mind be
Senior Embedded Software Architect +32-16-286540
Essensium/Mind http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint: 7CB5 E4CC 6C2E EFD4 6E3D A754 F963 ECAB 2450 2F1F
^ permalink raw reply [flat|nested] 53+ messages in thread* [Buildroot] [PATCH 00/11] RFC: Manual content reorganization
2012-11-09 21:25 ` Arnout Vandecappelle
@ 2012-11-09 22:45 ` Samuel Martin
0 siblings, 0 replies; 53+ messages in thread
From: Samuel Martin @ 2012-11-09 22:45 UTC (permalink / raw)
To: buildroot
2012/11/9 Arnout Vandecappelle <arnout@mind.be>:
> On 03/21/12 00:09, Samuel MARTIN wrote:
>>
>> This patch series aims to reorganize the manual content, as well as
>> complete it... thought there are still lacks here and there after that
>
>
> Sam,
>
> Do you think we could still get this into 2012.11?
On it, and hope so! ;-)
I think I'll repost the updated and rebased version by sunday, or
early next week.
Regards,
--
Sam
^ permalink raw reply [flat|nested] 53+ messages in thread