Skip to contentSkip to conversation

Documentation updates and improvements

PATCH New Thomas Petazzoni 3 participants 30 messages Feb 23, 2014

lore
Share & tools
lore
#0 lore raw

cover Documentation updates and improvements

Hello,

Here is a set of documentation updates and improvements, about toolchains, package infrastructures, dependency and build-time graphing, and also finally a documentation about <pkg>_OVERRIDE_SRCDIR.

Thomas

Thomas Petazzoni (13):
docs/manual: toolchain packages no longer use custom makefiles docs/manual: rephrase part about rebuilding packages docs/manual: rephrase and expand part on when a full rebuild is
necessary
docs/manual: reference Python and Lua infras from the list of package
infrastructures
docs/manual: add section about dependency graphs docs/manual: add section about build time graphing docs/manual: update informations about C library in internal backend docs/manual: update external toolchain examples docs/manual: mention that custom toolchains is also useful for BR
toolchains
docs/manual: rephrase paragraph about unsupported external toolchains docs/manual: refresh informations about *-menuconfig targets docs/manual: document the usage of <pkg>_OVERRIDE_SRCDIR docs/manual: mention the per-package graph-depends target

 docs/manual/adding-packages-directory.txt   |  11 +++
 docs/manual/advanced.txt                    |   2 +
 docs/manual/common-usage.txt                |  99 +++++++++++++++++++++
 docs/manual/configure.txt                   |  77 ++++++----------
 docs/manual/make-tips.txt                   |   6 +-
 docs/manual/package-make-target.txt         |   5 ++
 docs/manual/rebuilding-packages.txt         | 132 +++++++++++++++++++---------
 docs/manual/using-buildroot-development.txt |  84 ++++++++++++++++++
 8 files changed, 324 insertions(+), 92 deletions(-)
 create mode 100644 docs/manual/using-buildroot-development.txt
Signature · 1 line
1.8.3.2
#1 lore raw

PATCH 1/13 docs/manual: toolchain packages no longer use custom makefiles

---
 docs/manual/rebuilding-packages.txt | 3 ---
 1 file changed, 3 deletions(-)
docs/manual/rebuilding-packages.txt +0 -3
index 88d6670..da8d230 100644
@@ -69,8 +69,5 @@ files that just tell whether this or that action has been done):
   Buildroot will trigger the recompilation of the package from the
   compilation step (execution of +make+).
 
-Note: toolchain packages use custom makefiles. Their stamp files are named
-differently.
-
 Further details about package special make targets are explained in
 xref:pkg-build-steps[].
Signature · 1 line
1.8.3.2
#2 lore raw

PATCH 1/13 docs/manual: toolchain packages no longer use custom makefiles

Thomas, All,

On 2014-02-23 16:04 +0100, Thomas Petazzoni spake thusly:

Quoted 1 line

Regard,
Yann E. MORIN.

Quoted 24 lines
---
 docs/manual/rebuilding-packages.txt | 3 ---
 1 file changed, 3 deletions(-)
docs/manual/rebuilding-packages.txt +0 -3
index 88d6670..da8d230 100644
@@ -69,8 +69,5 @@ files that just tell whether this or that action has been done):
   Buildroot will trigger the recompilation of the package from the
   compilation step (execution of +make+).
 
-Note: toolchain packages use custom makefiles. Their stamp files are named
-differently.
-
 Further details about package special make targets are explained in
 xref:pkg-build-steps[].
Signature · 6 lines
1.8.3.2

_______________________________________________
buildroot mailing list
buildroot at busybox.net
http://lists.busybox.net/mailman/listinfo/buildroot
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'
#3 lore raw

PATCH 2/13 docs/manual: rephrase part about rebuilding packages

In reply to Thomas Petazzoni

There is no need to tell people should remove stamp files: they should use the make <pkg>-reconfigure and make <pkg>-rebuild make targets instead. We still keep an explanation about stamp files, just to give to the user an insight on how Buildroot works internally.

---
 docs/manual/rebuilding-packages.txt | 36 +++++++++++++++++++-----------------
 1 file changed, 19 insertions(+), 17 deletions(-)
docs/manual/rebuilding-packages.txt +19 -17
index da8d230..4872e88 100644
@@ -51,23 +51,25 @@ its build directory in +output/build+. Buildroot will then re-extract,
 re-configure, re-compile and re-install this package from scratch. You
 can ask buildroot to do this with the +make <package>-dirclean+ command.
 
-For convenience, the special make targets
-<package>-reconfigure and <package>-rebuild repeat the configure
-resp. build steps.
-
-However, if you don't want to rebuild the package completely from
-scratch, a better understanding of the Buildroot internals is
-needed. Internally, to keep track of which steps have been done and
-which steps remain to be done, Buildroot maintains stamp files (empty
-files that just tell whether this or that action has been done):
-
-* +output/build/<package>-<version>/.stamp_configured+. If removed,
-  Buildroot will trigger the recompilation of the package from the
-  configuration step (execution of +./configure+).
-
-* +output/build/<package>-<version>/.stamp_built+. If removed,
-  Buildroot will trigger the recompilation of the package from the
-  compilation step (execution of +make+).
+On the other hand, if you only want to restart the build process of a
+package from its compilation step, you can run +make
+<package>-rebuild+, followed by +make+ or +make <package>+. It will
+restart the compilation and installation of the package, but not from
+scratch: it basically simply re-executes +make+ and +make install+
+inside the package, so it will only rebuild files that changed.
+
+If you want to restart the build process of a package from its
+configuration step, you can run +make <package>-reconfigure+, followed
+by +make+ or +make <package>+. It will restart the configuration,
+compilation and installation of the package.
+
+Internally, Buildroot creates so-called _stamp files_ to keep track of
+which build steps have been completed for each package. They are
+stored in the package build directory,
++output/build/<package>-<version>/+ and are named
++.stamp_<step-name>+. The commands detailed above simply manipulate
+these stamp files to force Buildroot to restart a specific set of
+steps of a package build process.
 
 Further details about package special make targets are explained in
 xref:pkg-build-steps[].
Signature · 1 line
1.8.3.2
#4 lore raw

PATCH 2/13 docs/manual: rephrase part about rebuilding packages

Thomas, All,

On 2014-02-23 16:04 +0100, Thomas Petazzoni spake thusly:

Quoted 6 lines

There is no need to tell people should remove stamp files: they should use the make <pkg>-reconfigure and make <pkg>-rebuild make targets instead. We still keep an explanation about stamp files, just to give to the user an insight on how Buildroot works internally.

Regards,
Yann E. MORIN.

Quoted 58 lines
---
 docs/manual/rebuilding-packages.txt | 36 +++++++++++++++++++-----------------
 1 file changed, 19 insertions(+), 17 deletions(-)
docs/manual/rebuilding-packages.txt +19 -17
index da8d230..4872e88 100644
@@ -51,23 +51,25 @@ its build directory in +output/build+. Buildroot will then re-extract,
 re-configure, re-compile and re-install this package from scratch. You
 can ask buildroot to do this with the +make <package>-dirclean+ command.
 
