[ptxdist] [PATCH 1/4] doc: BUILDTIME versus RUNTIME

[ptxdist] [PATCH 1/4] doc: BUILDTIME versus RUNTIME

[Juergen Borleis]

Describe the difference of some detailed dependency descriptions in
Kconfig menufiles.

Signed-off-by: Juergen Borleis <jbe@pengutronix.de>
---
 doc/daily_work.inc | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/dev_manual.rst |  5 +++++
 2 files changed, 63 insertions(+)

diff --git a/doc/daily_work.inc b/doc/daily_work.inc
index 5708903db..e4260e448 100644
--- a/doc/daily_work.inc
+++ b/doc/daily_work.inc
@@ -1297,3 +1297,61 @@ non-interactive user, e.g. a different application.
    should use the **LGPL license for both parts** from the beginning. Else
    you may cannot move source code in such a way, because it would require a
    license change for this specific piece of source code (to be pedantic!).
+
+.. _external_dependencies_variants:
+
+Controling Package Dependencies in more Detail
+----------------------------------------------
+
+In section :ref:`external_dependencies` a simple method is shown how to define
+an external package dependency a particular package can have in order to build
+it.
+
+Implicit Dependencies
+~~~~~~~~~~~~~~~~~~~~~
+
+For the simple dependency definition PTXdist adds internally a dependency
+to the *install* stage of the defined external dependency (or to a different
+package to use PTXdist glossary).
+
+We must keep this in mind, because there are packages out there, which don't
+install anything in their *install* stage. They install something in their
+*targetinstall* stage instead. In this case even if the dependency is defined
+like shown in :ref:`external_dependencies`, building the particular package may
+fail depending on the build order.
+
+To avoid this, an explicit ``make`` style dependency must be added to the rule
+file. If the *compile* stage of package ``foo`` has a dependency to package
+``bar``'s *targetinstall* stage just add the following lines to your rule file:
+
+.. code-block:: make
+
+   $(STATEDIR)/foo.compile: $(STATEDIR)/bar.targetinstall
+
+Build-Time only Dependency
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes packages have a compile-time dependency to a different package, but
+can live without its content at run-time. An example can be a static library
+which is linked at compile-time and not required as a separate package at
+run-time. Another example is making use of this detailed dependency can make
+developer's life easier when using individual package lists for dedicated
+image files. Think about a development image and a production image which should
+be built at the same time but should contain a different packages list each
+(refer :ref:`multi_image_individual_root_filesystems` for details).
+
+Marking a menu file based dependency with ``if BUILDTIME`` limits the dependency
+to compile-time only. In this case its possible to have the package in one
+image's list, but not its dependency.
+
+Run-Time only Dependency
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The other way round is ``if RUNTIME``. This forces the dependency package is
+part of the final image as well, but PTXdist can improve its build-time job by
+reordering package's build.
+A use case for this run-time dependency can be a package which just installs a
+shell script. This shell script makes use of some shell commands which must be
+present at run-time and thus depends on a package which provides these shell
+commands. But these shell commands are not required to build the shell script
+itself. In this case PTXdist can build both packages independently.
diff --git a/doc/dev_manual.rst b/doc/dev_manual.rst
index a14e64b0f..f0c2e00ee 100644
--- a/doc/dev_manual.rst
+++ b/doc/dev_manual.rst
@@ -992,6 +992,8 @@ as expected:
 Whenever we change a *FOO* related menu entry, PTXdist should detect it
 and re-build the package when a new build is started.
 
+.. _external_dependencies:
+
 Managing External Compile Time Dependencies
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1035,6 +1037,9 @@ file looks like:
 
 PTXdist now builds the *zlib* first and our new package thereafter.
 
+Refer :ref:`external_dependencies_variants` for more specific dependency
+description.
+
 Managing External Compile Time Dependencies on Demand
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- 
2.11.0


_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de

[ptxdist] [PATCH 2/4] doc: follow 'proselint' and improve the text

[Juergen Borleis]

Follow the hints of the nice tool 'proselint'...

Signed-off-by: Juergen Borleis <jbe@pengutronix.de>
---
 doc/daily_work.inc  | 2 +-
 doc/ref_manual.rst  | 4 ++--
 doc/user_manual.inc | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/daily_work.inc b/doc/daily_work.inc
index e4260e448..3fc894106 100644
--- a/doc/daily_work.inc
+++ b/doc/daily_work.inc
@@ -356,7 +356,7 @@ Using available CPU Cores
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 PTXdist uses all available CPU cores when building a project by default.
-But there are some exceptions:
+There are some exceptions:
 
 -  the prepare stage of all autotools build system based packages can
    use only one CPU core. This is due to the fact, the running
diff --git a/doc/ref_manual.rst b/doc/ref_manual.rst
index 96274ac97..69f7fdee8 100644
--- a/doc/ref_manual.rst
+++ b/doc/ref_manual.rst
@@ -556,7 +556,7 @@ Usage:
 
 This macro is very similar to ``world/compile``. The only differences is
 that is uses the specified ``build arguments`` instead of
-``<PKG>_MAKE_OPT``.  This is usefull if ``make`` needs to be called more
+``<PKG>_MAKE_OPT``. This is usefull if ``make`` needs to be called more
 than once in the compile stage.
 
 world/execute, execute
@@ -622,7 +622,7 @@ The ``<source>`` parameter can be:
   parameter in this case to locate the file to copy from. 
   The <destination> is uses a path relative to the :ref:`package install
   directory<pkg_pkgdir>`. This only works if the package uses the default
