cd739a9757
:envvar: is currently used to tag environment variables, however, :envvar: role expects a matching .. envvar:: directive where the environment variable is defined. This patch fixes some cases by adding envvar directives and by converting certain cases to literals (it doesn't make sense to document all env vars in a list, as some are self-documented by contextual information). Ref. https://www.sphinx-doc.org/en/master/usage/restructuredtext/ roles.html#role-envvar Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
73 lines
3.0 KiB
ReStructuredText
73 lines
3.0 KiB
ReStructuredText
.. _custom_cmake_toolchains:
|
|
|
|
Custom CMake Toolchains
|
|
#######################
|
|
|
|
To use a custom toolchain defined in an external CMake file, :ref:`set these
|
|
environment variables <env_vars>`:
|
|
|
|
- Set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to your toolchain's name
|
|
- Set ``TOOLCHAIN_ROOT`` to the path to the directory containing your
|
|
toolchain's CMake configuration files.
|
|
|
|
Zephyr will then include the toolchain cmake files located in the
|
|
:file:`TOOLCHAIN_ROOT` directory:
|
|
|
|
- :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.
|
|
|
|
You can also set ``ZEPHYR_TOOLCHAIN_VARIANT`` and ``TOOLCHAIN_ROOT`` as CMake
|
|
variables when generating a build system for a Zephyr application, like so:
|
|
|
|
.. code-block:: console
|
|
|
|
west build ... -- -DZEPHYR_TOOLCHAIN_VARIANT=... -DTOOLCHAIN_ROOT=...
|
|
|
|
.. code-block:: console
|
|
|
|
cmake -DZEPHYR_TOOLCHAIN_VARIANT=... -DTOOLCHAIN_ROOT=...
|
|
|
|
If you do this, ``-C <initial-cache>`` `cmake option`_ may useful. If you save
|
|
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 ``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
|