-For convenience, the special make targets
-<package>-reconfigure and <package>-rebuild repeat the configure
-resp. build steps.
-
-However, if you don't want to rebuild the package completely from
-scratch, a better understanding of the Buildroot internals is
-needed. Internally, to keep track of which steps have been done and
-which steps remain to be done, Buildroot maintains stamp files (empty
-files that just tell whether this or that action has been done):
-
-* +output/build/<package>-<version>/.stamp_configured+. If removed,
-  Buildroot will trigger the recompilation of the package from the
-  configuration step (execution of +./configure+).
-
-* +output/build/<package>-<version>/.stamp_built+. If removed,
-  Buildroot will trigger the recompilation of the package from the
-  compilation step (execution of +make+).
+On the other hand, if you only want to restart the build process of a
+package from its compilation step, you can run +make
+<package>-rebuild+, followed by +make+ or +make <package>+. It will
+restart the compilation and installation of the package, but not from
+scratch: it basically simply re-executes +make+ and +make install+
+inside the package, so it will only rebuild files that changed.
+
+If you want to restart the build process of a package from its
+configuration step, you can run +make <package>-reconfigure+, followed
+by +make+ or +make <package>+. It will restart the configuration,
+compilation and installation of the package.
+
+Internally, Buildroot creates so-called _stamp files_ to keep track of
+which build steps have been completed for each package. They are
+stored in the package build directory,
++output/build/<package>-<version>/+ and are named
++.stamp_<step-name>+. The commands detailed above simply manipulate
+these stamp files to force Buildroot to restart a specific set of
+steps of a package build process.
 
 Further details about package special make targets are explained in
 xref:pkg-build-steps[].
Signature · 6 lines
1.8.3.2

_______________________________________________
buildroot mailing list
buildroot at busybox.net
http://lists.busybox.net/mailman/listinfo/buildroot
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'
#5 lore raw

PATCH 3/13 docs/manual: rephrase and expand part on when a full rebuild is necessary

In reply to Thomas Petazzoni
---
 docs/manual/rebuilding-packages.txt | 93 ++++++++++++++++++++++++++++---------
 1 file changed, 71 insertions(+), 22 deletions(-)
docs/manual/rebuilding-packages.txt +71 -22
index 4872e88..26e244c 100644
@@ -5,33 +5,82 @@
 Understanding when a full rebuild is necessary
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-A full rebuild is achieved by running:
+Buildroot does not attempt to detect what parts of the system should
+be rebuilt when the system configuration is changed through +make
+menuconfig+, +make xconfig+ or one of the other configuration
+tools. In some cases, Buildroot should rebuild the entire system, in
+some cases, only a specific subset of packages. But detecting this in
+a completely reliable manner is very difficult, and therefore the
+Buildroot developers have decided to simply not attempt to do this.
+
+Instead, it is the responsibility of the user to know when a full
+rebuild is necessary. As a hint, here are a few rules of thumb that
+can help you understand how to work with Buildroot:
+
+ * When the target architecture configuration is changed, a complete
+   rebuild is needed. Changing the architecture variant, the binary
+   format or the floating point strategy for example has an impact on
+   the entire system.
+
+ * When the toolchain configuration is changed, a complete rebuild
+   generally is needed. Changing the toolchain configuration often
+   involves changing the compiler version, the type of C library or
+   its configuration, or some other fundamental configuration item,
+   and these changes have an impact on the entire system.
+
+ * When an additional package is added to the configuration, a full
+   rebuild is not necessarily needed. Buildroot will detect that this
+   package has never been built, and will build it. However, if this
+   package is a library that can optionally be used by packages that
+   have already been built, Buildroot will not automatically rebuild
+   those. Either you know which packages should be rebuilt, and you
+   can rebuild them manually, or you should do a full rebuild. For
+   example, let's suppose you have built a system with the +ctorrent+
+   package, but without +openssl+. Your system works, but you realize
+   you would like to have SSL support in +ctorrent+, so you enable the
+   +openssl+ package in Buildroot configuration and restart the
+   build. Buildroot will detect that +openssl+ should be built and
+   will be build it, but it will not detect that +ctorrent+ should be
+   rebuilt to benefit from +openssl+ to add OpenSSL support. You will
+   either have to do a full rebuild, or rebuild +ctorrent+ itself.
+
+ * When a package is removed from the configuration, Buildroot does
+   not do anything special. It does not remove the files installed by
+   this package from the target root filesystem or from the toolchain
+   _sysroot_. A full rebuild is needed to get rid of this
+   package. However, generally you don't necessarily need this package
+   to be removed right now: you can wait for the next lunch break to
+   restart the build from scratch.
+
+ * When the sub-options of a package are changed, the package is not
+   automatically rebuilt. After making such changes, rebuilding only
+   this package is often sufficient, unless enabling the package
+   sub-option adds some features to the package that are useful for
+   another package which has already been built. Again, Buildroot does
+   not track when a package should be rebuilt: once a package has been
+   built, it is never rebuilt unless explicitly told to do so.
+
+ * When a change to the root filesystem skeleton is made, a full
+   rebuild is needed. However, when changes to the root filesystem
+   overlay, to a post-build script or a post-image script are made,
+   there is no need for a full rebuild: a simple +make+ invocation
+   will take the changes into account.
+
+Generally speaking, when you're facing a build error and you're unsure
+of the potential consequences of the configuration changes you've
+made, do a full rebuild. If you get the same build error, then you are
+sure that the error is not related to partial rebuilds of packages,
+and if this error occurs with packages from the official Buildroot, do
+not hesitate to report the problem! As your experience with Buildroot
+progresses, you will progressively learn when a full rebuild is really
+necessary, and you will save more and more time.
+
+For reference, a full rebuild is achieved by running:
 
 ---------------
 $ make clean all
 ---------------
 
