[v1] docs/manual/quickstart: Update output directory contents documentation.
diff mbox series

Message ID 20191118152814.12813-1-michael.drake@codethink.co.uk
State Changes Requested
Headers show
Series
  • [v1] docs/manual/quickstart: Update output directory contents documentation.
Related show

Commit Message

Michael Drake Nov. 18, 2019, 3:28 p.m. UTC
The documentation for the output/host/ directory has been updated
to mention that it contains the sysroot for the target toolchain,
as well as the host tools required for running buildroot.

The staging/ documentation has been updated to reflect that it is
a link to the target toolchain sysroot in the host/ directory.
---
 docs/manual/quickstart.txt | 28 +++++++++++++++-------------
 1 file changed, 15 insertions(+), 13 deletions(-)

Comments

Thomas Petazzoni Nov. 18, 2019, 4:21 p.m. UTC | #1
Hello Michael,

Thanks for this new iteration!

On Mon, 18 Nov 2019 15:28:14 +0000
Michael Drake <michael.drake@codethink.co.uk> wrote:

> The documentation for the output/host/ directory has been updated

A commit log should not be written using present perfect, but at the
present. Simply: "This commit updates the documentation to reflect ..."
or something like that. I suppose you're a native English speaker, so
you'll be much better than I can be at finding the right formulation.

> to mention that it contains the sysroot for the target toolchain,
> as well as the host tools required for running buildroot.
> 
> The staging/ documentation has been updated to reflect that it is

Here as well "has been updated" is confusing.

> a link to the target toolchain sysroot in the host/ directory.

We still need your Signed-off-by here.

> ---
>  docs/manual/quickstart.txt | 28 +++++++++++++++-------------
>  1 file changed, 15 insertions(+), 13 deletions(-)
> 
> diff --git a/docs/manual/quickstart.txt b/docs/manual/quickstart.txt
> index 74158ae249..642482a9f4 100644
> --- a/docs/manual/quickstart.txt
> +++ b/docs/manual/quickstart.txt
> @@ -87,15 +87,21 @@ This directory contains several subdirectories:
>    target). This directory contains one subdirectory for each of these
>    components.
>  
> -* +staging/+ which contains a hierarchy similar to a root filesystem
> -  hierarchy. This directory contains the headers and libraries of the
> -  cross-compilation toolchain and all the userspace packages selected
> -  for the target. However, this directory is 'not' intended to be
> -  the root filesystem for the target: it contains a lot of development
> -  files, unstripped binaries and libraries that make it far too big
> -  for an embedded system. These development files are used to compile
> -  libraries and applications for the target that depend on other
> -  libraries.
> +* +host/+ contains both the tools built for the host, and the sysroot
> +  of the target toolchain.  The former is an installation of tools
> +  compiled for the host that are needed for the proper execution of
> +  Buildroot, including the cross-compilation toolchain.  The latter
> +  is a hierarchy similar to a root filesystem hierarchy.  It contains
> +  the headers and libraries of the cross-compilation toolchain and all
> +  the userspace packages selected for the target.

As of today, it is in fact not true that the sysroot contains all
userspace packages selected for the target. Only packages that have
_INSTALL_STAGING = YES are installed in staging. Perhaps we should
rephrase this last sentence to something like:

	It contains the headers and libraries of all user-space
	packages that provide and install libraries used by other
	packages.

>  However, this
> +  directory is 'not' intended to be the root filesystem for the target:
> +  it contains a lot of development files, unstripped binaries and
> +  libraries that make it far too big for an embedded system. These
> +  development files are used to compile libraries and applications for
> +  the target that depend on other libraries.
> +
> +* +staging/+ is a symlink to the target toolchain sysroot inside
> +  +host/+, which exists for backwards compatibility.

Other than that, looks good to me. If your SoB line had been present, I
would have applied this version of patch and done the small tweaks
suggested here myself, but we really need your SoB.

Thanks!

Thomas

Patch
diff mbox series

diff --git a/docs/manual/quickstart.txt b/docs/manual/quickstart.txt
index 74158ae249..642482a9f4 100644
--- a/docs/manual/quickstart.txt
+++ b/docs/manual/quickstart.txt
@@ -87,15 +87,21 @@  This directory contains several subdirectories:
   target). This directory contains one subdirectory for each of these
   components.
 
-* +staging/+ which contains a hierarchy similar to a root filesystem
-  hierarchy. This directory contains the headers and libraries of the
-  cross-compilation toolchain and all the userspace packages selected
-  for the target. However, this directory is 'not' intended to be
-  the root filesystem for the target: it contains a lot of development
-  files, unstripped binaries and libraries that make it far too big
-  for an embedded system. These development files are used to compile
-  libraries and applications for the target that depend on other
-  libraries.
+* +host/+ contains both the tools built for the host, and the sysroot
+  of the target toolchain.  The former is an installation of tools
+  compiled for the host that are needed for the proper execution of
+  Buildroot, including the cross-compilation toolchain.  The latter
+  is a hierarchy similar to a root filesystem hierarchy.  It contains
+  the headers and libraries of the cross-compilation toolchain and all
+  the userspace packages selected for the target.  However, this
+  directory is 'not' intended to be the root filesystem for the target:
+  it contains a lot of development files, unstripped binaries and
+  libraries that make it far too big for an embedded system. These
+  development files are used to compile libraries and applications for
+  the target that depend on other libraries.
+
+* +staging/+ is a symlink to the target toolchain sysroot inside
+  +host/+, which exists for backwards compatibility.
 
 * +target/+ which contains 'almost' the complete root filesystem for
   the target: everything needed is present except the device files in
@@ -111,10 +117,6 @@  This directory contains several subdirectories:
   development files (headers, etc.) are not present, the binaries are
   stripped.
 
-* +host/+ contains the installation of tools compiled for the host
-  that are needed for the proper execution of Buildroot, including the
-  cross-compilation toolchain.
-
 These commands, +make menuconfig|nconfig|gconfig|xconfig+ and +make+, are the
 basic ones that allow to easily and quickly generate images fitting
 your needs, with all the features and applications you enabled.