diff options
| -rw-r--r-- | doc/daily_work.inc (renamed from doc/daily_work.rst) | 161 | ||||
| -rw-r--r-- | doc/daily_work_section.rst | 7 | ||||
| -rw-r--r-- | doc/faq.inc | 157 | ||||
| -rw-r--r-- | doc/index.rst | 2 | ||||
| -rw-r--r-- | doc/nfsroot.inc | 61 | ||||
| -rw-r--r-- | doc/ref_manual.rst | 3 | ||||
| -rw-r--r-- | doc/ref_parameter.inc | 3 | ||||
| -rw-r--r-- | doc/working_with_git_sources.inc | 6 |
8 files changed, 236 insertions, 164 deletions
diff --git a/doc/daily_work.rst b/doc/daily_work.inc index 2dc9c4c97..8f9f88c07 100644 --- a/doc/daily_work.rst +++ b/doc/daily_work.inc @@ -1,6 +1,3 @@ -Various Aspects of Daily Work -============================= - Using an External Kernel Source Tree ------------------------------------ @@ -1121,161 +1118,3 @@ application. Note: debugging is hard when all internal functions are hidden. For this case you should configure the libary with the ``--disable-hide`` or with ``--enable-debug`` which includes switching off hiding functions. - -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: - -:: - - 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. diff --git a/doc/daily_work_section.rst b/doc/daily_work_section.rst new file mode 100644 index 000000000..c5c963e4e --- /dev/null +++ b/doc/daily_work_section.rst @@ -0,0 +1,7 @@ +Various Aspects of Daily Work +============================= + +.. include:: daily_work.inc +.. include:: nfsroot.inc +.. include:: working_with_git_sources.inc +.. include:: faq.inc diff --git a/doc/faq.inc b/doc/faq.inc new file mode 100644 index 000000000..952705883 --- /dev/null +++ b/doc/faq.inc @@ -0,0 +1,157 @@ +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: + +:: + + 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. diff --git a/doc/index.rst b/doc/index.rst index da2c83dc8..bc608a51a 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -18,7 +18,7 @@ Contents: user_manual_section dev_manual ref_manual - daily_work + daily_work_section getting_help * :ref:`search` diff --git a/doc/nfsroot.inc b/doc/nfsroot.inc new file mode 100644 index 000000000..ee652edbf --- /dev/null +++ b/doc/nfsroot.inc @@ -0,0 +1,61 @@ +.. _nfsroot: + +Using a userland NFS Server for the Target +------------------------------------------ + +To improve the development of software for a target system, it is very exhausting +changing files or settings at the target itself. + +Or trying the application under development on the target again and again to see +if a feature works or a GUI looks nicer now or is more handy to control on a +small touchscreen display. + +Using the *Network File System* (NFS) can improve the development speed by grades +in this case. Everything filesystem related is still happening on the development +host and each modification can be used at the target immediately. + +Using PTXdist's built-in NFS Userland Server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +PTXdist can export the BSP's root filesystem by itself. Since a userspace +tool running as a regular user cannot open network ports below 1024, it uses +a different network port. The default is port **2049**. To make use of this +PTXdist feature, run inside the BSP at your development host: + +:: + + $ ptxdist nfsroot + [...] + Mount rootfs with nfsroot=/root,v3,tcp,port=2049,mountport=2049 + +At the target side a slighly different configuration must be used to work with +the userspace NFS server PTXdist provides instead of a regular kernel space +NFS server the Linux kernel provides. When starting PTXdist's ``nfsroot`` feature +it outputs the special command line we need to instruct the Linux kernel to +use this userland NFS server for its root filesystem to boot its userland from. + +What is still to be considered here is the network confiuration. Refer the +kernel documentation about the capabilities of the ``ip=`` kernel command line +option and check, if we need to setup a special IP address at the target side +to reach the host running PTXdist and its *nfsroot* feature. + +If we need a special IP address to setup, the kernel command line parameter to +use PTXdist's *nfsroot* feature, the parameter looks like this: + +:: + + nfsroot=<host-ip>:/root,v3,tcp,port=2049,mountport=2049 + +In the case we must replace the ``<host-ip>`` part of the line above with the +IP address of our host running PTXdist's *nfsroot* feature. + +If we run a recent Barebox bootloader with *bootspec* support, booting a target +via network only is very easy. In the Barebox prompt just enter: + +:: + + barebox@target:/ boot nfs://<host-ip>:2049//root + +In this case Barebox will mount the defined root filesysem via NFS, loads the +included bootspec file, read its information and continues to load the matching +kernel and maybe a matching device tree. diff --git a/doc/ref_manual.rst b/doc/ref_manual.rst index ab7101c94..9cfa2f0ab 100644 --- a/doc/ref_manual.rst +++ b/doc/ref_manual.rst @@ -166,7 +166,8 @@ Package Definition archive defined ``<PKG>_SOURCE`` and use it if available. Git URLs must either start with 'git://' or end with '.git'. They have a - mandatory ``tag=<tagname>`` option. + mandatory ``tag=<tagname>`` option. Refer :ref:`gitSources` how to make use of + it. Svn URLs must start with 'svn://'. They have a mandatory ``rev=r<number>`` option. diff --git a/doc/ref_parameter.inc b/doc/ref_parameter.inc index 6f2da7fb5..5347af244 100644 --- a/doc/ref_parameter.inc +++ b/doc/ref_parameter.inc @@ -178,7 +178,8 @@ Misc Actions list of available package types. ``nfsroot`` - run a userspace NFS server and export the nfsroot. + run a userspace NFS server and export the nfsroot (refer section + :ref:`nfsroot` for further details). ``print <var>`` print the contents of a variable. It will first look for a shell variable diff --git a/doc/working_with_git_sources.inc b/doc/working_with_git_sources.inc new file mode 100644 index 000000000..0514ba966 --- /dev/null +++ b/doc/working_with_git_sources.inc @@ -0,0 +1,6 @@ +.. _gitSources: + +Working with GIT sources +------------------------ + +TBD |