-In some cases, a full rebuild is mandatory:
-
-* each time the toolchain properties are changed, this includes:
-
-** after changing any toolchain option under the _Toolchain_ menu (if
-   the internal Buildroot backend is used);
-** after running +make uclibc-menuconfig+.
-
-* after removing some libraries from the package selection.
-
-In some cases, a full rebuild is recommended:
-
-* after adding some libraries to the package selection (otherwise,
-  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 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Signature · 1 line
1.8.3.2
#6 lore raw

PATCH 3/13 docs/manual: rephrase and expand part on when a full rebuild is necessary

Thomas, All,

On 2014-02-23 16:04 +0100, Thomas Petazzoni spake thusly:

Quoted 1 line

Regards,
Yann E. MORIN.

Quoted 120 lines
---
 docs/manual/rebuilding-packages.txt | 93 ++++++++++++++++++++++++++++---------
 1 file changed, 71 insertions(+), 22 deletions(-)
docs/manual/rebuilding-packages.txt +71 -22
index 4872e88..26e244c 100644
@@ -5,33 +5,82 @@
 Understanding when a full rebuild is necessary
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-A full rebuild is achieved by running:
+Buildroot does not attempt to detect what parts of the system should
+be rebuilt when the system configuration is changed through +make
+menuconfig+, +make xconfig+ or one of the other configuration
+tools. In some cases, Buildroot should rebuild the entire system, in
+some cases, only a specific subset of packages. But detecting this in
+a completely reliable manner is very difficult, and therefore the
+Buildroot developers have decided to simply not attempt to do this.
+
+Instead, it is the responsibility of the user to know when a full
+rebuild is necessary. As a hint, here are a few rules of thumb that
+can help you understand how to work with Buildroot:
+
+ * When the target architecture configuration is changed, a complete
+   rebuild is needed. Changing the architecture variant, the binary
+   format or the floating point strategy for example has an impact on
+   the entire system.
+
+ * When the toolchain configuration is changed, a complete rebuild
+   generally is needed. Changing the toolchain configuration often
+   involves changing the compiler version, the type of C library or
+   its configuration, or some other fundamental configuration item,
+   and these changes have an impact on the entire system.
+
+ * When an additional package is added to the configuration, a full
+   rebuild is not necessarily needed. Buildroot will detect that this
+   package has never been built, and will build it. However, if this
+   package is a library that can optionally be used by packages that
+   have already been built, Buildroot will not automatically rebuild
+   those. Either you know which packages should be rebuilt, and you
+   can rebuild them manually, or you should do a full rebuild. For
+   example, let's suppose you have built a system with the +ctorrent+
+   package, but without +openssl+. Your system works, but you realize
+   you would like to have SSL support in +ctorrent+, so you enable the
+   +openssl+ package in Buildroot configuration and restart the
+   build. Buildroot will detect that +openssl+ should be built and
+   will be build it, but it will not detect that +ctorrent+ should be
+   rebuilt to benefit from +openssl+ to add OpenSSL support. You will
+   either have to do a full rebuild, or rebuild +ctorrent+ itself.
+
+ * When a package is removed from the configuration, Buildroot does
+   not do anything special. It does not remove the files installed by
+   this package from the target root filesystem or from the toolchain
+   _sysroot_. A full rebuild is needed to get rid of this
+   package. However, generally you don't necessarily need this package
+   to be removed right now: you can wait for the next lunch break to
+   restart the build from scratch.
+
+ * When the sub-options of a package are changed, the package is not
+   automatically rebuilt. After making such changes, rebuilding only
+   this package is often sufficient, unless enabling the package
+   sub-option adds some features to the package that are useful for
+   another package which has already been built. Again, Buildroot does
+   not track when a package should be rebuilt: once a package has been
+   built, it is never rebuilt unless explicitly told to do so.
+
+ * When a change to the root filesystem skeleton is made, a full
+   rebuild is needed. However, when changes to the root filesystem
+   overlay, to a post-build script or a post-image script are made,
+   there is no need for a full rebuild: a simple +make+ invocation
+   will take the changes into account.
+
+Generally speaking, when you're facing a build error and you're unsure
+of the potential consequences of the configuration changes you've
+made, do a full rebuild. If you get the same build error, then you are
+sure that the error is not related to partial rebuilds of packages,
+and if this error occurs with packages from the official Buildroot, do
+not hesitate to report the problem! As your experience with Buildroot
+progresses, you will progressively learn when a full rebuild is really
+necessary, and you will save more and more time.
+
+For reference, a full rebuild is achieved by running:
 
 ---------------
 $ make clean all
 ---------------
 
-In some cases, a full rebuild is mandatory:
-
-* each time the toolchain properties are changed, this includes:
-
-** after changing any toolchain option under the _Toolchain_ menu (if
-   the internal Buildroot backend is used);
-** after running +make uclibc-menuconfig+.
-
-* after removing some libraries from the package selection.
-
-In some cases, a full rebuild is recommended:
-
-* after adding some libraries to the package selection (otherwise,
-  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 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Signature · 6 lines
1.8.3.2

_______________________________________________
buildroot mailing list
buildroot at busybox.net
http://lists.busybox.net/mailman/listinfo/buildroot
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'
#7 lore raw

PATCH 4/13 docs/manual: reference Python and Lua infras from the list of package infrastructures

In reply to Thomas Petazzoni
---
 docs/manual/adding-packages-directory.txt | 11 +++++++++++
 1 file changed, 11 insertions(+)
docs/manual/adding-packages-directory.txt +11 -0
index 754a145..eff92fa 100644
@@ -323,5 +323,16 @@ different way, using different infrastructures:
    CMake. We cover them through a xref:cmake-package-tutorial[tutorial]
    and xref:cmake-package-reference[reference].
 
+* *Makefiles for Python modules*: We have a dedicated infrastructure
+   for Python modules that use either the +distutils+ or the
+   +setuptools+ mechanism. We cover them through a
+   xref:python-package-tutorial[tutorial] and
+   xref:python-package-reference[reference].
+
+* *Makefiles for Lua modules*: We have a dedicated infrastructure for
+   Lua modules available through the LuaRocks web site. We cover them
+   through a xref:luarocks-package-tutorial[tutorial] and
+   xref:luarocks-package-reference[reference].
+
 Further formatting details: see xref:writing-rules-mk[the writing
 rules].
Signature · 1 line
1.8.3.2
#8 lore raw

PATCH 4/13 docs/manual: reference Python and Lua infras from the list of package infrastructures

Thomas, All,

On 2014-02-23 16:04 +0100, Thomas Petazzoni spake thusly:

Quoted 11 lines
---
 docs/manual/adding-packages-directory.txt | 11 +++++++++++
 1 file changed, 11 insertions(+)
docs/manual/adding-packages-directory.txt +0 -0
index 754a145..eff92fa 100644

docs/manual/adding-packages-directory.txt different way, using different infrastructures: · line 330

Quoted 8 lines
docs/manual/adding-packages-directory.txt +5 -0
@@ -323,5 +323,16 @@ different way, using different infrastructures:
    CMake. We cover them through a xref:cmake-package-tutorial[tutorial]
    and xref:cmake-package-reference[reference].
 
+* *Makefiles for Python modules*: We have a dedicated infrastructure
+   for Python modules that use either the +distutils+ or the
+   +setuptools+ mechanism. We cover them through a
+   xref:python-package-tutorial[tutorial] and
+   xref:python-package-reference[reference].

I believe english grammar mandates the following:
[...] a tutorial and a reference.

So, you're missing an 'a' between the 'and' and the 'reference'.

Also, what about the mandatory status of this? For other package onfrastructures, we say:
This infrastructure must be used for new packages that rely on [XXX] as their build system.

Why don't we add this for Python modules?

docs/manual/adding-packages-directory.txt different way, using different infrastructures: · line 335

Quoted 4 lines
docs/manual/adding-packages-directory.txt +4 -0
+* *Makefiles for Lua modules*: We have a dedicated infrastructure for
+   Lua modules available through the LuaRocks web site. We cover them
+   through a xref:luarocks-package-tutorial[tutorial] and
+   xref:luarocks-package-reference[reference].

Ditto 'a' and ditto 'mandatory'.

Regards,
Yann E. MORIN.

Signature · 6 lines
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'
#9 lore raw

PATCH 4/13 docs/manual: reference Python and Lua infras from the list of package infrastructures

Dear Yann E. MORIN,

Quoted 10 lines · Yann E. MORIN

docs/manual/adding-packages-directory.txt different way, using different infrastructures: · line 330

Quoted 5 lines
docs/manual/adding-packages-directory.txt +5 -0
+* *Makefiles for Python modules*: We have a dedicated infrastructure
+   for Python modules that use either the +distutils+ or the
+   +setuptools+ mechanism. We cover them through a
+   xref:python-package-tutorial[tutorial] and
+   xref:python-package-reference[reference].

I believe english grammar mandates the following:
[...] a tutorial and a reference.

So, you're missing an 'a' between the 'and' and the 'reference'.

Ok. I'll see if Peter applies the patch and makes the change himself before resending 13 patches :-)

Quoted 6 lines

Also, what about the mandatory status of this? For other package onfrastructures, we say:
This infrastructure must be used for new packages that rely on [XXX] as their build system.

Why don't we add this for Python modules?

I found it quite redundant, and in fact I believe it is now a bit useless even for autotools and cmake packages. It used to be useful at the time we had old-style packages that were not yet converted. But nowadays, it is quite clear that if the package infrastructure exists and matches the build system of a given package, then it must be used.

Thanks a lot for the review!

Thomas

Signature · 3 lines
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com
#10 lore raw

PATCH 5/13 docs/manual: add section about dependency graphs

In reply to Thomas Petazzoni
---
 docs/manual/common-usage.txt | 52 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
docs/manual/common-usage.txt +52 -0
index 9a8c92a..bef42c6 100644
@@ -149,3 +149,55 @@ of an ext2 filesystem may be corrupted; or, if you have sparse files in
 your filesystem, those parts may not be all-zeroes when read back). You
 should only use sparse files when handling files on the build machine, not
 when transferring them to an actual device that will be used on the target.
+
+Graphing the dependencies between packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[[graph-depends]]
+
+One of Buildroot's jobs is to know the dependencies between packages,
+and make sure they are built in the right order. These dependencies
+can sometimes be quite complicated, and for a given system, it is
+often not easy to understand why such or such package was brought into
+the build by Buildroot.
+
+In order to help understanding the dependencies, and therefore better
+understand what is the role of the different components in your
+embedded Linux system, Buildroot is capable of generating dependency
+graphs.
+
+To generate a dependency graph of the full system you have compiled,
+simply run:
+
+------------------------
+make graph-depends
+------------------------
+
+You will find the generated graph in
++output/graphs/graph-depends.pdf+.
+
+If your system is quite large, the dependency graph may be too complex
+and difficult to read. It is therefore possible to generate the
+dependency graph just for a given package:
+
+------------------------
+make <pkg>-graph-depends
+------------------------
+
+You will find the generated graph in
++output/graph/<pkg>-graph-depends.pdf+.
+
+Note that the dependency graphs are generated using the +dot+ tool
+from the _Graphviz_ project, which you must have installed on your
+system to use this feature. In most distributions, it is available as
+the +graphviz+ package.
+
+By default, the dependency graphs are generated in the PDF
+format. However, by passing the +GRAPH_OUT+ environment variable, you
+can switch to other output formats, such as PNG, PostScript or
+SVG. All formats supported by the +-T+ option of the +dot+ tool are
+supported.
+
+--------------------------------
+GRAPH_OUT=svg make graph-depends
+--------------------------------
Signature · 1 line
1.8.3.2
#11 lore raw

PATCH 5/13 docs/manual: add section about dependency graphs

Thomas, All,

On 2014-02-23 16:04 +0100, Thomas Petazzoni spake thusly:

Quoted 1 line

Regards,
Yann E. MORIN.

Quoted 71 lines
---
 docs/manual/common-usage.txt | 52 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
docs/manual/common-usage.txt +52 -0
index 9a8c92a..bef42c6 100644
@@ -149,3 +149,55 @@ of an ext2 filesystem may be corrupted; or, if you have sparse files in
 your filesystem, those parts may not be all-zeroes when read back). You
 should only use sparse files when handling files on the build machine, not
 when transferring them to an actual device that will be used on the target.
