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
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
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:
-- 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
+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
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
+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
in this step.
::
$ cp platform-<platformname>/packages/*-dev.tar.gz|
/home/jbe/OSELAS.BSP/Pengutronix/OSELAS.BSP-Pengutronix-Generic
-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.
--
2.11.0
_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de