-  or a similar *install* stage.  For our *foo* example used source file is
+  or a similar *install* stage. For our *foo* example used source file is
   ``<platform-dir>/packages/foo-1.1.0/<destination>``.
 
 The ``<dest>`` parameter can be:
diff --git a/doc/user_manual.inc b/doc/user_manual.inc
index 9f78f5b46..0a4e4b34c 100644
--- a/doc/user_manual.inc
+++ b/doc/user_manual.inc
@@ -314,7 +314,7 @@ Next we will build the BSP to show some of PTXdist’s main features.
 Selecting a Userland Configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-First of all we have to select a userland configuration. This step
+First we have to select a userland configuration. This step
 defines what kind of applications will be built for the hardware
 platform. The |ptxdistBSPName| project comes
 with a predefined configuration we select in the following step:
-- 
2.11.0


_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de

[ptxdist] [PATCH 3/4] doc: describe a strange behaviour and its solution

[Juergen Borleis]

Using a unusual 'umask' leads to a strange erroneous behaviour. This was
reported on the PTXdist mailing list.

Signed-off-by: Juergen Borleis <jbe@pengutronix.de>
---
 doc/daily_work.inc | 16 ++++++++++++++++
 doc/ref_manual.rst |  2 ++
 2 files changed, 18 insertions(+)

diff --git a/doc/daily_work.inc b/doc/daily_work.inc
index 3fc894106..74da11953 100644
--- a/doc/daily_work.inc
+++ b/doc/daily_work.inc
@@ -1355,3 +1355,19 @@ shell script. This shell script makes use of some shell commands which must be
 present at run-time and thus depends on a package which provides these shell
 commands. But these shell commands are not required to build the shell script
 itself. In this case PTXdist can build both packages independently.
+
+``umask`` Pitfall
+-----------------
+
+When using PTXdist keep in mind it requires some 'always expected' permissions
+to do its job (this does not include root permissions!). But it includes some
+permissions related to file permission masks.
+
+PTXdist requires a ``umask`` of ``0022`` to be able to create files accessible
+by regular users. This is important at build-time, since it propagates to the
+generated target filesystem images as well. For example the ``install_tree``
+macro (refer :ref:`install_tree,reference`) uses the file permissions it finds
+in the build machine's filesystem also for the target filesystem image. With
+a different ``umask`` than ``0022`` at build-time this may fail badly at
+run-time with strange erroneous behaviour (for example some daemons with
+regular user permissions cannot acces their own configuration files).
diff --git a/doc/ref_manual.rst b/doc/ref_manual.rst
index 69f7fdee8..e2be86060 100644
--- a/doc/ref_manual.rst
+++ b/doc/ref_manual.rst
@@ -681,6 +681,8 @@ Copy a file from the package install directory to the root filesystem:
 
  $(call install_copy, foo, 0, 0, 0755, -, /usr/bin/foo)
 
+.. _install_tree,reference:
+
 install_tree
 ~~~~~~~~~~~~
 
-- 
2.11.0


_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de

[ptxdist] [PATCH 4/4] doc: fix missing step to setup a Python virtualenv

[Juergen Borleis]

In order to build the PTXdist documentation a virtualenv is a useful
helper. This change mentions its correct setup.

Signed-off-by: Juergen Borleis <jbe@pengutronix.de>
---
 doc/including_bsp_doc.inc | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/including_bsp_doc.inc b/doc/including_bsp_doc.inc
index cfccc45b4..d4abcd8ea 100644
--- a/doc/including_bsp_doc.inc
+++ b/doc/including_bsp_doc.inc
@@ -32,6 +32,7 @@ when not globally present in the host system.
 .. code-block:: text
 
    $ pip3 install --upgrade --user pip virtualenv
+   $ virtualenv -p python3 env
    $ source env/bin/activate
    $ pip3 install sphinx
    $ pip3 install sphinx_rtd_theme
-- 
2.11.0


_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de

Re: [ptxdist] [PATCH 4/4] doc: fix missing step to setup a Python virtualenv

[Michael Olbrich]

On Fri, Feb 22, 2019 at 11:03:03AM +0100, Juergen Borleis wrote:
> In order to build the PTXdist documentation a virtualenv is a useful
> helper. This change mentions its correct setup.
> 
> Signed-off-by: Juergen Borleis <jbe@pengutronix.de>
> ---
>  doc/including_bsp_doc.inc | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/doc/including_bsp_doc.inc b/doc/including_bsp_doc.inc
> index cfccc45b4..d4abcd8ea 100644
> --- a/doc/including_bsp_doc.inc
> +++ b/doc/including_bsp_doc.inc
> @@ -32,6 +32,7 @@ when not globally present in the host system.
>  .. code-block:: text
>  
>     $ pip3 install --upgrade --user pip virtualenv
> +   $ virtualenv -p python3 env

We've had a patch like this before. I think the correct way to create this
is:

$ python3 -m venv env

And the 'pip3 install ...' above is no longer needed. Unfortunately I
didn't get any feedback from the Python experts about this...

Michael

>     $ source env/bin/activate
>     $ pip3 install sphinx
>     $ pip3 install sphinx_rtd_theme
> -- 
> 2.11.0
> 
> 
> _______________________________________________
> ptxdist mailing list
> ptxdist@pengutronix.de

-- 
Pengutronix e.K.                           |                             |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de