1 files changed, 169 insertions, 0 deletions
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.