doc: describe a strange behaviour and its solution

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>
Signed-off-by: Michael Olbrich <m.olbrich@pengutronix.de>

2 files changed, 18 insertions, 0 deletions

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
 ~~~~~~~~~~~~