Re: [ptxdist] [PATCH] doc: pre-built packages: fix typos, enhance some formulations & occasionally add information

[Roland Hieber <r.hieber@pengutronix.de>]

Some more changes you could include:

On 18.07.2017 15:27, Ulrich Ölmann wrote:
> Signed-off-by: Ulrich Ölmann <u.oelmann@pengutronix.de>
> ---
>  doc/daily_work.inc | 134 ++++++++++++++++++++++++++++-------------------------
>  1 file changed, 71 insertions(+), 63 deletions(-)
> 
> diff --git a/doc/daily_work.inc b/doc/daily_work.inc
> index 460693021606..46c4852c2547 100644
> --- a/doc/daily_work.inc
> +++ b/doc/daily_work.inc
> @@ -566,10 +566,10 @@ packages at the same time. Never worry again about your local host and
>  how slow it is. With the help of *ICECC* every host will be a high speed
>  development machine.
>  
> -Using pre-build archives
> +Using Pre-Built Archives
>  ------------------------
>  
> -PTXdist is a tool which creates all the required parts of a target’s
> +PTXdist is a tool which creates all the required parts of a target's

Is there a reason why you changed Unicode quotation marks for ASCII apostrophes?

>  filesystem to breathe life into it. And it creates these parts from any
>  kind of source files. If a PTXdist project consists of many packages the
>  build may take a huge amount of time.
> @@ -582,30 +582,30 @@ about 6 hours.
>  Introduction
>  ~~~~~~~~~~~~
>  
> -While the development of a PTXdist project it is needed to clean and
> +While developing a PTXdist project it is necessary to clean and
>  re-build everything from time to time to get a re-synced project result
>  which honors all changes made in the project. But since cleaning and
> -re-building everything from time to time is a very good test case if
> +re-building everything from time to time is a very good test case for if
>  some adaptions are still missing or if everything is complete, it can be
>  a real time sink to do so.
>  
> -To not lose developer’s temper when doing such tests, PTXdist can keep
> -archives from the last run which includes all the files the package’s
> -build system has installed while the PTXdist’s *install* stage runs for
> +To not lose developer's temper when doing such tests, PTXdist can keep
> +archives from the last run which includes all the files the package's
> +build system has installed while the PTXdist's *install* stage runs for
>  it.
>  
> -The next time PTXdist should build a package it can use the results from
> +The next time PTXdist shall build a package it can use the results from
>  the last run instead. This feature can drastically reduce the time to
>  re-build the whole project. But also, this PTXdist feature must handle

                          while we're at it:  must be handled ----------^

>  with care and so it is not enabled and used as default.
>  
>  This section describes how to make use of this PTXdist feature and what
> -pitfalls exists when doing so.
> +pitfalls exist when doing so.
>  
> -Creating pre-build archives
> +Creating Pre-Built Archives
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
> -To make PTXdist creating pre-build archives, enable this feature prior a
> +To make PTXdist create pre-built archives, enable this feature prior to a
>  build in the menu:
>  
>  ::
> @@ -613,7 +613,7 @@ build in the menu:
>      $ ptxdist menuconfig
>  
>          Project Name & Version --->
> -            [*] create pre-build archives
> +            [*] create pre-built archives
>  
>  Now run a regular build of the whole project:
>  
> @@ -622,14 +622,14 @@ Now run a regular build of the whole project:
>      $ ptxdist go
>  
>  When the build is finished, the directory ``packages`` contains
> -additional archives files with the name scheme ``*-dev.tar.gz``. These
> -files are the pre-build archives which PTXdist can use later on to
> +additional archive files with the name scheme ``*-dev.tar.gz``. These
> +files are the pre-built archives which PTXdist can use later on to
>  re-build the project.
>  
> -Using pre-build archives
> +Using Pre-Built Archives
>  ~~~~~~~~~~~~~~~~~~~~~~~~
>  
> -To make PTXdist using pre-build archives, enable this feature prior a
> +To make PTXdist use pre-built archives, enable this feature prior to a
>  build in the menu:
>  
>  ::
> @@ -637,90 +637,96 @@ build in the menu:
>      $ ptxdist menuconfig
>  
>          Project Name & Version --->
> -            [*] use pre-build archives
> +            [*] use pre-built archives
>              (</some/path/to/the/archives>)
>  
> -With the next build (e.g. ``ptxdist go``) PTXdist will look for a
> -specific package if its corresponding pre-build archive does exist. If
> -it does exist and the used hash value in the pre-build archive’s
> +During the next build (e.g. ``ptxdist go``) PTXdist will look for a
> +specific package if its corresponding pre-built archive exists. If
> +it exists and the used hash value in the pre-built archive's
>  filename matches, PTXdist will skip all source archive handling
>  (extract, patch, compile and install) and just extract and use the
> -pre-build archive’s content.
> +pre-built archive's content.
>  
> -A regular and save usecase of pre-build archives is:
> +Sufficient conditions for save application of pre-built archives are:

                             ^--- should be "safe" (adj), not "save" (verb)

