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.hie...@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
