[ptxdist] [PATCH 1/4] doc: dev_manual: improve Patch Series section

[ptxdist] [PATCH 1/4] doc: dev_manual: improve Patch Series section

[Roland Hieber]

A list is better readable here than prose.

Signed-off-by: Roland Hieber <r.hieber@pengutronix.de>
---
 doc/dev_manual.rst | 28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/doc/dev_manual.rst b/doc/dev_manual.rst
index a461f6851..ca682bccc 100644
--- a/doc/dev_manual.rst
+++ b/doc/dev_manual.rst
@@ -55,7 +55,7 @@ fail compiling some files, use wrong include paths or try to link
 against host libraries. To be successful in the embedded world, these
 types of failures must be fixed. If required, PTXdist provides such
 fixes per package. They are organized in *patch series* and can be found
-in the ``patches/`` directory within a subdirectory using the same name
+in a ``patches/`` directory within a subdirectory using the same name
 as the package itself.
 
 PTXdist uses the utility ``patch`` or ``quilt`` (or ``git`` on demand) to apply
@@ -65,26 +65,26 @@ which the patches must be applied.
 
 .. note:: Patches can be compressed.
 
-Besides the ``patches/`` directory at the main installation location,
-PTXdist searches two additional locations for a patch series for the
-package in question.
+Patches are looked for at several locations:
 
-One location is the project’s currently used platform directory. If the
-currently used platform is located in ``configs/``, PTXdist searches in
-./configs/|ptxdistPlatformConfigDir|/patches/<package name>
+1.  the ``patches/`` folder in your BSP (``${PTXDIST_WORKSPACE}/patches``)
 
-If no patch series was found in the platform directory, the next
-location PTXdist it searches for a patch series is the main project
-directory in ``./patches/<package name>``.
+2.  the folder ``patches/`` folder relative to your selected platformconfig
+    file (``${PTXDIST_PLATFORMCONFIGDIR}/patches``).
+    If your platformconfig file is at ``configs/platform-foo/platformconfig``,
+    this patch folder will be ``configs/platform-foo/patches/``.
 
-If both project local locations do not provide a patch series for the
-specific package, PTXdist falls back to the ``patches/`` directory at
-its main installation location.
+3.  the ``patches/`` folder in PTXdist's main installation directory
+    (``${PTXDIST_TOPDIR}/patches``)
+
+The list is tried from first to last.
+If no patches were found in one of the locations, the next location is tried.
+When all locations have been tried unsuccessfully, the package is not patched.
 
 This search order can be used to use specific patch series for specific
 cases.
 
--  platfom specific
+-  platform specific
 
 -  project specific
 
-- 
2.19.0


_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de

[ptxdist] [PATCH 2/4] doc: contributing: fix typos, add links, and make text easier to parse

[Roland Hieber]

Signed-off-by: Roland Hieber <r.hieber@pengutronix.de>
---
 doc/contributing.rst | 31 ++++++++++++++++---------------
 1 file changed, 16 insertions(+), 15 deletions(-)

diff --git a/doc/contributing.rst b/doc/contributing.rst
index 8e2d7883d..1db596c0e 100644
--- a/doc/contributing.rst
+++ b/doc/contributing.rst
@@ -6,13 +6,13 @@ PTXdist Packages
 
 While contributions to all parts of PTXdist are welcome, most contributions
 concern individual packages. Here is a checklist of things to look out for
-while creating or updating packages. These are not hard requirements but
+while creating or updating packages. These are not hard requirements, but
 there should be good reasons for different choices.
 
 How to Contribute
 ~~~~~~~~~~~~~~~~~
 
-Contributions should be sent as patches to the PTXdist mailing list. This
+Contributions should be sent as patches to the :ref:`PTXdist mailing list`. This
 is usually done with ``git send-email``.
 
 All patches must contain a descriptive subject and should, for all
@@ -26,11 +26,11 @@ Package Builds should be Reproducible
 
 Many packages autodetect which features are available. As a result, the
 exact features of a package may depend on the build host and the build
-order of the packages. To avoid this autodetection must be restricted as
+order of the packages. To avoid this, autodetection must be restricted as
 much as possible.
 
 For **autoconf** based packages, the first step is to specify all relevant