+
+Graphing the dependencies between packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[[graph-depends]]
+
+One of Buildroot's jobs is to know the dependencies between packages,
+and make sure they are built in the right order. These dependencies
+can sometimes be quite complicated, and for a given system, it is
+often not easy to understand why such or such package was brought into
+the build by Buildroot.
+
+In order to help understanding the dependencies, and therefore better
+understand what is the role of the different components in your
+embedded Linux system, Buildroot is capable of generating dependency
+graphs.
+
+To generate a dependency graph of the full system you have compiled,
+simply run:
+
+------------------------
+make graph-depends
+------------------------
+
+You will find the generated graph in
++output/graphs/graph-depends.pdf+.
+
+If your system is quite large, the dependency graph may be too complex
+and difficult to read. It is therefore possible to generate the
+dependency graph just for a given package:
+
+------------------------
+make <pkg>-graph-depends
+------------------------
+
+You will find the generated graph in
++output/graph/<pkg>-graph-depends.pdf+.
+
+Note that the dependency graphs are generated using the +dot+ tool
+from the _Graphviz_ project, which you must have installed on your
+system to use this feature. In most distributions, it is available as
+the +graphviz+ package.
+
+By default, the dependency graphs are generated in the PDF
+format. However, by passing the +GRAPH_OUT+ environment variable, you
+can switch to other output formats, such as PNG, PostScript or
+SVG. All formats supported by the +-T+ option of the +dot+ tool are
+supported.
+
+--------------------------------
+GRAPH_OUT=svg make graph-depends
+--------------------------------
Signature · 6 lines
1.8.3.2

_______________________________________________
buildroot mailing list
buildroot at busybox.net
http://lists.busybox.net/mailman/listinfo/buildroot
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'
#12 lore raw

PATCH 6/13 docs/manual: add section about build time graphing

In reply to Thomas Petazzoni
---
 docs/manual/common-usage.txt | 47 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)
docs/manual/common-usage.txt +47 -0
index bef42c6..76e4023 100644
@@ -201,3 +201,50 @@ supported.
 --------------------------------
 GRAPH_OUT=svg make graph-depends
 --------------------------------
+
+Graphing the build duration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[[graph-duration]]
+
+When the build of a system takes a long time, it is sometimes useful
+to be able to understand which packages are the longest to build, to
+see if anything can be done to speed up the build. In order to help
+such build time analysis, Buildroot collects the build time of each
+step of each package, and allows to generate graphs from these data.
+
+To generate the build time graph after a build, run:
+
+----------------
+make graph-build
+----------------
+
+This will generate a set of files in +output/graphs+ :
+
+* +build.hist-build.pdf+, an histogram of the build time for each
+  package, ordered in the build order.
+
+* +build.hist-duration.pdf+, an histogram of the build time for each
+  package, ordered by duration (longest first)
+
+* +build.hist-name.pdf+, an histogram of the build time for each
+  package, order by package name.
+
+* +build.pie-packages.pdf+, a pie chart of the build time per package
+
+* +build.pie-steps.pdf+, a pie chart of the global time spent in each
+  step of the packages build process.
+
+This +graph-build+ target requires the Python Matplotlib and Numpy
+libraries to be installed (+python-matplotlib+ and +python-numpy+ on
+most distributions), and also the +argparse+ module if you're using a
+Python version older than 2.7 (+python-argparse+ on most
+distributions).
+
+By default, the output format for the graph is PDF, but a different
+format can be selected using the +GRAPH_OUT+ environment variable. The
+only other format supported is PNG:
+
+----------------
+GRAPH_OUT=png make graph-build
+----------------
Signature · 1 line
1.8.3.2
#13 lore raw

PATCH 6/13 docs/manual: add section about build time graphing

Thomas, All,

On 2014-02-23 16:04 +0100, Thomas Petazzoni spake thusly:

Quoted 50 lines
---
 docs/manual/common-usage.txt | 47 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)
docs/manual/common-usage.txt +37 -0
index bef42c6..76e4023 100644
@@ -201,3 +201,50 @@ supported.
 --------------------------------
 GRAPH_OUT=svg make graph-depends
 --------------------------------
