[Buildroot] [PATCH 0/5] Docs: Misc. updates and trivial fixes

[Buildroot] [PATCH 0/5] Docs: Misc. updates and trivial fixes

[Samuel MARTIN]

Among miscellaneous fixes in the documentation, this patch series does:
- add a warning on the current about the deprecation of the html doc.
- complete some sections in the manual.

Samuel MARTIN (5):
  docs/buildroot.html: cleanup trailing whitespaces
  docs/buildroot.html: add new manual location and warning about this
    page
  docs: fix busybox url
  manual: fix typo
  manual: update Config.in dependency explainations

 docs/buildroot.html                         |   41 +++++++++++++++++---------
 docs/manual/adding-packages-directory.txt   |   42 ++++++++++++++++++++++++++-
 docs/manual/adding-packages-handwritten.txt |   14 ++++-----
 docs/manual/using.txt                       |    2 +-
 4 files changed, 77 insertions(+), 22 deletions(-)

--
1.7.9.4

[Buildroot] [PATCH 1/5] docs/buildroot.html: cleanup trailing whitespaces

[Samuel MARTIN]

Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>
---
 docs/buildroot.html |   24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/docs/buildroot.html b/docs/buildroot.html
index ddfb20a..28aefe4 100644
--- a/docs/buildroot.html
+++ b/docs/buildroot.html
@@ -39,22 +39,22 @@
 
     <h2 id="about">About Buildroot</h2>
 
-    <p>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 
+    <p>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.</p>
 
-    <p>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 
+    <p>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.</p>
 
-    <p>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, 
-    <code>gcc</code>), binary utils like assembler and linker (in our case, 
-    <code>binutils</code>) and a C standard library (for example 
-    <a href="http://www.gnu.org/software/libc/libc.html">GNU Libc</a>, 
-    <a href="http://www.uclibc.org/">uClibc</a> or 
+    <p>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,
+    <code>gcc</code>), binary utils like assembler and linker (in our case,
+    <code>binutils</code>) and a C standard library (for example
+    <a href="http://www.gnu.org/software/libc/libc.html">GNU Libc</a>,
+    <a href="http://www.uclibc.org/">uClibc</a> or
     <a href="http://www.fefe.de/dietlibc/">dietlibc</a>). 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
-- 
1.7.9.4

[Buildroot] [PATCH 1/5] docs/buildroot.html: cleanup trailing whitespaces

[Peter Korsgaard]

>>>>> "Samuel" == Samuel MARTIN <s.martin49@gmail.com> writes:

 Samuel> Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>

Committed, thanks.

-- 
Bye, Peter Korsgaard

[Buildroot] [PATCH 2/5] docs/buildroot.html: add new manual location and warning about this page

[Samuel MARTIN]

Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>
---
 docs/buildroot.html |   15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/docs/buildroot.html b/docs/buildroot.html
index 28aefe4..a01e1fc 100644
--- a/docs/buildroot.html
+++ b/docs/buildroot.html
@@ -37,6 +37,21 @@
       <li><a href="#links">Resources</a></li>
     </ul>
 
+    <p><b>WARNING:</b> Since the 2011.11 release, this page is on its way to be
+    deprecated. Information may be incomplete and out-dated.</p>
+
+    <p>To get an up-to-date documentation for
+    <a href="http://buildroot.net/">Buildroot</a>-2011.11 or a git view, just
+    run:</p>
+<pre>
+  $ make manual
+</pre>
+    <p><i>This requires <code>asciidoc</code> installed on the host system.</i></p>
+
+    <p>For releases since <a href="http://buildroot.net/">Buildroot</a>-2012.02,
+    manuals (html, pdf and text) are available in the  <code>docs/manual</code>
+    directory.</p>
+
     <h2 id="about">About Buildroot</h2>
 
     <p>Buildroot is a set of Makefiles and patches that allows you to easily
-- 
1.7.9.4

[Buildroot] [PATCH 2/5] docs/buildroot.html: add new manual location and warning about this page

[Peter Korsgaard]

>>>>> "Samuel" == Samuel MARTIN <s.martin49@gmail.com> writes:

 Samuel> Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>

Committed, thanks.

-- 
Bye, Peter Korsgaard

[Buildroot] [PATCH 3/5] docs: fix busybox url

[Samuel MARTIN]

Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>
---
 docs/buildroot.html   |    2 +-
 docs/manual/using.txt |    2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/buildroot.html b/docs/buildroot.html