> --  using one pre-build archive pool for one specific PTXdist project.
> +-  using one pre-built archive pool for one specific PTXdist project.
>  
>  -  using a constant PTXdist version all the time.
>  
>  -  using a constant OSELAS.Toolchain() version all the time.
>  
> --  no package with a pre-build archive in the project is under
> +-  no package with a pre-built archive in the project is under
>     development.
>  
> -The hash as a part of the pre-build archive’s filename does only reflect
> -the package’s configuration made in the menu (``ptxdist menuconfig``).
> +The hash as a part of the pre-built archive's filename does only reflect

My feeling for English would change this to "only reflects", less emphasis.

> +the package's configuration made in the menu (``ptxdist menuconfig``).
>  If this package specific configuration changes, a new hash value will be
> -the result and PTXdist can select the corresponding correct pre-build
> +the result and PTXdist can select the corresponding correctly pre-built
>  archive.
>  
>  This hash value change is an important fact, as many things outside and
>  inside the package can have a big impact of the binary result but
>  without a hash value change!
>  
> -Please be careful when using the pre-build archives if you:
> +Please be careful when using the pre-built archives if you:
>  
>  -  intend to switch to a different toolchain with the next build.
>  
> --  change the patch set applied to the corresponding package, e.g. a
> +-  change the patch set applied to the corresponding package, e.g. the
>     package is under development.
>  
> --  change the hard coded configure settings in the package’s rule file,
> -   e.g. a package is under development
> +-  change the hard coded configure settings in the package's rule file,
> +   e.g. the package is under development.
>  
> --  intend to use one pre-build archive pool from different PTXdist
> +-  intend to use one pre-built archive pool from different PTXdist
>     projects.
>  
> -To consider all these precautions the generated pre-build archives are
> -not transfered automatically where the next build expects them. This
> +-  change a global PTXdist configuration parameter (e.g. PTXCONF_GLOBAL_IPV6).
> +
> +To consider all these precautions the generated pre-built archives are
> +not transferred automatically to where the next build expects them. This
>  must be done manually by the user of the PTXdist project. Doing so, we
> -can decide on a package by package base if its pre-build archive should
> +can decide on a package by package base if its pre-built archive should

                                      ^--- basis?