+
+Graphing the build duration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[[graph-duration]]
+
+When the build of a system takes a long time, it is sometimes useful
+to be able to understand which packages are the longest to build, to
+see if anything can be done to speed up the build. In order to help
+such build time analysis, Buildroot collects the build time of each
+step of each package, and allows to generate graphs from these data.
+
+To generate the build time graph after a build, run:
+
+----------------
+make graph-build
+----------------
+
+This will generate a set of files in +output/graphs+ :
+
+* +build.hist-build.pdf+, an histogram of the build time for each
+  package, ordered in the build order.
+
+* +build.hist-duration.pdf+, an histogram of the build time for each
+  package, ordered by duration (longest first)
+
+* +build.hist-name.pdf+, an histogram of the build time for each
+  package, order by package name.
+
+* +build.pie-packages.pdf+, a pie chart of the build time per package
+
+* +build.pie-steps.pdf+, a pie chart of the global time spent in each
+  step of the packages build process.
+
+This +graph-build+ target requires the Python Matplotlib and Numpy
+libraries to be installed (+python-matplotlib+ and +python-numpy+ on
+most distributions), and also the +argparse+ module if you're using a

docs/manual/common-usage.txt supported. · line 250

Quoted 10 lines
docs/manual/common-usage.txt +10 -0
+Python version older than 2.7 (+python-argparse+ on most
+distributions).
+
+By default, the output format for the graph is PDF, but a different
+format can be selected using the +GRAPH_OUT+ environment variable. The
+only other format supported is PNG:
+
+----------------
+GRAPH_OUT=png make graph-build
+----------------

We also have GRAPH_ALT which sets an alternative colour-scheme for the time graphs:
GRAPH_ALT=y make graph-build

Which can be combined with GRAPH_OUT, of course.

Regards,
Yann E. MORIN.

Signature · 6 lines
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'
#14 lore raw

PATCH 7/13 docs/manual: update informations about C library in internal backend

In reply to Thomas Petazzoni

Now that we have eglibc and glibc support in the internal backend, and no longer marked as experimental, a little bit of rewording is needed. It is no longer necessary to indicate that uClibc was historically supported as the only C library, and that the glibc support is experimental. We also update the rest of the description to be less uClibc specific.

---
 docs/manual/configure.txt | 30 +++++++++++-------------------
 1 file changed, 11 insertions(+), 19 deletions(-)
docs/manual/configure.txt +11 -19
index 89df3d9..b566e8a 100644
@@ -68,12 +68,10 @@ The _internal toolchain backend_ is the backend where Buildroot builds
 by itself a cross-compilation toolchain, before building the userspace
 applications and libraries for your target embedded system.
 
-This backend is the historical backend of Buildroot, and has been
-limited for a long time to the usage of the
-http://www.uclibc.org[uClibc C library]. Support for the _eglibc_ C
-library has been added in 2013 and is at this point considered
-experimental. See the _External toolchain backend_ for another
-solution to use _glibc_ or _eglibc_.
+This backend supports several C libraries:
+http://www.uclibc.org[uClibc], the
+http://www.gnu.org/software/libc/libc.html[glibc] and
+http://www.eglibc.org[eglibc].
 
 Once you have selected this backend, a number of options appear. The
 most important ones allow to:
@@ -96,18 +94,7 @@ most important ones allow to:
    the C library might be using interfaces that are not provided by
    your Linux kernel.
 
- * Change the version and the configuration of the uClibc C library
-   (if uClibc is selected). The default options are usually
-   fine. However, if you really need to specifically customize the
-   configuration of your uClibc C library, you can pass a specific
-   configuration file here. Or alternatively, you can run the +make
-   uclibc-menuconfig+ command to get access to uClibc's configuration
-   interface. Note that all packages in Buildroot are tested against
-   the default uClibc configuration bundled in Buildroot: if you
-   deviate from this configuration by removing features from uClibc,
-   some packages may no longer build.
-
- * Change the version of the GCC compiler and binutils.
+ * Change the version of the GCC compiler, binutils and the C library.
 
  * Select a number of toolchain options (uClibc only): whether the
    toolchain should have largefile support (i.e support for files
@@ -118,7 +105,12 @@ most important ones allow to:
    libraries visible in Buildroot menus will change: many applications
    and libraries require certain toolchain options to be enabled. Most
    packages show a comment when a certain toolchain option is required
-   to be able to enable those packages.
+   to be able to enable those packages. If needed, you can further
+   refine the uClibc configuration by running +make
+   uclibc-menuconfig+. Note however that all packages in Buildroot are
+   tested against the default uClibc configuration bundled in
+   Buildroot: if you deviate from this configuration by removing
+   features from uClibc, some packages may no longer build.
 
 It is worth noting that whenever one of those options is modified,
 then the entire toolchain and system must be rebuilt. See
Signature · 1 line
1.8.3.2
#15 lore raw

PATCH 7/13 docs/manual: update informations about C library in internal backend

Thomas, All,

On 2014-02-23 16:04 +0100, Thomas Petazzoni spake thusly:

Quoted 18 lines

Now that we have eglibc and glibc support in the internal backend, and no longer marked as experimental, a little bit of rewording is needed. It is no longer necessary to indicate that uClibc was historically supported as the only C library, and that the glibc support is experimental. We also update the rest of the description to be less uClibc specific.

---
 docs/manual/configure.txt | 30 +++++++++++-------------------
 1 file changed, 11 insertions(+), 19 deletions(-)
docs/manual/configure.txt +0 -0
index 89df3d9..b566e8a 100644
@@ -68,12 +68,10 @@ The _internal toolchain backend_ is the backend where Buildroot builds
 by itself a cross-compilation toolchain, before building the userspace

docs/manual/configure.txt The _internal toolchain backend_ is the backend where Buildroot builds · line 72

Quoted 10 lines
docs/manual/configure.txt +2 -6
 applications and libraries for your target embedded system.
 
-This backend is the historical backend of Buildroot, and has been
-limited for a long time to the usage of the
-http://www.uclibc.org[uClibc C library]. Support for the _eglibc_ C
-library has been added in 2013 and is at this point considered
-experimental. See the _External toolchain backend_ for another
-solution to use _glibc_ or _eglibc_.
+This backend supports several C libraries:
+http://www.uclibc.org[uClibc], the

s/the// since you don't do it for the other two.

docs/manual/configure.txt most important ones allow to: · line 95

Quoted 8 lines
docs/manual/configure.txt +2 -0
+http://www.gnu.org/software/libc/libc.html[glibc] and
+http://www.eglibc.org[eglibc].
 
 Once you have selected this backend, a number of options appear. The
 most important ones allow to:
@@ -96,18 +94,7 @@ most important ones allow to:
    the C library might be using interfaces that are not provided by
    your Linux kernel.

Unrelated to your patch, but what about:
[...] the C library might be using interfaces, or exposing thos interfaces to applications, that are not provided by the running Linux kernel.

Quoted 20 lines
docs/manual/configure.txt +1 -12
- * Change the version and the configuration of the uClibc C library
-   (if uClibc is selected). The default options are usually
-   fine. However, if you really need to specifically customize the
-   configuration of your uClibc C library, you can pass a specific
-   configuration file here. Or alternatively, you can run the +make
-   uclibc-menuconfig+ command to get access to uClibc's configuration
-   interface. Note that all packages in Buildroot are tested against
-   the default uClibc configuration bundled in Buildroot: if you
-   deviate from this configuration by removing features from uClibc,
-   some packages may no longer build.
-
- * Change the version of the GCC compiler and binutils.
+ * Change the version of the GCC compiler, binutils and the C library.
 
  * Select a number of toolchain options (uClibc only): whether the
    toolchain should have largefile support (i.e support for files
@@ -118,7 +105,12 @@ most important ones allow to:
    libraries visible in Buildroot menus will change: many applications
    and libraries require certain toolchain options to be enabled. Most
    packages show a comment when a certain toolchain option is required

docs/manual/configure.txt most important ones allow to: · line 116

Quoted 10 lines
docs/manual/configure.txt +6 -1
-   to be able to enable those packages.
+   to be able to enable those packages. If needed, you can further
+   refine the uClibc configuration by running +make
+   uclibc-menuconfig+. Note however that all packages in Buildroot are
+   tested against the default uClibc configuration bundled in
+   Buildroot: if you deviate from this configuration by removing
+   features from uClibc, some packages may no longer build.
 
 It is worth noting that whenever one of those options is modified,
 then the entire toolchain and system must be rebuilt. See

Otherwise, looks good.

Regards,
Yann E. MORIN.

Signature · 6 lines
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'
#16 lore raw

PATCH 8/13 docs/manual: update external toolchain examples

In reply to Thomas Petazzoni

Replace ADI by Analog Devices, which is clearer for most people, and remove the Xilinx external toolchains since we have deprecated them.

---
 docs/manual/configure.txt | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)
docs/manual/configure.txt +3 -4
index b566e8a..a6afafb 100644
@@ -138,10 +138,9 @@ http://www.linaro.org[Linaro] for ARM,
 http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/[Sourcery
 CodeBench] for ARM, x86, x86-64, PowerPC, MIPS and SuperH,
 https://blackfin.uclinux.org/gf/project/toolchain[Blackfin toolchains
-from ADI], http://git.xilinx.com/[Xilinx toolchains for Microblaze],
-etc.) and is capable of downloading them automatically, or it can be
-pointed to a custom toolchain, either available for download or
-installed locally.
+from Analog Devices], etc.) and is capable of downloading them
+automatically, or it can be pointed to a custom toolchain, either
+available for download or installed locally.
 
 Then, you have three solutions to use an external toolchain:
 