index a01e1fc..d178df1 100644
--- a/docs/buildroot.html
+++ b/docs/buildroot.html
@@ -154,7 +154,7 @@
     <p>Buildroot has a nice configuration tool similar to the one you can find
     in the Linux kernel
     (<a href="http://www.kernel.org/">http://www.kernel.org/</a>) or in Busybox
-    (<a href="http://www.busybox.org/">http://www.busybox.org/</a>). Note that
+    (<a href="http://www.busybox.net/">http://www.busybox.net/</a>). 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:</p>
diff --git a/docs/manual/using.txt b/docs/manual/using.txt
index 8d7f0a7..a5dc9e1 100644
--- a/docs/manual/using.txt
+++ b/docs/manual/using.txt
@@ -6,7 +6,7 @@ Configuration and general usage
 
 Buildroot has a nice configuration tool similar to the one you can
 find in the http://www.kernel.org/[Linux kernel] or in
-http://www.busybox.org/[Busybox]. Note that you can (and should) build
+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:
-- 
1.7.9.4

[Buildroot] [PATCH 3/5] docs: fix busybox url

[Peter Korsgaard]

>>>>> "Samuel" == Samuel MARTIN <s.martin49@gmail.com> writes:

 Samuel> Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>

Committed, thanks.

-- 
Bye, Peter Korsgaard

[Buildroot] [PATCH 4/5] manual: fix typo

[Samuel MARTIN]

Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>
---
 docs/manual/adding-packages-directory.txt   |    3 ++-
 docs/manual/adding-packages-handwritten.txt |   14 +++++++-------
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
index 0852b04..04be820 100644
--- a/docs/manual/adding-packages-directory.txt
+++ b/docs/manual/adding-packages-directory.txt
@@ -8,12 +8,13 @@ Some packages have been grouped by topic in a sub-directory:
 +multimedia+, +java+, +x11r7+, and +games+. If your package fits in
 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
-and displayed in the configuration tool. It should basically contain :
+and displayed in the configuration tool. It should basically contain:
 
 ---------------------------
 config BR2_PACKAGE_LIBFOO
diff --git a/docs/manual/adding-packages-handwritten.txt b/docs/manual/adding-packages-handwritten.txt
index a9d247c..54ccf65 100644
--- a/docs/manual/adding-packages-handwritten.txt
+++ b/docs/manual/adding-packages-handwritten.txt
@@ -14,12 +14,12 @@ existing manual makefiles and to help understand how they work.*
 03: # libfoo
 04: #
 05: #############################################################
-06: LIBFOO_VERSION:=1.0
-07: LIBFOO_SOURCE:=libfoo-$(LIBFOO_VERSION).tar.gz
-08: LIBFOO_SITE:=http://www.foosoftware.org/downloads
-09: LIBFOO_DIR:=$(BUILD_DIR)/foo-$(FOO_VERSION)
-10: LIBFOO_BINARY:=foo
-11: LIBFOO_TARGET_BINARY:=usr/bin/foo
+06: LIBFOO_VERSION = 1.0
+07: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
+08: LIBFOO_SITE = http://www.foosoftware.org/downloads
+09: LIBFOO_DIR = $(BUILD_DIR)/foo-$(FOO_VERSION)
+10: LIBFOO_BINARY = foo
+11: LIBFOO_TARGET_BINARY = usr/bin/foo
 12:
 13: $(DL_DIR)/$(LIBFOO_SOURCE):
 14: 	$(call DOWNLOAD,$(LIBFOO_SITE),$(LIBFOO_SOURCE))
@@ -65,7 +65,7 @@ existing manual makefiles and to help understand how they work.*
 54: #
 55: #############################################################
 56: ifeq ($(BR2_PACKAGE_LIBFOO),y)
-57: TARGETS+=libfoo
+57: TARGETS += libfoo
 58: endif
 ------------------------
 
-- 
1.7.9.4

[Buildroot] [PATCH 4/5] manual: fix typo

[Peter Korsgaard]

>>>>> "Samuel" == Samuel MARTIN <s.martin49@gmail.com> writes:

 Samuel> Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>

Committed, thanks.

-- 
Bye, Peter Korsgaard

[Buildroot] [PATCH 5/5] manual: update Config.in dependency explainations

[Samuel MARTIN]

Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>
---
 docs/manual/adding-packages-directory.txt |   39 +++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
index 04be820..75ef763 100644
--- a/docs/manual/adding-packages-directory.txt
+++ b/docs/manual/adding-packages-directory.txt
@@ -87,6 +87,45 @@ comment "acl requires a toolchain with LARGEFILE support"
 --------------------------
 
 
+Note that these two dependency types are only transitive with the
+dependencies of the same kind.
+
+This means, in the following example:
+
+--------------------------
+config PACKAGE_A
+        bool "Package A"
+
+config PACKAGE_B
+        bool "Package B"
+        depends on PACKAGE_A
+
+config PACKAGE_C
+        bool "Package C"
+        depends on PACKAGE_B
+
+config PACKAGE_D
+        bool "Package D"
+        select PACKAGE_B
+
+config PACKAGE_E
+        bool "Package E"
+        select PACKAGE_D
+--------------------------
+
+* Selecting +Package C+ will be visible if +Package B+ has been
+  selected, so if +Package A+ has been selected too.
+
+* Selecting +Package E+ will select +Package D+, which will select
+  +Package B+, it will not check for the dependencies of +Package B+,
+  so it will not select +Package A+.
+
+Overall, for package library dependencies, +select+ should be
+prefered.
+
+One should avoid to mix up these two dependency types, though it
+should be adapted to each case.
+
 Note that such dependencies will make sure that the dependency option
 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
-- 
1.7.9.4

[Buildroot] [PATCH 5/5] manual: update Config.in dependency explainations

[Arnout Vandecappelle]

On Sunday 18 March 2012 09:54:03 Samuel MARTIN wrote:
> 
> Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>
> ---
>  docs/manual/adding-packages-directory.txt |   39 +++++++++++++++++++++++++++++
>  1 file changed, 39 insertions(+)
> 
> diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
> index 04be820..75ef763 100644
> --- a/docs/manual/adding-packages-directory.txt
> +++ b/docs/manual/adding-packages-directory.txt
> @@ -87,6 +87,45 @@ comment "acl requires a toolchain with LARGEFILE support"
>  --------------------------
>  
>  
> +Note that these two dependency types are only transitive with the
> +dependencies of the same kind.
> +
> +This means, in the following example:
> +
> +--------------------------
> +config PACKAGE_A
 I would use BR2_PACKAGE_* in the example.

> +        bool "Package A"
> +
> +config PACKAGE_B
> +        bool "Package B"
> +        depends on PACKAGE_A
> +
> +config PACKAGE_C
> +        bool "Package C"
> +        depends on PACKAGE_B
> +
> +config PACKAGE_D
> +        bool "Package D"
> +        select PACKAGE_B
> +
> +config PACKAGE_E
> +        bool "Package E"
> +        select PACKAGE_D
> +--------------------------
> +
> +* Selecting +Package C+ will be visible if +Package B+ has been
> +  selected, so if +Package A+ has been selected too.

 Rewrite:

Selecting +Package C+ will be visible if +Package B+ has been
selected, which in turn is only visible if +Package A+ has been selected.

> +
> +* Selecting +Package E+ will select +Package D+, which will select
> +  +Package B+, it will not check for the dependencies of +Package B+,
> +  so it will not select +Package A+.

 Add:

Since +Package B+ is selected but +Package A+ is not, this violates 
the dependency of +Package B+ on +Package A+.  Therefore, in such a 
situation, the transitive dependency has to be added explicitly.

--------------------------
config PACKAGE_D
	bool "Package D"
	select PACKAGE_B
	depends on PACKAGE_A

config PACKAGE_E
	bool "Package E"
	select PACKAGE_D
	depends on PACKAGE_A
--------------------------


> +
> +Overall, for package library dependencies, +select+ should be
> +prefered.

 My spell checker prefers preferred :-)

> +
> +One should avoid to mix up these two dependency types, though it
> +should be adapted to each case.

 I think this paragraph makes things more confusing instead of more
clear.  Perhaps just remove it?


 Regards,
 Arnout

> +
>  Note that such dependencies will make sure that the dependency option
>  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
> 

-- 
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

[Buildroot] [PATCH 5/5] manual: update Config.in dependency explainations

[Peter Korsgaard]

>>>>> "Samuel" == Samuel MARTIN <s.martin49@gmail.com> writes:

 Samuel> Signed-off-by: Samuel MARTIN <s.martin49@gmail.com>

Committed with the changes suggested by Arnout, thanks.

-- 
Bye, Peter Korsgaard

[Buildroot] [PATCH 0/5] Docs: Misc. updates and trivial fixes

[Arnout Vandecappelle]

On Sunday 18 March 2012 09:53:58 Samuel MARTIN wrote:
> Samuel MARTIN (5):
>   docs/buildroot.html: cleanup trailing whitespaces
>   docs/buildroot.html: add new manual location and warning about this
>     page
>   docs: fix busybox url
>   manual: fix typo
Acked-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
 for the first four patches

>   manual: update Config.in dependency explainations
 Small amendments here, see separate mail.

 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