[ptxdist] [PATCH 1/4] doc: document git patch workflow

[ptxdist] [PATCH 1/4] doc: document git patch workflow

[Roland Hieber]

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

diff --git a/doc/dev_manual.rst b/doc/dev_manual.rst
index a54888b43..3fe64a343 100644
--- a/doc/dev_manual.rst
+++ b/doc/dev_manual.rst
@@ -1223,7 +1223,6 @@ Creating Patches for a Package
 PTXdist uses the utilities *git*, *patch* or *quilt* to work with
 patches or patch series. We recommend *git*, as it can manage patch
 series in a very easy way.
-For this manual and the example we use *quilt* instead.
 
 Creating a Patch Series for a Package
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -1248,6 +1247,9 @@ and an empty ``patch`` file.
     $ touch patches/foo-1.1.0/dummy
     $ echo dummy > patches/foo-1.1.0/series
 
+Using quilt
+"""""""""""
+
 Next is to extract the package (if already done, we must remove it
 first):
 
@@ -1263,11 +1265,43 @@ present in ``patches/foo-1.1.0`` and can be used the next time we
 extract the package again.
 
 All we have to do now is to do the modification we need to make the
-package work. We change into the build directory and use *quilt* to
+package work. We change into the build directory and use quilt_ to
 create new patches, add files to respective patches, modify these files
 and refresh the patches to save our changes.
+See the *quilt* documentation for more information.
+
+.. _quilt: http://savannah.nongnu.org/projects/quilt
+
+Using Git
+"""""""""
+
+After touching the series file like above, apply an additional command line
+switch to extract the package into a Git repository:
+
+::
+
+    $ ptxdist --git extract foo
+
+.. note:: Optionally, you can enable the setting *Developer Options → use git to
+  apply patches* in `ptxdist setup` to enable this permanently.
+  However, note that this setting is still experimental.
+
+Then, change into the package build directory, patch the required files, and
+make Git commits on the way.
+The Git history should now look something like this:
+
+::
+
+    $ git log --oneline --decorate
+    * df343e821851 (HEAD -> master) Makefile: don't build the tests
+    * 65a360c2bd60 strfry.c: frobnicate the excusator
+    * fdc315f6844c (tag: foobar-1.1.0, tag: base) initial commit
+
+After commit your patches, call ``git ptx-patches`` to regenerate the patches
+and the series file in the ``patches/foo-0.1`` folder, so they don't get lost
+when cleaning the package.
 
-We recommend this way when modifying source files. But this way is
+We recommend working with patches when modifying source files. But this way is
 improper when an autotools based buildsystem itself needs modifications.
 Refer to section :ref:`configure_rebuild` on how PTXdist can
 handle this special task.
-- 
2.11.0


_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de

[ptxdist] [PATCH 2/4] doc: promote faq to own section

[Roland Hieber]

Signed-off-by: Roland Hieber <r.hieber@pengutronix.de>
---
 doc/daily_work_section.rst | 1 -
 doc/{faq.inc => faq.rst}   | 0
 doc/index.rst              | 1 +
 3 files changed, 1 insertion(+), 1 deletion(-)
 rename doc/{faq.inc => faq.rst} (100%)

diff --git a/doc/daily_work_section.rst b/doc/daily_work_section.rst
index daec36dca..0e4e6e767 100644
--- a/doc/daily_work_section.rst
+++ b/doc/daily_work_section.rst
@@ -5,4 +5,3 @@ Various Aspects of Daily Work
 .. include:: nfsroot.inc
 .. include:: working_with_git_sources.inc
 .. include:: including_bsp_doc.inc
-.. include:: faq.inc
diff --git a/doc/faq.inc b/doc/faq.rst
similarity index 100%
rename from doc/faq.inc
rename to doc/faq.rst
diff --git a/doc/index.rst b/doc/index.rst
index 9aad6cddb..7ab42d4c7 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -17,6 +17,7 @@ Welcome to the PTXdist Universe
    dev_manual
    ref_manual
    daily_work_section
+   faq
    getting_help
 
 * :ref:`search`
-- 
2.11.0


_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de

[ptxdist] [PATCH 3/4] doc: faq: apply more structure

[Roland Hieber]

Give the FAQ section some more structure by inserting one heading per
FAQ item, and separate questions and answers visible. This also causes
the questions to appear in the table of contents. Both should lead to
more readability of the FAQ section.

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

diff --git a/doc/faq.rst b/doc/faq.rst
index 952705883..2ebbba17c 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -1,157 +1,189 @@
 Frequently Asked Questions (FAQ)
 --------------------------------
 
