diff options
author | Juergen Borleis <jbe@pengutronix.de> | 2016-06-09 11:56:52 +0200 |
---|---|---|
committer | Michael Olbrich <m.olbrich@pengutronix.de> | 2016-06-20 15:04:56 +0200 |
commit | 50d238522588f8b320da924d82febaf0c2ffc6dc (patch) | |
tree | 8648a48232a0ca23ec98a5a57699f26a8dfebd9f /doc | |
parent | ee05281068c95b79d2e50fe30fedb3bebeb4b586 (diff) | |
download | ptxdist-50d238522588f8b320da924d82febaf0c2ffc6dc.tar.gz ptxdist-50d238522588f8b320da924d82febaf0c2ffc6dc.tar.xz |
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>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/index.rst | 2 | ||||
-rw-r--r-- | doc/user_adapting.inc | 169 | ||||
-rw-r--r-- | doc/user_images.inc | 32 | ||||
-rw-r--r-- | doc/user_manual.inc (renamed from doc/user_manual.rst) | 210 | ||||
-rw-r--r-- | doc/user_manual_section.rst | 16 |
5 files changed, 218 insertions, 211 deletions
diff --git a/doc/index.rst b/doc/index.rst index 44e7eca72..da2c83dc8 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 000000000..ed6732305 --- /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 000000000..2e6d4fa9b --- /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 c38df6afd..d5f5dca18 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 000000000..b0b63c0f9 --- /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* |