-``configure`` options. The :ref:`configure_helper` scripts can help filter
+``configure`` options. The :ref:`configure_helper` script can help filter
 out the unimportant options.
 
 There are also cache variables that can be used to enforce the outcome of
@@ -55,17 +55,17 @@ Packages Suboptions
 
 Suboptions for PTXdist packages are useful to make parts of the package
 optional. However, it is not always easy to decide what should be optional
-and how to map the build system options to packages suboptions. Here are a
+and how to map the build system options to package suboptions. Here are a
 few guidelines to help with that.
 
 -  Avoid unnecessary suboptions. When in doubt, use the package default or
    what other distributions use. If the creator of the package does not
-   know what to choose then the user wont either.
+   know what to choose, then the user won't either.
 -  Use suboptions to save disk space. If a feature adds extra dependencies
-   or uses a lot of space then a suboptions is useful to save the disk
+   or uses a lot of space then a suboption is useful to save disk
    space when the feature is not needed.
 -  Try to create high-level options. Some packages have very low-level
-   build options with very few useful combinations. Try to define
+   build options with very few useful combinations. Try to distill the
    high-level features or use-cases and define options for those.
 -  Options for new use-cases can always be added later. It's perfectly
    acceptable to just disable some unused features when creating a new
@@ -78,19 +78,20 @@ The most common contribution to PTXdist are new versions for existing
 packages. This is usually quite simple, but there are a few things to keep
 in mind:
 
--  New versions can have new build system options that should be used.
+-  New versions can have new build system options that should be set for
+   reproducible builds.
    :ref:`configure_helper` can be used to find the new options.
--  There may be patches for the old version. Make sure they are update as
-   well or removed if they are no longer needed.
+-  There may be patches for the old version. Make sure they are updated as
+   well, or removed if they are no longer needed.
 
 Misc
 ~~~~
 
-For new Packages, the top-level option and any non-obvious suboption should
+For new packages, the top-level option and any non-obvious suboptions should
 have a help text. The homepage of a package or the package description from
-other distributions a usually a good inspiration.
+other distributions are usually a good inspiration.
 
-The package templates to create new packages contain commented out default
+For new packages, the generated templates contain commented-out default
 sections. These are meant as a helper to simplify creating custom stages.
 Any remaining default stages must be removed.
 
@@ -119,7 +120,7 @@ needed. This tool contains a blacklist to filter out these options.
 ``-h, --help``
     Show the help message and exit
 
-``-p <pgk>, --pkg <pgk>``
+``-p <pkg>, --pkg <pkg>``
     The ptxdist package to check
 
 ``-o <old>, --old-src <old>``
-- 
2.19.0


_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de

[ptxdist] [PATCH 3/4] doc: getting help: prune section with only one subsection

[Roland Hieber]

Previously several mailing lists were mentioned in this section, but now
it has been shrunk down to only the PTXdist mailing list. Reflect this
change in the section header.

Signed-off-by: Roland Hieber <r.hieber@pengutronix.de>
---
 doc/getting_help.rst | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/doc/getting_help.rst b/doc/getting_help.rst
index 5a7613655..274e585ad 100644
--- a/doc/getting_help.rst
+++ b/doc/getting_help.rst
@@ -5,11 +5,8 @@ Below is a list of locations where you can get help in case of trouble.
 For questions how to do something special with PTXdist or general
 questions about Linux in the embedded world, try these.
 
-Mailing Lists
--------------
-
-About PTXdist in Particular
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+PTXdist Mailing List
+--------------------
 
 This is an English language public mailing list for questions about
 PTXdist. See
-- 
2.19.0


_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de

[ptxdist] [PATCH 4/4] doc: environment: general proof-reading and copy editing

[Roland Hieber]

Yes, this patch looks kind of messy, but it hopefully tidies the
environment section up. A lot of the patch is just inserting
punctuation at the right places and omitting them in not so right
places, harmonizing spelling, adding reST markup, and bringing the text
up to date.

Signed-off-by: Roland Hieber <r.hieber@pengutronix.de>
---
 doc/environment.rst | 216 ++++++++++++++++++++++----------------------
 1 file changed, 109 insertions(+), 107 deletions(-)