>  be used or not.
>  
> -Packages without pre-build archives support
> +If you are unsure if your modifications rendered some or all of your pre-built
> +archives invalid you can always delete and build them again to keep out of
> +harm's way.
> +
> +Packages without Pre-Built Archives Support
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
> -No host nor cross related packages can be used based on their pre-build
> -archives. These kind of packages are always (re-)built.
> +Neither host nor cross related packages support pre-built archives. These kind
> +of packages are always (re-)built.
>  
> -Only target related packages can be used based on their pre-build
> +Only target related packages can be used based on their pre-built
>  archives, but there are a few exceptions:
>  
> --  Linux kernel: It has an incomplete install stage, which results into
> -   an incomplete pre-build archive. Due to this, it cannot be used as a
> -   pre-build archive
> +-  Linux kernel: it has an incomplete install stage, which results in
> +   an incomplete pre-built archive. Due to this, it cannot be used as a
> +   pre-built archive.
>  
> --  Barebox bootloader: It has an incomplete install stage, which results
> -   into an incomplete pre-build archive. Due to this, it cannot be used
> -   as a pre-build archive
> +-  Barebox bootloader: it has an incomplete install stage, which results
> +   in an incomplete pre-built archive. Due to this, it cannot be used
> +   as a pre-built archive.
>  
> --  some other somehow broken packages all marked with a
> -   ``<packagename>_DEVPKG := NO`` in their corresponding rule file
> +-  a few somehow broken packages that are all explicitely marked with a
> +   ``<packagename>_DEVPKG := NO`` in their corresponding rule file.
>  
> -Workflow with pre-build archives
> +Workflow with Pre-Built Archives
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
> -We starting with an empty PTXdist project and enabling the pre-build
> +We are starting with an empty PTXdist project and enabling the pre-built
>  archive feature as mentioned in the previous section. After that
>  a regular build of the project can be made.
>  
> -When the build is finished its time to copy all the pre-build archives
> -of interest where the next build will expect them.
> +When the build is finished it's time to copy all the pre-built archives
> +of interest to where the next build will expect them.
>  The previous section mentions the step to enable their use. It also
>  allows to define a directory. The default path of this directory is made
> -from various other menu settings, to ensure the pre-build archives of
> -the current PTXdist project do not conflict with pre-build archives of
> -different PTXdist projects. To get an idea what the final path is, we
> +from various other menu settings to ensure the pre-built archives of
> +the current PTXdist project do not conflict with pre-built archives of
> +different PTXdist projects. To get an idea of what the final path is, we
>  can ask PTXdist.
>  
>  ::
> @@ -734,25 +740,27 @@ If this directory does not exist, we can simply create it:
>  
>      $ mkdir -p /home/jbe/OSELAS.BSP/Pengutronix/OSELAS.BSP-Pengutronix-Generic
>  
> -Now its time to copy the pre-build archives to this new directory. We
> -could simply copy all pre-build archives from the ``/packages``
> +Now its time to copy the pre-built archives to this new directory. We

       ^-- it's

> +could simply copy all pre-built archives from the ``/packages``
>  directory. But we should keep in mind, if any of the related packages
> -are under development, we must omit its corresponding pre-build archives
> +are under development, we must omit its corresponding pre-built archives

                                                               archive? --^
>  in this step.
>  
>  ::
>  
>      $ cp platform-<platformname>/packages/*-dev.tar.gz| /home/jbe/OSELAS.BSP/Pengutronix/OSELAS.BSP-Pengutronix-Generic

                                                         ^-- huh, why is there a pipe?

 - Roland

>  
> -Use cases
> +Use Cases
>  ~~~~~~~~~
>  
>  Some major possible use cases are covered in this section:
>  
> --  Speed up a re-build of one single project
> +-  speed up a re-build of one single project.
> +
> +-  share pre-built archives between two platforms based on the same
> +   architecture.
>  
> --  Sharing pre-build archives between two platforms based on the same
> -   architecture
> +-  increase reproducibility of binaries.
>  
>  To simply speed up a re-build of the whole project (without development
>  on any of the used packages) we just can copy all ``*-dev.tar.gz``
> @@ -760,11 +768,11 @@ archives after the first build to the location where PTXdist expects
>  them at the next build time.
>  
>  If two platforms are sharing the same architecture it is possible to
> -share pre-build archives as well. The best way it can work is, if both
> +share pre-built archives as well. The best way it can work is, if both
>  platforms are part of the same PTXdist project. They must also share the
>  same toolchain settings, patch series and rule files. If these
>  precautions are handled the whole project can be built for the first
> -platform and these pre-build archives can be used to build the project
> +platform and these pre-built archives can be used to build the project
>  for the second platform. This can reduce the required time to build the
>  second platform from hours to minutes.
>  
> 

_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de