docs: add description of python-clean command
@@ -101,6 +101,7 @@ Advanced Commands
- ``idf.py -p PORT erase_flash`` will use esptool.py to erase the target's entire flash chip.
- ``idf.py size`` prints some size information about the app. ``size-components`` and ``size-files`` are similar commands which print more detailed per-component or per-source-file information, respectively. If you define variable ``-DOUTPUT_JSON=1`` when running CMake (or ``idf.py``), the output will be formatted as JSON not as human readable text.
- ``idf.py reconfigure`` re-runs CMake_ even if it doesn't seem to need re-running. This isn't necessary during normal usage, but can be useful after adding/removing files from the source tree, or when modifying CMake cache variables. For example, ``idf.py -DNAME='VALUE' reconfigure`` can be used to set variable ``NAME`` in CMake cache to value ``VALUE``.
+- ``idf.py python-clean`` deletes generated Python byte code from the IDF directory which may cause issues when switching between IDF and Python versions. It is advised to run this target after switching versions of Python.
The order of multiple ``idf.py`` commands on the same invocation is not important, they will automatically be executed in the correct order for everything to take effect (ie building before flashing, erasing before flashing, etc.).
@@ -206,7 +207,25 @@ If using CMake directly, running ``cmake -D PYTHON=python3 ...`` will cause CMak
If using an IDE with CMake, setting the ``PYTHON`` value as a CMake cache override in the IDE UI will override the default Python interpreter.
-To manage the Python version more generally via the command line, check out the tools pyenv_ or virtualenv_. These let you change the default python version.
+To manage the Python version more generally via the command line, check out the tools pyenv_ or virtualenv_. These let you change the default Python version.
+
+Possible issues
+^^^^^^^^^^^^^^^
+
+The user of ``idf.py`` may sometimes experience ``ImportError`` described below.
+
+.. code-block:: none
+
+ Traceback (most recent call last):
+ File "/Users/user_name/e/esp-idf/tools/kconfig_new/confgen.py", line 27, in <module>
+ import kconfiglib
+ ImportError: bad magic number in 'kconfiglib': b'\x03\xf3\r\n'
+
+The exception is often caused by ``.pyc`` files generated by different Python versions. To solve the issue run the following command:
+
+.. code-block:: bash
+
+ idf.py python-clean
.. _example-project-structure:
