Some more changes you could include:
On 18.07.2017 15:27, Ulrich Ölmann wrote:
> Signed-off-by: Ulrich Ölmann <u.oelm...@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