-Q: PTXdist does not support to generate some files in a way I need them. What can I do?
-A: Everything PTXdist builds is controlled by “package rule files”,
-which in fact are Makefiles (``rules/*.make``). If you modify such a
-file you can change it’s behaviour in a way you need. It is generally
-no good idea to modify the generic package rule files installed by
-PTXdist, but it is always possible to copy one of them over into the
-``rules/`` directory of a project. Package rule files in the project
-will precede global rule files with the same name.
-
-Q: My kernel build fails. But I cannot detect the correct position,
-due to parallel building. How can I stop PTXdist to build in parallel?
-A: Force PTXdist to stop building in parallel which looks somehow
-like:
-
-::
-
-    $ ptxdist -j1 go
-
-Q: I made my own rule file and now I get error messages like
-
-::
-
-    my_project/rules/test.make:30: *** unterminated call to function `call': missing `)'.  Stop.
-
-But line 30 only contains ``@$(call targetinfo, $@)`` and it seems all
-right. What does it mean?
-A: Yes, this error message is confusing. But it usually only means
-that you should check the following (!) lines for missing backslashes
-(line separators).
-
-Q: I got a message similar to “package <some name> is empty. not
-generating.” What does it mean?
-A: The ’ipkg’ tool was advised to generate a new ipkg-packet, but the
-folder was empty. Sometime it means a typo in the package name when
-the ``install_copy`` macro was called. Ensure all these macros are using
-the same package name. Or did you disable a menuentry and now nothing
-will be installed?
-
-Q: How do I download all required packages at once?
-A: Run this command prior the build:
-
-::
-
-    $ ptxdist make get
-
-This starts to download all required packages in one run. It does
-nothing if the archives are already present in the source path. (run
-“PTXdist setup” first).
-
-Q: I want to backup the source archives my PTXdist project relys on.
-How can I find out what packages my project requires to build?
-A: First build your PTXdist project completely and then run the
-following command:
-
-::
-
-    $ ptxdist export_src <archive directory>
-
-It copies all archives from where are your source archives stored to
-<archive directory> which can be your backup media.
-
-Q: To avoid building the OSELAS toolchain on each development host, I
-copied it to another machine. But on this machine I cannot build any
-BSP with this toolchain correctly. All applications on the target are
-failing to start due to missing libraries.
-A: This happens when the toolchain was copied without regarding to
-retain links. There are archive programs around that convert links
-into real files. When you are using such programs to create a
-toolchain archive this toolchain will be broken after extracting it
-again. Solution: Use archive programs that retain links as they are
-(tar for example). Here an example for a broken toolchain:
-
-::
-
-    $ ll `find . -name "libcrypt*"`
-    -rwxr-xr-x 1 mkl ptx 55K 2007-07-25 14:54 ./lib/libcrypt-2.5.so*
-    -rwxr-xr-x 1 mkl ptx 55K 2007-07-25 14:54 ./lib/libcrypt.so.1*
-    -rw-r--r-- 1 mkl ptx 63K 2007-07-25 14:54 ./usr/lib/libcrypt.a
-    -rw-r--r-- 1 mkl ptx 64K 2007-07-25 14:54 ./usr/lib/libcrypt_p.a
-    -rwxr-xr-x 1 mkl ptx 55K 2007-07-25 14:54 ./usr/lib/libcrypt.so*
-
-And in contrast, this one is intact:
-
-::
-
-    $ ll `find . -name "libcrypt*"`
-    -rwxr-xr-x 1 mkl ptx 55K 2007-11-03 13:30 ./lib/libcrypt-2.5.so*
-    lrwxrwxrwx 1 mkl ptx  15 2008-02-20 14:52 ./lib/libcrypt.so.1 -> libcrypt-2.5.so*
-    -rw-r--r-- 1 mkl ptx 63K 2007-11-03 13:30 ./usr/lib/libcrypt.a
-    -rw-r--r-- 1 mkl ptx 64K 2007-11-03 13:30 ./usr/lib/libcrypt_p.a
-    lrwxrwxrwx 1 mkl ptx  23 2008-02-20 14:52 ./usr/lib/libcrypt.so -> ../../lib/libcrypt.so.1*
-
-Q: I followed the instructions how to integrate my own plain source
-project into PTXdist. But when I try to build it, I get:
-
-::
+PTXdist does not support to generate some files in a way I need them. What can I do?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Answer:
+  Everything PTXdist builds is controlled by “package rule files”,
+  which in fact are Makefiles (``rules/*.make``). If you modify such a
+  file you can change it’s behaviour in a way you need. It is generally
+  no good idea to modify the generic package rule files installed by
+  PTXdist, but it is always possible to copy one of them over into the
+  ``rules/`` directory of a project. Package rule files in the project
+  will precede global rule files with the same name.
+
+How can I stop PTXdist to build in parallel?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Question:
+  My build fails, but I cannot detect the correct position due to parallel
+  building.
+
+Answer:
+  Force PTXdist to stop building in parallel which looks somehow like::
+
+      $ ptxdist -j1 go
+
+I get errors like “unterminated call to function `call': missing `)'”
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Question:
+  I made my own rule file and now I get error messages like::
+
+      my_project/rules/test.make:30: *** unterminated call to function `call': missing `)'.  Stop.
+
+  But line 30 only contains ``@$(call targetinfo, $@)`` and it seems all
+  right. What does it mean?
+
+Answer:
+  Yes, this error message is confusing. But it usually only means
+  that you should check the following (!) lines for missing backslashes
+  (line separators).
+
+I got a message similar to “package <name> is empty. not generating.” What does it mean?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Answer:
+  The ’ipkg’ tool was advised to generate a new ipkg-packet, but the
+  folder was empty. Sometime it means a typo in the package name when
+  the ``install_copy`` macro was called. Ensure all these macros are using
+  the same package name. Or did you disable a menuentry and now nothing
+  will be installed?
+
+How do I download all required packages at once?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Answer:
+  Run this command prior the build::
+
+      $ ptxdist make get
+
+  This starts to download all required packages in one run. It does
+  nothing if the archives are already present in the source path. (run
+  “PTXdist setup” first).
+
+I want to backup all source archives for my BSP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Question:
+  I want to backup the source archives my PTXdist project relys on.
+  How can I find out what packages my project requires to build?
+
+Answer:
+  First build your PTXdist project completely and then run the
+  following command::
+
+      $ ptxdist export_src <archive directory>
+
+  It copies all archives from where are your source archives stored to
+  <archive directory> which can be your backup media.
+
+OSELAS toolchain fails to start due to missing libraries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Question:
+  To avoid building the OSELAS toolchain on each development host, I
+  copied it to another machine. But on this machine I cannot build any
+  BSP with this toolchain correctly. All applications on the target are
+  failing to start due to missing libraries.
+
+Answer:
+  This happens when the toolchain was copied without regarding to
+  retain links. There are archive programs around that convert links
+  into real files. When you are using such programs to create a
+  toolchain archive this toolchain will be broken after extracting it
+  again. Solution: Use archive programs that retain links as they are
+  (tar for example). Here an example for a broken toolchain::
+
+      $ ll `find . -name "libcrypt*"`
+      -rwxr-xr-x 1 mkl ptx 55K 2007-07-25 14:54 ./lib/libcrypt-2.5.so*
+      -rwxr-xr-x 1 mkl ptx 55K 2007-07-25 14:54 ./lib/libcrypt.so.1*
+      -rw-r--r-- 1 mkl ptx 63K 2007-07-25 14:54 ./usr/lib/libcrypt.a
+      -rw-r--r-- 1 mkl ptx 64K 2007-07-25 14:54 ./usr/lib/libcrypt_p.a
+      -rwxr-xr-x 1 mkl ptx 55K 2007-07-25 14:54 ./usr/lib/libcrypt.so*
+
+  And in contrast, this one is intact::
+
+      $ ll `find . -name "libcrypt*"`
+      -rwxr-xr-x 1 mkl ptx 55K 2007-11-03 13:30 ./lib/libcrypt-2.5.so*
+      lrwxrwxrwx 1 mkl ptx  15 2008-02-20 14:52 ./lib/libcrypt.so.1 -> libcrypt-2.5.so*
+      -rw-r--r-- 1 mkl ptx 63K 2007-11-03 13:30 ./usr/lib/libcrypt.a
+      -rw-r--r-- 1 mkl ptx 64K 2007-11-03 13:30 ./usr/lib/libcrypt_p.a
+      lrwxrwxrwx 1 mkl ptx  23 2008-02-20 14:52 ./usr/lib/libcrypt.so -> ../../lib/libcrypt.so.1*
+
+
+PTXdist does not find my own sources: “Unknown format, cannot extract”
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Question:
+  I followed the instructions how to integrate my own plain source
+  project into PTXdist. But when I try to build it, I get::
 
     extract: archive=/path/to/my/sources
     extract: dest=/path/to/my/project/build-target
     Unknown format, cannot extract!
 
-But the path exists!
-A: PTXdist interprets a ``file://`` (two slashes) in the URL as a
-project related relative path. So it searches only in the current
-project for the given path. Only ``file:///`` (three slashes) will
-force PTXdist to use the path as an absolute one. This means:
-``file://bla/blub`` will be used as ``./bla/blub`` and
-``file:///friesel/frasel`` as ``/friesel/frasel``.
-
-Q: I want to use more than one kernel revision in my BSP. How can I
-avoid maintaining one ptxconfig per kernel?
-A: One solution could be to include the kernel revision into the name
-of the kernel config file. Instead of the default kernelconfig.target
-name you should use ``kernelconfig-<revision>.target``. In the kernel
-config file menu entry you should enter
-``kernelconfig-$PTXCONF_KERNEL_VERSION.target``. Whenever you change
-the linux kernel Version menu entry now, this will ensure using a
-different kernel config file, too.
-
-Q: I’m trying to use a JAVA based package in PTXdist. But compiling
-fails badly. Does it ever work at Pengutronix?
-A: This kind of packages only build correctly when an original SUN VM
-SDK is used. Run PTXdist setup and point the Java SDK menu entry to
-the installation path of your SUN JAVA SDK.
-
-Q: I made a new project and everythings seems fine. But when I start my
-target with the root filesystem generated by PTXdist, it fails with:
-
-::
-
-    cannot run '/etc/init.d/rcS': No such file or directory
-
-A: The error message is confusing. But this script needs ``/bin/sh`` to
-run. Most of the time this message occures when ``/bin/sh`` does not
-exists. Did you enable it in your busybox configuration?
-
-Q: I have created a path for my source archives and try to make PTXdist
-use it. But whenever I run PTXdist now it fails with the following error
-message:
-
-::
-
-    /usr/local/bin/ptxdist: archives: command not found
-
-A: In this case the path was ``$HOME/source archives`` which includes a
-whitespace in the name of the directory to store the source archives in.
-Handling directory or filenames with whitespaces in applications isn’t
-trivial and also PTXdist suffers all over the place from this issue. The
-only solution is to avoid whitespaces in paths and filenames.
-
-Q: I have adapted my own rule file’s targetinstall stage, but PTXdist
-does not install the files. A: Check if the closing ``@$(call
-install_finish, [...])`` is present at the end of the targetinsall stage.
-If not, PTXdist will not complete this stage.
+  But the path exists!
+
+Answer:
+  PTXdist interprets a ``file://`` (two slashes) in the URL as a
+  project related relative path. So it searches only in the current
+  project for the given path. Only ``file:///`` (three slashes) will
+  force PTXdist to use the path as an absolute one. This means:
+  ``file://bla/blub`` will be used as ``./bla/blub`` and
+  ``file:///friesel/frasel`` as ``/friesel/frasel``.
+
+Using more than one kernel version per BSP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Question:
+  I want to use more than one kernel revision in my BSP. How can I
+  avoid maintaining one ptxconfig per kernel?
+
+Answer:
+  One solution could be to include the kernel revision into the name
+  of the kernel config file. Instead of the default kernelconfig.target
+  name you should use ``kernelconfig-<revision>.target``. In the kernel
+  config file menu entry you should enter
+  ``kernelconfig-$PTXCONF_KERNEL_VERSION.target``. Whenever you change
+  the linux kernel Version menu entry now, this will ensure using a
+  different kernel config file, too.
+
+Using Java packages
+~~~~~~~~~~~~~~~~~~~
+Question:
+  I’m trying to use a JAVA based package in PTXdist. But compiling
+  fails badly. Does it ever work at Pengutronix?
+
+Answer:
+  This kind of packages only build correctly when an original SUN VM
+  SDK is used. Run PTXdist setup and point the Java SDK menu entry to
+  the installation path of your SUN JAVA SDK.
+
+I get the error “cannot run '/etc/init.d/rcS': No such file or directory”
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Question:
+  I made a new project and everythings seems fine. But when I start my
+  target with the root filesystem generated by PTXdist, it fails with::
+
+      cannot run '/etc/init.d/rcS': No such file or directory
+
+Answer:
+  The error message is confusing. But this script needs ``/bin/sh`` to
+  run. Most of the time this message occures when ``/bin/sh`` does not
+  exists. Did you enable it in your busybox configuration?
+
+I get the error “ptxdist: archives: command not found”
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Question:
+  I have created a path for my source archives and try to make PTXdist
+  use it. But whenever I run PTXdist now it fails with the following error
+  message::
+
+      /usr/local/bin/ptxdist: archives: command not found
+
+Answer:
+  In this case the path was ``$HOME/source archives`` which includes a
+  whitespace in the name of the directory to store the source archives in.
+  Handling directory or filenames with whitespaces in applications isn’t
+  trivial and also PTXdist suffers all over the place from this issue. The
+  only solution is to avoid whitespaces in paths and filenames.
+
+I have adapted my own rule file’s targetinstall stage, but PTXdist does not install the files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Answer:
+  Check if the closing ``@$(call install_finish, [...])`` is present at
+  the end of the targetinsall stage.  If not, PTXdist will not complete
+  this stage.
-- 
2.11.0


_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de

[ptxdist] [PATCH 4/4] doc: faq: copy editing, small rewrites for more clarity

[Roland Hieber]

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

diff --git a/doc/faq.rst b/doc/faq.rst
index 2ebbba17c..e194dd914 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -6,12 +6,15 @@ PTXdist does not support to generate some files in a way I need them. What can I
 Answer:
   Everything PTXdist builds is controlled by “package rule files”,
   which in fact are Makefiles (``rules/*.make``). If you modify such a
-  file you can change it’s behaviour in a way you need. It is generally
-  no good idea to modify the generic package rule files installed by
+  file you can change its behaviour in a way you need. It is generally
+  not a good idea to modify the generic package rule files installed by
   PTXdist, but it is always possible to copy one of them over into the
-  ``rules/`` directory of a project. Package rule files in the project
+  ``rules/`` directory of your project. Package rule files in the project
   will precede global rule files with the same name.
 
+  Read the section :ref:`_ptx_dev_manual` in the Developer’s Manual to get
+  more information.
+
 How can I stop PTXdist to build in parallel?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Question:
@@ -36,16 +39,16 @@ Question:
 Answer:
   Yes, this error message is confusing. But it usually only means
   that you should check the following (!) lines for missing backslashes
-  (line separators).
+  (line continuation).
 
 I got a message similar to “package <name> is empty. not generating.” What does it mean?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Answer:
-  The ’ipkg’ tool was advised to generate a new ipkg-packet, but the
-  folder was empty. Sometime it means a typo in the package name when
+  The ``ipkg`` tool was advised to generate a new ipkg archive, but the
+  folder was empty. Sometimes this is just a typo in the package name when
   the ``install_copy`` macro was called. Ensure all these macros are using
-  the same package name. Or did you disable a menuentry and now nothing
-  will be installed?
+  the same package name. Or did you disable a menu entry and now nothing
+  is installed?
 
 How do I download all required packages at once?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -55,8 +58,8 @@ Answer:
       $ ptxdist make get
 
   This starts to download all required packages in one run. It does
-  nothing if the archives are already present in the source path. (run
-  “PTXdist setup” first).
+  nothing if the archives are already present in the source path. Run
+  ``ptxdist setup`` first to set up the desired source folder.
 
 I want to backup all source archives for my BSP
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -71,7 +74,7 @@ Answer:
       $ ptxdist export_src <archive directory>
 
   It copies all archives from where are your source archives stored to
-  <archive directory> which can be your backup media.
+  the path ``<archive directory>`` which can be on your backup media.
 
 OSELAS toolchain fails to start due to missing libraries
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -82,12 +85,14 @@ Question:
   failing to start due to missing libraries.
 
 Answer:
-  This happens when the toolchain was copied without regarding to
-  retain links. There are archive programs around that convert links
+  This happens when the toolchain was copied without regard to
+  retaining symlinks. There are archive programs around that convert links
   into real files. When you are using such programs to create a
   toolchain archive this toolchain will be broken after extracting it
-  again. Solution: Use archive programs that retain links as they are
-  (tar for example). Here an example for a broken toolchain::
+  again.
+  
+  Solution: Use archive programs that retain symlinks as they are
+  (tar for example). Here is an example of a broken toolchain::
 
       $ ll `find . -name "libcrypt*"`
       -rwxr-xr-x 1 mkl ptx 55K 2007-07-25 14:54 ./lib/libcrypt-2.5.so*
@@ -130,27 +135,27 @@ Using more than one kernel version per BSP
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Question:
   I want to use more than one kernel revision in my BSP. How can I
-  avoid maintaining one ptxconfig per kernel?
+  avoid maintaining one platformconfig per kernel?
 
 Answer:
   One solution could be to include the kernel revision into the name
-  of the kernel config file. Instead of the default kernelconfig.target
-  name you should use ``kernelconfig-<revision>.target``. In the kernel
-  config file menu entry you should enter
-  ``kernelconfig-$PTXCONF_KERNEL_VERSION.target``. Whenever you change
-  the linux kernel Version menu entry now, this will ensure using a
-  different kernel config file, too.
+  of the kernel config file. Instead of the default ``kernelconfig``
+  name you could use ``kernelconfig-<revision>`` instead. In ``ptxdist
+  menuconfig platform`` under *Linux kernel → patching & configuration*,
+  change the entry *kernel config file* to something like
+  ``kernelconfig-$PTXCONF_KERNEL_VERSION``.
 
 Using Java packages
 ~~~~~~~~~~~~~~~~~~~
 Question:
-  I’m trying to use a JAVA based package in PTXdist. But compiling
+  I’m trying to use a Java based package in PTXdist. But compiling
   fails badly. Does it ever work at Pengutronix?
 
 Answer:
-  This kind of packages only build correctly when an original SUN VM
-  SDK is used. Run PTXdist setup and point the Java SDK menu entry to
-  the installation path of your SUN JAVA SDK.
+  Some Java packages only build correctly when an original Oracle Java
+  SDK is used on the host.
+  Run ``ptxdist setup`` and point the *Java SDK* menu entry to
+  the installation path of your Oracle Java SDK.
 
 I get the error “cannot run '/etc/init.d/rcS': No such file or directory”
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -168,22 +173,22 @@ Answer:
 I get the error “ptxdist: archives: command not found”
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Question:
-  I have created a path for my source archives and try to make PTXdist
-  use it. But whenever I run PTXdist now it fails with the following error
+  I have set a path for my source archives in ``ptxdist setup``.
+  But whenever I run PTXdist now it fails with the following error
   message::
 
       /usr/local/bin/ptxdist: archives: command not found
 
 Answer:
-  In this case the path was ``$HOME/source archives`` which includes a
-  whitespace in the name of the directory to store the source archives in.
+  This happens if your source download path contains whitespace, e.g
+  ``$HOME/source archives``.
   Handling directory or filenames with whitespaces in applications isn’t
   trivial and also PTXdist suffers all over the place from this issue. The
-  only solution is to avoid whitespaces in paths and filenames.
+  only solution is to avoid whitespace in paths and filenames.
 
 I have adapted my own rule file’s targetinstall stage, but PTXdist does not install the files
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Answer:
   Check if the closing ``@$(call install_finish, [...])`` is present at
-  the end of the targetinsall stage.  If not, PTXdist will not complete
+  the end of the *targetinstall* stage. If not, PTXdist will not complete
   this stage.
-- 
2.11.0


_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de

Re: [ptxdist] [PATCH 1/4] doc: document git patch workflow

[Bastian Stender]

Hey,

On 07/14/2017 12:57 PM, Roland Hieber wrote:
> Signed-off-by: Roland Hieber <r.hieber@pengutronix.de>
> ---
>  doc/dev_manual.rst | 40 +++++++++++++++++++++++++++++++++++++---
>  1 file changed, 37 insertions(+), 3 deletions(-)
>
> diff --git a/doc/dev_manual.rst b/doc/dev_manual.rst
> index a54888b43..3fe64a343 100644
> --- a/doc/dev_manual.rst
> +++ b/doc/dev_manual.rst
> @@ -1223,7 +1223,6 @@ Creating Patches for a Package
>  PTXdist uses the utilities *git*, *patch* or *quilt* to work with
>  patches or patch series. We recommend *git*, as it can manage patch
>  series in a very easy way.
> -For this manual and the example we use *quilt* instead.
>
>  Creating a Patch Series for a Package
>  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> @@ -1248,6 +1247,9 @@ and an empty ``patch`` file.
>      $ touch patches/foo-1.1.0/dummy
>      $ echo dummy > patches/foo-1.1.0/series
>
> +Using quilt
> +"""""""""""
> +
>  Next is to extract the package (if already done, we must remove it
>  first):
>
> @@ -1263,11 +1265,43 @@ present in ``patches/foo-1.1.0`` and can be used the next time we
>  extract the package again.
>
>  All we have to do now is to do the modification we need to make the
> -package work. We change into the build directory and use *quilt* to
> +package work. We change into the build directory and use quilt_ to
>  create new patches, add files to respective patches, modify these files
>  and refresh the patches to save our changes.
> +See the *quilt* documentation for more information.
> +
> +.. _quilt: http://savannah.nongnu.org/projects/quilt
> +
> +Using Git
> +"""""""""
> +
> +After touching the series file like above, apply an additional command line
> +switch to extract the package into a Git repository:
> +
> +::
> +
> +    $ ptxdist --git extract foo
> +
> +.. note:: Optionally, you can enable the setting *Developer Options → use git to
> +  apply patches* in `ptxdist setup` to enable this permanently.
> +  However, note that this setting is still experimental.

Maybe we should mention that this can lead to unexpected side effects. I 
remember debugging a package configured with autoconf and AX_IS_RELEASE:

   https://www.gnu.org/software/autoconf-archive/ax_is_release.html

This lead to treating warnings as errors with "use git to apply patches" 
and thus compilation failed.

> +
> +Then, change into the package build directory, patch the required files, and
> +make Git commits on the way.
> +The Git history should now look something like this:
> +
> +::
> +
> +    $ git log --oneline --decorate
> +    * df343e821851 (HEAD -> master) Makefile: don't build the tests
> +    * 65a360c2bd60 strfry.c: frobnicate the excusator
> +    * fdc315f6844c (tag: foobar-1.1.0, tag: base) initial commit
> +
> +After commit your patches, call ``git ptx-patches`` to regenerate the patches
> +and the series file in the ``patches/foo-0.1`` folder, so they don't get lost
> +when cleaning the package.

This should be consistent, so ``patches/foo-1.1.0``.

>
> -We recommend this way when modifying source files. But this way is
> +We recommend working with patches when modifying source files. But this way is
>  improper when an autotools based buildsystem itself needs modifications.
>  Refer to section :ref:`configure_rebuild` on how PTXdist can
>  handle this special task.
>

Bastian

_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de

Re: [ptxdist] [PATCH 1/4] doc: document git patch workflow

[Roland Hieber]

On 14.07.2017 14:21, Bastian Stender wrote:
>> +.. note:: Optionally, you can enable the setting *Developer Options →
>> use git to
>> +  apply patches* in `ptxdist setup` to enable this permanently.
>> +  However, note that this setting is still experimental.
>
> Maybe we should mention that this can lead to unexpected side effects. I
> remember debugging a package configured with autoconf and AX_IS_RELEASE:
>
>   https://www.gnu.org/software/autoconf-archive/ax_is_release.html
>
> This lead to treating warnings as errors with "use git to apply patches"
> and thus compilation failed.

Yes, I remembered something like that, but I couldn't reproduce the 
exact error so I just formulated it generally.

>> +After commit your patches, call ``git ptx-patches`` to regenerate the
>> patches
>> +and the series file in the ``patches/foo-0.1`` folder, so they don't
>> get lost
>> +when cleaning the package.
>
> This should be consistent, so ``patches/foo-1.1.0``.

Oh, I changed it afterwards and overlooked that one. Thanks, will send v2.

  - Roland

_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de

Re: [ptxdist] [PATCH 4/4] doc: faq: copy editing, small rewrites for more clarity

[Michael Olbrich]

On Fri, Jul 14, 2017 at 12:57:15PM +0200, Roland Hieber wrote:
> Signed-off-by: Roland Hieber <r.hieber@pengutronix.de>
> ---
>  doc/faq.rst | 69 +++++++++++++++++++++++++++++++++----------------------------
>  1 file changed, 37 insertions(+), 32 deletions(-)
> 
> diff --git a/doc/faq.rst b/doc/faq.rst
> index 2ebbba17c..e194dd914 100644
> --- a/doc/faq.rst
> +++ b/doc/faq.rst
> @@ -6,12 +6,15 @@ PTXdist does not support to generate some files in a way I need them. What can I
>  Answer:
>    Everything PTXdist builds is controlled by “package rule files”,
>    which in fact are Makefiles (``rules/*.make``). If you modify such a
> -  file you can change it’s behaviour in a way you need. It is generally
> -  no good idea to modify the generic package rule files installed by
> +  file you can change its behaviour in a way you need. It is generally
> +  not a good idea to modify the generic package rule files installed by
>    PTXdist, but it is always possible to copy one of them over into the
> -  ``rules/`` directory of a project. Package rule files in the project
> +  ``rules/`` directory of your project. Package rule files in the project
>    will precede global rule files with the same name.
>  
> +  Read the section :ref:`_ptx_dev_manual` in the Developer’s Manual to get

This produces an error. I think, this should be ':ref:`ptx_dev_manual`'.

Michael

> +  more information.
> +
>  How can I stop PTXdist to build in parallel?
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  Question:
> @@ -36,16 +39,16 @@ Question:
>  Answer:
>    Yes, this error message is confusing. But it usually only means
>    that you should check the following (!) lines for missing backslashes
> -  (line separators).
> +  (line continuation).
>  
>  I got a message similar to “package <name> is empty. not generating.” What does it mean?
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  Answer:
> -  The ’ipkg’ tool was advised to generate a new ipkg-packet, but the
> -  folder was empty. Sometime it means a typo in the package name when
> +  The ``ipkg`` tool was advised to generate a new ipkg archive, but the
> +  folder was empty. Sometimes this is just a typo in the package name when
>    the ``install_copy`` macro was called. Ensure all these macros are using
> -  the same package name. Or did you disable a menuentry and now nothing
> -  will be installed?
> +  the same package name. Or did you disable a menu entry and now nothing
> +  is installed?
>  
>  How do I download all required packages at once?
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> @@ -55,8 +58,8 @@ Answer:
>        $ ptxdist make get
>  
>    This starts to download all required packages in one run. It does
> -  nothing if the archives are already present in the source path. (run
> -  “PTXdist setup” first).
> +  nothing if the archives are already present in the source path. Run
> +  ``ptxdist setup`` first to set up the desired source folder.
>  
>  I want to backup all source archives for my BSP
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> @@ -71,7 +74,7 @@ Answer:
>        $ ptxdist export_src <archive directory>
>  
>    It copies all archives from where are your source archives stored to
> -  <archive directory> which can be your backup media.
> +  the path ``<archive directory>`` which can be on your backup media.
>  
>  OSELAS toolchain fails to start due to missing libraries
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> @@ -82,12 +85,14 @@ Question:
>    failing to start due to missing libraries.
>  
>  Answer:
> -  This happens when the toolchain was copied without regarding to
> -  retain links. There are archive programs around that convert links
> +  This happens when the toolchain was copied without regard to
> +  retaining symlinks. There are archive programs around that convert links
>    into real files. When you are using such programs to create a
>    toolchain archive this toolchain will be broken after extracting it
> -  again. Solution: Use archive programs that retain links as they are
> -  (tar for example). Here an example for a broken toolchain::
> +  again.
> +  
> +  Solution: Use archive programs that retain symlinks as they are
> +  (tar for example). Here is an example of a broken toolchain::
>  
>        $ ll `find . -name "libcrypt*"`
>        -rwxr-xr-x 1 mkl ptx 55K 2007-07-25 14:54 ./lib/libcrypt-2.5.so*
> @@ -130,27 +135,27 @@ Using more than one kernel version per BSP
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  Question:
>    I want to use more than one kernel revision in my BSP. How can I
> -  avoid maintaining one ptxconfig per kernel?
> +  avoid maintaining one platformconfig per kernel?
>  
>  Answer:
>    One solution could be to include the kernel revision into the name
> -  of the kernel config file. Instead of the default kernelconfig.target
> -  name you should use ``kernelconfig-<revision>.target``. In the kernel
> -  config file menu entry you should enter
> -  ``kernelconfig-$PTXCONF_KERNEL_VERSION.target``. Whenever you change
> -  the linux kernel Version menu entry now, this will ensure using a
> -  different kernel config file, too.
> +  of the kernel config file. Instead of the default ``kernelconfig``
> +  name you could use ``kernelconfig-<revision>`` instead. In ``ptxdist
> +  menuconfig platform`` under *Linux kernel → patching & configuration*,
> +  change the entry *kernel config file* to something like
> +  ``kernelconfig-$PTXCONF_KERNEL_VERSION``.
>  
>  Using Java packages
>  ~~~~~~~~~~~~~~~~~~~
>  Question:
> -  I’m trying to use a JAVA based package in PTXdist. But compiling
> +  I’m trying to use a Java based package in PTXdist. But compiling
>    fails badly. Does it ever work at Pengutronix?
>  
>  Answer:
> -  This kind of packages only build correctly when an original SUN VM
> -  SDK is used. Run PTXdist setup and point the Java SDK menu entry to
> -  the installation path of your SUN JAVA SDK.
> +  Some Java packages only build correctly when an original Oracle Java
> +  SDK is used on the host.
> +  Run ``ptxdist setup`` and point the *Java SDK* menu entry to
> +  the installation path of your Oracle Java SDK.
>  
>  I get the error “cannot run '/etc/init.d/rcS': No such file or directory”
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> @@ -168,22 +173,22 @@ Answer:
>  I get the error “ptxdist: archives: command not found”
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  Question:
> -  I have created a path for my source archives and try to make PTXdist
> -  use it. But whenever I run PTXdist now it fails with the following error
> +  I have set a path for my source archives in ``ptxdist setup``.
> +  But whenever I run PTXdist now it fails with the following error
>    message::
>  
>        /usr/local/bin/ptxdist: archives: command not found
>  
>  Answer:
> -  In this case the path was ``$HOME/source archives`` which includes a
> -  whitespace in the name of the directory to store the source archives in.
> +  This happens if your source download path contains whitespace, e.g
> +  ``$HOME/source archives``.
>    Handling directory or filenames with whitespaces in applications isn’t
>    trivial and also PTXdist suffers all over the place from this issue. The
> -  only solution is to avoid whitespaces in paths and filenames.
> +  only solution is to avoid whitespace in paths and filenames.
>  
>  I have adapted my own rule file’s targetinstall stage, but PTXdist does not install the files
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  Answer:
>    Check if the closing ``@$(call install_finish, [...])`` is present at
> -  the end of the targetinsall stage.  If not, PTXdist will not complete
> +  the end of the *targetinstall* stage. If not, PTXdist will not complete
>    this stage.
> -- 
> 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

Re: [ptxdist] [PATCH 3/4] doc: faq: apply more structure

[Michael Olbrich]

On Fri, Jul 14, 2017 at 12:57:14PM +0200, Roland Hieber wrote:
> Give the FAQ section some more structure by inserting one heading per
> FAQ item, and separate questions and answers visible. This also causes
> the questions to appear in the table of contents. Both should lead to
> more readability of the FAQ section.
> 
> Signed-off-by: Roland Hieber <r.hieber@pengutronix.de>
> ---
>  doc/faq.rst | 330 +++++++++++++++++++++++++++++++++---------------------------
>  1 file changed, 181 insertions(+), 149 deletions(-)
> 
> diff --git a/doc/faq.rst b/doc/faq.rst
> index 952705883..2ebbba17c 100644
> --- a/doc/faq.rst
> +++ b/doc/faq.rst
> @@ -1,157 +1,189 @@
>  Frequently Asked Questions (FAQ)
>  --------------------------------
>  
> -Q: PTXdist does not support to generate some files in a way I need them. What can I do?
> -A: Everything PTXdist builds is controlled by “package rule files”,
> -which in fact are Makefiles (``rules/*.make``). If you modify such a
> -file you can change it’s behaviour in a way you need. It is generally
> -no good idea to modify the generic package rule files installed by
> -PTXdist, but it is always possible to copy one of them over into the
> -``rules/`` directory of a project. Package rule files in the project
> -will precede global rule files with the same name.
> -
> -Q: My kernel build fails. But I cannot detect the correct position,
> -due to parallel building. How can I stop PTXdist to build in parallel?
> -A: Force PTXdist to stop building in parallel which looks somehow
> -like:
> -
> -::
> -
> -    $ ptxdist -j1 go
> -
> -Q: I made my own rule file and now I get error messages like
> -
> -::
> -
> -    my_project/rules/test.make:30: *** unterminated call to function `call': missing `)'.  Stop.
> -
> -But line 30 only contains ``@$(call targetinfo, $@)`` and it seems all
> -right. What does it mean?
> -A: Yes, this error message is confusing. But it usually only means
> -that you should check the following (!) lines for missing backslashes
> -(line separators).
> -
> -Q: I got a message similar to “package <some name> is empty. not
> -generating.” What does it mean?
> -A: The ’ipkg’ tool was advised to generate a new ipkg-packet, but the
> -folder was empty. Sometime it means a typo in the package name when
> -the ``install_copy`` macro was called. Ensure all these macros are using
> -the same package name. Or did you disable a menuentry and now nothing
> -will be installed?
> -
> -Q: How do I download all required packages at once?
> -A: Run this command prior the build:
> -
> -::
> -
> -    $ ptxdist make get
> -
> -This starts to download all required packages in one run. It does
> -nothing if the archives are already present in the source path. (run
> -“PTXdist setup” first).
> -
> -Q: I want to backup the source archives my PTXdist project relys on.
> -How can I find out what packages my project requires to build?
> -A: First build your PTXdist project completely and then run the
> -following command:
> -
> -::
> -
> -    $ ptxdist export_src <archive directory>
> -
> -It copies all archives from where are your source archives stored to
> -<archive directory> which can be your backup media.
> -
> -Q: To avoid building the OSELAS toolchain on each development host, I
> -copied it to another machine. But on this machine I cannot build any
> -BSP with this toolchain correctly. All applications on the target are
> -failing to start due to missing libraries.
> -A: This happens when the toolchain was copied without regarding to
> -retain links. There are archive programs around that convert links
> -into real files. When you are using such programs to create a
> -toolchain archive this toolchain will be broken after extracting it
> -again. Solution: Use archive programs that retain links as they are
> -(tar for example). Here an example for a broken toolchain:
> -
> -::
> -
> -    $ ll `find . -name "libcrypt*"`
> -    -rwxr-xr-x 1 mkl ptx 55K 2007-07-25 14:54 ./lib/libcrypt-2.5.so*
> -    -rwxr-xr-x 1 mkl ptx 55K 2007-07-25 14:54 ./lib/libcrypt.so.1*
> -    -rw-r--r-- 1 mkl ptx 63K 2007-07-25 14:54 ./usr/lib/libcrypt.a
> -    -rw-r--r-- 1 mkl ptx 64K 2007-07-25 14:54 ./usr/lib/libcrypt_p.a
> -    -rwxr-xr-x 1 mkl ptx 55K 2007-07-25 14:54 ./usr/lib/libcrypt.so*
> -
> -And in contrast, this one is intact:
> -
> -::
> -
> -    $ ll `find . -name "libcrypt*"`
> -    -rwxr-xr-x 1 mkl ptx 55K 2007-11-03 13:30 ./lib/libcrypt-2.5.so*
> -    lrwxrwxrwx 1 mkl ptx  15 2008-02-20 14:52 ./lib/libcrypt.so.1 -> libcrypt-2.5.so*
> -    -rw-r--r-- 1 mkl ptx 63K 2007-11-03 13:30 ./usr/lib/libcrypt.a
> -    -rw-r--r-- 1 mkl ptx 64K 2007-11-03 13:30 ./usr/lib/libcrypt_p.a
> -    lrwxrwxrwx 1 mkl ptx  23 2008-02-20 14:52 ./usr/lib/libcrypt.so -> ../../lib/libcrypt.so.1*
> -
> -Q: I followed the instructions how to integrate my own plain source
> -project into PTXdist. But when I try to build it, I get:
> -
> -::
> +PTXdist does not support to generate some files in a way I need them. What can I do?
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Answer:
> +  Everything PTXdist builds is controlled by “package rule files”,
> +  which in fact are Makefiles (``rules/*.make``). If you modify such a
> +  file you can change it’s behaviour in a way you need. It is generally
> +  no good idea to modify the generic package rule files installed by
> +  PTXdist, but it is always possible to copy one of them over into the
> +  ``rules/`` directory of a project. Package rule files in the project
> +  will precede global rule files with the same name.
> +
> +How can I stop PTXdist to build in parallel?
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Question:
> +  My build fails, but I cannot detect the correct position due to parallel
> +  building.
> +
> +Answer:
> +  Force PTXdist to stop building in parallel which looks somehow like::
> +
> +      $ ptxdist -j1 go
> +
> +I get errors like “unterminated call to function `call': missing `)'”

This produces warnings. Use "'" instead of "`" here.

Michael

> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Question:
> +  I made my own rule file and now I get error messages like::
> +
> +      my_project/rules/test.make:30: *** unterminated call to function `call': missing `)'.  Stop.
> +
> +  But line 30 only contains ``@$(call targetinfo, $@)`` and it seems all
> +  right. What does it mean?
> +
> +Answer:
> +  Yes, this error message is confusing. But it usually only means
> +  that you should check the following (!) lines for missing backslashes
> +  (line separators).
> +
> +I got a message similar to “package <name> is empty. not generating.” What does it mean?
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Answer:
> +  The ’ipkg’ tool was advised to generate a new ipkg-packet, but the
> +  folder was empty. Sometime it means a typo in the package name when
> +  the ``install_copy`` macro was called. Ensure all these macros are using
> +  the same package name. Or did you disable a menuentry and now nothing
> +  will be installed?
> +
> +How do I download all required packages at once?
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Answer:
> +  Run this command prior the build::
> +
> +      $ ptxdist make get
> +
> +  This starts to download all required packages in one run. It does
> +  nothing if the archives are already present in the source path. (run
> +  “PTXdist setup” first).
> +
> +I want to backup all source archives for my BSP
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Question:
> +  I want to backup the source archives my PTXdist project relys on.
> +  How can I find out what packages my project requires to build?
> +
> +Answer:
> +  First build your PTXdist project completely and then run the
> +  following command::
> +
> +      $ ptxdist export_src <archive directory>
> +
> +  It copies all archives from where are your source archives stored to
> +  <archive directory> which can be your backup media.
> +
> +OSELAS toolchain fails to start due to missing libraries
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Question:
> +  To avoid building the OSELAS toolchain on each development host, I
> +  copied it to another machine. But on this machine I cannot build any
> +  BSP with this toolchain correctly. All applications on the target are
> +  failing to start due to missing libraries.
> +
> +Answer:
> +  This happens when the toolchain was copied without regarding to
> +  retain links. There are archive programs around that convert links
> +  into real files. When you are using such programs to create a
> +  toolchain archive this toolchain will be broken after extracting it
> +  again. Solution: Use archive programs that retain links as they are
> +  (tar for example). Here an example for a broken toolchain::
> +
> +      $ ll `find . -name "libcrypt*"`
> +      -rwxr-xr-x 1 mkl ptx 55K 2007-07-25 14:54 ./lib/libcrypt-2.5.so*
> +      -rwxr-xr-x 1 mkl ptx 55K 2007-07-25 14:54 ./lib/libcrypt.so.1*
> +      -rw-r--r-- 1 mkl ptx 63K 2007-07-25 14:54 ./usr/lib/libcrypt.a
> +      -rw-r--r-- 1 mkl ptx 64K 2007-07-25 14:54 ./usr/lib/libcrypt_p.a
> +      -rwxr-xr-x 1 mkl ptx 55K 2007-07-25 14:54 ./usr/lib/libcrypt.so*
> +
> +  And in contrast, this one is intact::
> +
> +      $ ll `find . -name "libcrypt*"`
> +      -rwxr-xr-x 1 mkl ptx 55K 2007-11-03 13:30 ./lib/libcrypt-2.5.so*
> +      lrwxrwxrwx 1 mkl ptx  15 2008-02-20 14:52 ./lib/libcrypt.so.1 -> libcrypt-2.5.so*
> +      -rw-r--r-- 1 mkl ptx 63K 2007-11-03 13:30 ./usr/lib/libcrypt.a
> +      -rw-r--r-- 1 mkl ptx 64K 2007-11-03 13:30 ./usr/lib/libcrypt_p.a
> +      lrwxrwxrwx 1 mkl ptx  23 2008-02-20 14:52 ./usr/lib/libcrypt.so -> ../../lib/libcrypt.so.1*
> +
> +
> +PTXdist does not find my own sources: “Unknown format, cannot extract”
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Question:
> +  I followed the instructions how to integrate my own plain source
> +  project into PTXdist. But when I try to build it, I get::
>  
>      extract: archive=/path/to/my/sources
>      extract: dest=/path/to/my/project/build-target
>      Unknown format, cannot extract!
>  
> -But the path exists!
> -A: PTXdist interprets a ``file://`` (two slashes) in the URL as a
> -project related relative path. So it searches only in the current
> -project for the given path. Only ``file:///`` (three slashes) will
> -force PTXdist to use the path as an absolute one. This means:
> -``file://bla/blub`` will be used as ``./bla/blub`` and
> -``file:///friesel/frasel`` as ``/friesel/frasel``.
> -
> -Q: I want to use more than one kernel revision in my BSP. How can I
> -avoid maintaining one ptxconfig per kernel?
> -A: One solution could be to include the kernel revision into the name
> -of the kernel config file. Instead of the default kernelconfig.target
> -name you should use ``kernelconfig-<revision>.target``. In the kernel
> -config file menu entry you should enter
> -``kernelconfig-$PTXCONF_KERNEL_VERSION.target``. Whenever you change
> -the linux kernel Version menu entry now, this will ensure using a
> -different kernel config file, too.
> -
> -Q: I’m trying to use a JAVA based package in PTXdist. But compiling
> -fails badly. Does it ever work at Pengutronix?
> -A: This kind of packages only build correctly when an original SUN VM
> -SDK is used. Run PTXdist setup and point the Java SDK menu entry to
> -the installation path of your SUN JAVA SDK.
> -
> -Q: I made a new project and everythings seems fine. But when I start my
> -target with the root filesystem generated by PTXdist, it fails with:
> -
> -::
> -
> -    cannot run '/etc/init.d/rcS': No such file or directory
> -
> -A: The error message is confusing. But this script needs ``/bin/sh`` to
> -run. Most of the time this message occures when ``/bin/sh`` does not
> -exists. Did you enable it in your busybox configuration?
> -
> -Q: I have created a path for my source archives and try to make PTXdist
> -use it. But whenever I run PTXdist now it fails with the following error
> -message:
> -
> -::
> -
> -    /usr/local/bin/ptxdist: archives: command not found
> -
> -A: In this case the path was ``$HOME/source archives`` which includes a
> -whitespace in the name of the directory to store the source archives in.
> -Handling directory or filenames with whitespaces in applications isn’t
> -trivial and also PTXdist suffers all over the place from this issue. The
> -only solution is to avoid whitespaces in paths and filenames.
> -
> -Q: I have adapted my own rule file’s targetinstall stage, but PTXdist
> -does not install the files. A: Check if the closing ``@$(call
> -install_finish, [...])`` is present at the end of the targetinsall stage.
> -If not, PTXdist will not complete this stage.
> +  But the path exists!
> +
> +Answer:
> +  PTXdist interprets a ``file://`` (two slashes) in the URL as a
> +  project related relative path. So it searches only in the current
> +  project for the given path. Only ``file:///`` (three slashes) will
> +  force PTXdist to use the path as an absolute one. This means:
> +  ``file://bla/blub`` will be used as ``./bla/blub`` and
> +  ``file:///friesel/frasel`` as ``/friesel/frasel``.
> +
> +Using more than one kernel version per BSP
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Question:
> +  I want to use more than one kernel revision in my BSP. How can I
> +  avoid maintaining one ptxconfig per kernel?
> +
> +Answer:
> +  One solution could be to include the kernel revision into the name
> +  of the kernel config file. Instead of the default kernelconfig.target
> +  name you should use ``kernelconfig-<revision>.target``. In the kernel
> +  config file menu entry you should enter
> +  ``kernelconfig-$PTXCONF_KERNEL_VERSION.target``. Whenever you change
> +  the linux kernel Version menu entry now, this will ensure using a
> +  different kernel config file, too.
> +
> +Using Java packages
> +~~~~~~~~~~~~~~~~~~~
> +Question:
> +  I’m trying to use a JAVA based package in PTXdist. But compiling
> +  fails badly. Does it ever work at Pengutronix?
> +
> +Answer:
> +  This kind of packages only build correctly when an original SUN VM
> +  SDK is used. Run PTXdist setup and point the Java SDK menu entry to
> +  the installation path of your SUN JAVA SDK.
> +
> +I get the error “cannot run '/etc/init.d/rcS': No such file or directory”
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Question:
> +  I made a new project and everythings seems fine. But when I start my
> +  target with the root filesystem generated by PTXdist, it fails with::
> +
> +      cannot run '/etc/init.d/rcS': No such file or directory
> +
> +Answer:
> +  The error message is confusing. But this script needs ``/bin/sh`` to
> +  run. Most of the time this message occures when ``/bin/sh`` does not
> +  exists. Did you enable it in your busybox configuration?
> +
> +I get the error “ptxdist: archives: command not found”
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Question:
> +  I have created a path for my source archives and try to make PTXdist
> +  use it. But whenever I run PTXdist now it fails with the following error
> +  message::
> +
> +      /usr/local/bin/ptxdist: archives: command not found
> +
> +Answer:
> +  In this case the path was ``$HOME/source archives`` which includes a
> +  whitespace in the name of the directory to store the source archives in.
> +  Handling directory or filenames with whitespaces in applications isn’t
> +  trivial and also PTXdist suffers all over the place from this issue. The
> +  only solution is to avoid whitespaces in paths and filenames.
> +
> +I have adapted my own rule file’s targetinstall stage, but PTXdist does not install the files
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Answer:
> +  Check if the closing ``@$(call install_finish, [...])`` is present at
> +  the end of the targetinsall stage.  If not, PTXdist will not complete
> +  this stage.
> -- 
> 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

Re: [ptxdist] [PATCH 1/4] doc: document git patch workflow

[Michael Olbrich]

On Fri, Jul 14, 2017 at 12:57:12PM +0200, Roland Hieber wrote:
> Signed-off-by: Roland Hieber <r.hieber@pengutronix.de>
> ---
>  doc/dev_manual.rst | 40 +++++++++++++++++++++++++++++++++++++---
>  1 file changed, 37 insertions(+), 3 deletions(-)
> 
> diff --git a/doc/dev_manual.rst b/doc/dev_manual.rst
> index a54888b43..3fe64a343 100644
> --- a/doc/dev_manual.rst
> +++ b/doc/dev_manual.rst
> @@ -1223,7 +1223,6 @@ Creating Patches for a Package
>  PTXdist uses the utilities *git*, *patch* or *quilt* to work with
>  patches or patch series. We recommend *git*, as it can manage patch
>  series in a very easy way.
> -For this manual and the example we use *quilt* instead.
>  
>  Creating a Patch Series for a Package
>  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> @@ -1248,6 +1247,9 @@ and an empty ``patch`` file.
>      $ touch patches/foo-1.1.0/dummy
>      $ echo dummy > patches/foo-1.1.0/series
>  
> +Using quilt
> +"""""""""""
> +
>  Next is to extract the package (if already done, we must remove it
>  first):
>  
> @@ -1263,11 +1265,43 @@ present in ``patches/foo-1.1.0`` and can be used the next time we
>  extract the package again.
>  
>  All we have to do now is to do the modification we need to make the
> -package work. We change into the build directory and use *quilt* to
> +package work. We change into the build directory and use quilt_ to
>  create new patches, add files to respective patches, modify these files
>  and refresh the patches to save our changes.
> +See the *quilt* documentation for more information.

Maybe put the link into the sentence that mentions the docs?

> +
> +.. _quilt: http://savannah.nongnu.org/projects/quilt
> +
> +Using Git
> +"""""""""
> +
> +After touching the series file like above, apply an additional command line
> +switch to extract the package into a Git repository:
> +
> +::
> +
> +    $ ptxdist --git extract foo
> +
> +.. note:: Optionally, you can enable the setting *Developer Options → use git to
> +  apply patches* in `ptxdist setup` to enable this permanently.
> +  However, note that this setting is still experimental.
> +
> +Then, change into the package build directory, patch the required files, and
> +make Git commits on the way.
> +The Git history should now look something like this:
> +
> +::
> +
> +    $ git log --oneline --decorate
> +    * df343e821851 (HEAD -> master) Makefile: don't build the tests
> +    * 65a360c2bd60 strfry.c: frobnicate the excusator
> +    * fdc315f6844c (tag: foobar-1.1.0, tag: base) initial commit
> +
> +After commit your patches, call ``git ptx-patches`` to regenerate the patches
> +and the series file in the ``patches/foo-0.1`` folder, so they don't get lost
> +when cleaning the package.

Add something like this:

Note: PTXdist will only create a git repository for packages with patches.
To use git to generate the first patch, creates an empty series file
``patches/foobar-1.1.0/series`` before extracting the packages. This will
tell PTXdist to use git anyways and ``git ptx-patches`` will put the
patches there.

Michael

>  
> -We recommend this way when modifying source files. But this way is
> +We recommend working with patches when modifying source files. But this way is
>  improper when an autotools based buildsystem itself needs modifications.
>  Refer to section :ref:`configure_rebuild` on how PTXdist can
>  handle this special task.
> -- 
> 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

Re: [ptxdist] [PATCH 1/4] doc: document git patch workflow

[Uwe Kleine-König]

On Fri, Jul 14, 2017 at 12:57:12PM +0200, Roland Hieber wrote:
> Signed-off-by: Roland Hieber <r.hieber@pengutronix.de>
> ---
>  doc/dev_manual.rst | 40 +++++++++++++++++++++++++++++++++++++---
>  1 file changed, 37 insertions(+), 3 deletions(-)
> 
> diff --git a/doc/dev_manual.rst b/doc/dev_manual.rst
> index a54888b43..3fe64a343 100644
> --- a/doc/dev_manual.rst
> +++ b/doc/dev_manual.rst
> @@ -1223,7 +1223,6 @@ Creating Patches for a Package
>  PTXdist uses the utilities *git*, *patch* or *quilt* to work with
>  patches or patch series. We recommend *git*, as it can manage patch
>  series in a very easy way.
> -For this manual and the example we use *quilt* instead.
>  
>  Creating a Patch Series for a Package
>  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> @@ -1248,6 +1247,9 @@ and an empty ``patch`` file.
>      $ touch patches/foo-1.1.0/dummy
>      $ echo dummy > patches/foo-1.1.0/series
>  
> +Using quilt
> +"""""""""""
> +
>  Next is to extract the package (if already done, we must remove it
>  first):
>  
> @@ -1263,11 +1265,43 @@ present in ``patches/foo-1.1.0`` and can be used the next time we
>  extract the package again.
>  
>  All we have to do now is to do the modification we need to make the
> -package work. We change into the build directory and use *quilt* to
> +package work. We change into the build directory and use quilt_ to
>  create new patches, add files to respective patches, modify these files
>  and refresh the patches to save our changes.
> +See the *quilt* documentation for more information.
> +
> +.. _quilt: http://savannah.nongnu.org/projects/quilt
> +
> +Using Git
> +"""""""""
> +
> +After touching the series file like above, apply an additional command line
> +switch to extract the package into a Git repository:
> +
> +::
> +
> +    $ ptxdist --git extract foo
> +
> +.. note:: Optionally, you can enable the setting *Developer Options → use git to
> +  apply patches* in `ptxdist setup` to enable this permanently.
> +  However, note that this setting is still experimental.
> +
> +Then, change into the package build directory, patch the required files, and
> +make Git commits on the way.
> +The Git history should now look something like this:
> +
> +::
> +
> +    $ git log --oneline --decorate
> +    * df343e821851 (HEAD -> master) Makefile: don't build the tests
> +    * 65a360c2bd60 strfry.c: frobnicate the excusator
> +    * fdc315f6844c (tag: foobar-1.1.0, tag: base) initial commit
> +
> +After commit your patches, call ``git ptx-patches`` to regenerate the patches

My German feeling for English tells me, this should read:

	After committing your patches call ...

(i.e. s/commit/committing/ s/,//)

> +and the series file in the ``patches/foo-0.1`` folder, so they don't get lost
> +when cleaning the package.
>  
> -We recommend this way when modifying source files. But this way is
> +We recommend working with patches when modifying source files.

I don't understand this sentence. Is there an alternative to patches?
The only option I can think of it getting your patches upstream which is
still better than patches in ptxdist.

>  But this way is improper when an autotools based buildsystem itself
>  needs modifications.

Maybe:

Both approaches (git and quilt) are not suitable to modify files that
are autogenerated in autotools based buildsystems.

>  Refer to section :ref:`configure_rebuild` on how PTXdist can
>  handle this special task.

Best regards
Uwe

-- 
Pengutronix e.K.                           | Uwe Kleine-König            |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |

_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de