summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJuergen Borleis <jbe@pengutronix.de>2016-06-09 11:56:52 +0200
committerMichael Olbrich <m.olbrich@pengutronix.de>2016-06-20 15:04:56 +0200
commit50d238522588f8b320da924d82febaf0c2ffc6dc (patch)
tree8648a48232a0ca23ec98a5a57699f26a8dfebd9f
parentee05281068c95b79d2e50fe30fedb3bebeb4b586 (diff)
downloadptxdist-50d238522588f8b320da924d82febaf0c2ffc6dc.tar.gz
Split the user manual section into separate file
...to be able to replace or append the content individually. Signed-off-by: Juergen Borleis <jbe@pengutronix.de>
-rw-r--r--doc/index.rst2
-rw-r--r--doc/user_adapting.inc169
-rw-r--r--doc/user_images.inc32
-rw-r--r--doc/user_manual.inc (renamed from doc/user_manual.rst)210
-rw-r--r--doc/user_manual_section.rst16
5 files changed, 218 insertions, 211 deletions
diff --git a/doc/index.rst b/doc/index.rst
index 44e7eca..da2c83d 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -15,7 +15,7 @@ Contents:
welcome
environment
- user_manual
+ user_manual_section
dev_manual
ref_manual
daily_work
diff --git a/doc/user_adapting.inc b/doc/user_adapting.inc
new file mode 100644
index 0000000..ed67323
--- /dev/null
+++ b/doc/user_adapting.inc
@@ -0,0 +1,169 @@
+Adapting the |ptxdistBSPName| Project
+-------------------------------------
+
+Handling a fully prepared PTXdist project is easy. But everything is
+fixed to the settings the developer selected. We now want to adapt the
+project in a few simple settings.
+
+Working with Kconfig
+~~~~~~~~~~~~~~~~~~~~
+
+Whenever we modify our project, PTXdist is using *Kconfig* to manipulate
+the settings. *Kconfig* means *kernel configurator* and was mainly
+developed to configure the Linux kernel itself. But it is easy to adapt,
+to use and so popular that more and more projects are using *Kconfig*
+for their purposes. PTXdist is one of them.
+
+What is Kconfig
+^^^^^^^^^^^^^^^
+
+It is a user interface to select given resources in a convenient way.
+The resources that we can select are given in simple text files. It uses
+a powerful “language” in these text files to organize them in a
+hierarchical manner, solves challenges like resource dependencies,
+supports help and search features. PTXdist uses all of these features.
+*Kconfig* supports a text based user interface by using the *ncurses*
+library to manipulate the screen content and should work on nearly all
+host systems.
+
+Navigate in Kconfig menu (select, search, ...)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To navigate through the configuration tree, we are using the arrow keys.
+Up and down navigates vertically in the menu entries. Right and left
+navigates between *Select*, *Exit* and *Help* (in the bottom part of our
+visual screen).
+
+To enter one of the menus, we navigate to this entry to highlight it and
+press the *Enter* key. To leave it, we select *Exit* and press the
+*Enter* key again. There are shortcuts available, instead of pressing
+the *Enter* key to enter a menu we also can press *alt-s* and to leave a
+menu *alt-e*. Also an ESC double hit leaves any menu we are in.
+
+To select a menu entry, we use the *Space* key. This will toggle the
+selection. Or, to be more precise and faster, we use the key *y* to
+select an entry, and key *n* to deselect it.
+
+To get help for a specific menu topic, we navigate vertically to
+highlight it and horizontally to select the *Help* entry. Then we can
+press *Enter* to see the help.
+
+To search for specific keywords, we press the */* key and enter a word.
+Kconfig then lists all occurences of this word in all menus.
+
+Meaning of visual feedbacks in Kconfig
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- | Submenus to enter are marked with a trailing ``--->``
+ | Note: Some submenus are also marked with a leading bracket ``[ ]``.
+ To enter them we first must select/enable them ``[*]``
+
+- Entries with a list of selectable alternatives are also marked with a
+ trailing ``--->``
+
+- Entries we can select are marked with a leading empty bracket ``[ ]``
+
+- Entries that are already selected are marked with a leading filled
+ bracket ``[*]``
+
+- Entries that are selected due to dependencies into other selected
+ entries are marked with a leading ``-*-``
+
+- Some entries need a free text to enter, they are marked with leading
+ brackets ``()`` and the free text in it
+
+Adapting Userland Settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To do so, we run:
+
+::
+
+ $ ptxdist menuconfig
+
+will show the following console output
+
+.. figure:: figures/menuconfig_intro.png
+ :alt: Main userland configuration menu
+ :align: center
+
+ Main userland configuration menu
+
+The main building blocks in the *userland configuration* menu are:
+
+- Host Options: Some parts of the project are build host relevant only.
+ For example PTXdist can build the DDD debugger to debug applications
+ running on the target.
+
+- Root Filesystem: Settings to arrange target’s root filesystem and to
+ select the main C run-time library
+
+- Applications: Everything we like to run on our target.
+
+At this point it could be useful to walk to the whole menus and their
+submenus to get an idea about the amount of features and applications
+PTXdist currently supports.
+
+Note: don't forget to save your changes prior leaving this menu.
+
+Adapting Platform Settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To do so, we run:
+
+::
+
+ $ ptxdist menuconfig platform
+
+The main building blocks in the *platform configuration* menu are:
+
+- Architecture: Basic settings, like the main and sub architecture the
+ target system uses, the toolchain to be used to build everything and
+ some other architecture dependent settings.
+
+- Linux kernel: Which kernel revision and kernel configuration should
+ be used
+
+- Bootloader: Which bootloader (if any) should be built in the project
+
+- The kind of image to populate a root filesystem into the target
+ system
+
+Note: don't forget to save your changes prior leaving this menu.
+
+Adapting Linux Kernel Settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Just run the following command:
+
+::
+
+ $ ptxdist menuconfig kernel
+
+Note: don't forget to save your changes prior leaving this menu.
+
+Adapting Bootloader Settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Just run the following command:
+
+::
+
+ $ ptxdist menuconfig barebox
+
+Note: don't forget to save your changes prior leaving this menu.
+
+Making Changes Real
+~~~~~~~~~~~~~~~~~~~
+
+After a change in whatever menu the next build-run will compile
+or re-compile the changed parts. Due to complex dependencies between these parts
+PTXdist might compile or re-compile more than the changed part.
+
+To apply the changes just run:
+
+::
+
+ $ ptxdist go
+
+Note: If nothing was changed, ``ptxdist go`` also will do nothing.
diff --git a/doc/user_images.inc b/doc/user_images.inc
new file mode 100644
index 0000000..2e6d4fa
--- /dev/null
+++ b/doc/user_images.inc
@@ -0,0 +1,32 @@
+Creating a Root Filesystem Image
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After we have built the root filesystem content, we can make an image,
+which can be flashed to the target system or copied on some kind of disk
+media. To do so, we just run
+
+::
+
+ $ ptxdist images
+
+PTXdist now extracts the content of priorly created *\*.ipk* packages to
+a temporary directory and generates an image out of it. PTXdist supports
+following image types:
+
+- **hd.img:** contains bootloader, kernel and root files in an ext2
+- partition. Mostly used for X86 target systems.
+
+- **root.jffs2:** root files inside a jffs2 filesystem.
+
+- **uRamdisk:** a u-boot loadable Ramdisk
+
+- **initrd.gz:** a traditional initrd RAM disk to be used as initrdramfs
+- by the kernel
+
+- **root.ext2:** root files inside an ext2 filesystem.
+
+- **root.squashfs:** root files inside a squashfs filesystem.
+
+- **root.tgz:** root files inside a plain gzip compressed tar ball.
+
+All these files can be found in ``images`` if enabled.
diff --git a/doc/user_manual.rst b/doc/user_manual.inc
index c38df6a..d5f5dca 100644
--- a/doc/user_manual.rst
+++ b/doc/user_manual.inc
@@ -1,10 +1,3 @@
-PTXdist User’s Manual
-=====================
-
-This chapter should give any newbie the information he/she needs to be
-able to handle any embedded Linux projects based on PTXdist. Also the
-advanced user may find new valueable information.
-
How does it work?
-----------------
@@ -442,206 +435,3 @@ And one important file in case of trouble:
|ptxdistPlatformDir|\ ``/logfile``
Every run of PTXdist will add its output to this file. If something
fails, this file can help to find the cause.
-
-Creating a Root Filesystem Image
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-After we have built the root filesystem content, we can make an image,
-which can be flashed to the target system or copied on some kind of disk
-media. To do so, we just run
-
-::
-
- $ ptxdist images
-
-PTXdist now extracts the content of priorly created *\*.ipk* packages to
-a temporary directory and generates an image out of it. PTXdist supports
-following image types:
-
-- **hd.img:** contains bootloader, kernel and root files in an ext2
-- partition. Mostly used for X86 target systems.
-
-- **root.jffs2:** root files inside a jffs2 filesystem.
-
-- **uRamdisk:** a u-boot loadable Ramdisk
-
-- **initrd.gz:** a traditional initrd RAM disk to be used as initrdramfs
-- by the kernel
-
-- **root.ext2:** root files inside an ext2 filesystem.
-
-- **root.squashfs:** root files inside a squashfs filesystem.
-
-- **root.tgz:** root files inside a plain gzip compressed tar ball.
-
-All these files can be found in ``images`` if enabled.
-
-Adapting the |ptxdistBSPName| Project
--------------------------------------
-
-Handling a fully prepared PTXdist project is easy. But everything is
-fixed to the settings the developer selected. We now want to adapt the
-project in a few simple settings.
-
-Working with Kconfig
-~~~~~~~~~~~~~~~~~~~~
-
-Whenever we modify our project, PTXdist is using *Kconfig* to manipulate
-the settings. *Kconfig* means *kernel configurator* and was mainly
-developed to configure the Linux kernel itself. But it is easy to adapt,
-to use and so popular that more and more projects are using *Kconfig*
-for their purposes. PTXdist is one of them.
-
-What is Kconfig
-^^^^^^^^^^^^^^^
-
-It is a user interface to select given resources in a convenient way.
-The resources that we can select are given in simple text files. It uses
-a powerful “language” in these text files to organize them in a
-hierarchical manner, solves challenges like resource dependencies,
-supports help and search features. PTXdist uses all of these features.
-*Kconfig* supports a text based user interface by using the *ncurses*
-library to manipulate the screen content and should work on nearly all
-host systems.
-
-Navigate in Kconfig menu (select, search, ...)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To navigate through the configuration tree, we are using the arrow keys.
-Up and down navigates vertically in the menu entries. Right and left
-navigates between *Select*, *Exit* and *Help* (in the bottom part of our
-visual screen).
-
-To enter one of the menus, we navigate to this entry to highlight it and
-press the *Enter* key. To leave it, we select *Exit* and press the
-*Enter* key again. There are shortcuts available, instead of pressing
-the *Enter* key to enter a menu we also can press *alt-s* and to leave a
-menu *alt-e*. Also an ESC double hit leaves any menu we are in.
-
-To select a menu entry, we use the *Space* key. This will toggle the
-selection. Or, to be more precise and faster, we use the key *y* to
-select an entry, and key *n* to deselect it.
-
-To get help for a specific menu topic, we navigate vertically to
-highlight it and horizontally to select the *Help* entry. Then we can
-press *Enter* to see the help.
-
-To search for specific keywords, we press the */* key and enter a word.
-Kconfig then lists all occurences of this word in all menus.
-
-Meaning of visual feedbacks in Kconfig
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-- | Submenus to enter are marked with a trailing ``--->``
- | Note: Some submenus are also marked with a leading bracket ``[ ]``.
- To enter them we first must select/enable them ``[*]``
-
-- Entries with a list of selectable alternatives are also marked with a
- trailing ``--->``
-
-- Entries we can select are marked with a leading empty bracket ``[ ]``
-
-- Entries that are already selected are marked with a leading filled
- bracket ``[*]``
-
-- Entries that are selected due to dependencies into other selected
- entries are marked with a leading ``-*-``
-
-- Some entries need a free text to enter, they are marked with leading
- brackets ``()`` and the free text in it
-
-Adapting Userland Settings
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To do so, we run:
-
-::
-
- $ ptxdist menuconfig
-
-will show the following console output
-
-.. figure:: figures/menuconfig_intro.png
- :alt: Main userland configuration menu
- :align: center
-
- Main userland configuration menu
-
-The main building blocks in the *userland configuration* menu are:
-
-- Host Options: Some parts of the project are build host relevant only.
- For example PTXdist can build the DDD debugger to debug applications
- running on the target.
-
-- Root Filesystem: Settings to arrange target’s root filesystem and to
- select the main C run-time library
-
-- Applications: Everything we like to run on our target.
-
-At this point it could be useful to walk to the whole menus and their
-submenus to get an idea about the amount of features and applications
-PTXdist currently supports.
-
-Note: don't forget to save your changes prior leaving this menu.
-
-Adapting Platform Settings
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To do so, we run:
-
-::
-
- $ ptxdist menuconfig platform
-
-The main building blocks in the *platform configuration* menu are:
-
-- Architecture: Basic settings, like the main and sub architecture the
- target system uses, the toolchain to be used to build everything and
- some other architecture dependent settings.
-
-- Linux kernel: Which kernel revision and kernel configuration should
- be used
-
-- Bootloader: Which bootloader (if any) should be built in the project
-
-- The kind of image to populate a root filesystem into the target
- system
-
-Note: don't forget to save your changes prior leaving this menu.
-
-Adapting Linux Kernel Settings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Just run the following command:
-
-::
-
- $ ptxdist menuconfig kernel
-
-Note: don't forget to save your changes prior leaving this menu.
-
-Adapting Bootloader Settings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Just run the following command:
-
-::
-
- $ ptxdist menuconfig barebox
-
-Note: don't forget to save your changes prior leaving this menu.
-
-Making Changes Real
-~~~~~~~~~~~~~~~~~~~
-
-After a change in whatever menu the next build-run will compile
-or re-compile the changed parts. Due to complex dependencies between these parts
-PTXdist might compile or re-compile more than the changed part.
-
-To apply the changes just run:
-
-::
-
- $ ptxdist go
-
-Note: If nothing was changed, ``ptxdist go`` also will do nothing.
diff --git a/doc/user_manual_section.rst b/doc/user_manual_section.rst
new file mode 100644
index 0000000..b0b63c0
--- /dev/null
+++ b/doc/user_manual_section.rst
@@ -0,0 +1,16 @@
+PTXdist User’s Manual
+=====================
+
+This chapter should give any newbie the information he/she needs to be
+able to handle any embedded Linux projects based on PTXdist. Also the
+advanced user may find new valueable information.
+
+.. include:: user_manual.inc
+.. include:: user_images.inc
+.. include:: user_adapting.inc
+
+But most of the time, a user needs more detailed adaptions to be able to
+fit all requirements of the new platform. At this point of time we are
+no longer ordinary users of PTXdist, we become developers now.
+
+So, right now it’s time to read the *PTXdist Developer’s Manual*