From 185545e9f40ae0f2795b84b481374e284ae24fdf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mart=C3=AD=20Bol=C3=ADvar?= Date: Thu, 12 Aug 2021 06:18:18 -0700 Subject: [PATCH] doc: dts: explain how to view preprocessor output MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is the debugging tool of last resort for figuring out where a devicetree macro went wrong, but it's very effective. Document how to do it on GCC based toolchains. Signed-off-by: Martí Bolívar --- doc/guides/dts/troubleshooting.rst | 33 ++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/doc/guides/dts/troubleshooting.rst b/doc/guides/dts/troubleshooting.rst index 8d80780dc79..4997b158a83 100644 --- a/doc/guides/dts/troubleshooting.rst +++ b/doc/guides/dts/troubleshooting.rst @@ -79,6 +79,39 @@ And if you're trying to **set** that property in a devicetree overlay: clock-frequency = <115200>; }; +Look at the preprocessor output +******************************* + +To save preprocessor output when using GCC-based toolchains, add +``-save-temps=obj`` to the ``EXTRA_CFLAGS`` CMake variable. For example, to +build :ref:`hello_world` with west with this option set, use: + +.. code-block:: sh + + west build -b BOARD samples/hello_world -- -DEXTRA_CFLAGS=-save-temps=obj + +This will create a preprocessor output file named :file:`foo.c.i` in the build +directory for each source file :file:`foo.c`. + +You can then search for the file in the build directory to see what your +devicetree macros expanded to. For example, on macOS and Linux, using ``find`` +to find :file:`main.c.i`: + +.. code-block:: sh + + $ find build -name main.c.i + build/CMakeFiles/app.dir/src/main.c.i + +It's usually easiest to run a style formatter on the results before opening +them. For example, to use ``clang-format`` to reformat the file in place: + +.. code-block:: sh + + clang-format -i build/CMakeFiles/app.dir/src/main.c.i + +You can then open the file in your favorite editor to view the final C results +after preprocessing. + Validate properties *******************