diff --git a/doc/environment.rst b/doc/environment.rst
index 867531138..d87877030 100644
--- a/doc/environment.rst
+++ b/doc/environment.rst
@@ -10,7 +10,7 @@ evaluation board package or by downloading them from the Pengutronix web
 site.
 
 The central place for OSELAS related documentation is
-http://www.oselas.com and http://www.ptxdist.org. These websites provide
+http://www.ptxdist.org. This website provides
 all required packages and documentation (at least for software
 components which are available to the public).
 
@@ -26,7 +26,7 @@ Main Parts of PTXdist
 ~~~~~~~~~~~~~~~~~~~~~
 
 The most important software component which is necessary to build an
-OSELAS.BSP( ) board support package is the ``ptxdist`` tool. So before
+OSELAS.BSP() board support package is the ``ptxdist`` tool. So before
 starting any work we’ll have to install PTXdist on the development host.
 
 PTXdist consists of the following parts:
@@ -64,12 +64,11 @@ Toolchains:
     The different OSELAS toolchains can be found at
     https://www.pengutronix.de/en/software/toolchain.html.
 
-    Building a toolchain is not part of this manual, refer for
-    application note “Building Toolchains” instead.
+    Refer to the section `Building a Toolchain`_ for more information.
 
-Board Support Package
+Board Support Package:
     This is an optional component, mostly shipped aside with a piece of
-    hardware. There are various BSP available, some are generic, some
+    hardware. There are various BSPs available, some are generic, some
     are intended for a specific hardware.
 
 Extracting the Sources
@@ -146,7 +145,7 @@ to be done now is to configure the package:
     $ ./configure
 
 This will check your system for required components PTXdist relies on.
-If all required components are found the output ends with:
+If all required components are found, the output ends with:
 
 ::
 
@@ -163,7 +162,7 @@ If all required components are found the output ends with:
 
     Report bugs to ptxdist@pengutronix.de
 
-Without further arguments PTXdist is configured to be installed into
+Without further arguments, PTXdist is configured to be installed into
 ``/usr/local``, which is the standard location for user installed
 programs. To change the installation path to anything non-standard, we
 use the ``--prefix`` argument to the ``configure`` script. The
@@ -175,7 +174,7 @@ versions can be installed in parallel. So if an old version of PTXdist
 is already installed, there is no need to remove it.
 
 One of the most important tasks for the ``configure`` script is to find
-out if all the programs PTXdist depends on are already present on the
+out whether all the programs PTXdist depends on are already present on the
 development host. The script will stop with an error message in case
 something is missing. If this happens, the missing tools have to be
 installed from the distribution befor re-running the ``configure``
@@ -187,7 +186,7 @@ When the ``configure`` script is finished successfully, we can now run
 
     $ make
 
-All program parts are being compiled, and if there are no errors we can
+All program parts are being compiled, and if there are no errors, we can
 now install PTXdist into it’s final location. In order to write to
 ``/usr/local``, this step has to be performed as user *root*:
 
@@ -197,7 +196,7 @@ now install PTXdist into it’s final location. In order to write to
     [enter password]
     [...]
 
