1.. _menuconfig:
2
3Interactive Kconfig interfaces
4##############################
5
6There are two interactive configuration interfaces available for exploring the
7available Kconfig options and making temporary changes: ``menuconfig`` and
8``guiconfig``. ``menuconfig`` is a curses-based interface that runs in the
9terminal, while ``guiconfig`` is a graphical configuration interface.
10
11.. note::
12
13   The configuration can also be changed by editing :file:`zephyr/.config` in
14   the application build directory by hand. Using one of the configuration
15   interfaces is often handier, as they correctly handle dependencies between
16   configuration symbols.
17
18   If you try to enable a symbol with unsatisfied dependencies in
19   :file:`zephyr/.config`, the assignment will be ignored and overwritten when
20   re-configuring.
21
22To make a setting permanent, you should set it in a :file:`*.conf` file, as
23described in :ref:`setting_configuration_values`.
24
25.. tip::
26
27   Saving a minimal configuration file (with e.g. :kbd:`D` in menuconfig) and
28   inspecting it can be handy when making settings permanent. The minimal
29   configuration file only lists symbols that differ from their default value.
30
31To run one of the configuration interfaces, do this:
32
33#. Build your application as usual using either ``west`` or ``cmake``:
34
35   .. zephyr-app-commands::
36      :tool: all
37      :cd-into:
38      :board: <board>
39      :goals: build
40      :compact:
41
42#. To run the terminal-based ``menuconfig`` interface, use either of these
43   commands:
44
45   .. code-block:: bash
46
47      west build -t menuconfig
48
49   .. code-block:: bash
50
51      ninja menuconfig
52
53   To run the graphical ``guiconfig``, use either of these commands:
54
55   .. code-block:: bash
56
57      west build -t guiconfig
58
59   .. code-block:: bash
60
61      ninja guiconfig
62
63   .. note::
64
65      If you get an import error for ``tkinter`` when trying to run
66      ``guiconfig``, you are missing required packages. See
67      :ref:`installation_linux`. The package you need is usually called
68      something like ``python3-tk``/``python3-tkinter``.
69
70      ``tkinter`` is not included by default in many Python installations,
71      despite being part of the standard library.
72
73   The two interfaces are shown below:
74
75   .. figure:: menuconfig.png
76      :alt: menuconfig interface
77
78   .. figure:: guiconfig.png
79      :alt: guiconfig interface
80
81   ``guiconfig`` always shows the help text and other information related to
82   the currently selected item in the bottom window pane. In the terminal
83   interface, press :kbd:`?` to view the same information.
84
85   .. note::
86
87      If you prefer to work in the ``guiconfig`` interface, then it's a good
88      idea to check any changes to Kconfig files you make in *single-menu
89      mode*, which is toggled via a checkbox at the top. Unlike full-tree
90      mode, single-menu mode will distinguish between symbols defined with
91      ``config`` and symbols defined with ``menuconfig``, showing you what
92      things would look like in the ``menuconfig`` interface.
93
94#. Change configuration values in the ``menuconfig`` interface as follows:
95
96   * Navigate the menu with the arrow keys. Common `Vim
97     <https://www.vim.org>`__ key bindings are supported as well.
98
99   * Use :kbd:`Space` and :kbd:`Enter` to enter menus and toggle values. Menus
100     appear with ``--->`` next to them. Press :kbd:`ESC` to return to the
101     parent menu.
102
103     Boolean configuration options are shown with :guilabel:`[ ]` brackets,
104     while numeric and string-valued configuration symbols are shown with
105     :guilabel:`( )` brackets. Symbol values that can't be changed are shown as
106     :guilabel:`- -` or :guilabel:`-*-`.
107
108     .. note::
109
110        You can also press :kbd:`Y` or :kbd:`N` to set a boolean configuration
111        symbol to the corresponding value.
112
113   * Press :kbd:`?` to display information about the currently selected symbol,
114     including its help text. Press :kbd:`ESC` or :kbd:`Q` to return from the
115     information display to the menu.
116
117   In the ``guiconfig`` interface, either click on the image next to the symbol
118   to change its value, or double-click on the row with the symbol (this only
119   works if the symbol has no children, as double-clicking a symbol with
120   children open/closes its menu instead).
121
122   ``guiconfig`` also supports keyboard controls, which are similar to
123   ``menuconfig``.
124
125#. Pressing :kbd:`Q` in the ``menuconfig`` interface will bring up the
126   save-and-quit dialog (if there are changes to save):
127
128   .. figure:: menuconfig-quit.png
129      :alt: Save and Quit Dialog
130
131   Press :kbd:`Y` to save the kernel configuration options to the default
132   filename (:file:`zephyr/.config`). You will typically save to the default
133   filename unless you are experimenting with different configurations.
134
135   The ``guiconfig`` interface will also prompt for saving the configuration on
136   exit if it has been modified.
137
138   .. note::
139
140      The configuration file used during the build is always
141      :file:`zephyr/.config`. If you have another saved configuration that you
142      want to build with, copy it to :file:`zephyr/.config`. Make sure to back
143      up your original configuration file.
144
145      Also note that filenames starting with ``.`` are not listed by ``ls`` by
146      default on Linux and macOS. Use the ``-a`` flag to see them.
147
148Finding a symbol in the menu tree and navigating to it can be tedious. To jump
149directly to a symbol, press the :kbd:`/` key (this also works in
150``guiconfig``). This brings up the following dialog, where you can search for
151symbols by name and jump to them. In ``guiconfig``, you can also change symbol
152values directly within the dialog.
153
154.. figure:: menuconfig-jump-to.png
155   :alt: menuconfig jump-to dialog
156
157.. figure:: guiconfig-jump-to.png
158   :alt: guiconfig jump-to dialog
159
160If you jump to a symbol that isn't currently visible (e.g., due to having
161unsatisfied dependencies), then *show-all mode* will be enabled. In show-all
162mode, all symbols are displayed, including currently invisible symbols. To turn
163off show-all mode, press :kbd:`A` in ``menuconfig`` or :kbd:`Ctrl-A` in
164``guiconfig``.
165
166.. note::
167
168   Show-all mode can't be turned off if there are no visible items in the
169   current menu.
170
171To figure out why a symbol you jumped to isn't visible, inspect its
172dependencies, either by pressing :kbd:`?` in ``menuconfig`` or in the
173information pane at the bottom in ``guiconfig``. If you discover that the
174symbol depends on another symbol that isn't enabled, you can jump to that
175symbol in turn to see if it can be enabled.
176
177.. note::
178
179   In ``menuconfig``, you can press :kbd:`Ctrl-F` to view the help of the
180   currently selected item in the jump-to dialog without leaving the dialog.
181
182For more information on ``menuconfig`` and ``guiconfig``, see the Python
183docstrings at the top of :zephyr_file:`menuconfig.py
184<scripts/kconfig/menuconfig.py>` and :zephyr_file:`guiconfig.py
185<scripts/kconfig/guiconfig.py>`.
186