Re: [ptxdist] [PATCH 3/4] doc: faq: apply more structure
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 > --- > 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 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 > - > -It copies all archives from where are your source archives stored to > - 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? > +~~~
[ptxdist] [PATCH 3/4] doc: faq: apply more structure
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 --- 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 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 - -It copies all archives from where are your source archives stored to - 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 packag
