summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJuergen Borleis <jbe@pengutronix.de>2016-06-08 18:02:19 +0200
committerMichael Olbrich <m.olbrich@pengutronix.de>2016-06-20 15:04:57 +0200
commit185c2bebaa1686f2faacca62fca24be1c6909163 (patch)
tree68ec80f91c24bf599c9fccdf5af9d5243259137e
parent50d238522588f8b320da924d82febaf0c2ffc6dc (diff)
downloadptxdist-185c2bebaa1686f2faacca62fca24be1c6909163.tar.gz
Split the daily-work section into separate files
...to be able to replace or append the content individually. Signed-off-by: Juergen Borleis <jbe@pengutronix.de>
-rw-r--r--doc/daily_work.inc (renamed from doc/daily_work.rst)161
-rw-r--r--doc/daily_work_section.rst7
-rw-r--r--doc/faq.inc157
-rw-r--r--doc/index.rst2
-rw-r--r--doc/nfsroot.inc61
-rw-r--r--doc/ref_manual.rst3
-rw-r--r--doc/ref_parameter.inc3
-rw-r--r--doc/working_with_git_sources.inc6
8 files changed, 236 insertions, 164 deletions
diff --git a/doc/daily_work.rst b/doc/daily_work.inc
index 2dc9c4c..8f9f88c 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 0000000..c5c963e
--- /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 0000000..9527058
--- /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 da2c83d..bc608a5 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 0000000..ee652ed
--- /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 ab7101c..9cfa2f0 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 6f2da7f..5347af2 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 0000000..0514ba9
--- /dev/null
+++ b/doc/working_with_git_sources.inc
@@ -0,0 +1,6 @@
+.. _gitSources:
+
+Working with GIT sources
+------------------------
+
+TBD