Signature · 1 line
1.8.3.2
#17 lore raw

PATCH 8/13 docs/manual: update external toolchain examples

Thomas, All,

On 2014-02-23 16:04 +0100, Thomas Petazzoni spake thusly:

Quoted 4 lines

Replace ADI by Analog Devices, which is clearer for most people, and remove the Xilinx external toolchains since we have deprecated them.

Regards,
Yann E. MORIN.

Quoted 29 lines
---
 docs/manual/configure.txt | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)
docs/manual/configure.txt +3 -4
index b566e8a..a6afafb 100644
@@ -138,10 +138,9 @@ http://www.linaro.org[Linaro] for ARM,
 http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/[Sourcery
 CodeBench] for ARM, x86, x86-64, PowerPC, MIPS and SuperH,
 https://blackfin.uclinux.org/gf/project/toolchain[Blackfin toolchains
-from ADI], http://git.xilinx.com/[Xilinx toolchains for Microblaze],
-etc.) and is capable of downloading them automatically, or it can be
-pointed to a custom toolchain, either available for download or
-installed locally.
+from Analog Devices], etc.) and is capable of downloading them
+automatically, or it can be pointed to a custom toolchain, either
+available for download or installed locally.
 
 Then, you have three solutions to use an external toolchain:
 
Signature · 6 lines
1.8.3.2

_______________________________________________
buildroot mailing list
buildroot at busybox.net
http://lists.busybox.net/mailman/listinfo/buildroot
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'
#18 lore raw

PATCH 9/13 docs/manual: mention that custom toolchains is also useful for BR toolchains

In reply to Thomas Petazzoni
---
 docs/manual/configure.txt | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)
docs/manual/configure.txt +8 -8
index a6afafb..42d84fe 100644
@@ -159,14 +159,14 @@ Then, you have three solutions to use an external toolchain:
   toolchain.
 
 * Use a completely custom external toolchain. This is particularly
-  useful for toolchains generated using crosstool-NG. To do this,
-  select the +Custom toolchain+ solution in the +Toolchain+ list. You
-  need to fill the +Toolchain path+, +Toolchain prefix+ and +External
-  toolchain C library+ options. Then, you have to tell Buildroot what
-  your external toolchain supports. If your external toolchain uses
-  the 'glibc' library, you only have to tell whether your toolchain
-  supports C\+\+ or not and whether it has built-in RPC support. If
-  your external toolchain uses the 'uClibc'
+  useful for toolchains generated using crosstool-NG or with Buildroot
+  itself. To do this, select the +Custom toolchain+ solution in the
+  +Toolchain+ list. You need to fill the +Toolchain path+, +Toolchain
+  prefix+ and +External toolchain C library+ options. Then, you have
+  to tell Buildroot what your external toolchain supports. If your
+  external toolchain uses the 'glibc' library, you only have to tell
+  whether your toolchain supports C\+\+ or not and whether it has
+  built-in RPC support. If your external toolchain uses the 'uClibc'
   library, then you have to tell Buildroot if it supports largefile,
   IPv6, RPC, wide-char, locale, program invocation, threads and
   C++. At the beginning of the execution, Buildroot will tell you if
Signature · 1 line
1.8.3.2
#19 lore raw

PATCH 9/13 docs/manual: mention that custom toolchains is also useful for BR toolchains

Thomas, All,

On 2014-02-23 16:04 +0100, Thomas Petazzoni spake thusly:

Quoted 1 line

Regards,
Yann E. MORIN.

Quoted 38 lines
---
 docs/manual/configure.txt | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)
docs/manual/configure.txt +8 -8
index a6afafb..42d84fe 100644
@@ -159,14 +159,14 @@ Then, you have three solutions to use an external toolchain:
   toolchain.
 
 * Use a completely custom external toolchain. This is particularly
-  useful for toolchains generated using crosstool-NG. To do this,
-  select the +Custom toolchain+ solution in the +Toolchain+ list. You
-  need to fill the +Toolchain path+, +Toolchain prefix+ and +External
-  toolchain C library+ options. Then, you have to tell Buildroot what
-  your external toolchain supports. If your external toolchain uses
-  the 'glibc' library, you only have to tell whether your toolchain
-  supports C\+\+ or not and whether it has built-in RPC support. If
-  your external toolchain uses the 'uClibc'
+  useful for toolchains generated using crosstool-NG or with Buildroot
+  itself. To do this, select the +Custom toolchain+ solution in the
+  +Toolchain+ list. You need to fill the +Toolchain path+, +Toolchain
+  prefix+ and +External toolchain C library+ options. Then, you have
+  to tell Buildroot what your external toolchain supports. If your
+  external toolchain uses the 'glibc' library, you only have to tell
+  whether your toolchain supports C\+\+ or not and whether it has
+  built-in RPC support. If your external toolchain uses the 'uClibc'
   library, then you have to tell Buildroot if it supports largefile,
   IPv6, RPC, wide-char, locale, program invocation, threads and
   C++. At the beginning of the execution, Buildroot will tell you if
Signature · 6 lines
1.8.3.2

_______________________________________________
buildroot mailing list
buildroot at busybox.net
http://lists.busybox.net/mailman/listinfo/buildroot
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'
#20 lore raw

