[ptxdist] [PATCH] doc: add section about install_replace

[Alexander Dahl <post@lespocky.de>]

This describes the install_replace macro. Some text stolen from
rules/post/install.make and the existing documentation of install_lib.

Signed-off-by: Alexander Dahl <post@lespocky.de>
---
 doc/ref_manual.rst | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/doc/ref_manual.rst b/doc/ref_manual.rst
index d10f477..0647065 100644
--- a/doc/ref_manual.rst
+++ b/doc/ref_manual.rst
@@ -873,6 +873,43 @@ Note: The package's install stage must be 'DESTDIR' aware to be able to make
 it install its content into the corresponding packages directory (in our example
 ``<platform-dir>/packages/foo-1.0.0/`` here).
 
+install_replace
+~~~~~~~~~~~~~~~
+
+Usage:
+
+.. code-block:: make
+
+ $(call install_replace, <package>, <filename>, <placeholder>, <value>)
+
+Replace placeholder with value in a previously installed file.
+
+The parameters and their meanings:
+
+**<package>**
+  Name of the IPKG/OPKG the macro should work on
+**<filename>**
+  Absolute filepath in target root filesystem
+**<placeholder>**
+  A string in the file which should be replaced. Usually some uppercase word
+  surrounded by @ signs
+**<value>**
+  The value which should appear in the root filesystem instead of the
+  placeholder, could be some PTXCONF variable
+
+The ``install_replace`` macro can be used in targetinstall stage to adapt some
+template and replace strings with content from menu variables or other
+sources. For example look at the timezone you set in the ptxdist menu. An
+``install_replace`` call in ``rules/timezone.make`` replaces the string
+``@TIMEZONE@`` in the file ``/etc/timezone`` in ``projectroot`` with the
+content of the menu variable ``PTXCONF_TIMEZONE_LOCALTIME``. A typical call
+would look like this:
+
+.. code-block:: make
+
+ @$(call install_replace, timezone, /etc/timezone, @TIMEZONE@, \
+        $(PTXCONF_TIMEZONE_LOCALTIME))
+
 
 .. _param_macros:
 
-- 
2.1.4


_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de