Skip to content
Permalink
Browse files

doc: Add guiconfig documentation

Add documentation for the new GUI configuration interface in the
Application Development guide.

Also update all the images, touch up the language a bit, and tweak some
minor stuff:

 - Say *.conf instead of .conf to make it clearer that .conf isn't the
   literal name

 - Add a missing -D<board> argument when running cmake

 - Use figure:: instead of image::. Comes out left-aligned and with
   space between the images, which looks nicer.

 - Explain what '- -' and '-*-' means in the terminal menuconfig.

tkinter isn't included by default in many Python installations, despite
being part of the Python standard library, so also add the required
packages to the Development Environment Setup section of the manual. Add
a note to the Application Development section as well, to help
debugging.

Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
  • Loading branch information...
ulfalizer authored and nashif committed May 6, 2019
1 parent a1c3cc6 commit baf38e9cb8dabbe36e3245afe8f366535fddea82
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
@@ -1146,7 +1146,7 @@ inter-dependencies between options, see the :ref:`configuration_options`.
.. note::

Dependencies between options can also be viewed in the interactive
configuration interface, which is explained in the
configuration interface, which is described in the
:ref:`override_kernel_conf` section. It will have the most up-to-date
dependencies, and also shows which dependencies are currently unsatisfied.

@@ -1214,23 +1214,25 @@ The example below shows a comment line and an override setting
Overriding the Default Configuration
------------------------------------

An interactive configuration interface is available for making temporary
changes to the configuration. This can be handy during development.
Making temporary changes to the configuration can be handy during development.
There are two interactive configuration interfaces available for changing the
configuration: ``menuconfig``, which runs in the terminal, and ``guiconfig``, a
graphical configuration interface.

.. note::

The configuration can also be changed by editing :file:`zephyr/.config` in
the application build directory by hand. Using the configuration interface
is safer, as it correctly handles dependencies between configurations
symbols.
the application build directory by hand. Using one of the configuration
interfaces is usually safer, as they correctly handle dependencies between
configuration symbols.

To make a setting permanent, you should set it in a :file:`.conf` file, as
To make a setting permanent, you should set it in a :file:`*.conf` file, as
described above in :ref:`application_set_conf`.

The steps below will run the interactive configuration interface:
Follow these steps to run the configuration interfaces.

#. Create a build directory :file:`<home>/app/build` inside your application
directory and generate build files inside it with CMake, as follows:
directory and generate build files inside it with CMake:

.. code-block:: bash
@@ -1240,63 +1242,102 @@ The steps below will run the interactive configuration interface:
cd %userprofile%\app
mkdir build && cd build
cmake -GNinja ..
cmake -GNinja -D<board> ..
#. Run the following command from the build directory (:file:`<home>/app/build`)
to start the configuration interface:
#. Use this command to run the terminal-based ``menuconfig`` interface:

.. code-block:: bash
ninja menuconfig
The configuration interface is shown below:
Use this command to run the graphical ``guiconfig`` interface:

.. image:: figures/app_kernel_conf_1.png
:align: center
:alt: Main Configuration Menu
.. code-block:: bash
ninja guiconfig
.. note::

If you get an import error for ``tkinter`` when trying to run
``guiconfig``, you are missing required packages. See
:ref:`installation_linux`. The package is usually called something like
``python3-tk``/``python3-tkinter``.

``tkinter`` is not included by default in many Python installations,
despite being part of the standard library.

#. Change configuration symbols to their desired values as follows:
The two interfaces are shown below:

.. figure:: figures/menuconfig.png
:alt: menuconfig interface

.. figure:: figures/guiconfig.png
:alt: guiconfig interface

``guiconfig`` always shows the help text and other information related to
the currently selected item in the bottom window pane. In the terminal
interface, press :kbd:`?` to view the same information.

.. note::

* Use the arrow keys to navigate the menu.
If you prefer to work in the ``guiconfig`` interface, then it's a good
idea to check any changes to Kconfig files you make in *single-menu
mode*, which is toggled via a checkbox at the top. Unlike full-tree
mode, single-menu mode will distinguish between symbols defined with
``config`` and symbols defined with ``menuconfig``, showing you what
things would look like in the ``menuconfig`` interface.

#. Change configuration values in the ``menuconfig`` interface as follows:

* Navigate the menu with the arrow keys.

.. note::

Common `Vim <https://www.vim.org>`_ key bindings are supported as well.

* Press :kbd:`Enter` or :kbd:`Space` to enter submenus and choices, which
appear with ``--->`` next to them. Press :kbd:`ESC` returns to the parent
menu.
* Press :kbd:`Enter` to enter menus and choices, which appear with ``--->``
next to them. Press :kbd:`ESC` to return to the parent menu.

* Press :kbd:`Space` to toggle or configure a symbol value. Boolean
configuration symbols are shown with :guilabel:`[ ]` brackets, while
numeric and string-valued configuration symbols are shown with
:guilabel:`( )` brackets.
* Press :kbd:`Space` to change symbol values. Boolean configuration symbols
are shown with :guilabel:`[ ]` brackets, while numeric and string-valued
configuration symbols are shown with :guilabel:`( )` brackets. Symbol
values that can't be changed are indicated with :guilabel:`- -` and
:guilabel:`-*-`.

.. note::

You can also press :kbd:`Y` or :kbd:`N` to set a boolean configuration
symbol, to the corresponding value.
symbol to the corresponding value.