PATCH 10/13 docs/manual: rephrase paragraph about unsupported external toolchains

In reply to Thomas Petazzoni

The ELDK now relies on Yocto, so it no longer has the funky non-standard way of doing multilib. Also, we didn't mention that Yocto toolchains/SDK are not suitable for usage with Buildroot. Therefore, this commit rewords this part of the documentation to explain that Yocto/OpenEmbedded SDKs cannot be used as external toolchains in Buildroot, and why.

---
 docs/manual/configure.txt | 24 +++++++-----------------
 1 file changed, 7 insertions(+), 17 deletions(-)
docs/manual/configure.txt +7 -17
index 42d84fe..9a12440 100644
@@ -179,23 +179,13 @@ Buildroot itself. In general, all toolchains that support the
 'sysroot' feature should work. If not, do not hesitate to contact the
 developers.
 
-We do not support toolchains from the
-http://www.denx.de/wiki/DULG/ELDK[ELDK] of Denx, for two reasons:
-
-* The ELDK does not contain a pure toolchain (i.e just the compiler,
-  binutils, the C and C++ libraries), but a toolchain that comes with
-  a very large set of pre-compiled libraries and programs. Therefore,
-  Buildroot cannot import the 'sysroot' of the toolchain, as it would
-  contain hundreds of megabytes of pre-compiled libraries that are
-  normally built by Buildroot.
-
-* The ELDK toolchains have a completely non-standard custom mechanism
-  to handle multiple library variants. Instead of using the standard
-  GCC 'multilib' mechanism, the ARM ELDK uses different symbolic links
-  to the compiler to differentiate between library variants (for ARM
-  soft-float and ARM VFP), and the PowerPC ELDK compiler uses a
-  +CROSS_COMPILE+ environment variable. This non-standard behaviour
-  makes it difficult to support ELDK in Buildroot.
+We do not support toolchains or SDK generated by OpenEmbedded or
+Yocto, because these toolchains are not pure toolchains (i.e just the
+compiler, binutils, the C and C++ libraries). Instead these toolchains
+come with a very large set of pre-compiled libraries and
+programs. Therefore, Buildroot cannot import the 'sysroot' of the
+toolchain, as it would contain hundreds of megabytes of pre-compiled
+libraries that are normally built by Buildroot.
 
 We also do not support using the distribution toolchain (i.e the
 gcc/binutils/C library installed by your distribution) as the
Signature · 1 line
1.8.3.2
#21 lore raw

PATCH 11/13 docs/manual: refresh informations about *-menuconfig targets

In reply to Thomas Petazzoni
---
 docs/manual/make-tips.txt | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)
docs/manual/make-tips.txt +4 -2
index 0159ffe..faf59f2 100644
@@ -32,10 +32,12 @@ The result of the search shows the help message of the matching items.
 Not all targets are always available,
 some settings in the +.config+ file may hide some targets:
 
+* +busybox-menuconfig+ and +busybox-savedefconfig+ ony work when
+  +busybox+ is enabled;
 * +linux-menuconfig+ and +linux-savedefconfig+ only work when
   +linux+ is enabled;
-* +uclibc-menuconfig+ is only available when the
-  Buildroot internal toolchain backend is used;
+* +uclibc-menuconfig+ is only available when the uClibc C library is
+  selected in the internal toolchain backend;
 * +barebox-menuconfig+ and +barebox-savedefconfig+ only work when the
   +barebox+ bootloader is enabled.
 
Signature · 1 line
1.8.3.2
#22 lore raw

PATCH 11/13 docs/manual: refresh informations about *-menuconfig targets

Thomas, All,

On 2014-02-23 16:04 +0100, Thomas Petazzoni spake thusly:

Quoted 1 line

Regards,
Yann E. MORIN.

Quoted 30 lines
---
 docs/manual/make-tips.txt | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)
docs/manual/make-tips.txt +4 -2
index 0159ffe..faf59f2 100644
@@ -32,10 +32,12 @@ The result of the search shows the help message of the matching items.
 Not all targets are always available,
 some settings in the +.config+ file may hide some targets:
 
+* +busybox-menuconfig+ and +busybox-savedefconfig+ ony work when
+  +busybox+ is enabled;
 * +linux-menuconfig+ and +linux-savedefconfig+ only work when
   +linux+ is enabled;
-* +uclibc-menuconfig+ is only available when the
-  Buildroot internal toolchain backend is used;
+* +uclibc-menuconfig+ is only available when the uClibc C library is
+  selected in the internal toolchain backend;
 * +barebox-menuconfig+ and +barebox-savedefconfig+ only work when the
   +barebox+ bootloader is enabled.
 
Signature · 6 lines
1.8.3.2

_______________________________________________
buildroot mailing list
buildroot at busybox.net
http://lists.busybox.net/mailman/listinfo/buildroot
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'
#23 lore raw

PATCH 12/13 docs/manual: document the usage of <pkg>_OVERRIDE_SRCDIR

In reply to Thomas Petazzoni
---
 docs/manual/advanced.txt                    |  2 +
 docs/manual/using-buildroot-development.txt | 84 +++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+)
 create mode 100644 docs/manual/using-buildroot-development.txt
docs/manual/advanced.txt +2 -0
index 764b71a..fb337f5 100644
@@ -11,3 +11,5 @@ include::ccache-support.txt[]
 include::download-location.txt[]
 
 include::package-make-target.txt[]
+
+include::using-buildroot-development.txt[]
docs/manual/using-buildroot-development.txt new file +84 -0

84 lines not on this page · raw message

Signature · 1 line
1.8.3.2
#24 lore raw

PATCH 12/13 docs/manual: document the usage of <pkg>_OVERRIDE_SRCDIR

Thomas, All,

On 2014-02-23 16:04 +0100, Thomas Petazzoni spake thusly:

Quoted 23 lines
---
 docs/manual/advanced.txt                    |  2 +
 docs/manual/using-buildroot-development.txt | 84 +++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+)
 create mode 100644 docs/manual/using-buildroot-development.txt
docs/manual/advanced.txt +2 -0
index 764b71a..fb337f5 100644
@@ -11,3 +11,5 @@ include::ccache-support.txt[]
 include::download-location.txt[]
 
 include::package-make-target.txt[]
+
+include::using-buildroot-development.txt[]
docs/manual/using-buildroot-development.txt new file +0 -0
new file mode 100644
index 0000000..3267302

docs/manual/using-buildroot-development.txt line 10

Quoted 10 lines
docs/manual/using-buildroot-development.txt new file +10 -0
@@ -0,0 +1,84 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Using Buildroot during development
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The normal operation of Buildroot is to download a tarball, extract
+it, configure, compile and install the software component found inside
+this tarball. The source code is extracted in
++output/build/<package>-<name>+, which is a temporary directory:

output/build/<package>-<version>

docs/manual/using-buildroot-development.txt line 15

Quoted 5 lines
docs/manual/using-buildroot-development.txt new file +5 -0
+whenever +make clean+ is used, this directory is entirely removed, and
+re-recreated at the next +make+ invocation. Even when a Git or
+Subversion repository is used as the input for the package source
+code, Buildroot creates a tarball out of it, and then behaves as it
+does normally with tarballs.

normally does

docs/manual/using-buildroot-development.txt line 25

