* [Buildroot] [PATCH 01/23] dependencies.sh: remove makeinfo (texinfo) from the requirement list
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
@ 2012-11-11 13:14 ` Samuel Martin
2012-11-11 17:10 ` Thomas Petazzoni
2012-11-11 13:14 ` [Buildroot] [PATCH 02/23] manual: make clean target consistent with others in buildroot Samuel Martin
` (22 subsequent siblings)
23 siblings, 1 reply; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:14 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
diff --git a/support/dependencies/dependencies.sh b/support/dependencies/dependencies.sh
index 9f0f6a9..403ad75 100755
--- a/support/dependencies/dependencies.sh
+++ b/support/dependencies/dependencies.sh
@@ -131,12 +131,10 @@ if ! $SHELL --version 2>&1 | grep -q '^GNU bash'; then
fi;
# Check that a few mandatory programs are installed
-for prog in awk bison flex msgfmt makeinfo patch gzip bzip2 perl tar wget cpio python unzip rsync ${DL_TOOLS} ; do
+for prog in awk bison flex msgfmt patch gzip bzip2 perl tar wget cpio python unzip rsync ${DL_TOOLS} ; do
if ! which $prog > /dev/null ; then
/bin/echo -e "\nYou must install '$prog' on your build machine";
- if test $prog = "makeinfo" ; then
- /bin/echo -e "makeinfo is usually part of the texinfo package in your distribution\n"
- elif test $prog = "msgfmt" ; then
+ if test $prog = "msgfmt" ; then
/bin/echo -e "msgfmt is usually part of the gettext package in your distribution\n"
elif test $prog = "svn" ; then
/bin/echo -e "svn is usually part of the subversion package in your distribution\n"
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 01/23] dependencies.sh: remove makeinfo (texinfo) from the requirement list
2012-11-11 13:14 ` [Buildroot] [PATCH 01/23] dependencies.sh: remove makeinfo (texinfo) from the requirement list Samuel Martin
@ 2012-11-11 17:10 ` Thomas Petazzoni
2012-11-15 23:00 ` Peter Korsgaard
0 siblings, 1 reply; 34+ messages in thread
From: Thomas Petazzoni @ 2012-11-11 17:10 UTC (permalink / raw)
To: buildroot
Dear Samuel Martin,
On Sun, 11 Nov 2012 14:14:39 +0100, Samuel Martin wrote:
>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
Why do you think they are no longer necessary? IIRC, they are needed
for the build of binutils/gcc during the internal backend toolchain
build. But I admittedly haven't tested building with these recently.
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] 34+ messages in thread
* [Buildroot] [PATCH 01/23] dependencies.sh: remove makeinfo (texinfo) from the requirement list
2012-11-11 17:10 ` Thomas Petazzoni
@ 2012-11-15 23:00 ` Peter Korsgaard
0 siblings, 0 replies; 34+ messages in thread
From: Peter Korsgaard @ 2012-11-15 23:00 UTC (permalink / raw)
To: buildroot
>>>>> "Thomas" == Thomas Petazzoni <thomas.petazzoni@free-electrons.com> writes:
Thomas> Dear Samuel Martin,
Thomas> On Sun, 11 Nov 2012 14:14:39 +0100, Samuel Martin wrote:
>>
>> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
Thomas> Why do you think they are no longer necessary? IIRC, they are
Thomas> needed for the build of binutils/gcc during the internal
Thomas> backend toolchain build. But I admittedly haven't tested
Thomas> building with these recently.
Ok, I'll drop this patch for now as discussed on IRC.
--
Bye, Peter Korsgaard
^ permalink raw reply [flat|nested] 34+ messages in thread
* [Buildroot] [PATCH 02/23] manual: make clean target consistent with others in buildroot
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
2012-11-11 13:14 ` [Buildroot] [PATCH 01/23] dependencies.sh: remove makeinfo (texinfo) from the requirement list Samuel Martin
@ 2012-11-11 13:14 ` Samuel Martin
2012-11-11 22:57 ` Arnout Vandecappelle
2012-11-11 13:14 ` [Buildroot] [PATCH 03/23] manual: set toc depth to 4 for html outputs Samuel Martin
` (21 subsequent siblings)
23 siblings, 1 reply; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:14 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 1eaf73a..83d2fcb 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -38,10 +38,10 @@ $(call GENDOC_INNER,$(1),chunked,split-html,chunked,Split HTML)
$(call GENDOC_INNER,$(1),pdf,pdf,pdf,PDF,--dblatex-opts "-P latex.output.revhistory=0")
$(call GENDOC_INNER,$(1),text,txt,text,Text)
$(call GENDOC_INNER,$(1),epub,epub,epub,EPUB)
-clean: clean-$(1)
-clean-$(1):
+clean clean-$(1): $(1)-clean
+$(1)-clean:
$(Q)$(RM) -rf $(O)/docs/$(1)
-.PHONY: $(1) clean-$(1)
+.PHONY: $(1) $(1)-clean
endef
MANUAL_SOURCES = $(wildcard docs/manual/*.txt) $(wildcard docs/images/*)
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 02/23] manual: make clean target consistent with others in buildroot
2012-11-11 13:14 ` [Buildroot] [PATCH 02/23] manual: make clean target consistent with others in buildroot Samuel Martin
@ 2012-11-11 22:57 ` Arnout Vandecappelle
2012-11-11 23:34 ` Samuel Martin
0 siblings, 1 reply; 34+ messages in thread
From: Arnout Vandecappelle @ 2012-11-11 22:57 UTC (permalink / raw)
To: buildroot
On 11/11/12 14:14, Samuel Martin wrote:
> Signed-off-by: Samuel Martin<s.martin49@gmail.com>
>
> diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
> index 1eaf73a..83d2fcb 100644
> --- a/docs/manual/manual.mk
> +++ b/docs/manual/manual.mk
> @@ -38,10 +38,10 @@ $(call GENDOC_INNER,$(1),chunked,split-html,chunked,Split HTML)
> $(call GENDOC_INNER,$(1),pdf,pdf,pdf,PDF,--dblatex-opts "-P latex.output.revhistory=0")
> $(call GENDOC_INNER,$(1),text,txt,text,Text)
> $(call GENDOC_INNER,$(1),epub,epub,epub,EPUB)
> -clean: clean-$(1)
> -clean-$(1):
> +clean clean-$(1): $(1)-clean
I think you can safely remove clean-$(1) - or should we consider this API?
Regards,
Arnout
> +$(1)-clean:
> $(Q)$(RM) -rf $(O)/docs/$(1)
> -.PHONY: $(1) clean-$(1)
> +.PHONY: $(1) $(1)-clean
> endef
>
> MANUAL_SOURCES = $(wildcard docs/manual/*.txt) $(wildcard docs/images/*)
--
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] 34+ messages in thread
* [Buildroot] [PATCH 02/23] manual: make clean target consistent with others in buildroot
2012-11-11 22:57 ` Arnout Vandecappelle
@ 2012-11-11 23:34 ` Samuel Martin
2012-11-15 21:56 ` Peter Korsgaard
0 siblings, 1 reply; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 23:34 UTC (permalink / raw)
To: buildroot
2012/11/11 Arnout Vandecappelle <arnout@mind.be>:
> On 11/11/12 14:14, Samuel Martin wrote:
>>
>> Signed-off-by: Samuel Martin<s.martin49@gmail.com>
>>
>> diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
>> index 1eaf73a..83d2fcb 100644
>> --- a/docs/manual/manual.mk
>> +++ b/docs/manual/manual.mk
>> @@ -38,10 +38,10 @@ $(call
>> GENDOC_INNER,$(1),chunked,split-html,chunked,Split HTML)
>> $(call GENDOC_INNER,$(1),pdf,pdf,pdf,PDF,--dblatex-opts "-P
>> latex.output.revhistory=0")
>> $(call GENDOC_INNER,$(1),text,txt,text,Text)
>> $(call GENDOC_INNER,$(1),epub,epub,epub,EPUB)
>> -clean: clean-$(1)
>> -clean-$(1):
>> +clean clean-$(1): $(1)-clean
>
>
> I think you can safely remove clean-$(1) - or should we consider this API?
Actually, I kept it to, at least, not break the release.
IIRC, Peter generates the manual and includes it in the release tarball.
That's why I choose the safe path ;-) but I can remove it as soon as
Peter has confirmed it does not break anything.
Regards,
--
Sam
^ permalink raw reply [flat|nested] 34+ messages in thread
* [Buildroot] [PATCH 02/23] manual: make clean target consistent with others in buildroot
2012-11-11 23:34 ` Samuel Martin
@ 2012-11-15 21:56 ` Peter Korsgaard
2012-11-15 22:07 ` Samuel Martin
0 siblings, 1 reply; 34+ messages in thread
From: Peter Korsgaard @ 2012-11-15 21:56 UTC (permalink / raw)
To: buildroot
>>>>> "Samuel" == Samuel Martin <s.martin49@gmail.com> writes:
>> I think you can safely remove clean-$(1) - or should we consider this API?
Samuel> Actually, I kept it to, at least, not break the release. IIRC,
Samuel> Peter generates the manual and includes it in the release
Samuel> tarball. That's why I choose the safe path ;-) but I can
Samuel> remove it as soon as Peter has confirmed it does not break
Samuel> anything.
I just use 'make release' which doesn't use the clean target, so it can
get removed.
--
Bye, Peter Korsgaard
^ permalink raw reply [flat|nested] 34+ messages in thread
* [Buildroot] [PATCH 02/23] manual: make clean target consistent with others in buildroot
2012-11-15 21:56 ` Peter Korsgaard
@ 2012-11-15 22:07 ` Samuel Martin
0 siblings, 0 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-15 22:07 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 1eaf73a..fd9091e 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -38,10 +38,10 @@ $(call GENDOC_INNER,$(1),chunked,split-html,chunked,Split HTML)
$(call GENDOC_INNER,$(1),pdf,pdf,pdf,PDF,--dblatex-opts "-P latex.output.revhistory=0")
$(call GENDOC_INNER,$(1),text,txt,text,Text)
$(call GENDOC_INNER,$(1),epub,epub,epub,EPUB)
-clean: clean-$(1)
-clean-$(1):
+clean: $(1)-clean
+$(1)-clean:
$(Q)$(RM) -rf $(O)/docs/$(1)
-.PHONY: $(1) clean-$(1)
+.PHONY: $(1) $(1)-clean
endef
MANUAL_SOURCES = $(wildcard docs/manual/*.txt) $(wildcard docs/images/*)
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread
* [Buildroot] [PATCH 03/23] manual: set toc depth to 4 for html outputs
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
2012-11-11 13:14 ` [Buildroot] [PATCH 01/23] dependencies.sh: remove makeinfo (texinfo) from the requirement list Samuel Martin
2012-11-11 13:14 ` [Buildroot] [PATCH 02/23] manual: make clean target consistent with others in buildroot Samuel Martin
@ 2012-11-11 13:14 ` Samuel Martin
2012-11-11 13:14 ` [Buildroot] [PATCH 04/23] manual: rework the whole documentation stub Samuel Martin
` (20 subsequent siblings)
23 siblings, 0 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:14 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index 83d2fcb..0043ebf 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -33,8 +33,8 @@ endef
# The variable <DOCUMENT_NAME>_SOURCES defines the dependencies.
################################################################################
define GENDOC
-$(call GENDOC_INNER,$(1),xhtml,html,html,HTML)
-$(call GENDOC_INNER,$(1),chunked,split-html,chunked,Split HTML)
+$(call GENDOC_INNER,$(1),xhtml,html,html,HTML,--xsltproc-opts "--stringparam toc.section.depth 4")
+$(call GENDOC_INNER,$(1),chunked,split-html,chunked,Split HTML,--xsltproc-opts "--stringparam toc.section.depth 4")
$(call GENDOC_INNER,$(1),pdf,pdf,pdf,PDF,--dblatex-opts "-P latex.output.revhistory=0")
$(call GENDOC_INNER,$(1),text,txt,text,Text)
$(call GENDOC_INNER,$(1),epub,epub,epub,EPUB)
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 04/23] manual: rework the whole documentation stub
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
` (2 preceding siblings ...)
2012-11-11 13:14 ` [Buildroot] [PATCH 03/23] manual: set toc depth to 4 for html outputs Samuel Martin
@ 2012-11-11 13:14 ` Samuel Martin
2012-11-11 13:14 ` [Buildroot] [PATCH 05/23] manual: rework introduction.txt and add embedded-basics.txt Samuel Martin
` (19 subsequent siblings)
23 siblings, 0 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:14 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>
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/starting-up.txt
create mode 100644 docs/manual/working-with.txt
diff --git a/docs/manual/adding-packages-autotools.txt b/docs/manual/adding-packages-autotools.txt
index b85b7af..1184b69 100644
--- a/docs/manual/adding-packages-autotools.txt
+++ b/docs/manual/adding-packages-autotools.txt
@@ -1,10 +1,12 @@
+// -*- mode:doc; -*-
+
Infrastructure for autotools-based packages
--------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[[autotools-package-tutorial]]
+autotools-package+ tutorial
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
First, let's see how to write a +.mk+ file for an autotools-based
package, with an example :
@@ -64,7 +66,7 @@ package to be built.
[[autotools-package-reference]]
+autotools-package+ reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The main macro of the autotools package infrastructure is
+autotools-package+. It is similar to the +generic-package+ macro. The ability to
diff --git a/docs/manual/adding-packages-cmake.txt b/docs/manual/adding-packages-cmake.txt
index da4984a..81ac0a7 100644
--- a/docs/manual/adding-packages-cmake.txt
+++ b/docs/manual/adding-packages-cmake.txt
@@ -1,10 +1,12 @@
+// -*- mode:doc; -*-
+
Infrastructure for CMake-based packages
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[[cmake-package-tutorial]]
+cmake-package+ tutorial
-~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^
First, let's see how to write a +.mk+ file for a CMake-based package,
with an example :
@@ -63,7 +65,7 @@ package to be built.
[[cmake-package-reference]]
+cmake-package+ reference
-~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^
The main macro of the CMake package infrastructure is
+cmake-package+. It is similar to the +generic-package+ macro. The ability to
diff --git a/docs/manual/adding-packages-conclusion.txt b/docs/manual/adding-packages-conclusion.txt
index 3475827..ac20875 100644
--- a/docs/manual/adding-packages-conclusion.txt
+++ b/docs/manual/adding-packages-conclusion.txt
@@ -1,5 +1,7 @@
+// -*- mode:doc; -*-
+
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 4a96415..6030e08 100644
--- a/docs/manual/adding-packages-directory.txt
+++ b/docs/manual/adding-packages-directory.txt
@@ -1,5 +1,7 @@
+// -*- mode:doc; -*-
+
Package directory
------------------
+~~~~~~~~~~~~~~~~~
First of all, create a directory under the +package+ directory for
your software, for example +libfoo+.
@@ -10,7 +12,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 +148,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-generic.txt b/docs/manual/adding-packages-generic.txt
index 7ecdb91..e3f16c2 100644
--- a/docs/manual/adding-packages-generic.txt
+++ b/docs/manual/adding-packages-generic.txt
@@ -1,5 +1,7 @@
+// -*- mode:doc; -*-
+
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 +11,7 @@ system is based on hand-written Makefiles or shell scripts.
[[generic-package-tutorial]]
+generic-package+ Tutorial
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------
01: #############################################################
@@ -90,7 +92,7 @@ Makefile code necessary to make your package working.
[[generic-package-reference]]
+generic-package+ Reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are two variants of the generic target. The +generic-package+ macro is
used for packages to be cross-compiled for the target. The
diff --git a/docs/manual/adding-packages-gettext.txt b/docs/manual/adding-packages-gettext.txt
index e0df1a4..89461a7 100644
--- a/docs/manual/adding-packages-gettext.txt
+++ b/docs/manual/adding-packages-gettext.txt
@@ -1,5 +1,7 @@
+// -*- mode:doc; -*-
+
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.txt b/docs/manual/adding-packages.txt
index f672ec6..8221c85 100644
--- a/docs/manual/adding-packages.txt
+++ b/docs/manual/adding-packages.txt
@@ -1,6 +1,8 @@
-Adding new packages to Buildroot
-================================
+// -*- mode:doc -*- ;
+
[[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..cd53182
--- /dev/null
+++ b/docs/manual/advanced.txt
@@ -0,0 +1,12 @@
+// -*- mode:doc; -*-
+
+Advanced usage
+--------------
+
+include::using-buildroot-toolchain.txt[]
+
+include::external-toolchain.txt[]
+
+include::ccache-support.txt[]
+
+include::download-location.txt[]
diff --git a/docs/manual/appendix.txt b/docs/manual/appendix.txt
index f41c82c..a6642b5 100644
--- a/docs/manual/appendix.txt
+++ b/docs/manual/appendix.txt
@@ -1,3 +1,5 @@
+// -*- mode:doc; -*-
+
Appendix
========
diff --git a/docs/manual/board-support.txt b/docs/manual/board-support.txt
index d1d9d63..e20e721 100644
--- a/docs/manual/board-support.txt
+++ b/docs/manual/board-support.txt
@@ -1,5 +1,8 @@
+// -*- mode:doc -*- ;
+
+[[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..95cd662 100644
--- a/docs/manual/ccache-support.txt
+++ b/docs/manual/ccache-support.txt
@@ -1,5 +1,8 @@
+// -*- mode:doc -*- ;
+
+[[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..b343606
--- /dev/null
+++ b/docs/manual/common-usage.txt
@@ -0,0 +1,6 @@
+// -*- mode:doc; -*-
+
+Daily use
+---------
+
+include::rebuilding-packages.txt[]
diff --git a/docs/manual/customize-busybox-config.txt b/docs/manual/customize-busybox-config.txt
index 60e6a55..fe9cdda 100644
--- a/docs/manual/customize-busybox-config.txt
+++ b/docs/manual/customize-busybox-config.txt
@@ -1,6 +1,8 @@
-Customizing the Busybox configuration
--------------------------------------
+// -*- mode:doc -*- ;
+
[[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 +22,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..1072270 100644
--- a/docs/manual/customize-kernel-config.txt
+++ b/docs/manual/customize-kernel-config.txt
@@ -1,5 +1,8 @@
+// -*- mode:doc -*- ;
+
+[[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 44007c7..7ac5195 100644
--- a/docs/manual/customize-rootfs.txt
+++ b/docs/manual/customize-rootfs.txt
@@ -1,5 +1,8 @@
+// -*- mode:doc -*- ;
+
+[[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..91657cf 100644
--- a/docs/manual/customize-toolchain.txt
+++ b/docs/manual/customize-toolchain.txt
@@ -1,12 +1,14 @@
-Customizing the toolchain
--------------------------
+// -*- mode:doc -*- ;
+
[[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 +17,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 +34,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..88121ea 100644
--- a/docs/manual/customize-uclibc-config.txt
+++ b/docs/manual/customize-uclibc-config.txt
@@ -1,6 +1,8 @@
-Customizing the uClibc configuration
-------------------------------------
+// -*- mode:doc -*- ;
+
[[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..1e6f4e8 100644
--- a/docs/manual/customize.txt
+++ b/docs/manual/customize.txt
@@ -1,5 +1,7 @@
+// -*- mode:doc; -*-
+
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..37f703d
--- /dev/null
+++ b/docs/manual/developer-guide.txt
@@ -0,0 +1,8 @@
+// -*- mode:doc; -*-
+
+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..8c66a76 100644
--- a/docs/manual/download-location.txt
+++ b/docs/manual/download-location.txt
@@ -1,5 +1,7 @@
+// -*- mode:doc; -*-
+
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..b337376 100644
--- a/docs/manual/external-toolchain.txt
+++ b/docs/manual/external-toolchain.txt
@@ -1,6 +1,8 @@
-Using an external toolchain
-===========================
+// -*- mode:doc -*- ;
+
[[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..a51caa0 100644
--- a/docs/manual/getting.txt
+++ b/docs/manual/getting.txt
@@ -1,5 +1,8 @@
+// -*- mode:doc -*- ;
+
+[[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..879cff3 100644
--- a/docs/manual/how-buildroot-works.txt
+++ b/docs/manual/how-buildroot-works.txt
@@ -1,5 +1,7 @@
+// -*- mode:doc; -*-
+
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/makedev-syntax.txt b/docs/manual/makedev-syntax.txt
index 4728c4b..4703b2f 100644
--- a/docs/manual/makedev-syntax.txt
+++ b/docs/manual/makedev-syntax.txt
@@ -1,3 +1,5 @@
+// -*- mode:doc -*- ;
+
[[makedev-syntax]]
Makedev syntax documentation
----------------------------
diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
index de4b594..00bd037 100644
--- a/docs/manual/manual.txt
+++ b/docs/manual/manual.txt
@@ -1,3 +1,5 @@
+// -*- mode:doc; -*-
+
The Buildroot user manual
=========================
:toc:
@@ -11,25 +13,13 @@ image::logo.png[]
include::introduction.txt[]
-include::getting.txt[]
-
-include::using.txt[]
-
-include::customize.txt[]
-
-include::rebuilding-packages.txt[]
-
-include::how-buildroot-works.txt[]
-
-include::using-buildroot-toolchain.txt[]
-
-include::external-toolchain.txt[]
+include::starting-up.txt[]
-include::ccache-support.txt[]
+include::working-with.txt[]
-include::download-location.txt[]
+include::going-further.txt[]
-include::adding-packages.txt[]
+include::developer-guide.txt[]
include::faq.txt[]
diff --git a/docs/manual/rebuilding-packages.txt b/docs/manual/rebuilding-packages.txt
index fb6d696..824b35c 100644
--- a/docs/manual/rebuilding-packages.txt
+++ b/docs/manual/rebuilding-packages.txt
@@ -1,5 +1,7 @@
+// -*- mode:doc -*- ;
+
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..8ba16c9
--- /dev/null
+++ b/docs/manual/starting-up.txt
@@ -0,0 +1,9 @@
+// -*- mode:doc; -*-
+
+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..750fa99 100644
--- a/docs/manual/using-buildroot-toolchain.txt
+++ b/docs/manual/using-buildroot-toolchain.txt
@@ -1,5 +1,7 @@
+// -*- mode:doc; -*-
+
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 fcbd24b..5741473 100644
--- a/docs/manual/using.txt
+++ b/docs/manual/using.txt
@@ -1,8 +1,7 @@
-Using Buildroot
-===============
+// -*- mode:doc; -*-
-Configuration and general usage
--------------------------------
+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
diff --git a/docs/manual/working-with.txt b/docs/manual/working-with.txt
new file mode 100644
index 0000000..3c57504
--- /dev/null
+++ b/docs/manual/working-with.txt
@@ -0,0 +1,21 @@
+// -*- mode:doc; -*-
+
+Working with Buildroot
+======================
+
+This section explains how you can customize Buildroot to fit your
+needs.
+
+include::customize.txt[]
+
+include::common-usage.txt[]
+
+Hacking Buildroot
+-----------------
+
+If Buildroot does not yet fit all your requirements, you may be
+interested in hacking 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.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 05/23] manual: rework introduction.txt and add embedded-basics.txt
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
` (3 preceding siblings ...)
2012-11-11 13:14 ` [Buildroot] [PATCH 04/23] manual: rework the whole documentation stub Samuel Martin
@ 2012-11-11 13:14 ` Samuel Martin
2012-11-11 13:14 ` [Buildroot] [PATCH 06/23] manual: rework using.txt and update common-usage.txt Samuel Martin
` (18 subsequent siblings)
23 siblings, 0 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:14 UTC (permalink / raw)
To: buildroot
Split and rephrasing of introduction.txt.
Cross-toolchain 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..27dda37
--- /dev/null
+++ b/docs/manual/embedded-basics.txt
@@ -0,0 +1,110 @@
+// -*- mode:doc; -*-
+
+Embedded system basics
+----------------------
+
+When developing an embedded system, there are a number of choices to
+do:
+
+* the cross-toolchain: target architecture/C library/...
+* the bootloader
+* kernel options
+* the device management
+* the init system
+* the package selection (busybox vs. "real" programs, ...)
+* ...
+
+Some of them may be influenced by the target hardware.
+
+Some of them may also add some constraints when you will develop the
+final application for what your target is designed (e.g. some
+functions may be provided by soem C libraries and missing in some
+others, ...). So, these choices should be carefully done.
+
+Buildroot allows to set most of these options to fit your needs.
+
+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.
+
+[[cross-compilation-and-cross-toolchain]]
+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.
+
+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 offers a number of options and settings that can be tuned
+when defining the cross-toolchain (refer to xref:toolchain-custom[]).
+
+[[bootloader]]
+Bootloader
+~~~~~~~~~~
+
+TODO
+
+[[device-management]]
+Device management
+~~~~~~~~~~~~~~~~~
+
+TODO
+
+[[init-system]]
+Init system
+~~~~~~~~~~~
+
+TODO
diff --git a/docs/manual/going-further.txt b/docs/manual/going-further.txt
index 6f3cd6e..15324c4 100644
--- a/docs/manual/going-further.txt
+++ b/docs/manual/going-further.txt
@@ -1,6 +1,10 @@
+// -*- mode:doc; -*-
+
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..91ecb04 100644
--- a/docs/manual/introduction.txt
+++ b/docs/manual/introduction.txt
@@ -1,69 +1,21 @@
+// -*- mode:doc; -*-
+
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 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.
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.
-
-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.
+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.
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 06/23] manual: rework using.txt and update common-usage.txt
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
` (4 preceding siblings ...)
2012-11-11 13:14 ` [Buildroot] [PATCH 05/23] manual: rework introduction.txt and add embedded-basics.txt Samuel Martin
@ 2012-11-11 13:14 ` Samuel Martin
2012-11-11 13:14 ` [Buildroot] [PATCH 07/23] manual: customize-rootfs.txt: refactoring, misc. fixes and update Samuel Martin
` (17 subsequent siblings)
23 siblings, 0 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:14 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>
diff --git a/docs/manual/common-usage.txt b/docs/manual/common-usage.txt
index b343606..c08c10e 100644
--- a/docs/manual/common-usage.txt
+++ b/docs/manual/common-usage.txt
@@ -4,3 +4,98 @@ 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
+~~~~~~~~~~~~~~~~~~~~
+
+As default, everything built by Buildroot is stored in the directory
++output+ in the buildroot tree.
+
+Buildroot also 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.
+ +
+ Note that the uClibc configuration file can also be set from the
+ configuration interface, so through the Buildroot .config file; this
+ the actual recommended way of setting it.
+ +
+* +BUSYBOX_CONFIG_FILE=<path/to/.config>+, path to
+ the Busybox configuration file.
+ +
+ Note that the Busybox configuration file can also be set from the
+ configuration interface, so through the Buildroot .config file; this
+ the actual recommended way of setting it.
+ +
+* +BUILDROOT_DL_DIR+ to override the directory in which
+ Buildroot stores/retrieves downloaded files
+ +
+ Note that the Buildroot download directory can also be set from the
+ configuration interface, so through the Buildroot .config file; this
+ the actual recommended way of setting it.
+
+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 5741473..56ed23b 100644
--- a/docs/manual/using.txt
+++ b/docs/manual/using.txt
@@ -5,8 +5,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:
@@ -29,12 +29,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 favorite interface.
For each menu entry in the configuration tool, you can find associated
help that describes the purpose of the entry.
@@ -56,9 +55,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
+ appropriate toolchain backend is used, or simply import a toolchain
+ if an external toolchain
* Build/install selected target packages
* Build a kernel image, if selected
* Build a bootloader image, if selected
@@ -105,81 +104,12 @@ 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 usage are given in
+xref:make-tips[].
Complying with opensource licenses
----------------------------------
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 07/23] manual: customize-rootfs.txt: refactoring, misc. fixes and update
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
` (5 preceding siblings ...)
2012-11-11 13:14 ` [Buildroot] [PATCH 06/23] manual: rework using.txt and update common-usage.txt Samuel Martin
@ 2012-11-11 13:14 ` Samuel Martin
2012-11-11 13:14 ` [Buildroot] [PATCH 08/23] manual: update rebuilding-packages.txt Samuel Martin
` (16 subsequent siblings)
23 siblings, 0 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:14 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
diff --git a/docs/manual/customize-rootfs.txt b/docs/manual/customize-rootfs.txt
index 7ac5195..d6224ff 100644
--- a/docs/manual/customize-rootfs.txt
+++ b/docs/manual/customize-rootfs.txt
@@ -4,7 +4,8 @@
Customizing the generated target filesystem
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-There are a few ways to customize the resulting target filesystem:
+Besides changing one or another configuration through +make *config+,
+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
@@ -12,28 +13,33 @@ There are a few ways to customize the resulting target filesystem:
rebuild the target filesystem image. This method allows you to do
anything to the target filesystem, but if you decide to completely
rebuild your toolchain and tools, these changes will be lost.
+ _Changes are not resistent to the +make clean+ command_.
* Create your own 'target skeleton'. You can start with the default
skeleton available under +system/skeleton+ and then customize it to
suit your needs. The +BR2_ROOTFS_SKELETON_CUSTOM+ and
+BR2_ROOTFS_SKELETON_CUSTOM_PATH+ will allow you to specify the
- location of your custom skeleton. At build time, the contents of the
+ location of your custom skeleton. These options can be found in the
+ +System configuration+ menu. At build time, the contents of the
skeleton are copied to output/target before any package
installation.
* In the Buildroot configuration, you can specify the path to a
- post-build script, that gets called 'after' Buildroot builds all the
+ *post-build script*, that gets called 'after' Buildroot builds all the
selected software, but 'before' the rootfs packages are
- assembled. The destination root filesystem folder is given as the
- first argument to this script, and this script can then be used to
- copy programs, static data or any other needed file to your target
- filesystem. You should, however, use this feature with care.
- Whenever you find that a certain package generates wrong or unneeded
- files, you should fix that package rather than work around it with a
- post-build cleanup script.
+ assembled. The +BR2_ROOTFS_POST_BUILD_SCRIPT+ will allow you to
+ specify the location of your post-build script. This option can be
+ found in the +System configuration+ menu. The destination root
+ filesystem folder *is given as the first argument to this script,
+ and this script can then be used to copy programs, static data or
+ any other needed file to your target filesystem. You should,
+ however, use this feature with care. Whenever you find that a
+ certain package generates wrong or unneeded files, you should fix
+ that package rather than work around it with a post-build cleanup
+ script. _Among these first 3 methods, this one should be prefere_d.
* A special package, 'customize', stored in +package/customize+ can be
used. You can put all the files that you want to see in the final
target root filesystem in +package/customize/source+, and then
- enable this special package in the configuration system.
-
+ enable this special package in the configuration system. _This
+ method is marked as deprecated_.
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 08/23] manual: update rebuilding-packages.txt
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
` (6 preceding siblings ...)
2012-11-11 13:14 ` [Buildroot] [PATCH 07/23] manual: customize-rootfs.txt: refactoring, misc. fixes and update Samuel Martin
@ 2012-11-11 13:14 ` Samuel Martin
2012-11-11 13:14 ` [Buildroot] [PATCH 09/23] manual: adding-package-directory.txt: update, cleanup and typo fixes Samuel Martin
` (15 subsequent siblings)
23 siblings, 0 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:14 UTC (permalink / raw)
To: buildroot
- update "Understanding how to rebuild packages" section
- add "Understanding when a full rebuild is necessary" section
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
diff --git a/docs/manual/rebuilding-packages.txt b/docs/manual/rebuilding-packages.txt
index 824b35c..2225200 100644
--- a/docs/manual/rebuilding-packages.txt
+++ b/docs/manual/rebuilding-packages.txt
@@ -1,5 +1,39 @@
// -*- mode:doc -*- ;
+[[full-rebuild]]
+Understanding when a full rebuild is necessary
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A full rebuild is achieved by running:
+
+---------------
+$ make clean all
+---------------
+
+In what cases, a full rebuild is mandatory:
+
+* each time the toolchain properties are changed, this includes:
+
+** after changing some toolchain option under the _Toolchain_ menu (if
+ the internal Buildroot backend is used);
+** after running +make ctng-menuconfig+ (if the crosstool-NG backend
+ is used);
+** after running +make uclibc-menuconfig+.
+
+* after removing some libraries from the package selection.
+
+In what cases, a full rebuild is recommended:
+
+* after adding some libraries to the package selection (otherwise,
+ some packages that can be optionally linked against those libraries
+ won't be rebuilt, so they won't support those new available
+ features).
+
+In other cases, it is up to you to decide if you should or not run a
+full rebuild, but you should know what is impacted and understand what
+you are doing anyway.
+
+[[rebuild-pkg]]
Understanding how to rebuild packages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -42,27 +76,10 @@ files are relevant:
Buildroot will trigger the recompilation of the package from the
compilation step (execution of +make+).
-For other packages, an analysis of the specific 'package.mk' file is
-needed. For example, the zlib Makefile used to look like this (before
-it was converted to the generic package infrastructure):
-
------------------
-$(ZLIB_DIR)/.configured: $(ZLIB_DIR)/.patched
- (cd $(ZLIB_DIR); rm -rf config.cache; \
- [...]
- )
- touch $@
-
-$(ZLIB_DIR)/libz.a: $(ZLIB_DIR)/.configured
- $(MAKE) -C $(ZLIB_DIR) all libz.a
- touch -c $@
------------------
-
-If you want to trigger the reconfiguration, you need to remove
-+output/build/zlib-version/.configured+. If you want to trigger only
-the recompilation, you need to remove
-+output/build/zlib-version/libz.a+.
-
-Note that most packages, if not all, will progressively be ported over
-to the generic or autotools infrastructure, making it much easier to
-rebuild individual packages.
+.Notes
+- Since the _Buildroot-2012.11_ release, all packages rely on the
+Buildroot infrastructures.
+- Only toolchain packages remain using custom makefiles (i.e. do not
+use any Buildroot infrastructure).
+- Most packages and toolchain packages, if not all, will progressively
+be ported over to the generic, autotools or CMake infrastructure,
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 09/23] manual: adding-package-directory.txt: update, cleanup and typo fixes
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
` (7 preceding siblings ...)
2012-11-11 13:14 ` [Buildroot] [PATCH 08/23] manual: update rebuilding-packages.txt Samuel Martin
@ 2012-11-11 13:14 ` Samuel Martin
2012-11-11 13:14 ` [Buildroot] [PATCH 10/23] manual: add prerequisite.txt Samuel Martin
` (14 subsequent siblings)
23 siblings, 0 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:14 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
index 6030e08..35d28b6 100644
--- a/docs/manual/adding-packages-directory.txt
+++ b/docs/manual/adding-packages-directory.txt
@@ -49,6 +49,7 @@ supposed to contain anything but the 'bare' name of the package.
source "package/libfoo/Config.in"
--------------------------
+[[depends-on-vs-select]]
The +Config.in+ file of your package must also ensure that
dependencies are enabled. Typically, Buildroot uses the following
rules:
@@ -59,15 +60,26 @@ rules:
dependencies are selected. For example, the _libgtk2_ package uses
+select BR2_PACKAGE_LIBGLIB2+ to make sure this library is also
enabled.
+ The +select+ keyword express the dependency with a backward
+ semantic.
* Use a +depends on+ type of dependency when the user really needs to
be aware of the dependency. Typically, Buildroot uses this type of
- dependency for dependencies on toolchain options (large file
- support, RPC support, IPV6 support), or for dependencies on "big"
- things, such as the X.org system. In some cases, especially
- dependency on toolchain options, it is recommended to add a
- +comment+ displayed when the option is not enabled, so that the user
- knows why the package is not available.
+ dependency for dependencies on toolchain options (target
+ architecture, MMU support, C library, C++ support, large file
+ support, thread support, RPC support, IPV6 support, WCHAR support),
+ or for dependencies on "big" things, such as the X.org system. In
+ some cases, especially dependency on toolchain options, it is
+ recommended to add a +comment+ displayed when the option is not
+ enabled, so that the user knows why the package is not available.
+ The +depends on+ keyword express the dependency with a forward
+ semantic.
+
+.Note
+The current problem with the _kconfig_ language is that these two
+dependency semantics are not internally linked. Therefore, it may be
+possible to select a package, whom one of its dependencies/requirement
+is not met.
An example illustrates both the usage of +select+ and +depends on+.
@@ -147,6 +159,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
^^^^^^^^^^^^^^
@@ -182,8 +197,5 @@ different way, using different infrastructures:
CMake. We cover them through a xref:cmake-package-tutorial[tutorial]
and xref:cmake-package-reference[reference].
-* *Hand-written Makefiles:* These are currently obsolete, and no new
- manual Makefiles should be added. However, since there are still
- 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].
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 10/23] manual: add prerequisite.txt
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
` (8 preceding siblings ...)
2012-11-11 13:14 ` [Buildroot] [PATCH 09/23] manual: adding-package-directory.txt: update, cleanup and typo fixes Samuel Martin
@ 2012-11-11 13:14 ` Samuel Martin
2012-11-11 13:14 ` [Buildroot] [PATCH 11/23] manual: add make-tips.txt Samuel Martin
` (13 subsequent siblings)
23 siblings, 0 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:14 UTC (permalink / raw)
To: buildroot
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..b24731f
--- /dev/null
+++ b/docs/manual/prerequisite.txt
@@ -0,0 +1,84 @@
+// -*- mode:doc -*- ;
+
+[[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
+(package names may vary between 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:
+
+** +which+
+** +sed+
+** +make+ (version 3.82 or any later)
+** +binutils+
+** +build-essential+ (only for Debian based systems)
+** +gcc+ (version 2.95 or any later)
+** `g++` (version 2.95 or any later)
+** +bash+
+** +gawk+
+** +bison+
+** +flex+
+** +gettext+
+** +patch+
+** +gzip+
+** +bzip2+
+** +perl+
+** +tar+
+** +cpio+
+** +python+ (version 2.6 or 2.7)
+** +unzip+
+** +rsync+
+
+* Source fetching tools:
+** +wget+
+
+* Configuration interface dependencies (requires development libraries):
+** +ncurses5+
+
+[[requirement-optional]]
+
+Optional packages
+~~~~~~~~~~~~~~~~~
+
+* Source fetching tools:
++
+In the official tree, most of the package sources are retrieved
+using +wget+, few are only available through their +git+, +mercurial+,
+or +svn+ repository.
++
+All other source fetching methods are implemented and may be used in a
+development context.
++
+** +bazaar+
+** +cvs+
+** +git+
+** +mercurial+
+** +rsync+
+** +scp+
+** +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)
+
+* Documentation generation tools:
+** +asciidoc+
diff --git a/docs/manual/starting-up.txt b/docs/manual/starting-up.txt
index 8ba16c9..2999fd4 100644
--- a/docs/manual/starting-up.txt
+++ b/docs/manual/starting-up.txt
@@ -3,6 +3,8 @@
Starting up
===========
+include::prerequisite.txt[]
+
include::getting.txt[]
include::using.txt[]
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 11/23] manual: add make-tips.txt
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
` (9 preceding siblings ...)
2012-11-11 13:14 ` [Buildroot] [PATCH 10/23] manual: add prerequisite.txt Samuel Martin
@ 2012-11-11 13:14 ` Samuel Martin
2012-11-11 13:14 ` [Buildroot] [PATCH 12/23] manual: faq.txt: rework and update Samuel Martin
` (12 subsequent siblings)
23 siblings, 0 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:14 UTC (permalink / raw)
To: buildroot
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..5b00536
--- /dev/null
+++ b/docs/manual/make-tips.txt
@@ -0,0 +1,58 @@
+// -*- mode:doc -*- ;
+
+[[make-tips]]
+'make' tips
+-----------
+
+Because Buildroot is a set of Makefiles and patches, there are few
+things useful to know, such as:
+
++make *config+ commands offer a search tool. Read the help message in
+the different frontend menu to know how to use it:
+
+* in _menuconfig_, search tool is called by pressing +/+;
+* in _xconfig_, search tool is called by pressing +ctrl+ + +f+.
+
+The result of the search show the help message of the matching items.
+
+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:
+
+* +busybox-menuconfig+ depends on whether +busybox+ is enabled or not
+ in the +Package selection+ menu
+* +linux-menuconfig+ and +linux-savedefconfig+ depend 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+ depend 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 cache of compiler used by Buildroot. To delete it, refer
+to xref:ccache[].
diff --git a/docs/manual/working-with.txt b/docs/manual/working-with.txt
index 3c57504..4ea9239 100644
--- a/docs/manual/working-with.txt
+++ b/docs/manual/working-with.txt
@@ -6,6 +6,8 @@ Working with Buildroot
This section explains how you can customize Buildroot to fit your
needs.
+include::make-tips.txt[]
+
include::customize.txt[]
include::common-usage.txt[]
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 12/23] manual: faq.txt: rework and update
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
` (10 preceding siblings ...)
2012-11-11 13:14 ` [Buildroot] [PATCH 11/23] manual: add make-tips.txt Samuel Martin
@ 2012-11-11 13:14 ` Samuel Martin
2012-11-11 13:14 ` [Buildroot] [PATCH 13/23] manual: add writing-rules.txt Samuel Martin
` (11 subsequent siblings)
23 siblings, 0 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:14 UTC (permalink / raw)
To: buildroot
Also rename faq.txt -> faq-troubleshooting.txt
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
create mode 100644 docs/manual/faq-troubleshooting.txt
delete mode 100644 docs/manual/faq.txt
diff --git a/docs/manual/faq-troubleshooting.txt b/docs/manual/faq-troubleshooting.txt
new file mode 100644
index 0000000..6911c55
--- /dev/null
+++ b/docs/manual/faq-troubleshooting.txt
@@ -0,0 +1,134 @@
+// -*- mode:doc; -*-
+
+Frequently Asked Questions & Troubleshooting
+============================================
+
+[[faq-boot-hang-after-starting]]
+The boot hangs after 'Starting network...'
+------------------------------------------
+
+If the boot process seems to hand after the following messages
+(messages not necessarily exactly similar, depending on the list of
+packages selected):
+
+------------------------
+Freeing init memory: 3972K
+Initializing random number generator... done.
+Starting network...
+Starting dropbear sshd: generating rsa key... generating dsa key... OK
+------------------------
+
+then it means that your system is running, but didn't start a shell on
+the serial console. In order to have the system start a shell on your
+serial console, you have to go in the Buildroot configuration, +System
+configuration+, and modify +Port to run a getty (login prompt) on+ and
++Baudrate to use+ as appropriate. This will automatically tune the
++/etc/inittab+ file of the generated system so that a shell starts on
+the correct serial port.
+
+[[faq-module-init-tool-build-failure]]
+module-init-tools fails to build with 'cannot find -lc'
+-------------------------------------------------------
+
+If the build of +module-init-tools+ for the host fails with:
+
+------------------------
+/usr/bin/ld: cannot find -lc
+------------------------
+
+then probably you are running a Fedora (or similar) distribution, and
+you should install the +glibc-static+ package. This is because the
++module-init-tools+ build process wants to link statically against the
+C library.
+
+[[faq-no-compiler-on-target]]
+Why there is no compiler on the target?
+---------------------------------------
+
+It has been decided that the support of the _native compiler for the
+target_ would be stopped since the Buildroot-2012.11 release because:
+
+* this feature was not maintained nor tested and often broken;
+* this feature was only available for Buildroot toolchains;
+* Buildroot mostly targets _small_ or _very small_ target hardware
+ with limited resource onboard (CPU, ram, mass-storage), on which
+ compiling does not make much sense.
+
+If you need a compiler on your target anyway, then Buildroot is not
+suitable for your purpose. In such case, you need a _real
+distribution_ and you should for something like:
+
+* http://www.openembedded.org[openembedded]
+* https://www.yoctoproject.org[yocto]
+* http://www.emdebian.org[emdebian]
+* https://fedoraproject.org/wiki/Architectures[Fedora]
+* http://en.opensuse.org/Portal:ARM[openSUSE ARM]
+* http://archlinuxarm.org[Arch Linux ARM]
+* ...
+
+[[faq-no-dev-files-on-target]]
+Why there is no development files on the target?
+------------------------------------------------
+
+Since there is no compiler available on the target (see
+xref:faq-no-compiler-on-target[]), it does not make sense to waste
+space with headers or static libraries.
+
+Therefore, those files are always removed from the target since the
+Buildroot-2012.11 release.
+
+[[faq-no-doc-on-target]]
+Why there is no documentation on the target?
+--------------------------------------------
+
+Because Buildroot mostly targets _small_ or _very small_ target
+hardware with limited resource onboard (CPU, ram, mass-storage), it
+does not make sense to waste space with the documentation data.
+
+If you need documentation data on your target anyway, then Buildroot
+is not suitable for your purpose, and you should look for a _real
+distribution_ (see: xref:faq-no-compiler-on-target[]).
+
+[[faq-depends-on-vs-select]]
++Config.in+: _depends on_ vs _select_
+-------------------------------------
+
+When adding a new package to Buildroot, you will most likely have to
+deal with expressing the dependencies of this package.
+
+In the +Config.in+ file, dependencies may be expressed following two
+semantics.
+See xref:depends-on-vs-select[].
+
+[[faq-why-not-visible-package]]
+Why some packages are not visible in the Buildroot config menu?
+---------------------------------------------------------------
+
+If a package exists in the Buildroot tree and does not appears in the
+config menu, this most likely means that some of the package's
+dependencies are not met.
+
+To know more about the dependencies of a package, search the package
+symbol using in teh config menu (see xref:make-tips[]).
+
+Then, you may have to recursively enable several options (which
+correspond to the unmeet dependencies) to finally be able to select
+the package.
+
+If the package is not visible due to some unmeet toolchain options,
+then you should certainly run a full rebuild (see xref:make-tips[] for
+more explanations).
+
+[[faq-why-not-use-target-as-chroot]]
+Why not use the target directory as a chroot directory?
+-------------------------------------------------------
+
+There are plenty of reason to *not* use the target directory a chroot
+one, among these:
+
+* files' owners, modes and permissions are not correctly set in the
+ target directory;
+* devices nodes are not created in the target directory.
+
+Because of that, commands run in through chroot, using the target
+directory as new root, will fail.
diff --git a/docs/manual/faq.txt b/docs/manual/faq.txt
deleted file mode 100644
index 97a754b..0000000
--- a/docs/manual/faq.txt
+++ /dev/null
@@ -1,59 +0,0 @@
-Frequently Asked Questions
-==========================
-
-The boot hangs after 'Starting network...'
-------------------------------------------
-
-If the boot process seems to hand after the following messages
-(messages not necessarily exactly similar, depending on the list of
-packages selected):
-
-------------------------
-Freeing init memory: 3972K
-Initializing random number generator... done.
-Starting network...
-Starting dropbear sshd: generating rsa key... generating dsa key... OK
-------------------------
-
-then it means that your system is running, but didn't start a shell on
-the serial console. In order to have the system start a shell on your
-serial console, you have to go in the Buildroot configuration, +System
-configuration+, and modify +Port to run a getty (login prompt) on+ and
-+Baudrate to use+ as appropriate. This will automatically tune the
-+/etc/inittab+ file of the generated system so that a shell starts on
-the correct serial port.
-
-module-init-tools fails to build with 'cannot find -lc'
--------------------------------------------------------
-
-If the build of +module-init-tools+ for the host fails with:
-
-------------------------
-/usr/bin/ld: cannot find -lc
-------------------------
-
-then probably you are running a Fedora (or similar) distribution, and
-you should install the +glibc-static+ package. This is because the
-+module-init-tools+ build process wants to link statically against the
-C library.
-
-How to add package from github
-------------------------------
-
-If the package has no release version, or its version cannot be
-identified using tag, then the sha1 of the particular commit should be
-used to identify the version (the first 7 characters of the sha1 are
-enough):
-
-------------------------
-FOO_VERSION = 1234567
-FOO_SITE = http://github.com/<user>/<package>/tarball/<branch>
-------------------------
-
-If the package version matches a tag, then this tag should be used to
-identify the version:
-
-------------------------
-FOO_VERSION = v1.0
-FOO_SITE = http://github.com/<user>/<package>/tarball/$(FOO_VERSION)
-------------------------
diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
index 00bd037..4df1657 100644
--- a/docs/manual/manual.txt
+++ b/docs/manual/manual.txt
@@ -17,10 +17,10 @@ include::starting-up.txt[]
include::working-with.txt[]
+include::faq-troubleshooting.txt[]
+
include::going-further.txt[]
include::developer-guide.txt[]
-include::faq.txt[]
-
include::appendix.txt[]
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 13/23] manual: add writing-rules.txt
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
` (11 preceding siblings ...)
2012-11-11 13:14 ` [Buildroot] [PATCH 12/23] manual: faq.txt: rework and update Samuel Martin
@ 2012-11-11 13:14 ` Samuel Martin
2012-11-11 13:14 ` [Buildroot] [PATCH 14/23] manual: add get-involved.txt Samuel Martin
` (10 subsequent siblings)
23 siblings, 0 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:14 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
create mode 100644 docs/manual/writing-rules.txt
diff --git a/docs/manual/developer-guide.txt b/docs/manual/developer-guide.txt
index 37f703d..b254b0f 100644
--- a/docs/manual/developer-guide.txt
+++ b/docs/manual/developer-guide.txt
@@ -3,6 +3,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..e0a5a2a
--- /dev/null
+++ b/docs/manual/writing-rules.txt
@@ -0,0 +1,125 @@
+// -*- mode:doc; -*-
+
+Writing rules
+-------------
+
+Overall, those writing rules are here to help you add new files in
+Buildroot or refactor existing ones.
+
+If you slightly modify some existing file, the important thing is
+keeping the 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 entries for almost anything configurable in
+Buildroot.
+
+An 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.
+
+The configuration system used in Buildroot, so the content of the
++Config.in+ files, is regular _Kconfig_. Further details about
+_Kconfig_: refer to
+http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt[].
+
+[[writing-rules-mk]]
+
+The +.mk+ file
+~~~~~~~~~~~~~~
+
+* Assignment: use +=+ preceded 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 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/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.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 14/23] manual: add get-involved.txt
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
` (12 preceding siblings ...)
2012-11-11 13:14 ` [Buildroot] [PATCH 13/23] manual: add writing-rules.txt Samuel Martin
@ 2012-11-11 13:14 ` Samuel Martin
2012-11-11 13:14 ` [Buildroot] [PATCH 15/23] manual: add contribute.txt Samuel Martin
` (9 subsequent siblings)
23 siblings, 0 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:14 UTC (permalink / raw)
To: buildroot
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..566516b
--- /dev/null
+++ b/docs/manual/get-involved.txt
@@ -0,0 +1,98 @@
+// -*- mode:doc; -*-
+
+Getting involved
+================
+
+Like any open source project, 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 looking 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 IRC, share relevant logs or pieces of code
+using a code sharing website (see
+http://en.wikipedia.org/wiki/Comparison_of_pastebins[], and pick one).
+
+[[patchwork]]
+Patchwork
+---------
+
+The Buildroot patch management interface is at
+http://patchwork.buildroot.org[].
+
+All patches and comments sent through the mailing list are
+automatically indexed in http://patchwork.buildroot.org[patchwork].
+
+Bugtracker
+----------
+
+The Buildroot bugtracker is at https://bugs.busybox.net[].
+
+Buildroot wikipage
+------------------
+
+After the Buildroot developer day on 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_.
+
+[[events]]
+Events
+------
+
+Buildroot Developer Days aside ELC-E 2012 (November 3-4, 2012 - Barcelona)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Event page: http://elinux.org/Buildroot:DeveloperDaysELCE2012[]
+
+Buildroot presentation at LSM 2012 (July 12-14, 2012 - Geneva)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Announcement: http://lists.busybox.net/pipermail/buildroot/2012-May/053845.html[]
+
+Buildroot Developer Days aside FOSDEM 2012 (February 3, 2012 - Brussels)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Announcement & agenda thread: http://lists.busybox.net/pipermail/buildroot/2012-January/049340.html[]
+* Report: http://lists.busybox.net/pipermail/buildroot/2012-February/050371.html[]
diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
index 4df1657..3331cbf 100644
--- a/docs/manual/manual.txt
+++ b/docs/manual/manual.txt
@@ -23,4 +23,6 @@ include::going-further.txt[]
include::developer-guide.txt[]
+include::get-involved.txt[]
+
include::appendix.txt[]
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 15/23] manual: add contribute.txt
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
` (13 preceding siblings ...)
2012-11-11 13:14 ` [Buildroot] [PATCH 14/23] manual: add get-involved.txt Samuel Martin
@ 2012-11-11 13:14 ` Samuel Martin
2012-11-11 13:14 ` [Buildroot] [PATCH 16/23] manual: add package-make-target.txt Samuel Martin
` (8 subsequent siblings)
23 siblings, 0 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:14 UTC (permalink / raw)
To: buildroot
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..ddf790d
--- /dev/null
+++ b/docs/manual/contribute.txt
@@ -0,0 +1,126 @@
+// -*- mode:doc; -*-
+
+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 subscribed to it, then refer to
+xref:mailing-list-subscribe[].
+
+Recently, a web interface is also used to manage patches sent to the
+mailing list, see xref:patchwork[].
+
+[NOTE]
+_Please, do not attach patches to bugs, send them to the mailing list
+instead_ (see xref:submitting-patches[]).
+
+[[submitting-patches]]
+Submitting patches
+------------------
+
+When your changes are done, and committed 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, you 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-off-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 favorite 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.
+
+Make sure posted *patches are not line-wrapped*, otherwise it cannot
+easily be applied. In such a case, fix your e-mail client, or better,
+use +git send-email+ to send your patches.
+
+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.
+
+Autobuild
+---------
+
+The Buildroot community is currently setting up automatic build i
+order to test more and more configuration. All build results are
+available at http://autobuild.buildroot.org[]
+
+A way to contribute is fixing broken builds.
+
+In the commit message of a patch fixing an _autobuild_, add a
+reference to the _build result directory_ (the +dir+ link in the _data
+column_):
+
+---------------------
+Fixes http://autobuild.buildroot.org/results/51000a9d4656afe9e0ea6f07b9f8ed374c2e4069
+---------------------
+
+[[reporting-bugs]]
+Reporting issues/bugs, get help
+-------------------------------
+
+Before reporting some issues, please chek
+xref:mailing-list-subscribe[the mailing list archive] in case someone had
+already reported and fixed a similar problem.
+
+Whatever the way you choose to report some bugs or get help,
+xref:bugtracker[opening a bug] or
+xref:mailing-list-subscribe[send a mail to the mailing list], there is
+a number of detail to provide in order to help people reproduce and
+find a solution to the issue.
+
+Try to think as you would be the one who will help someone else; in
+that case, what would you need?
+
+Here is a short list of details to provide in such case:
+
+* host machine (OS/release)
+* version of Buildroot
+* target for which the build fails
+* package(s) which the build fails
+* the command that fails and its output
+* any information you think that may be relevant
+
+Additionnally, your can add the +.config+ file.
+
+If some of these details are too large, do not hesitate to use some
+pastebin service (see
+http://en.wikipedia.org/wiki/Comparison_of_pastebins[]).
diff --git a/docs/manual/get-involved.txt b/docs/manual/get-involved.txt
index 566516b..3a00b1e 100644
--- a/docs/manual/get-involved.txt
+++ b/docs/manual/get-involved.txt
@@ -61,11 +61,14 @@ http://patchwork.buildroot.org[].
All patches and comments sent through the mailing list are
automatically indexed in http://patchwork.buildroot.org[patchwork].
+[[bugtracker]]
Bugtracker
----------
The Buildroot bugtracker is at https://bugs.busybox.net[].
+To open a bug, see xref:reporting-bugs[].
+
Buildroot wikipage
------------------
diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
index 3331cbf..4032a6b 100644
--- a/docs/manual/manual.txt
+++ b/docs/manual/manual.txt
@@ -25,4 +25,6 @@ include::developer-guide.txt[]
include::get-involved.txt[]
+include::contribute.txt[]
+
include::appendix.txt[]
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 16/23] manual: add package-make-target.txt
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
` (14 preceding siblings ...)
2012-11-11 13:14 ` [Buildroot] [PATCH 15/23] manual: add contribute.txt Samuel Martin
@ 2012-11-11 13:14 ` Samuel Martin
2012-11-11 13:14 ` [Buildroot] [PATCH 17/23] manual: add download-infra.txt Samuel Martin
` (7 subsequent siblings)
23 siblings, 0 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:14 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
create mode 100644 docs/manual/package-make-target.txt
diff --git a/docs/manual/advanced.txt b/docs/manual/advanced.txt
index cd53182..ba6574c 100644
--- a/docs/manual/advanced.txt
+++ b/docs/manual/advanced.txt
@@ -10,3 +10,5 @@ include::external-toolchain.txt[]
include::ccache-support.txt[]
include::download-location.txt[]
+
+include::package-make-target.txt[]
diff --git a/docs/manual/package-make-target.txt b/docs/manual/package-make-target.txt
new file mode 100644
index 0000000..1813af3
--- /dev/null
+++ b/docs/manual/package-make-target.txt
@@ -0,0 +1,88 @@
+// -*- mode:doc; -*-
+
+[[pkg-build-steps]]
+
+Package make targets
+~~~~~~~~~~~~~~~~~~~~
+
+A +make <package>+ call achieves several _make targets_ with, as a
+result, this particular package and its dependencies built, installed
+in their destination directory (target, staging or host directory).
+
+For packages based on the Buildroot infrastructures (+generic-package+,
++autotools-package+ or +cmake-package+), each of those
+actions/steps/commands. For packages relying on other build system,
+then there is no other choice than looking at the +.mk+ file (see also
+the xref:rebuild-pkg[]).
+
+For packages relying on the Buildroot infrastructures, there are
+numerous special make targets that can be called independently like
+this:
+
+------------
+make <package>-<target>
+------------
+
+In order, the package build commands are:
+
+[width="90%",cols="^1,4",options="header"]
+|===================================================
+| command/target | Description
+
+| +source+ | Fetch the source (download the tarball, clone
+the source repository, etc)
+
+| +depends+ | Build and install all dependencies required to
+build the package
+
+| +extract+ | Put the source in the package build directory
+(extract the tarball, copy the source, etc)
+
+| +patch+ | Apply the patches if any
+
+| +configure+ | Run the configure command
+
+| +build+ | Compile the source
+
+| +install-staging+ |
+*target package:* Run the installation of the package in the
+staging directory
+
+*host package:* Does nothing
+
+| +install-target+ |
+*target package:* Run the installation of the package in the
+staging directory
+
+*host package:* Does nothing
+
+| +install+ |
+*target package:* Run the 2 previous installation commands for the
+target packages
+
+*host package:* Run the installation of the package in the host
+directory
+
+|===================================================
+
+Additionally, there are some other useful make targets:
+
+[width="90%",cols="^1,4",options="header"]
+|===================================================
+| command/target | Description
+
+| +show-depends+ | Displays the dependencies required to build the
+package
+
+| +clean+ | Clean the package build directory, also
+uninstall the package from both the target and the staging directory
+
+| +dirclean+ | Remove the whole package build directory
+
+| +rebuild+ | Rebuild only necessary binaries and install them
+again
+
+| +reconfigure+ | Run again the configure command, then rebuild
+only necessary binaries, and lastly install them again
+
+|===================================================
diff --git a/docs/manual/rebuilding-packages.txt b/docs/manual/rebuilding-packages.txt
index 2225200..a723d11 100644
--- a/docs/manual/rebuilding-packages.txt
+++ b/docs/manual/rebuilding-packages.txt
@@ -83,3 +83,7 @@ Buildroot infrastructures.
use any Buildroot infrastructure).
- Most packages and toolchain packages, if not all, will progressively
be ported over to the generic, autotools or CMake infrastructure,
+making it much easier to rebuild individual packages.
+
+Further details about package special make target at the
+xref:pkg-build-steps[].
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 17/23] manual: add download-infra.txt
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
` (15 preceding siblings ...)
2012-11-11 13:14 ` [Buildroot] [PATCH 16/23] manual: add package-make-target.txt Samuel Martin
@ 2012-11-11 13:14 ` Samuel Martin
2012-11-11 13:14 ` [Buildroot] [PATCH 18/23] manual: add patch-policy.txt Samuel Martin
` (6 subsequent siblings)
23 siblings, 0 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:14 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
create mode 100644 docs/manual/download-infra.txt
diff --git a/docs/manual/developer-guide.txt b/docs/manual/developer-guide.txt
index b254b0f..f3fc1dd 100644
--- a/docs/manual/developer-guide.txt
+++ b/docs/manual/developer-guide.txt
@@ -7,4 +7,6 @@ include::writing-rules.txt[]
include::adding-packages.txt[]
+include::download-infra.txt[]
+
include::board-support.txt[]
diff --git a/docs/manual/download-infra.txt b/docs/manual/download-infra.txt
new file mode 100644
index 0000000..63908ad
--- /dev/null
+++ b/docs/manual/download-infra.txt
@@ -0,0 +1,8 @@
+// -*- mode:doc -*- ;
+
+[[download-infra]]
+
+Download infrastructure
+-----------------------
+
+TODO
diff --git a/docs/manual/prerequisite.txt b/docs/manual/prerequisite.txt
index b24731f..693347b 100644
--- a/docs/manual/prerequisite.txt
+++ b/docs/manual/prerequisite.txt
@@ -61,7 +61,7 @@ using +wget+, few are only available through their +git+, +mercurial+,
or +svn+ repository.
+
All other source fetching methods are implemented and may be used in a
-development context.
+development context (further details: refer to xref:download-infra[]).
+
** +bazaar+
** +cvs+
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 18/23] manual: add patch-policy.txt
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
` (16 preceding siblings ...)
2012-11-11 13:14 ` [Buildroot] [PATCH 17/23] manual: add download-infra.txt Samuel Martin
@ 2012-11-11 13:14 ` Samuel Martin
2012-11-11 13:14 ` [Buildroot] [PATCH 19/23] manual: add adding-package-tips.txt Samuel Martin
` (5 subsequent siblings)
23 siblings, 0 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:14 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
create mode 100644 docs/manual/patch-policy.txt
diff --git a/docs/manual/developer-guide.txt b/docs/manual/developer-guide.txt
index f3fc1dd..5002897 100644
--- a/docs/manual/developer-guide.txt
+++ b/docs/manual/developer-guide.txt
@@ -7,6 +7,8 @@ include::writing-rules.txt[]
include::adding-packages.txt[]
+include::patch-policy.txt[]
+
include::download-infra.txt[]
include::board-support.txt[]
diff --git a/docs/manual/patch-policy.txt b/docs/manual/patch-policy.txt
new file mode 100644
index 0000000..551ea12
--- /dev/null
+++ b/docs/manual/patch-policy.txt
@@ -0,0 +1,128 @@
+// -*- mode:doc; -*-
+
+[[patch-policy]]
+
+Patch Policy
+------------
+
+While integrating a new package or updating an existing one, it may be
+necessary to patch the source of the software to get it built within
+Buildroot.
+
+Buildroot offers an infrastructure to automatically handle this during
+the builds. It support several ways of applying patch sets:
+
+Provinding patches
+~~~~~~~~~~~~~~~~~~
+
+Additionnal tarball
+^^^^^^^^^^^^^^^^^^^
+
+If there needs to apply a patch set available as a tarball and
+downloadable, then add the patch tarball to the +<packagename>_PATCH+
+variable.
+
+Note that the patch tarballs are downloaded from the same site as the
+sources.
+
+Within Buildroot
+^^^^^^^^^^^^^^^^
+
+Most of the patches are provided within Buildroot, in the package
+directory, because they aim to fix cross-compilation, +libc+ support,
+or whatever the reason is.
+
+These patch files should have the extension +*.patch+.
+
+A +series+ file, like +quilt+ uses it, may also be added in the
+package directory. In that case, the +series+ file defines the patch
+application order.
+
+How patches are applied
+~~~~~~~~~~~~~~~~~~~~~~~
+
+. Run the +<packagename>_PRE_PATCH_HOOKS+ commands if defined;
+
+. Cleanup the build directory from any existing +*.rej+ files;
+
+. If +<packagename>_PATCH+ is defined, then patches from these
+ tarballs are applied;
+
+. If there are some +*.patch+ files in the package directory or in the
+ a package subdirectory named +<packagename>-<packageversion>+, then:
++
+* If a +series+ file exists in the package directory, then patches are
+ applied according to the +series+ file;
++
+* Otherwise, patch files matching `<packagename>-*.patch` or
+ `<packagename>-*.patch.<arch>` (where +<arch>+ is the architecture
+ name) are applied following the +ls+ command order.
+
+. Run the +<packagename>_POST_PATCH_HOOKS+ commands if defined.
+
+If something goes wrong in the steps _3_ or _4_, then the build fails.
+
+Format and licensing of the package patches
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Patches are released under the same license the software that is
+modified.
+
+A message explaining what does the patch and why should be add in the
+patch's header.
+
+You should add a +signed-off-by+ statement in the header of the each
+patch to help keeping track of the changes.
+
+If the software is under versionning, it is recommended to use the SCM
+software to generate the patch set.
+
+Otherwise, concatenate the header with the output of the
++diff -purN source.c.orig source.c+ command.
+
+At the end, the patch should look like:
+
+---------------
+configure.ac: add C++ support test
+
+signed-off-by John Doe <john.doe@noname.org>
+
+--- configure.ac.orig
++++ configure.ac
+@@ -40,2 +40,12 @@
+
+AC_PROG_MAKE_SET
++
++AC_CACHE_CHECK([whether the C++ compiler works],
++ [rw_cv_prog_cxx_works],
++ [AC_LANG_PUSH([C++])
++ AC_LINK_IFELSE([AC_LANG_PROGRAM([], [])],
++ [rw_cv_prog_cxx_works=yes],
++ [rw_cv_prog_cxx_works=no])
++ AC_LANG_POP([C++])])
++
++AM_CONDITIONAL([CXX_WORKS], [test "x$rw_cv_prog_cxx_works" = "xyes"])
+---------------
+
+Integrating patches found on the Web
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When integrating a patch whom you are not the author, you have to add
+few things in the header of the patch itself.
+
+Depending on whether the patch has been pick-up from the project
+repository itself, or from somewhere on the web, add one of the
+following tags:
+
+---------------
+Backported from: <some commit id>
+---------------
+
+or
+
+---------------
+Fetch from: <some url>
+---------------
+
+It is also possible to add few words about the changes that may have
+been necessary if any.
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 19/23] manual: add adding-package-tips.txt
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
` (17 preceding siblings ...)
2012-11-11 13:14 ` [Buildroot] [PATCH 18/23] manual: add patch-policy.txt Samuel Martin
@ 2012-11-11 13:14 ` Samuel Martin
2012-11-11 13:14 ` [Buildroot] [PATCH 20/23] manual: add legal-info.txt Samuel Martin
` (4 subsequent siblings)
23 siblings, 0 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:14 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
create mode 100644 docs/manual/adding-packages-tips.txt
diff --git a/docs/manual/adding-packages-tips.txt b/docs/manual/adding-packages-tips.txt
new file mode 100644
index 0000000..acc73d3
--- /dev/null
+++ b/docs/manual/adding-packages-tips.txt
@@ -0,0 +1,54 @@
+// -*- mode:doc; -*-
+
+Tips and tricks
+~~~~~~~~~~~~~~~
+
+[[package-name-variable-relation]]
+Package name, config entry name and makefile variable relationship
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In Buildroot, there are some relation between:
+
+* the _package name_, which is the package directory name (and the
+ name of the +*.mk+ file);
+
+* the config entry name that is declared in the +Config.in+ file;
+
+* the makefile variable prefix.
+
+Thus, it is mandatory to keep consistency between all this stuff,
+matching the following rules:
+
+* the _make_ target name will be the _package name_ itself (e.g.:
+ +foo-bar_boo+);
+
+* the config entry is the upper case _package name_ with `.` and `-`
+ characters substituted with `_`, prefixed with +BR2_PACKAGE_+ (e.g.:
+ +BR2_PACKAGE_FOO_BAR_BOO+);
+
+* the +*.mk+ file variable prefix is the upper case _package name_
+ `.` and `-` characters substituted with `_` (e.g.:
+ +FOO_BAR_BOO_VERSION+).
+
+
+[[github-download-url]]
+How to add package from github
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the package has no release version, or its version cannot be
+identified using tag, then the sha1 of the particular commit should be
+used to identify the version (the first 7 characters of the sha1 are
+enough):
+
+------------------------
+FOO_VERSION = 1234567
+FOO_SITE = http://github.com/<user>/<package>/tarball/<branch>
+------------------------
+
+If the package version matches a tag, then this tag should be used to
+identify the version:
+
+------------------------
+FOO_VERSION = v1.0
+FOO_SITE = http://github.com/<user>/<package>/tarball/$(FOO_VERSION)
+------------------------
diff --git a/docs/manual/adding-packages.txt b/docs/manual/adding-packages.txt
index 8221c85..b909d47 100644
--- a/docs/manual/adding-packages.txt
+++ b/docs/manual/adding-packages.txt
@@ -19,4 +19,6 @@ include::adding-packages-cmake.txt[]
include::adding-packages-gettext.txt[]
+include::adding-packages-tips.txt[]
+
include::adding-packages-conclusion.txt[]
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 20/23] manual: add legal-info.txt
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
` (18 preceding siblings ...)
2012-11-11 13:14 ` [Buildroot] [PATCH 19/23] manual: add adding-package-tips.txt Samuel Martin
@ 2012-11-11 13:14 ` Samuel Martin
2012-11-11 13:14 ` [Buildroot] [PATCH 21/23] manual: add pkg-list.txt (generated list of available packages) Samuel Martin
` (3 subsequent siblings)
23 siblings, 0 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:14 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
create mode 100644 docs/manual/legal-notice.txt
diff --git a/docs/manual/adding-packages-generic.txt b/docs/manual/adding-packages-generic.txt
index e3f16c2..b05043a 100644
--- a/docs/manual/adding-packages-generic.txt
+++ b/docs/manual/adding-packages-generic.txt
@@ -22,33 +22,35 @@ system is based on hand-written Makefiles or shell scripts.
06: LIBFOO_VERSION = 1.0
07: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
08: LIBFOO_SITE = http://www.foosoftware.org/download
-09: LIBFOO_INSTALL_STAGING = YES
-10: LIBFOO_DEPENDENCIES = host-libaaa libbbb
-11:
-12: define LIBFOO_BUILD_CMDS
-13: $(MAKE) CC="$(TARGET_CC)" LD="$(TARGET_LD)" -C $(@D) all
-14: endef
-15:
-16: define LIBFOO_INSTALL_STAGING_CMDS
-17: $(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a
-18: $(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h
-19: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib
-20: endef
-21:
-22: define LIBFOO_INSTALL_TARGET_CMDS
-23: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib
-24: $(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
-25: endef
-26:
-27: define LIBFOO_DEVICES
-28: /dev/foo c 666 0 0 42 0 - - -
-29: endef
-30:
-31: define LIBFOO_PERMISSIONS
-32: /bin/foo f 4755 0 0 - - - - -
-33: endef
-34:
-35: $(eval $(generic-package))
+09: LIBFOO_LICENSE = GPLv3+
+10: LIBFOO_LICENSE_FILES = COPYING
+11: LIBFOO_INSTALL_STAGING = YES
+12: LIBFOO_DEPENDENCIES = host-libaaa libbbb
+13:
+14: define LIBFOO_BUILD_CMDS
+15: $(MAKE) CC="$(TARGET_CC)" LD="$(TARGET_LD)" -C $(@D) all
+16: endef
+17:
+18: define LIBFOO_INSTALL_STAGING_CMDS
+19: $(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a
+20: $(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h
+21: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib
+22: endef
+23:
+24: define LIBFOO_INSTALL_TARGET_CMDS
+25: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib
+26: $(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
+27: endef
+28:
+29: define LIBFOO_DEVICES
+30: /dev/foo c 666 0 0 42 0 - - -
+31: endef
+32:
+33: define LIBFOO_PERMISSIONS
+34: /bin/foo f 4755 0 0 - - - - -
+35: endef
+36:
+37: $(eval $(generic-package))
--------------------------------
The Makefile begins on line 6 to 8 with metadata information: the
@@ -245,7 +247,7 @@ information is (assuming the package name is +libfoo+) :
* +LIBFOO_LICENSE+ defines the license (or licenses) under which the package
is released.
This name will appear in the manifest file produced by +make legal-info+.
- If the license is one of those listed in xref:legal-info[],
+ If the license appears in xref:legal-info-list-licenses[the following list],
use the same string to make the manifest file uniform.
Otherwise, describe the license in a precise and concise way, avoiding
ambiguous names such as +BSD+ which actually name a family of licenses.
diff --git a/docs/manual/legal-notice.txt b/docs/manual/legal-notice.txt
new file mode 100644
index 0000000..22e5769
--- /dev/null
+++ b/docs/manual/legal-notice.txt
@@ -0,0 +1,136 @@
+// -*- mode:doc; -*-
+
+[[legal-info]]
+
+Legal notice and licensing
+==========================
+
+Complying with opensource licenses
+----------------------------------
+
+All of the end products of Buildroot (toolchain, root filesystem, kernel,
+bootloaders) contain opensource software, released under various licenses.
+
+Using opensource software gives you the freedom to build rich embedded
+systems choosing from a wide range of packages, but also gives some
+obligations that you must know and honour.
+Some licenses require you to publish the license text in the documentation of
+your product. Other require you to redistribute the source code of the
+software to those that receive your product.
+
+The exact requirements of each license is documented in each package, and it is
+your (or your legal office's) responsibility to comply with these requirements.
+To make this easier for you, Buildroot can collect for you some material you
+will probably need. To produce this material, after you configured Buildroot
+with +make menuconfig+, +make xconfig+ or +make gconfig+, run:
+
+--------------------
+make legal-info
+--------------------
+
+Buildroot will collect legally-relevant material in your output directory,
+under the +legal-info/+ subdirectory.
+There you will find:
+
+* A +README+ file, that summarizes the produced material and contains warnings
+ about material that Buildroot could not produce.
+* +buildroot.config+: this is the Buildroot configuration file that is usually
+ produced with +make menuconfig+, and which is necessary to reproduce the
+ build.
+* The source code for all packages; this is saved in the +sources/+
+ subdirectory (except for proprietary packages, whose source code is not
+ saved);
+ patches applied to some packages by Buildroot are distributed with the
+ Buildroot sources and are not duplicated in the +sources/+ subdirectory.
+* A manifest file listing the configured packages, their version, license and
+ related information.
+ Some of these information might be not defined in Buildroot; in this case
+ they are clearly marked as "unknown" or similar.
+* A +licenses/+ subdirectory, which contains the license text of packages.
+ If the license file(s) are not defined in Buildroot, the file is not produced
+ and a warning in the +README+ indicates this.
+
+Please note that the aim of the +legal-info+ feature of Buildroot is to
+produce all the material that is somehow relevant for legal compliance with the
+package licenses. Buildroot does not try to produce the exact material that
+you must somehow make public. It does surely produce some more material than is
+needed for a strict legal compliance. For example, it produces the source code
+for packages released under BSD-like licenses, that you might not want to
+redistribute in source form.
+
+Moreover, due to technical limitations, Buildroot does not produce some
+material that you will or may need, such as the toolchain source code and the
+Buildroot source code itself.
+When you run +make legal-info+, Buildroot produces warnings in the +README+
+file to inform you of relevant material that could not be saved.
+
+[[legal-info-list-licenses]]
+Here is a list of the licenses that are most widely used by packages in
+Buildroot, with the name used in the manifest file:
+
+* +GPLv2+:
+ http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[
+ GNU General Public License, version 2];
+* +GPLv2++:
+ http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[
+ GNU General Public License, version 2]
+ or (at your option) any later version;
+* +GPLv3+:
+ http://www.gnu.org/licenses/gpl.html[
+ GNU General Public License, version 3];
+* +GPLv3++:
+ http://www.gnu.org/licenses/gpl.html[
+ GNU General Public License, version 3]
+ or (at your option) any later version;
+* +GPL+:
+ http://www.gnu.org/licenses/gpl.html[
+ GNU General Public License] (any version);
+* +LGPLv2.1+:
+ http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html[
+ GNU Lesser General Public License, version 2.1];
+* +LGPLv2.1++:
+ http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html[
+ GNU Lesser General Public License, version 2.1]
+ or (at your option) any later version;
+* +LGPLv3+:
+ http://www.gnu.org/licenses/lgpl.html[
+ GNU Lesser General Public License, version 3];
+* +LGPLv3++:
+ http://www.gnu.org/licenses/lgpl.html[
+ GNU Lesser General Public License, version 3]
+ or (at your option) any later version;
+* +LGPL+:
+ http://www.gnu.org/licenses/lgpl.html[
+ GNU Lesser General Public License] (any version);
+* +BSD-4c+: Original BSD 4-clause license;
+* +BSD-3c+: BSD 3-clause license;
+* +BSD-2c+: BSD 2-clause license;
+* +PROPRIETARY+: marks a non-opensource package;
+ Buildroot does not save any licensing info or source code for these packages.
+
+Complying with the Buildroot license
+------------------------------------
+
+Buildroot itself is an opensource software, released under the
+http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[GNU General Public
+License, version 2] or (at your option) any later version.
+However, being a build system, it is not normally part of the end product:
+if you develop the root filesystem, kernel, bootloader or toolchain for a
+device, the code of Buildroot is only present on the development machine, not
+in the device storage.
+
+Nevertheless, the general view of the Buildroot developers is that you should
+release the Buildroot source code along with the source code of other packages
+when releasing a product that contains GPL-licensed software.
+This is because the
+http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[GNU GPL]
+defines the "'complete source code'" for an executable work as "'all the
+source code for all modules it contains, plus any associated interface
+definition files, plus the scripts used to control compilation and installation
+of the executable'".
+Buildroot is part of the 'scripts used to control compilation and
+installation of the executable', and as such it is considered part of the
+material that must be redistributed.
+
+Keep in mind this is only the Buildroot developers' opinion, and you should
+consult your legal department or lawyer in case of any doubt.
diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
index 4032a6b..a1ee68a 100644
--- a/docs/manual/manual.txt
+++ b/docs/manual/manual.txt
@@ -23,6 +23,8 @@ include::going-further.txt[]
include::developer-guide.txt[]
+include::legal-notice.txt[]
+
include::get-involved.txt[]
include::contribute.txt[]
diff --git a/docs/manual/using.txt b/docs/manual/using.txt
index 56ed23b..e8136f8 100644
--- a/docs/manual/using.txt
+++ b/docs/manual/using.txt
@@ -110,133 +110,3 @@ your needs, with all the supports and applications you enabled.
More details about the "make" command usage are given in
xref:make-tips[].
-
-Complying with opensource licenses
-----------------------------------
-[[legal-info]]
-
-All of the end products of Buildroot (toolchain, root filesystem, kernel,
-bootloaders) contain opensource software, released under various licenses.
-
-Using opensource software gives you the freedom to build rich embedded
-systems choosing from a wide range of packages, but also gives some
-obligations that you must know and honour.
-Some licenses require you to publish the license text in the documentation of
-your product. Other require you to redistribute the source code of the
-software to those that receive your product.
-
-The exact requirements of each license is documented in each package, and it is
-your (or your legal office's) responsibility to comply with these requirements.
-To make this easier for you, Buildroot can collect for you some material you
-will probably need. To produce this material, after you configured Buildroot
-with +make menuconfig+, +make xconfig+ or +make gconfig+, run:
-
---------------------
-make legal-info
---------------------
-
-Buildroot will collect legally-relevant material in your output directory,
-under the +legal-info/+ subdirectory.
-There you will find:
-
-* A +README+ file, that summarizes the produced material and contains warnings
- about material that Buildroot could not produce.
-* +buildroot.config+: this is the Buildroot configuration file that is usually
- produced with +make menuconfig+, and which is necessary to reproduce the
- build.
-* The source code for all packages; this is saved in the +sources/+
- subdirectory (except for proprietary packages, whose source code is not
- saved);
- patches applied to some packages by Buildroot are distributed with the
- Buildroot sources and are not duplicated in the +sources/+ subdirectory.
-* A manifest file listing the configured packages, their version, license and
- related information.
- Some of these information might be not defined in Buildroot; in this case
- they are clearly marked as "unknown" or similar.
-* A +licenses/+ subdirectory, which contains the license text of packages.
- If the license file(s) are not defined in Buildroot, the file is not produced
- and a warning in the +README+ indicates this.
-
-Please note that the aim of the +legal-info+ feature of Buildroot is to
-produce all the material that is somehow relevant for legal compliance with the
-package licenses. Buildroot does not try to produce the exact material that
-you must somehow make public. It does surely produce some more material than is
-needed for a strict legal compliance. For example, it produces the source code
-for packages released under BSD-like licenses, that you might not want to
-redistribute in source form.
-
-Moreover, due to technical limitations, Buildroot does not produce some
-material that you will or may need, such as the toolchain source code and the
-Buildroot source code itself.
-When you run +make legal-info+, Buildroot produces warnings in the +README+
-file to inform you of relevant material that could not be saved.
-
-Here is a list of the licenses that are most widely used by packages in
-Buildroot, with the name used in the manifest file:
-
-* +GPLv2+:
- http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[
- GNU General Public License, version 2];
-* +GPLv2++:
- http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[
- GNU General Public License, version 2]
- or (at your option) any later version;
-* +GPLv3+:
- http://www.gnu.org/licenses/gpl.html[
- GNU General Public License, version 3];
-* +GPLv3++:
- http://www.gnu.org/licenses/gpl.html[
- GNU General Public License, version 3]
- or (at your option) any later version;
-* +GPL+:
- http://www.gnu.org/licenses/gpl.html[
- GNU General Public License] (any version);
-* +LGPLv2.1+:
- http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html[
- GNU Lesser General Public License, version 2.1];
-* +LGPLv2.1++:
- http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html[
- GNU Lesser General Public License, version 2.1]
- or (at your option) any later version;
-* +LGPLv3+:
- http://www.gnu.org/licenses/lgpl.html[
- GNU Lesser General Public License, version 3];
-* +LGPLv3++:
- http://www.gnu.org/licenses/lgpl.html[
- GNU Lesser General Public License, version 3]
- or (at your option) any later version;
-* +LGPL+:
- http://www.gnu.org/licenses/lgpl.html[
- GNU Lesser General Public License] (any version);
-* +BSD-4c+: Original BSD 4-clause license;
-* +BSD-3c+: BSD 3-clause license;
-* +BSD-2c+: BSD 2-clause license;
-* +PROPRIETARY+: marks a non-opensource package;
- Buildroot does not save any licensing info or source code for these packages.
-
-Complying with the Buildroot license
-------------------------------------
-
-Buildroot itself is an opensource software, released under the
-http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[GNU General Public
-License, version 2] or (at your option) any later version.
-However, being a build system, it is not normally part of the end product:
-if you develop the root filesystem, kernel, bootloader or toolchain for a
-device, the code of Buildroot is only present on the development machine, not
-in the device storage.
-
-Nevertheless, the general view of the Buildroot developers is that you should
-release the Buildroot source code along with the source code of other packages
-when releasing a product that contains GPL-licensed software.
-This is because the
-http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[GNU GPL]
-defines the "'complete source code'" for an executable work as "'all the
-source code for all modules it contains, plus any associated interface
-definition files, plus the scripts used to control compilation and installation
-of the executable'".
-Buildroot is part of the 'scripts used to control compilation and
-installation of the executable', and as such it is considered part of the
-material that must be redistributed.
-
-Keep in mind this is only the Buildroot developers' opinion, and you should
-consult your legal department or lawyer in case of any doubt.
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 21/23] manual: add pkg-list.txt (generated list of available packages)
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
` (19 preceding siblings ...)
2012-11-11 13:14 ` [Buildroot] [PATCH 20/23] manual: add legal-info.txt Samuel Martin
@ 2012-11-11 13:14 ` Samuel Martin
2012-11-11 23:11 ` Arnout Vandecappelle
2012-11-11 13:15 ` [Buildroot] [PATCH 22/23] manual: add deprecated-list.txt Samuel Martin
` (2 subsequent siblings)
23 siblings, 1 reply; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:14 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
create mode 100644 docs/manual/pkg-list.txt
diff --git a/docs/manual/appendix.txt b/docs/manual/appendix.txt
index a6642b5..6f1e9f3 100644
--- a/docs/manual/appendix.txt
+++ b/docs/manual/appendix.txt
@@ -4,3 +4,16 @@ Appendix
========
include::makedev-syntax.txt[]
+
+[[package-list]]
+Available packages
+------------------
+// docs/manaual/pkg-list.txt is generated using the following command:
+// $ git grep -E '\((autotools|cmake|generic)-package\)' package/ | \
+// cut -d':' -f1 | grep '\.mk$' | \
+// sed -e 's;.*\?/\(.*\?\).mk;* \1;' | \
+// sort > docs/manual/pkg-list.txt
+
+include::pkg-list.txt[]
+
+include::deprecated-list.txt[]
diff --git a/docs/manual/pkg-list.txt b/docs/manual/pkg-list.txt
new file mode 100644
index 0000000..5d9b54f
--- /dev/null
+++ b/docs/manual/pkg-list.txt
@@ -0,0 +1,870 @@
+* acl
+* acpid
+* alsa-lib
+* alsamixergui
+* alsa-utils
+* apr
+* apr-util
+* argp-standalone
+* argus
+* arptables
+* at
+* atk
+* attr
+* audiofile
+* aumix
+* autoconf
+* automake
+* avahi
+* axel
+* bash
+* beecrypt
+* bellagio
+* berkeleydb
+* bind
+* binutils
+* bison
+* blackbox
+* bluez_utils
+* bmon
+* boa
+* bonnie
+* boost
+* bootutils
+* bridge-utils
+* bsdiff
+* busybox
+* bwm-ng
+* bzip2
+* cairo
+* can-utils
+* ccache
+* ccid
+* cdrkit
+* cgilua
+* cifs-utils
+* cjson
+* cloop
+* cmake
+* collectd
+* connman
+* conntrack-tools
+* copas
+* coreutils
+* coxpcall
+* cpanminus
+* cpuload
+* cramfs
+* ctorrent
+* cups
+* cvs
+* dash
+* dbus
+* dbus-glib
+* dbus-python
+* devmem2
+* dhcp
+* dhcpdump
+* dhrystone
+* dialog
+* diffutils
+* directfb
+* directfb-examples
+* distcc
+* divine
+* dmalloc
+* dmidecode
+* dmraid
+* dnsmasq
+* docker
+* doom-wad
+* dosfstools
+* dropbear
+* dsp-tools
+* dstat
+* e2fsprogs
+* ebtables
+* ed
+* eeprog
+* empty
+* enchant
+* erlang
+* ethtool
+* evtest
+* expat
+* expedite
+* explorercanvas
+* ezxml
+* faad2
+* fbdump
+* fbgrab
+* fbset
+* fbterm
+* fb-test-app
+* fbv
+* fconfig
+* feh
+* ffmpeg
+* fftw
+* file
+* findutils
+* fis
+* flac
+* flashrom
+* flex
+* flot
+* fltk
+* fluxbox
+* fmtools
+* fontconfig
+* freerdp
+* freetype
+* fxload
+* gadgetfs-test
+* gamin
+* gawk
+* gdbm
+* gdisk
+* gdk-pixbuf
+* genext2fs
+* genromfs
+* gettext
+* giblib
+* glib-networking
+* gmp
+* gmpc
+* gnuchess
+* gnupg
+* gnutls
+* gob2
+* googlefontdirectory
+* gperf
+* gpsd
+* gqview
+* grantlee
+* grep
+* gsl
+* gst-dsp
+* gst-ffmpeg
+* gst-omapfb
+* gst-plugins-bad
+* gst-plugins-base
+* gst-plugins-good
+* gst-plugins-ugly
+* gstreamer
+* gtk2-engines
+* gtk2-theme-hicolor
+* gtkperf
+* gvfs
+* gzip
+* haserl
+* hdparm
+* heirloom-mailx
+* hiawatha
+* hostapd
+* htop
+* hwdata
+* i2c-tools
+* icu
+* ifplugd
+* igh-ethercat
+* imagemagick
+* imlib2
+* inadyn
+* inotify-tools
+* input-event-daemon
+* input-tools
+* intltool
+* iostat
+* iperf
+* ipkg
+* iproute2
+* ipsec-tools
+* ipset
+* iptables
+* irda-utils
+* iw
+* jpeg
+* jquery
+* jquery-sparkline
+* jquery-validation
+* jsmin
+* json-c
+* kbd
+* kexec
+* kismet
+* kmod
+* lame
+* latencytop
+* lcdapi
+* lcdproc
+* leafpad
+* less
+* libaio
+* libao
+* libarchive
+* libargtable2
+* libart
+* libatomic_ops
+* libcap
+* libcap-ng
+* libcdaudio
+* libcgi
+* libcgicc
+* libconfig
+* libconfuse
+* libcue
+* libcuefile
+* libcurl
+* libdaemon
+* libdmtx
+* libdnet
+* libdrm
+* libdvdnav
+* libdvdread
+* libecore
+* libedbus
+* libedje
+* libeet
+* libefreet
+* libeina
+* libelementary
+* libelf
+* libembryo
+* liberation
+* libesmtp
+* libethumb
+* libev
+* libevas
+* libevent
+* libexif
+* libeXosip2
+* libfcgi
+* libffi
+* libfreefare
+* libftdi
+* libfuse
+* libgail
+* libgcrypt
+* libgeotiff
+* libglade
+* libglib2
+* libgpg-error
+* libgtk2
+* libhid
+* libical
+* libiconv
+* libid3tag
+* libidn
+* libiqrf
+* liblo
+* liblockfile
+* liblog4c-localtime
+* libmad
+* libmbus
+* libmicrohttpd
+* libmms
+* libmnl
+* libmodbus
+* libmpd
+* libmpeg2
+* libnetfilter-acct
+* libnetfilter-conntrack
+* libnetfilter-cthelper
+* libnetfilter-cttimeout
+* libnetfilter-log
+* libnetfilter-queue
+* libnfc
+* libnfc-llcp
+* libnfnetlink
+* libnl
+* libnspr
+* libnss
+* liboauth
+* libogg
+* liboping
+* libosip2
+* libpcap
+* libplayer
+* libpng
+* libraw
+* libraw1394
+* libreplaygain
+* libroxml
+* librsvg
+* librsync
+* libsamplerate
+* libsexy
+* libsigc
+* libsndfile
+* libsoup
+* libsvgtiny
+* libsysfs
+* libtheora
+* libtirpc
+* libtool
+* libtorrent
+* libtpl
+* libungif
+* libupnp
+* liburcu
+* libusb
+* libusb-compat
+* libv4l
+* libvncserver
+* libvorbis
+* libxcb
+* libxml2
+* libxml-parser-perl
+* libxslt
+* libyaml
+* lighttpd
+* links
+* linphone
+* linux-firmware
+* linux-fusion
+* linux-pam
+* lite
+* live555
+* lmbench
+* lm-sensors
+* lockfile-progs
+* logrotate
+* logsurfer
+* lrzsz
+* lshw
+* lsof
+* lsuio
+* ltp-testsuite
+* ltrace
+* lttng-babeltrace
+* lttng-libust
+* lttng-modules
+* lttng-tools
+* lua
+* luacjson
+* luaexpat
+* luafilesystem
+* luajit
+* luasocket
+* lvm2
+* lzma
+* lzo
+* lzop
+* m4
+* macchanger
+* madplay
+* make
+* makedevs
+* matchbox-common
+* matchbox-desktop
+* matchbox-fakekey
+* matchbox-keyboard
+* matchbox-lib
+* matchbox-panel
+* matchbox-startup-monitor
+* matchbox-wm
+* mcookie
+* mdadm
+* mediastreamer
+* memstat
+* memtester
+* mesa3d
+* metacity
+* microperl
+* midori
+* mii-diag
+* minicom
+* mobile_broadband_provider_info
+* module-init-tools
+* monit
+* mpc
+* mpd
+* mpfr
+* mpg123
+* mplayer
+* mrouted
+* msmtp
+* mtd
+* mtdev
+* mtdev2tuio
+* musepack
+* mutt
+* mxml
+* mysql_client
+* nano
+* nanocom
+* nasm
+* nbd
+* ncftp
+* ncurses
+* ndisc6
+* neon
+* netatalk
+* netcat
+* netkitbase
+* netkittelnet
+* netperf
+* netplug
+* netsnmp
+* netstat-nat
+* network-manager
+* newt
+* nfacct
+* nfs-utils
+* ngircd
+* ngrep
+* noip
+* nss-mdns
+* ntfs-3g
+* ntp
+* nuttcp
+* ocf-linux
+* ofono
+* olsr
+* open2300
+* opencv
+* openntpd
+* openocd
+* openssh
+* openssl
+* openswan
+* openvpn
+* opkg
+* oprofile
+* opus
+* opus-tools
+* orc
+* ortp
+* owl-linux
+* pango
+* parted
+* patch
+* pciutils
+* pcmanfm
+* pcre
+* pcsc-lite
+* perl
+* php
+* picocom
+* pixman
+* pkgconf
+* pkg-config
+* poco
+* polarssl
+* popt
+* portaudio
+* portmap
+* pppd
+* pptp-linux
+* prboom
+* procps
+* proftpd
+* protobuf
+* psmisc
+* pthread-stubs
+* pulseaudio
+* pv
+* python
+* python3
+* python-dpkt
+* python-id3
+* python-mad
+* python-meld3
+* python-netifaces
+* python-nfc
+* python-protobuf
+* python-pygame
+* python-serial
+* python-setuptools
+* qextserialport
+* qt
+* qtuio
+* quagga
+* quota
+* radvd
+* ramspeed
+* rdesktop
+* read-edid
+* readline
+* rings
+* rng-tools
+* rpcbind
+* rpm
+* rp-pppoe
+* rrdtool
+* rsh-redone
+* rsync
+* rsyslog
+* rtai
+* rtorrent
+* rt-tests
+* rubix
+* ruby
+* samba
+* sane-backends
+* sawman
+* schifra
+* sconeserver
+* screen
+* sdl
+* sdl_gfx
+* sdl_image
+* sdl_mixer
+* sdl_net
+* sdl_sound
+* sdl_ttf
+* sdparm
+* sed
+* ser2net
+* setserial
+* shared-mime-info
+* slang
+* smartmontools
+* socat
+* socketcand
+* sound-theme-borealis
+* sound-theme-freedesktop
+* spawn-fcgi
+* speex
+* sqlcipher
+* sqlite
+* squashfs
+* squashfs3
+* squid
+* sredird
+* sshfs
+* sstrip
+* startup-notification
+* statserial
+* strace
+* stress
+* stunnel
+* sudo
+* supervisor
+* sylpheed
+* synergy
+* sysklogd
+* sysprof
+* sysstat
+* systemd
+* sysvinit
+* taglib
+* tar
+* tcl
+* tcpdump
+* tcpreplay
+* tftpd
+* thttpd
+* tidsp-binaries
+* tiff
+* time
+* tinyhttpd
+* ti-utils
+* tn5250
+* torsmo
+* transmission
+* tremor
+* tslib
+* ttcp
+* uboot-tools
+* udev
+* udpcast
+* uemacs
+* ulogd
+* unionfs
+* usb_modeswitch
+* usb_modeswitch_data
+* usbmount
+* usbutils
+* ushare
+* util-linux
+* vala
+* valgrind
+* vim
+* vorbis-tools
+* vpnc
+* vsftpd
+* vtun
+* wavpack
+* webkit
+* webrtc-audio-processing
+* wget
+* whetstone
+* which
+* wipe
+* wireless_tools
+* wpa_supplicant
+* wsapi
+* x11vnc
+* xapp_appres
+* xapp_bdftopcf
+* xapp_beforelight
+* xapp_bitmap
+* xapp_editres
+* xapp_fonttosfnt
+* xapp_fslsfonts
+* xapp_fstobdf
+* xapp_iceauth
+* xapp_ico
+* xapp_listres
+* xapp_luit
+* xapp_mkfontdir
+* xapp_mkfontscale
+* xapp_oclock
+* xapp_rgb
+* xapp_rstart
+* xapp_scripts
+* xapp_sessreg
+* xapp_setxkbmap
+* xapp_showfont
+* xapp_smproxy
+* xapp_twm
+* xapp_viewres
+* xapp_x11perf
+* xapp_xauth
+* xapp_xbacklight
+* xapp_xbiff
+* xapp_xcalc
+* xapp_xclipboard
+* xapp_xclock
+* xapp_xcmsdb
+* xapp_xcursorgen
+* xapp_xdbedizzy
+* xapp_xditview
+* xapp_xdm
+* xapp_xdpyinfo
+* xapp_xdriinfo
+* xapp_xedit
+* xapp_xev
+* xapp_xeyes
+* xapp_xf86dga
+* xapp_xfd
+* xapp_xfontsel
+* xapp_xfs
+* xapp_xfsinfo
+* xapp_xgamma
+* xapp_xgc
+* xapp_xhost
+* xapp_xinit
+* xapp_xinput
+* xapp_xinput-calibrator
+* xapp_xkbcomp
+* xapp_xkbevd
+* xapp_xkbprint
+* xapp_xkbutils
+* xapp_xkill
+* xapp_xload
+* xapp_xlogo
+* xapp_xlsatoms
+* xapp_xlsclients
+* xapp_xlsfonts
+* xapp_xmag
+* xapp_xman
+* xapp_xmessage
+* xapp_xmh
+* xapp_xmodmap
+* xapp_xmore
+* xapp_xplsprinters
+* xapp_xpr
+* xapp_xprehashprinterlist
+* xapp_xprop
+* xapp_xrandr
+* xapp_xrdb
+* xapp_xrefresh
+* xapp_xset
+* xapp_xsetmode
+* xapp_xsetpointer
+* xapp_xsetroot
+* xapp_xsm
+* xapp_xstdcmap
+* xapp_xvidtune
+* xapp_xvinfo
+* xapp_xwd
+* xapp_xwininfo
+* xapp_xwud
+* xavante
+* xcb-proto
+* xcb-util
+* xdata_xbitmaps
+* xdata_xcursor-themes
+* xdriver_xf86-input-acecad
+* xdriver_xf86-input-aiptek
+* xdriver_xf86-input-evdev
+* xdriver_xf86-input-joystick
+* xdriver_xf86-input-keyboard
+* xdriver_xf86-input-mouse
+* xdriver_xf86-input-synaptics
+* xdriver_xf86-input-tslib
+* xdriver_xf86-input-vmmouse
+* xdriver_xf86-input-void
+* xdriver_xf86-video-apm
+* xdriver_xf86-video-ark
+* xdriver_xf86-video-ast
+* xdriver_xf86-video-ati
+* xdriver_xf86-video-chips
+* xdriver_xf86-video-cirrus
+* xdriver_xf86-video-dummy
+* xdriver_xf86-video-fbdev
+* xdriver_xf86-video-geode
+* xdriver_xf86-video-glide
+* xdriver_xf86-video-glint
+* xdriver_xf86-video-i128
+* xdriver_xf86-video-i740
+* xdriver_xf86-video-intel
+* xdriver_xf86-video-mach64
+* xdriver_xf86-video-mga
+* xdriver_xf86-video-neomagic
+* xdriver_xf86-video-newport
+* xdriver_xf86-video-nv
+* xdriver_xf86-video-openchrome
+* xdriver_xf86-video-r128
+* xdriver_xf86-video-rendition
+* xdriver_xf86-video-s3
+* xdriver_xf86-video-s3virge
+* xdriver_xf86-video-savage
+* xdriver_xf86-video-siliconmotion
+* xdriver_xf86-video-sis
+* xdriver_xf86-video-sisusb
+* xdriver_xf86-video-suncg14
+* xdriver_xf86-video-suncg3
+* xdriver_xf86-video-suncg6
+* xdriver_xf86-video-sunffb
+* xdriver_xf86-video-sunleo
+* xdriver_xf86-video-suntcx
+* xdriver_xf86-video-tdfx
+* xdriver_xf86-video-tga
+* xdriver_xf86-video-trident
+* xdriver_xf86-video-tseng
+* xdriver_xf86-video-v4l
+* xdriver_xf86-video-vesa
+* xdriver_xf86-video-vmware
+* xdriver_xf86-video-voodoo
+* xdriver_xf86-video-wsfb
+* xdriver_xf86-video-xgi
+* xdriver_xf86-video-xgixp
+* xenomai
+* xerces
+* xfont_encodings
+* xfont_font-adobe-100dpi
+* xfont_font-adobe-75dpi
+* xfont_font-adobe-utopia-100dpi
+* xfont_font-adobe-utopia-75dpi
+* xfont_font-adobe-utopia-type1
+* xfont_font-alias
+* xfont_font-arabic-misc
+* xfont_font-bh-100dpi
+* xfont_font-bh-75dpi
+* xfont_font-bh-lucidatypewriter-100dpi
+* xfont_font-bh-lucidatypewriter-75dpi
+* xfont_font-bh-ttf
+* xfont_font-bh-type1
+* xfont_font-bitstream-100dpi
+* xfont_font-bitstream-75dpi
+* xfont_font-bitstream-speedo
+* xfont_font-bitstream-type1
+* xfont_font-cronyx-cyrillic
+* xfont_font-cursor-misc
+* xfont_font-daewoo-misc
+* xfont_font-dec-misc
+* xfont_font-ibm-type1
+* xfont_font-isas-misc
+* xfont_font-jis-misc
+* xfont_font-micro-misc
+* xfont_font-misc-cyrillic
+* xfont_font-misc-ethiopic
+* xfont_font-misc-meltho
+* xfont_font-misc-misc
+* xfont_font-mutt-misc
+* xfont_font-schumacher-misc
+* xfont_font-screen-cyrillic
+* xfont_font-sony-misc
+* xfont_font-sun-misc
+* xfont_font-util
+* xfont_font-winitzki-cyrillic
+* xfont_font-xfree86-type1
+* xfsprogs
+* xinetd
+* xkeyboard-config
+* xl2tp
+* xlib_libdmx
+* xlib_libfontenc
+* xlib_libFS
+* xlib_libICE
+* xlib_liboldX
+* xlib_libpciaccess
+* xlib_libSM
+* xlib_libX11
+* xlib_libXau
+* xlib_libXaw
+* xlib_libXcomposite
+* xlib_libXcursor
+* xlib_libXdamage
+* xlib_libXdmcp
+* xlib_libXext
+* xlib_libXfixes
+* xlib_libXfont
+* xlib_libXfontcache
+* xlib_libXft
+* xlib_libXi
+* xlib_libXinerama
+* xlib_libxkbfile
+* xlib_libxkbui
+* xlib_libXmu
+* xlib_libXp
+* xlib_libXpm
+* xlib_libXprintAppUtil
+* xlib_libXprintUtil
+* xlib_libXrandr
+* xlib_libXrender
+* xlib_libXres
+* xlib_libXScrnSaver
+* xlib_libXt
+* xlib_libXtst
+* xlib_libXv
+* xlib_libXvMC
+* xlib_libXxf86dga
+* xlib_libXxf86vm
+* xlib_xtrans
+* xmlstarlet
+* xproto_applewmproto
+* xproto_bigreqsproto
+* xproto_compositeproto
+* xproto_damageproto
+* xproto_dmxproto
+* xproto_dri2proto
+* xproto_fixesproto
+* xproto_fontcacheproto
+* xproto_fontsproto
+* xproto_glproto
+* xproto_inputproto
+* xproto_kbproto
+* xproto_printproto
+* xproto_randrproto
+* xproto_recordproto
+* xproto_renderproto
+* xproto_resourceproto
+* xproto_scrnsaverproto
+* xproto_videoproto
+* xproto_windowswmproto
+* xproto_xcmiscproto
+* xproto_xextproto
+* xproto_xf86bigfontproto
+* xproto_xf86dgaproto
+* xproto_xf86driproto
+* xproto_xf86rushproto
+* xproto_xf86vidmodeproto
+* xproto_xineramaproto
+* xproto_xproto
+* xserver_xorg-server
+* xstroke
+* xterm
+* xutil_makedepend
+* xutil_util-macros
+* xvkbd
+* xz
+* yajl
+* yasm
+* zeromq
+* zlib
+* zxing
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 21/23] manual: add pkg-list.txt (generated list of available packages)
2012-11-11 13:14 ` [Buildroot] [PATCH 21/23] manual: add pkg-list.txt (generated list of available packages) Samuel Martin
@ 2012-11-11 23:11 ` Arnout Vandecappelle
0 siblings, 0 replies; 34+ messages in thread
From: Arnout Vandecappelle @ 2012-11-11 23:11 UTC (permalink / raw)
To: buildroot
On 11/11/12 14:14, Samuel Martin wrote:
> +Available packages
> +------------------
> +// docs/manaual/pkg-list.txt is generated using the following command:
> +// $ git grep -E '\((autotools|cmake|generic)-package\)' package/ | \
> +// cut -d':' -f1 | grep '\.mk$' | \
> +// sed -e 's;.*\?/\(.*\?\).mk;* \1;' | \
> +// sort> docs/manual/pkg-list.txt
> +
> +include::pkg-list.txt[]
Would it be possible to generate this list dynamically? Saves us the trouble
of keeping it consistent manually. It could be difficult to convince a2x to
look into the output directory for its include:: files, though.
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] 34+ messages in thread
* [Buildroot] [PATCH 22/23] manual: add deprecated-list.txt
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
` (20 preceding siblings ...)
2012-11-11 13:14 ` [Buildroot] [PATCH 21/23] manual: add pkg-list.txt (generated list of available packages) Samuel Martin
@ 2012-11-11 13:15 ` Samuel Martin
2012-11-11 13:15 ` [Buildroot] [PATCH 23/23] manual: add beyond-buildroot.txt Samuel Martin
2012-11-11 13:23 ` [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
23 siblings, 0 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:15 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
create mode 100644 docs/manual/deprecated-list.txt
diff --git a/docs/manual/deprecated-list.txt b/docs/manual/deprecated-list.txt
new file mode 100644
index 0000000..6dc87a4
--- /dev/null
+++ b/docs/manual/deprecated-list.txt
@@ -0,0 +1,46 @@
+// -*- mode:doc -*- ;
+
+[[deprecated]]
+Deprecated list
+---------------
+
+The following stuff are marked as _deprecated_ in Buildroot due to
+their status either too old or unmaintained.
+
+// list generated using the followings command:
+// $ git grep -EB4 'depends on BR2_DEPRECATED'
+// and
+// $ git grep -EB4 'depends on BR2_DEPRECATED' | \
+// grep -Eo '(:|-).*?(config|comment) BR2_.*'
+//
+// Need manual checks and sorting.
+
+* Packages:
+
+** +busybox+ 1.18.x
+** +customize+
+** +lzma+
+** +microperl+
+** +netkitbase+
+** +netkittelnet+
+** +pkg-config+
+** +squashfs3+
+** +ttcp+
+
+* Toolchain:
+
+** +gdb+ 6.8
+** +gdb+ 7.0.1
+** +gdb+ 7.1
+** +kernel headers+ 2.6.37
+** +kernel headers+ 2.6.38
+** +kernel headers+ 2.6.39
+
+* Bootloaders:
+
+** +u-boot+ 2011-06
+** +u-boot+ 2011-09
+
+* Output images:
+
+** squashfs3 image
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 23/23] manual: add beyond-buildroot.txt
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
` (21 preceding siblings ...)
2012-11-11 13:15 ` [Buildroot] [PATCH 22/23] manual: add deprecated-list.txt Samuel Martin
@ 2012-11-11 13:15 ` Samuel Martin
2012-11-11 13:23 ` [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
23 siblings, 0 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:15 UTC (permalink / raw)
To: buildroot
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
create mode 100644 docs/manual/beyond-buildroot.txt
diff --git a/docs/manual/beyond-buildroot.txt b/docs/manual/beyond-buildroot.txt
new file mode 100644
index 0000000..12ce78c
--- /dev/null
+++ b/docs/manual/beyond-buildroot.txt
@@ -0,0 +1,38 @@
+// -*- mode:doc; -*-
+
+Beyond Buildroot
+================
+
+Boot the generated images
+-------------------------
+
+NFS boot
+~~~~~~~~
+
+To achieve NFS-boot, enable _tar root filesystem_ in the _Filesystem
+images_ menu.
+
+After complete build, just run the following commands to setup the
+NFS-root directory:
+
+-------------------
+sudo tar -xavf /path/to/output_dir/rootfs.tar -C /path/to/nfs_root_dir
+-------------------
+
+Then, you can execute a NFS-boot from your target.
+
+Chroot
+------
+
+If you want to chroot in a generated image, then there are few thing
+you should be aware of:
+
+* you should setup the new root from the _tar root filesystem_ image;
+
+* either the selected target architecture is compatible with your host
+ machine, or you should use some +qemu-*+ binary and correctly set it
+ within the +binfmt+ properties to be able to run the binaries built
+ for the target on your host machine;
+
+* Buildroot does not currently provide +host-qemu+ and +binfmt+
+ correctly built and set for that kind of use.
diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
index a1ee68a..c34e0ca 100644
--- a/docs/manual/manual.txt
+++ b/docs/manual/manual.txt
@@ -25,6 +25,8 @@ include::developer-guide.txt[]
include::legal-notice.txt[]
+include::beyond-buildroot.txt[]
+
include::get-involved.txt[]
include::contribute.txt[]
--
1.8.0
^ permalink raw reply related [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc
2012-11-11 13:14 [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
` (22 preceding siblings ...)
2012-11-11 13:15 ` [Buildroot] [PATCH 23/23] manual: add beyond-buildroot.txt Samuel Martin
@ 2012-11-11 13:23 ` Samuel Martin
2012-11-11 23:13 ` Arnout Vandecappelle
2012-11-15 23:01 ` Peter Korsgaard
23 siblings, 2 replies; 34+ messages in thread
From: Samuel Martin @ 2012-11-11 13:23 UTC (permalink / raw)
To: buildroot
2012/11/11 Samuel Martin <s.martin49@gmail.com>:
> Hi folks,
>
> Here is another round of the documentation refactoring, that, as we agreed
> during the last Buildroot developer Days, aims to be merged to move forward on
> this topic.
>
> This series has been rebased on the commit:
> 234fe4433489bca81b79311239569525cc008d9d
>
> and can be fetched from:
> https://github.com/tSed/buildroot.git for-2012.11/doc
>
> In addition to the new sections and random updates added since the last
> subimission of this patch series, the manual has grown quite a lot, especially
> since the last Buildroot developer Days.
>
> In details:
>
> * Added few tips when using Buildroot.
>
> * FAQ: Explanation why compiler/dev. files/documentation is not supported on the
> target.
>
> * Start some explanation when 'make clean all' is necessary.
>
> * Added few tips for adding package.
>
> * Describe the sub-target of a package build.
>
> * Add few tips about how to use generated images.
>
> * Add a bunch of information about the Buildroot project community
> (how to get help, how to contribute, ...)
>
> * Update the appendices:
> - add the list of the deprecated stuff
> - add the list of the packages integrated in Buildroot (which make a lot of
> noise in the diff stat :P)
>
Ooops, forgot to mention that there still is some "TODO" here and
there in this series,
because I think I haven't all inputs to write them...
So, feel free to fill the gaps! :)
Regards,
--
Sam
^ permalink raw reply [flat|nested] 34+ messages in thread* [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc
2012-11-11 13:23 ` [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
@ 2012-11-11 23:13 ` Arnout Vandecappelle
2012-11-15 23:01 ` Peter Korsgaard
1 sibling, 0 replies; 34+ messages in thread
From: Arnout Vandecappelle @ 2012-11-11 23:13 UTC (permalink / raw)
To: buildroot
On 11/11/12 14:23, Samuel Martin wrote:
> Ooops, forgot to mention that there still is some "TODO" here and
> there in this series,
> because I think I haven't all inputs to write them...
> So, feel free to fill the gaps!
Once this has been committed, I'll read the whole manual and (try to) fix
open issues and spelling mistakes (if any :-) and fill in the gaps.
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] 34+ messages in thread
* [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc
2012-11-11 13:23 ` [Buildroot] [PATCH 00/23] Pull request for branch for-2012/doc Samuel Martin
2012-11-11 23:13 ` Arnout Vandecappelle
@ 2012-11-15 23:01 ` Peter Korsgaard
1 sibling, 0 replies; 34+ messages in thread
From: Peter Korsgaard @ 2012-11-15 23:01 UTC (permalink / raw)
To: buildroot
>>>>> "Samuel" == Samuel Martin <s.martin49@gmail.com> writes:
Samuel> 2012/11/11 Samuel Martin <s.martin49@gmail.com>:
>> Hi folks,
>>
>> Here is another round of the documentation refactoring, that, as we agreed
>> during the last Buildroot developer Days, aims to be merged to move forward on
>> this topic.
Committed series, thanks (except for 1/23).
--
Bye, Peter Korsgaard
^ permalink raw reply [flat|nested] 34+ messages in thread