* Press :kbd:`?` to display information about the currently selected symbol.
Press :kbd:`ESC` or :kbd:`Q` to return from the information display to the
menu.

#. After configuring the kernel options for your application, press
:kbd:`Q` to bring up the save-and-quit dialog:
In the ``guiconfig`` interface, either click on the image next to the symbol
to change its value, or double-click on the row with the symbol.
Double-clicking only works for changing the value if the symbol has no
children. Double-clicking a symbol with children will show/hide its children
instead.

``guiconfig`` also supports keyboard controls: :kbd:`Space` toggles values,
and :kbd:`Enter` opens/closes menus.

#. Pressing :kbd:`Q` in the ``menuconfig`` interface will bring up the
save-and-quit dialog (if there are changes to save):

.. image:: figures/app_kernel_conf_2.png
:align: center
.. figure:: figures/menuconfig-quit.png
:alt: Save and Quit Dialog

#. Press :kbd:`Y` to save the kernel configuration options to the default
filename (:file:`zephyr/.config`).
Press :kbd:`Y` to save the kernel configuration options to the default
filename (:file:`zephyr/.config`). You will typically save to the default
filename unless you are experimenting with different configurations.

Typically, you will save to the default filename unless you are
experimenting with various configuration scenarios.
The ``guiconfig`` interface will also prompt for saving the configuration on
exit if it has been modified.

.. note::

At present, the configuration file used during building is always
The configuration file used during the build is always
:file:`zephyr/.config`. If you have another saved configuration that you
want to build with, copy it to :file:`zephyr/.config`. Make sure to back
up your original configuration file.
@@ -1305,26 +1346,42 @@ The steps below will run the interactive configuration interface:
default on Linux and macOS. Use the ``-a`` flag to see them.

Finding a symbol in the menu tree and navigating to it can be tedious. To jump
directly to a symbol, press the :kbd:`/` key. This brings up the following
dialog, where you can search for symbols by name and jump to them:
directly to a symbol, press the :kbd:`/` key (this also works in
``guiconfig``). This brings up the following dialog, where you can search for
symbols by name and jump to them. In ``guiconfig``, you can also change symbol
values directly within the dialog.

.. image:: figures/app_kernel_conf_3.png
:align: center
:alt: Menuconfig Search Dialog
.. figure:: figures/menuconfig-jump-to.png
:alt: menuconfig jump-to dialog

.. figure:: figures/guiconfig-jump-to.png
:alt: guiconfig jump-to dialog

If you jump to a symbol that isn't currently visible (e.g., due to having
unsatisfied dependencies) then *show-all mode* will be enabled. In show-all
mode, all symbols are displayed, including currently invisible symbols. To
disable show-all mode, press :kbd:`A`.
unsatisfied dependencies), then *show-all mode* will be enabled. In show-all
mode, all symbols are displayed, including currently invisible symbols. To turn
off show-all mode, press :kbd:`A` in ``menuconfig`` or :kbd:`Ctrl-A` in
``guiconfig``.

.. note::

Show-all mode can't be disabled if there are no visible items in the menu.
Show-all mode can't be turned off if there are no visible items in the
current menu.

To figure out why a symbol you jumped to isn't visible, inspect its
dependencies by pressing :kbd:`?`. If you discover that the symbol depends on
another symbol that isn't enabled, you can jump to that symbol, in turn, to see
if it can be enabled.
dependencies, either by pressing :kbd:`?` in ``menuconfig`` or in the
information pane at the bottom in ``guiconfig``. If you discover that the
symbol depends on another symbol that isn't enabled, you can jump to that
symbol in turn to see if it can be enabled.

.. note::

In ``menuconfig``, you can press :kbd:`Ctrl-F` to view the help of the
currently selected item in the jump-to dialog without leaving the dialog.

For more information on ``menuconfig`` and ``guiconfig``, see the Python
docstrings at the top of ``scripts/kconfig/menuconfig.py`` and
``scripts/kconfig/guiconfig.py``.

.. _application_dt:

@@ -76,8 +76,8 @@ On Ubuntu:

sudo apt-get install --no-install-recommends git cmake ninja-build gperf \
ccache dfu-util device-tree-compiler wget \
python3-pip python3-setuptools python3-wheel xz-utils file make gcc \
gcc-multilib
python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \
make gcc gcc-multilib

On Fedora:

@@ -86,21 +86,21 @@ On Fedora:

sudo dnf group install "Development Tools" "C Development Tools and Libraries"
dnf install git cmake ninja-build gperf ccache dfu-util dtc wget \
python3-pip xz file glibc-devel.i686 libstdc++-devel.i686
python3-pip python3-tkinter xz file glibc-devel.i686 libstdc++-devel.i686

On Clear Linux:

.. code-block:: console

sudo swupd bundle-add c-basic dev-utils dfu-util dtc \
os-core-dev python-basic python3-basic
os-core-dev python-basic python3-basic python3-tcl

On Arch:

.. code-block:: console

sudo pacman -S git cmake ninja gperf ccache dfu-util dtc wget \
python-pip python-setuptools python-wheel xz file make
python-pip python-setuptools python-wheel tk xz file make

.. important::
Zephyr requires a recent version of CMake. Read through

0 comments on commit baf38e9

Please sign in to comment.
You can’t perform that action at this time.