Quoted 9 lines
docs/manual/using-buildroot-development.txt new file +9 -0
+This behavior is well-suited when Buildroot is used mainly as an
+integration tool, to build and integrate all the components of an
+embedded Linux system. However, if one uses Buildroot during the
+development of certain components of the system, this behavior is not
+very convenient: one would instead like to make a small change to the
+source code of one package, and be able to quickly rebuild the system
+with Buildroot.
+
+Making changes directly in +output/build/<package>-<name>+ is not

output/build/<package>-<version>

docs/manual/using-buildroot-development.txt

Quoted 9 lines
docs/manual/using-buildroot-development.txt new file +9 -0
+appropriate solution, because this directory is removed on +make
+clean+.
+
+Therefore, Buildroot provides a specific mechanism for this use case:
+the +<pkg>_OVERRIDE_SRCDIR+ mechanism. Buildroot reads an _override_
+file, which allows the user to tell Buildroot the location of the
+source for certain packages. By default this _override_ file is named
++local.mk+ and located in the top directory of the Buildroot source
+tree,

Wrong, now it is locate in $(CONFIG_DIR), that is, the directory where we have the .config file, since:

    b1e514d Config: default BR2_PACKAGE_OVERRIDE_FILE to $(CONFIG_DIR)/local.mk

This is Buildroot's top dir when building in-tree, and for out-of-tree builds, it's in $(O).

[--SNIP--]

Otherwise, LGTM.

Regards,
Yann E. MORIN.

Signature · 6 lines
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'
#25 lore raw

PATCH 12/13 docs/manual: document the usage of <pkg>_OVERRIDE_SRCDIR

Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line

"Yann" == Yann E MORIN <[email protected]> writes:

Hi,

Quoted 12 lines

docs/manual/using-buildroot-development.txt

Quoted 9 lines
docs/manual/using-buildroot-development.txt new file +9 -0
+appropriate solution, because this directory is removed on +make
+clean+.
+
+Therefore, Buildroot provides a specific mechanism for this use case:
+the +<pkg>_OVERRIDE_SRCDIR+ mechanism. Buildroot reads an _override_
+file, which allows the user to tell Buildroot the location of the
+source for certain packages. By default this _override_ file is named
++local.mk+ and located in the top directory of the Buildroot source
+tree,

Wrong, now it is locate in $(CONFIG_DIR), that is, the directory where we have the .config file, since:

Quoted 4 lines
    b1e514d Config: default BR2_PACKAGE_OVERRIDE_FILE to $(CONFIG_DIR)/local.mk

This is Buildroot's top dir when building in-tree, and for out-of-tree builds, it's in $(O).

True, but that commit is only in next, and I imho think this series belongs on master, so I'll leave it for now.

Signature · 1 line
Bye, Peter Korsgaard
#26 lore raw

PATCH 12/13 docs/manual: document the usage of <pkg>_OVERRIDE_SRCDIR

On 2014-02-23 22:29 +0100, Peter Korsgaard spake thusly:

Quoted 18 lines
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line

"Yann" == Yann E MORIN <[email protected]> writes:

Hi,

Quoted 13 lines

docs/manual/using-buildroot-development.txt

Quoted 9 lines
docs/manual/using-buildroot-development.txt new file +9 -0
+appropriate solution, because this directory is removed on +make
+clean+.
+
+Therefore, Buildroot provides a specific mechanism for this use case:
+the +<pkg>_OVERRIDE_SRCDIR+ mechanism. Buildroot reads an _override_
+file, which allows the user to tell Buildroot the location of the
+source for certain packages. By default this _override_ file is named
++local.mk+ and located in the top directory of the Buildroot source
+tree,

Wrong, now it is locate in $(CONFIG_DIR), that is, the directory where we have the .config file, since:

    b1e514d Config: default BR2_PACKAGE_OVERRIDE_FILE to $(CONFIG_DIR)/local.mk
Quoted 5 lines
Quoted 2 lines

This is Buildroot's top dir when building in-tree, and for out-of-tree builds, it's in $(O).

True, but that commit is only in next, and I imho think this series belongs on master, so I'll leave it for now.

Right! In fact, I was looking at my tree, which has it. It's eda3d0e on -next.

And I agree, this series belongs to master. We'll just have to remember it at merge time.

Sorry for the disruption.

Regards,
Yann E. MORIN.

Signature · 6 lines
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'
#27 lore raw

PATCH 13/13 docs/manual: mention the per-package graph-depends target

In reply to Thomas Petazzoni
---
 docs/manual/package-make-target.txt | 5 +++++
 1 file changed, 5 insertions(+)
docs/manual/package-make-target.txt +5 -0
index 9eefe68..bd514f4 100644
@@ -63,6 +63,11 @@ Additionally, there are some other useful make targets:
 | +show-depends+    | Displays the dependencies required to build the
 package
 
+| +graph-depends+   | Generate a dependency graph of the package, in the
+context of the current Buildroot configuration. See
+xref:graph-depends[this section] for more details about dependency
+graphs.
+
 | +dirclean+        | Remove the whole package build directory
 
 | +rebuild+         | Re-run the compilation commands - this only makes
Signature · 1 line
1.8.3.2
#28 lore raw

PATCH 13/13 docs/manual: mention the per-package graph-depends target

Thomas, All,

On 2014-02-23 16:04 +0100, Thomas Petazzoni spake thusly:

Quoted 1 line

Regards,
Yann E. MORIN.

Quoted 27 lines
---
 docs/manual/package-make-target.txt | 5 +++++
 1 file changed, 5 insertions(+)
docs/manual/package-make-target.txt +5 -0
index 9eefe68..bd514f4 100644
@@ -63,6 +63,11 @@ Additionally, there are some other useful make targets:
 | +show-depends+    | Displays the dependencies required to build the
 package
 
+| +graph-depends+   | Generate a dependency graph of the package, in the
+context of the current Buildroot configuration. See
+xref:graph-depends[this section] for more details about dependency
+graphs.
+
 | +dirclean+        | Remove the whole package build directory
 
 | +rebuild+         | Re-run the compilation commands - this only makes
Signature · 6 lines
1.8.3.2

_______________________________________________
buildroot mailing list
buildroot at busybox.net
http://lists.busybox.net/mailman/listinfo/buildroot
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'
#29 lore raw

cover Documentation updates and improvements

In reply to Thomas Petazzoni
Quoted 19 lines
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line

"Thomas" == Thomas Petazzoni <[email protected]> writes:

Hello,
Here is a set of documentation updates and improvements, about toolchains, package infrastructures, dependency and build-time graphing, and also finally a documentation about <pkg>_OVERRIDE_SRCDIR.

Thomas

Thomas Petazzoni (13):
docs/manual: toolchain packages no longer use custom makefiles docs/manual: rephrase part about rebuilding packages docs/manual: rephrase and expand part on when a full rebuild is
necessary
docs/manual: reference Python and Lua infras from the list of package
infrastructures
docs/manual: add section about dependency graphs docs/manual: add section about build time graphing

Quoted 8 lines

docs/manual: update informations about C library in internal backend docs/manual: update external toolchain examples docs/manual: mention that custom toolchains is also useful for BR
toolchains
docs/manual: rephrase paragraph about unsupported external toolchains docs/manual: refresh informations about *-menuconfig targets docs/manual: document the usage of <pkg>_OVERRIDE_SRCDIR docs/manual: mention the per-package graph-depends target

Committed series with the minor changes suggested by Yann, thanks.

Signature · 1 line
Bye, Peter Korsgaard