-If we don’t have root access to the machine it is also possible to
+If we don’t have root access to the machine, it is also possible to
 install PTXdist into some different directory with the ``--prefix`` option.
 We need to take care that the ``bin/`` directory below the new
 installation dir is added to our ``$PATH`` environment variable (for
@@ -216,7 +215,7 @@ Configuring PTXdist
 
 When using PTXdist for the first time, some setup properties have to be
 configured. Two settings are the most important ones: where to store the
-source archives and if a proxy must be used to gain access to the world
+source archives and whether a proxy must be used to gain access to the world
 wide web.
 
 Run PTXdist’s setup:
@@ -227,19 +226,15 @@ Run PTXdist’s setup:
 
 Due to the fact that PTXdist is working with sources only, it needs
 various source archives from the world wide web. If these archives are
-not present on our host, PTXdist starts the ``wget`` command to download
-them on demand.
+not present on our host, PTXdist will download them on demand.
 
 Proxy Setup
 ^^^^^^^^^^^
 
-To do so, an internet access is required. If this access is managed by a
-proxy ``wget`` command must be advised to use it. PTXdist can be
-configured to advise the ``wget`` command automatically: navigate to
+To do so, internet access is required. If this access is managed by a
+proxy, PTXdist can be configured to use it: navigate to
 entry *Proxies* and enter the required addresses and ports to access the
-proxy in the form:
-
-``<protocol>://<address>:<port>``
+proxy in the form: ``<protocol>://<address>:<port>``
 
 
 .. _source-arch-loc:
@@ -247,8 +242,8 @@ proxy in the form:
 Source Archive Location
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-Whenever PTXdist downloads source archives it stores these archives in a
-project local manner. This is the default behaviour. If we are working
+Whenever PTXdist downloads source archives, it stores these archives
+locally in the project folder. This is the default behaviour. If we are working
 with more than one PTXdist based project, every project would download
 its own required archives in this case. To share all source archives
 between all projects, PTXdist can be configured to share only one
@@ -259,22 +254,19 @@ should store archives to share between its projects.
 Toolchains
 ----------
 
-Before we can start building our first userland we need a cross
+Before we can start building our first userland, we need a cross
 toolchain. On Linux, toolchains are no monolithic beasts. Most parts of
 what we need to cross compile code for the embedded target comes from
-the *GNU Compiler Collection*, ``gcc``. The gcc packet includes the
-compiler frontend, ``gcc``, plus several backend tools (cc1, g++, ld
+the *GNU Compiler Collection*, ``gcc``. The gcc package includes the
+compiler frontend, ``gcc``, plus several backend tools (``cc1``, ``g++``, ``ld``
 etc.) which actually perform the different stages of the compile
 process. ``gcc`` does not contain the assembler, so we also need the
 *GNU Binutils package* which provides lowlevel stuff.
 
 Cross compilers and tools are usually named like the corresponding host
 tool, but with a prefix – the *GNU target*. For example, the cross
-compilers for ARM and powerpc may look like
-
-``arm-softfloat-linux-gnu-gcc``
-
-``powerpc-unknown-linux-gnu-gcc``
+compilers for ARM and powerpc may look like 
+``arm-softfloat-linux-gnu-gcc`` or ``powerpc-unknown-linux-gnu-gcc``.
 
 With these compiler frontends we can convert e.g. a C program into
 binary code for specific machines. So for example if a C program is to
@@ -301,54 +293,54 @@ stage compiler, which is used to build normal user space code, is being
 built against the libc itself. For example, if the target does not
 contain a hardware floating point unit, but the toolchain generates
 floating point code, it will fail. This is also the case when the
-toolchain builds code for i686 CPUs, whereas the target is i586.
+toolchain builds code for i686 CPUs, but the target is i586.
 
 So in order to make things working consistently it is necessary that the
-run-time libc is identical with the libc the compiler was built against.
+run-time libc is identical with the libc that the compiler was built against.
 
 PTXdist doesn’t contain a pre-built binary toolchain. Remember that it’s
-not a distribution but a development tool. But it can be used to build a
+not a distribution, but a development tool. But it can be used to build a
 toolchain for our target. Building the toolchain usually has only to be
 done once. It may be a good idea to do that over night, because it may
 take several hours, depending on the target architecture and development
 host power.
 
-Using existing Toolchains from different Vendors
+Using Existing Toolchains from Different Vendors
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If a toolchain from a different vendor than OSELAS is already installed
-which is known to be working, the toolchain building step with PTXdist
+and is known to be working, building the toolchain with PTXdist
 may be omitted.
 
-The OSELAS.BoardSupport() Packages shipped for PTXdist have been tested
+The OSELAS.BSP() packages shipped for PTXdist have been tested
 with the OSELAS.Toolchains() built with the same PTXdist version. So if
 an external toolchain is being used which isn’t known to be stable, a
 target may fail. Note that not all compiler versions and combinations
 work properly in a cross environment.
 
-Every OSELAS.BoardSupport() Package checks for its OSELAS.Toolchain it’s
+Every OSELAS.BSP() checks for the OSELAS.Toolchain() it was
 tested against, so using a toolchain from a different vendor than OSELAS
 requires an additional step:
 
-Open the OSELAS.BoardSupport() Package menu with:
+Open the OSELAS.BSP() menu with:
 
 ::
 
     $ ptxdist platformconfig
 
-and navigate to ``architecture ---> toolchain`` and
-``check for specific toolchain vendor``. Clear this entry to disable the
+and navigate to *architecture* → *toolchain* →
+*check for specific toolchain vendor*. Clear this entry to disable the
 toolchain vendor check.
 
-Preconditions a toolchain from a different vendor than OSELAS must meet:
+Toolchains from a different vendor must meet some preconditions:
 
--  it shall be built with the configure option ``--with-sysroot``
+-  it must be built with the configure option ``--with-sysroot``
    pointing to its own C libraries.
 
 -  it should not support the *multilib* feature as this may confuse
-   PTXdist which libraries are to select for the root filesystem
+   PTXdist as to which libraries are to be copied to the root filesystem
 
-If we want to check if our toolchain was built with the
+If we want to check whether our toolchain was built with the
 ``--with-sysroot`` option, we just run this simple command:
 
 ::
@@ -359,60 +351,56 @@ If this command **does not** output anything, this toolchain was not
 built with the ``--with-sysroot`` option and cannot be used with
 PTXdist.
 
-Omitting building a Toolchain
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Using a Pre-Built Toolchain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Pengutronix also provides ’ready to use’ toolchains in a binary manner.
-These toolchains are built from the OSELAS.Toolchain bundle, so they
+Pengutronix also provides ready-to-use binary toolchains.
+These toolchains are built from the OSELAS.Toolchain() bundle, so they
 comply with all of Pengutronix’s board support packages and we can use
-them instead of building our own one.
+them instead of building our own.
 
 The binary OSELAS toolchains are provided as *Debian Distribution
-Packages*. Also most non-Debian distributions can handle such packages.
+Packages*, but the contents of those packages are usable on
+non-Debian distributions as well.
 
 In order to install the OSELAS binary toolchains on a Debian based
 system the following steps are required:
 
-Add the OSELAS Server as a Package Source
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Add the Pengutronix Debian Archive
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-To register the OSELAS package server to the list of known package
-servers, we add a new file with the name ``pengutronix.list`` into the
-directory ``/etc/apt/sources.list.d/``. The basename of this file isn’t
-important, while the extension ``.list`` is.
+To make the package repository known to the package manager, *apt*, we create a
+new file named ``pengutronix.list`` in the directory
+``/etc/apt/sources.list.d/``.
+(The basename of this file isn’t important, but the extension ``.list`` is.)
 
 The contents of this new file describe the Pengutronix server as an
 available package source. It is defined via one text line:
 
 ::
 
-    deb http://debian.pengutronix.de/debian/ sid main contrib non-free
-
-Note: if the directory ``/etc/apt/sources.list.d/`` does not exist, the
-text line mentioned above must be added to the file
-``/etc/apt/sources.list`` instead.
+    deb https://debian.pengutronix.de/debian/ sid main contrib non-free
 
-Make the OSELAS Server Content available
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. note::
+  If the directory ``/etc/apt/sources.list.d/`` does not exist, the
+  text line mentioned above must be added to the file
+  ``/etc/apt/sources.list`` instead.
 
-The package manager now must update its packages list with the following
+The package manager must now update its packages list with the following
 command:
 
 ::
 
     $ apt-get update
 
-Install the Archive Keyring
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
 To avoid warnings about untrusted package sources we can install the
-OSELAS archive keyring with the following command:
+Pengutronix archive keyring with the following command:
 
 ::
 
     $ apt-get install pengutronix-archive-keyring
 
-Install the binary OSELAS Toolchain
+Install the Binary OSELAS Toolchain
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Now everything is in place to install the binary OSELAS toolchain for
@@ -424,31 +412,41 @@ the board support package:
 
 These package names are very long and hard to type without making typos.
 An easier way is to ask the package manager for available toolchains and
-just use the name by copy and paste it.
+just copy and paste the name.
 
 ::
 
     $ apt-cache search "oselas.toolchain-.*-|oselasTCNarch|.*|oselasTCNvariant|.*"
     oselas.toolchain-|oselasTCNVendorVersion|-|ptxdistCompilerName|-<ptxdistCompilerVersion>
 
-The binary OSELAS Toolchain Package for non-Debian Distributions
+The Binary OSELAS Toolchain Package for non-Debian Distributions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The *Debian Distribution Packages* can be found on our server at
-http://debian.pengutronix.de/debian/pool/main/o/
+You can also use the Debian packages for non-Debian Linux distributions.
+
+The Debian packages can be found on our server at
+http://debian.pengutronix.de/debian/pool/main/o/oselas.toolchain
+
+Navigate to the path 
+``| oselas.toolchain-|oselasTCNVendorVersion|-|ptxdistCompilerName|-|ptxdistCompilerVersion|/``
+and download the package named
+``| oselas.toolchain-|oselasTCNVendorVersion|-|ptxdistCompilerName|-|ptxdistCompilerVersion|\*.deb``
 
-The related OSELAS toolchain package can be found here:
+Package filenames for 32-bit host machines end with ``*_i386.deb``,
+for 64-bit host machines the filenames end with ``*_amd64.deb``.
 
-Subpath is:
+You can simply unpack the Debian packages with ``ar``::
 
-| oselas.toolchain-|oselasTCNVendorVersion|-|ptxdistCompilerName|-|ptxdistCompilerVersion|/
+    ar x | oselas.toolchain-|oselasTCNVendorVersion|-|ptxdistCompilerName|-|ptxdistCompilerVersion|\*.deb
 
-Package filename is:
+This will create the files ``debian-binary``, ``control.tar.gz`` and
+``data.tar.xz``.  Ignore the first two, and unpack ``data.tar.xz`` into your
+root file system::
 
-| oselas.toolchain-|oselasTCNVendorVersion|-|ptxdistCompilerName|-|ptxdistCompilerVersion|\*.deb
+    $ sudo tar xf data.tar.xz -C /
 
-Package filenames for 32 bit host machines are ending on ``*_i386.deb``
-and for 64 bit host machines on ``*_amd64.deb``.
+The toolchain can now be found in
+``/opt/OSELAS.Toolchain-|oselasTCNVendorVersion|/|ptxdistCompilerName|/|ptxdistCompilerVersion|/``.
 
 Building a Toolchain
 ~~~~~~~~~~~~~~~~~~~~
@@ -457,25 +455,23 @@ If there is no different toolchain available yet, the next step is to build one
 at least for the desired target architecture.
 
 PTXdist handles toolchain building as a simple project, like all other
-projects, too. So we can download the OSELAS.Toolchain bundle and build
-the required toolchain for the OSELAS.BoardSupport() Package.
+projects, too. So we can download the OSELAS.Toolchain() bundle and build
+the required toolchain for the OSELAS.BSP() project.
 
-Building any toolchain of the OSELAS.Toolchain-|oselasTCNVendorVersion| is
+Building any toolchain of the OSELAS.Toolchain-|oselasTCNVendorVersion| family is
 tested with PTXdist-|oselasTCNVendorptxdistversion|.
 Pengutronix recommends to use this specific PTXdist to build the
 toolchain. So, it might be essential to install more than one PTXdist
 revision to build the toolchain and later on the Board Support Package
 if the latter one is made for a different PTXdist revision.
 
-A PTXdist project generally allows to build into some project defined
-directory; all OSELAS.Toolchain projects that come with PTXdist are
-configured to use the standard installation paths mentioned below.
-
-All OSELAS.Toolchain projects install their result into
-/opt/OSELAS.Toolchain-|oselasTCNVendorVersion|/.
+A PTXdist project generally allows building into some project defined
+directory; all OSELAS.Toolchain() projects that come with PTXdist are
+configured to use the standard installation paths mentioned below,
+and install their result into /opt/OSELAS.Toolchain-|oselasTCNVendorVersion|/.
 
 Usually the ``/opt`` directory is not world writeable. So in order to
-build our OSELAS.Toolchain into that directory we need to use a root
+build our OSELAS.Toolchain() into that directory we need to use a root
 account to change the permissions. PTXdist detects this case and asks
 if we want to run ``sudo`` to do the job for us. Alternatively we can
 enter:
@@ -487,21 +483,23 @@ enter:
    $ chmod a+rwx /opt/OSELAS.Toolchain-|oselasTCNVendorVersion|
 
 We recommend to keep this installation path as PTXdist expects the
-toolchains at ``/opt``. Whenever we go to select a platform in a
-project, PTXdist tries to find the right toolchain from data read from
+toolchains in ``/opt``. Whenever we go to select a platform in a
+project, PTXdist 
+
+tries to find the right toolchain from data read from
 the platform configuration settings and a toolchain at ``/opt`` that
 matches to these settings. But that’s for our convenience only. If we
-decide to install the toolchains at a different location, we still can
+decide to install the toolchains at a different location, we can still
 use the *toolchain* parameter to define the toolchain to be used on a
 per project base.
 
 Building the OSELAS.Toolchain for |ptxdistBSPName|
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Do the following steps in your own home directory ($HOME). The final
-OSELAS.Toolchain gets installed to ``/opt``, but must **never** be
-compiled in the ``/opt`` directory. You will get many funny error
-messages, if you try to compile the OSELAS-Toolchain in ``/opt``.
+Do the following steps in your own home directory (``$HOME``). The final
+OSELAS.Toolchain gets installed to ``opt/``, but must **never** be
+compiled in the ``opt/`` directory. You will get many funny error
+messages if you try to compile the OSELAS-Toolchain in ``opt/``.
 
 To compile and install an OSELAS.Toolchain we have to extract the
 OSELAS.Toolchain archive, change into the new folder, configure the
@@ -533,20 +531,24 @@ few hours.
 
 Measured times on different machines:
 
--  Single Pentium 2.5 GHz, 2 GiB RAM: about 2 hours
-
--  Turion ML-34, 2 GiB RAM: about 1 hour 30 minutes
-
--  Dual Athlon 2.1 GHz, 2 GiB RAM: about 1 hour 20 minutes
-
--  Dual Quad-Core-Pentium 1.8 GHz, 8 GiB RAM: about 25 minutes
-
--  24 Xeon cores 2.54 GHz, 96 GiB RAM: about 22 minutes
++---------------------------------------------+--------------------------+
+| Machine                                     | Build Time               |
++=============================================+==========================+
+| Single Pentium 2.5 GHz, 2 GiB RAM           | about 2 hours            |
++---------------------------------------------+--------------------------+
+| Turion ML-34, 2 GiB RAM                     | about 1 hour 30 minutes  |
++---------------------------------------------+--------------------------+
+| Dual Athlon 2.1 GHz, 2 GiB RAM              | about 1 hour 20 minutes  |
++---------------------------------------------+--------------------------+
+| Dual Quad-Core-Pentium 1.8 GHz, 8 GiB RAM   | about 25 minutes         |
++---------------------------------------------+--------------------------+
+| 24 Xeon cores 2.54 GHz, 96 GiB RAM          | about 22 minutes         |
++---------------------------------------------+--------------------------+
 
 Another possibility is to read the next chapters of this manual, to find
 out how to start a new project.
 
-When the OSELAS.Toolchain project build is finished, PTXdist is ready
+When the OSELAS.Toolchain() project build is finished, PTXdist is ready
 for prime time and we can continue with our first project.
 
 Protecting the Toolchain
-- 
2.19.0


_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de

Re: [ptxdist] [PATCH 2/4] doc: contributing: fix typos, add links, and make text easier to parse

[Roland Hieber]

On Fri, Oct 05, 2018 at 11:45:16AM +0200, Roland Hieber wrote:
> Signed-off-by: Roland Hieber <r.hieber@pengutronix.de>
> ---
>  doc/contributing.rst | 31 ++++++++++++++++---------------
>  1 file changed, 16 insertions(+), 15 deletions(-)
> 
> diff --git a/doc/contributing.rst b/doc/contributing.rst
> index 8e2d7883d..1db596c0e 100644
> --- a/doc/contributing.rst
> +++ b/doc/contributing.rst
> @@ -6,13 +6,13 @@ PTXdist Packages
>  
>  While contributions to all parts of PTXdist are welcome, most contributions
>  concern individual packages. Here is a checklist of things to look out for
> -while creating or updating packages. These are not hard requirements but
> +while creating or updating packages. These are not hard requirements, but
>  there should be good reasons for different choices.
>  
>  How to Contribute
>  ~~~~~~~~~~~~~~~~~
>  
> -Contributions should be sent as patches to the PTXdist mailing list. This
> +Contributions should be sent as patches to the :ref:`PTXdist mailing list`. This

Oh, that section is not present until it is added in PATCH 3/4. If you
could switch those two on applying, that would be great, otherwise I'll
fix in v2.

 - Roland

>  is usually done with ``git send-email``.
>  
>  All patches must contain a descriptive subject and should, for all
> @@ -26,11 +26,11 @@ Package Builds should be Reproducible
>  
>  Many packages autodetect which features are available. As a result, the
>  exact features of a package may depend on the build host and the build
> -order of the packages. To avoid this autodetection must be restricted as
> +order of the packages. To avoid this, autodetection must be restricted as
>  much as possible.
>  
>  For **autoconf** based packages, the first step is to specify all relevant
> -``configure`` options. The :ref:`configure_helper` scripts can help filter
> +``configure`` options. The :ref:`configure_helper` script can help filter
>  out the unimportant options.
>  
>  There are also cache variables that can be used to enforce the outcome of
> @@ -55,17 +55,17 @@ Packages Suboptions
>  
>  Suboptions for PTXdist packages are useful to make parts of the package
>  optional. However, it is not always easy to decide what should be optional
> -and how to map the build system options to packages suboptions. Here are a
> +and how to map the build system options to package suboptions. Here are a
>  few guidelines to help with that.
>  
>  -  Avoid unnecessary suboptions. When in doubt, use the package default or
>     what other distributions use. If the creator of the package does not
> -   know what to choose then the user wont either.
> +   know what to choose, then the user won't either.
>  -  Use suboptions to save disk space. If a feature adds extra dependencies
> -   or uses a lot of space then a suboptions is useful to save the disk
> +   or uses a lot of space then a suboption is useful to save disk
>     space when the feature is not needed.
>  -  Try to create high-level options. Some packages have very low-level
> -   build options with very few useful combinations. Try to define
> +   build options with very few useful combinations. Try to distill the
>     high-level features or use-cases and define options for those.
>  -  Options for new use-cases can always be added later. It's perfectly
>     acceptable to just disable some unused features when creating a new
> @@ -78,19 +78,20 @@ The most common contribution to PTXdist are new versions for existing
>  packages. This is usually quite simple, but there are a few things to keep
>  in mind:
>  
> --  New versions can have new build system options that should be used.
> +-  New versions can have new build system options that should be set for
> +   reproducible builds.
>     :ref:`configure_helper` can be used to find the new options.
> --  There may be patches for the old version. Make sure they are update as
> -   well or removed if they are no longer needed.
> +-  There may be patches for the old version. Make sure they are updated as
> +   well, or removed if they are no longer needed.
>  
>  Misc
>  ~~~~
>  
> -For new Packages, the top-level option and any non-obvious suboption should
> +For new packages, the top-level option and any non-obvious suboptions should
>  have a help text. The homepage of a package or the package description from
> -other distributions a usually a good inspiration.
> +other distributions are usually a good inspiration.
>  
> -The package templates to create new packages contain commented out default
> +For new packages, the generated templates contain commented-out default
>  sections. These are meant as a helper to simplify creating custom stages.
>  Any remaining default stages must be removed.
>  
> @@ -119,7 +120,7 @@ needed. This tool contains a blacklist to filter out these options.
>  ``-h, --help``
>      Show the help message and exit
>  
> -``-p <pgk>, --pkg <pgk>``
> +``-p <pkg>, --pkg <pkg>``
>      The ptxdist package to check
>  
>  ``-o <old>, --old-src <old>``
> -- 
> 2.19.0
> 
> 
> _______________________________________________
> ptxdist mailing list
> ptxdist@pengutronix.de

-- 
Roland Hieber                     | r.hieber@pengutronix.de     |
Pengutronix e.K.                  | https://www.pengutronix.de/ |
Peiner Str. 6-8, 31137 Hildesheim | Phone: +49-5121-206917-5086 |
Amtsgericht Hildesheim, HRA 2686  | Fax:   +49-5121-206917-5555 |

_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de