michaelh/zephyr
1
0
Fork 0
Code Releases Activity

toolchain: doc: Custom toolchain doc updated for other.h requirement

Browse source 
Added missing toolchain name to path for generic.cmake and target.cmake.

Added section explaining the need for, and the use of, the
toolchain/other.h header file.

Signed-off-by: Danny Oerndrup <daor@demant.com>
This commit is contained in:
Danny Oerndrup 2021-07-16 11:54:01 +02:00 • committed by Anas Nashif
commit e3ab68ff1a
1 changed files with 34 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

39
doc/getting_started/toolchain_custom_cmake.rst
View file

@ -13,12 +13,16 @@ environment variables <env_vars>`:
Zephyr will then include the toolchain cmake files located in the
:file:`TOOLCHAIN_ROOT` directory:
- :file:`cmake/toolchain/generic.cmake`: configures the toolchain for "generic"
use, which mostly means running the C preprocessor on :ref:`devicetree
input files <dt-input-files>`.
- :file:`cmake/toolchain/target.cmake`: configures the toolchain for "target"
use, i.e. building Zephyr and your application's source code.
- :file:`cmake/toolchain/<toolchain name>/generic.cmake`: configures the
toolchain for "generic" use, which mostly means running the C preprocessor
on the generated
:ref:`devicetree` file.
- :file:`cmake/toolchain/<toolchain name>/target.cmake`: configures the
toolchain for "target" use, i.e. building Zephyr and your application's
source code.
Here <toolchain name> is the same as the name provided in
:envvar:`ZEPHYR_TOOLCHAIN_VARIANT`
See the zephyr files :zephyr_file:`cmake/generic_toolchain.cmake` and
:zephyr_file:`cmake/target_toolchain.cmake` for more details on what your
:file:`generic.cmake` and :file:`target.cmake` files should contain.
@ -39,5 +43,30 @@ your :makevar:`ZEPHYR_TOOLCHAIN_VARIANT`, :makevar:`TOOLCHAIN_ROOT`, and other
settings in a file named :file:`my-toolchain.cmake`, you can then invoke cmake
as ``cmake -C my-toolchain.cmake ...`` to save typing.
Zephyr includes :file:`include/toolchain.h` which again includes a toolchain
specific header based on the compiler identifier, such as ``__llvm__`` or
``__GNUC__``.
Some custom compilers identify themselves as the compiler on which they are
based, for example ``llvm`` which then gets the :file:`toolchain/llvm.h` included.
This included file may though not be right for the custom toolchain. In order
to solve this, and thus to get the :file:`include/other.h` included instead,
add the set(TOOLCHAIN_USE_CUSTOM 1) cmake line to the generic.cmake and/or
target.cmake files located under
:file:`<TOOLCHAIN_ROOT>/cmake/toolchain/<toolchain name>/`.
When :makevar:`TOOLCHAIN_USE_CUSTOM` is set, the :file:`other.h` must be
available out-of-tree and it must include the correct header for the custom
toolchain.
A good location for the :file:`other.h` header file, would be a
directory under the directory specified in :envvar:`TOOLCHAIN_ROOT` as
:file:`include/toolchain`.
To get the toolchain header included in zephyr's build, the
:makevar:`USERINCLUDE` can be set to point to the include directory, as shown
here:
.. code-block:: console
west build -- -DZEPHYR_TOOLCHAIN_VARIANT=... -DTOOLCHAIN_ROOT=... -DUSERINCLUDE=...
.. _cmake option:
https://cmake.org/cmake/help/latest/manual/cmake.1.html#options