OrgZephyr/zephyr
OrgZephyr
/
zephyr
mirror of https://github.com/zephyrproject-rtos/zephyr.git
1
0
Fork 0
Code Issues Releases Wiki Activity
zephyr/doc/getting_started/toolchain_custom_cmake.rst

44 lines
1.7 KiB
ReStructuredText
Raw Normal View History

doc: overhaul getting_started The getting started documentation has become a bit of a mess over time: - The reader needs to jump forward and backward in the documents depending on what their system already has installed (e.g. "start by cloning Zephyr, oh wait, see below if you don't have Git yet" etc.). - The operating system setup guides, toolchain setup instructions, and application build and run information have each become their own balkanized fiefdom, with duplicated, confusing and sometimes inconsistent results. - Linux documentation for all distributions is incomplete in some places (the Arch documentation in particular is vestigial) and wrong in others (platforms like Ubuntu still nominally require tools, like autoconf, that haven't been necessary since we stopped using the C Kconfig tools) - The dependencies needed to build the documentation have gotten *huge* since the LaTeX additions and massively overstate the footprint of Zephyr's real dependencies. This is particularly a problem on Linux, where those dependencies were not clearly separated from those needed to build Zephyr. - The toolchain setup documentation is confusing and scattered across the main file and the platform-specific files. There are various bits of incomplete and/or incorrect information. For example, the docs imply that you can use the Zephyr SDK on non-Linux hosts, which isn't true. As another example, some toolchains, such as GNU Arm Embedded, are documented several times. As a final example, some toolchains, such as Intel's ISSM, are squirrelled away in the Windows document when there are Linux builds available. Overhaul the pages to fix these issues and otherwise clean up the language. One significant side-effect is that all the toolchain-related information is rooted in a single toctree. Another is that it should now be possible to follow the instructions, in order, on any supported platform. Signed-off-by: Marti Bolivar <marti@foundries.io>
2018-10-15 13:20:24 +08:00
.. _custom_cmake_toolchains:
Custom CMake Toolchains
#######################
doc: unify documentation on setting environment variables There are a few different places where alternatives for setting environment variables are described. None of them is 100% complete, so the results are likely to be confusing. Make a single page on setting environment variables, how the zephyrrc files work, how the zephyr-env scripts work, and some of the important environment variables, with appropriate references elsewhere. (This is inspired by the Arch wiki's excellent page on installing programs.) Link to it from the getting started and application development pages instead of repeating the information. This has the benefit of shortening the getting started guide a bit more. Add some concrete advice on checking the toolchain environment variables in particular. This is a stumbling block for beginners. Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
2019-05-07 13:36:30 +08:00
To use a custom toolchain defined in an external CMake file, :ref:`set these
environment variables <env_vars>`:
doc: overhaul getting_started The getting started documentation has become a bit of a mess over time: - The reader needs to jump forward and backward in the documents depending on what their system already has installed (e.g. "start by cloning Zephyr, oh wait, see below if you don't have Git yet" etc.). - The operating system setup guides, toolchain setup instructions, and application build and run information have each become their own balkanized fiefdom, with duplicated, confusing and sometimes inconsistent results. - Linux documentation for all distributions is incomplete in some places (the Arch documentation in particular is vestigial) and wrong in others (platforms like Ubuntu still nominally require tools, like autoconf, that haven't been necessary since we stopped using the C Kconfig tools) - The dependencies needed to build the documentation have gotten *huge* since the LaTeX additions and massively overstate the footprint of Zephyr's real dependencies. This is particularly a problem on Linux, where those dependencies were not clearly separated from those needed to build Zephyr. - The toolchain setup documentation is confusing and scattered across the main file and the platform-specific files. There are various bits of incomplete and/or incorrect information. For example, the docs imply that you can use the Zephyr SDK on non-Linux hosts, which isn't true. As another example, some toolchains, such as GNU Arm Embedded, are documented several times. As a final example, some toolchains, such as Intel's ISSM, are squirrelled away in the Windows document when there are Linux builds available. Overhaul the pages to fix these issues and otherwise clean up the language. One significant side-effect is that all the toolchain-related information is rooted in a single toctree. Another is that it should now be possible to follow the instructions, in order, on any supported platform. Signed-off-by: Marti Bolivar <marti@foundries.io>
2018-10-15 13:20:24 +08:00
doc: unify documentation on setting environment variables There are a few different places where alternatives for setting environment variables are described. None of them is 100% complete, so the results are likely to be confusing. Make a single page on setting environment variables, how the zephyrrc files work, how the zephyr-env scripts work, and some of the important environment variables, with appropriate references elsewhere. (This is inspired by the Arch wiki's excellent page on installing programs.) Link to it from the getting started and application development pages instead of repeating the information. This has the benefit of shortening the getting started guide a bit more. Add some concrete advice on checking the toolchain environment variables in particular. This is a stumbling block for beginners. Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
2019-05-07 13:36:30 +08:00
- Set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to your toolchain's name
- Set :envvar:`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:
doc: overhaul getting_started The getting started documentation has become a bit of a mess over time: - The reader needs to jump forward and backward in the documents depending on what their system already has installed (e.g. "start by cloning Zephyr, oh wait, see below if you don't have Git yet" etc.). - The operating system setup guides, toolchain setup instructions, and application build and run information have each become their own balkanized fiefdom, with duplicated, confusing and sometimes inconsistent results. - Linux documentation for all distributions is incomplete in some places (the Arch documentation in particular is vestigial) and wrong in others (platforms like Ubuntu still nominally require tools, like autoconf, that haven't been necessary since we stopped using the C Kconfig tools) - The dependencies needed to build the documentation have gotten *huge* since the LaTeX additions and massively overstate the footprint of Zephyr's real dependencies. This is particularly a problem on Linux, where those dependencies were not clearly separated from those needed to build Zephyr. - The toolchain setup documentation is confusing and scattered across the main file and the platform-specific files. There are various bits of incomplete and/or incorrect information. For example, the docs imply that you can use the Zephyr SDK on non-Linux hosts, which isn't true. As another example, some toolchains, such as GNU Arm Embedded, are documented several times. As a final example, some toolchains, such as Intel's ISSM, are squirrelled away in the Windows document when there are Linux builds available. Overhaul the pages to fix these issues and otherwise clean up the language. One significant side-effect is that all the toolchain-related information is rooted in a single toctree. Another is that it should now be possible to follow the instructions, in order, on any supported platform. Signed-off-by: Marti Bolivar <marti@foundries.io>
2018-10-15 13:20:24 +08:00
doc: unify documentation on setting environment variables There are a few different places where alternatives for setting environment variables are described. None of them is 100% complete, so the results are likely to be confusing. Make a single page on setting environment variables, how the zephyrrc files work, how the zephyr-env scripts work, and some of the important environment variables, with appropriate references elsewhere. (This is inspired by the Arch wiki's excellent page on installing programs.) Link to it from the getting started and application development pages instead of repeating the information. This has the benefit of shortening the getting started guide a bit more. Add some concrete advice on checking the toolchain environment variables in particular. This is a stumbling block for beginners. Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
2019-05-07 13:36:30 +08:00
- :file:`cmake/toolchain/generic.cmake`: configures the toolchain for "generic"
getting_started: changes for custom toolchains This option uses a lot of typing, so point out there's a way to save keystrokes using -C. Tweak the language around the target toolchain. Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
2019-06-07 06:33:07 +08:00
use, which mostly means running the C preprocessor on the generated
:ref:`device-tree` file.
- :file:`cmake/toolchain/target.cmake`: configures the toolchain for "target"
use, i.e. building Zephyr and your application's source code.
doc: overhaul getting_started The getting started documentation has become a bit of a mess over time: - The reader needs to jump forward and backward in the documents depending on what their system already has installed (e.g. "start by cloning Zephyr, oh wait, see below if you don't have Git yet" etc.). - The operating system setup guides, toolchain setup instructions, and application build and run information have each become their own balkanized fiefdom, with duplicated, confusing and sometimes inconsistent results. - Linux documentation for all distributions is incomplete in some places (the Arch documentation in particular is vestigial) and wrong in others (platforms like Ubuntu still nominally require tools, like autoconf, that haven't been necessary since we stopped using the C Kconfig tools) - The dependencies needed to build the documentation have gotten *huge* since the LaTeX additions and massively overstate the footprint of Zephyr's real dependencies. This is particularly a problem on Linux, where those dependencies were not clearly separated from those needed to build Zephyr. - The toolchain setup documentation is confusing and scattered across the main file and the platform-specific files. There are various bits of incomplete and/or incorrect information. For example, the docs imply that you can use the Zephyr SDK on non-Linux hosts, which isn't true. As another example, some toolchains, such as GNU Arm Embedded, are documented several times. As a final example, some toolchains, such as Intel's ISSM, are squirrelled away in the Windows document when there are Linux builds available. Overhaul the pages to fix these issues and otherwise clean up the language. One significant side-effect is that all the toolchain-related information is rooted in a single toctree. Another is that it should now be possible to follow the instructions, in order, on any supported platform. Signed-off-by: Marti Bolivar <marti@foundries.io>
2018-10-15 13:20:24 +08:00
doc: unify documentation on setting environment variables There are a few different places where alternatives for setting environment variables are described. None of them is 100% complete, so the results are likely to be confusing. Make a single page on setting environment variables, how the zephyrrc files work, how the zephyr-env scripts work, and some of the important environment variables, with appropriate references elsewhere. (This is inspired by the Arch wiki's excellent page on installing programs.) Link to it from the getting started and application development pages instead of repeating the information. This has the benefit of shortening the getting started guide a bit more. Add some concrete advice on checking the toolchain environment variables in particular. This is a stumbling block for beginners. Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
2019-05-07 13:36:30 +08:00
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.
doc: overhaul getting_started The getting started documentation has become a bit of a mess over time: - The reader needs to jump forward and backward in the documents depending on what their system already has installed (e.g. "start by cloning Zephyr, oh wait, see below if you don't have Git yet" etc.). - The operating system setup guides, toolchain setup instructions, and application build and run information have each become their own balkanized fiefdom, with duplicated, confusing and sometimes inconsistent results. - Linux documentation for all distributions is incomplete in some places (the Arch documentation in particular is vestigial) and wrong in others (platforms like Ubuntu still nominally require tools, like autoconf, that haven't been necessary since we stopped using the C Kconfig tools) - The dependencies needed to build the documentation have gotten *huge* since the LaTeX additions and massively overstate the footprint of Zephyr's real dependencies. This is particularly a problem on Linux, where those dependencies were not clearly separated from those needed to build Zephyr. - The toolchain setup documentation is confusing and scattered across the main file and the platform-specific files. There are various bits of incomplete and/or incorrect information. For example, the docs imply that you can use the Zephyr SDK on non-Linux hosts, which isn't true. As another example, some toolchains, such as GNU Arm Embedded, are documented several times. As a final example, some toolchains, such as Intel's ISSM, are squirrelled away in the Windows document when there are Linux builds available. Overhaul the pages to fix these issues and otherwise clean up the language. One significant side-effect is that all the toolchain-related information is rooted in a single toctree. Another is that it should now be possible to follow the instructions, in order, on any supported platform. Signed-off-by: Marti Bolivar <marti@foundries.io>
2018-10-15 13:20:24 +08:00
doc: unify documentation on setting environment variables There are a few different places where alternatives for setting environment variables are described. None of them is 100% complete, so the results are likely to be confusing. Make a single page on setting environment variables, how the zephyrrc files work, how the zephyr-env scripts work, and some of the important environment variables, with appropriate references elsewhere. (This is inspired by the Arch wiki's excellent page on installing programs.) Link to it from the getting started and application development pages instead of repeating the information. This has the benefit of shortening the getting started guide a bit more. Add some concrete advice on checking the toolchain environment variables in particular. This is a stumbling block for beginners. Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
2019-05-07 13:36:30 +08:00
You can also set ``ZEPHYR_TOOLCHAIN_VARIANT`` and ``TOOLCHAIN_ROOT`` as CMake
variables when generating a build system for a Zephyr application, like so:
doc: overhaul getting_started The getting started documentation has become a bit of a mess over time: - The reader needs to jump forward and backward in the documents depending on what their system already has installed (e.g. "start by cloning Zephyr, oh wait, see below if you don't have Git yet" etc.). - The operating system setup guides, toolchain setup instructions, and application build and run information have each become their own balkanized fiefdom, with duplicated, confusing and sometimes inconsistent results. - Linux documentation for all distributions is incomplete in some places (the Arch documentation in particular is vestigial) and wrong in others (platforms like Ubuntu still nominally require tools, like autoconf, that haven't been necessary since we stopped using the C Kconfig tools) - The dependencies needed to build the documentation have gotten *huge* since the LaTeX additions and massively overstate the footprint of Zephyr's real dependencies. This is particularly a problem on Linux, where those dependencies were not clearly separated from those needed to build Zephyr. - The toolchain setup documentation is confusing and scattered across the main file and the platform-specific files. There are various bits of incomplete and/or incorrect information. For example, the docs imply that you can use the Zephyr SDK on non-Linux hosts, which isn't true. As another example, some toolchains, such as GNU Arm Embedded, are documented several times. As a final example, some toolchains, such as Intel's ISSM, are squirrelled away in the Windows document when there are Linux builds available. Overhaul the pages to fix these issues and otherwise clean up the language. One significant side-effect is that all the toolchain-related information is rooted in a single toctree. Another is that it should now be possible to follow the instructions, in order, on any supported platform. Signed-off-by: Marti Bolivar <marti@foundries.io>
2018-10-15 13:20:24 +08:00
doc: Cleanup references to cmake Clean up some stray references to cmake in doc, boards and samples that don't make explicit use of the zephyr app extension, as well as other minor doc fixes. Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
2019-06-14 03:59:12 +08:00
.. code-block:: console
west build ... -- -DZEPHYR_TOOLCHAIN_VARIANT=... -DTOOLCHAIN_ROOT=...
doc: overhaul getting_started The getting started documentation has become a bit of a mess over time: - The reader needs to jump forward and backward in the documents depending on what their system already has installed (e.g. "start by cloning Zephyr, oh wait, see below if you don't have Git yet" etc.). - The operating system setup guides, toolchain setup instructions, and application build and run information have each become their own balkanized fiefdom, with duplicated, confusing and sometimes inconsistent results. - Linux documentation for all distributions is incomplete in some places (the Arch documentation in particular is vestigial) and wrong in others (platforms like Ubuntu still nominally require tools, like autoconf, that haven't been necessary since we stopped using the C Kconfig tools) - The dependencies needed to build the documentation have gotten *huge* since the LaTeX additions and massively overstate the footprint of Zephyr's real dependencies. This is particularly a problem on Linux, where those dependencies were not clearly separated from those needed to build Zephyr. - The toolchain setup documentation is confusing and scattered across the main file and the platform-specific files. There are various bits of incomplete and/or incorrect information. For example, the docs imply that you can use the Zephyr SDK on non-Linux hosts, which isn't true. As another example, some toolchains, such as GNU Arm Embedded, are documented several times. As a final example, some toolchains, such as Intel's ISSM, are squirrelled away in the Windows document when there are Linux builds available. Overhaul the pages to fix these issues and otherwise clean up the language. One significant side-effect is that all the toolchain-related information is rooted in a single toctree. Another is that it should now be possible to follow the instructions, in order, on any supported platform. Signed-off-by: Marti Bolivar <marti@foundries.io>
2018-10-15 13:20:24 +08:00
.. code-block:: console
cmake -DZEPHYR_TOOLCHAIN_VARIANT=... -DTOOLCHAIN_ROOT=...
getting_started: changes for custom toolchains This option uses a lot of typing, so point out there's a way to save keystrokes using -C. Tweak the language around the target toolchain. Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
2019-06-07 06:33:07 +08:00
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.
.. _cmake option:
https://cmake.org/cmake/help/latest/manual/cmake.1.html#options