michaelh/zephyr
1
0
Fork 0
Code Releases Activity
zephyr/doc/getting_started/toolchain_3rd_party_x_compilers.rst

96 lines
2.8 KiB
ReStructuredText
Raw Permalink 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 07:20:24 +02:00
.. _third_party_x_compilers:
3rd Party Toolchains
####################
A "3rd party toolchain" is an officially supported toolchain provided by an
external organization. Several of these are available.
doc: periodic updates to getting started guide Updates based on discussion and changes in supported features. - Make the guide shorter by removing content that's not relevant to most users who are truly just getting started, such as information about pre-LTS versions that did not support west, and by being more concise in some places. - Decrease the number of colored boxes. At the latest TSC F2F, the "note / warning / note / tip" contents were identified as a readability problem. - Add additional information based on new west features, like "west boards". Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
2019-05-13 22:07:57 +02:00
.. _toolchain_gnuarmemb:
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 07:20:24 +02:00
GNU ARM Embedded
****************
#. Download and install a `GNU ARM Embedded`_ build for your operating system
and extract it on your file system.
.. warning::
doc: Instruct Windows users to not install the lastest gnuarmemb The latest release of the Windows toolchain has a critical bug, Windows users should install the next-to-latest release instead. To prevent Windows users from being affected we add a note about this in the documentation. Bug: https://github.com/zephyrproject-rtos/zephyr/issues/12257 Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
2019-03-07 10:51:14 +01:00
Do not install the toolchain into a path with spaces. On
Windows, we'll assume you install into the directory
:file:`C:\\gnu_arm_embedded`.
doc: gsg: Link to the gatekeeper section from the toolchains Add a warning about the Gatekeeper issues that Catalina introduces in the section about GNU Arm Embedded. Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
2020-03-09 18:33:17 +01:00
.. warning::
On macOS Catalina or later you might need to :ref:`change a security
policy <mac-gatekeeper>` for the toolchain to be able to run from the
terminal.
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 07:36:30 +02:00
#. :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 07:20:24 +02:00
- Set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to ``gnuarmemb``.
- Set :envvar:`GNUARMEMB_TOOLCHAIN_PATH` to the toolchain installation
directory.
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 07:36:30 +02:00
#. To check that you have set these variables correctly in your current
environment, follow these example shell sessions (the
:envvar:`GNUARMEMB_TOOLCHAIN_PATH` values may be different on your system):
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 07:20:24 +02:00
.. code-block:: console
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 07:36:30 +02:00
# Linux, macOS:
$ echo $ZEPHYR_TOOLCHAIN_VARIANT
gnuarmemb
$ echo $GNUARMEMB_TOOLCHAIN_PATH
/home/you/Downloads/gnu_arm_embedded
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 07:20:24 +02: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 07:36:30 +02:00
# Windows
> echo %ZEPHYR_TOOLCHAIN_VARIANT%
gnuarmemb
> echo %GNUARMEMB_TOOLCHAIN_PATH%
C:\gnu_arm_embedded
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 07:20:24 +02:00
Crosstool-NG
************
You can build toolchains from source code using crosstool-NG.
#. Follow the steps on the crosstool-NG website to `prepare your host
<http://crosstool-ng.github.io/docs/os-setup/>`_.
#. Follow the `Zephyr SDK with Crosstool NG instructions
<https://github.com/zephyrproject-rtos/sdk-ng/blob/master/README.md>`_ to
build your toolchain. Repeat as necessary to build toolchains for multiple
target architectures.
You will need to clone the ``sdk-ng`` repo and run the following command:
.. code-block:: console
./go.sh <arch>
.. note::
Currently, only i586 and Arm toolchain builds are verified.
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 07:36:30 +02:00
#. :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 07:20:24 +02:00
- Set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to ``xtools``.
- Set :envvar:`XTOOLS_TOOLCHAIN_PATH` to the toolchain build directory.
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 07:36:30 +02:00
#. To check that you have set these variables correctly in your current
environment, follow these example shell sessions (the
:envvar:`XTOOLS_TOOLCHAIN_PATH` values may be different on your system):
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 07:20:24 +02:00
.. code-block:: console
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 07:36:30 +02:00
# Linux, macOS:
$ echo $ZEPHYR_TOOLCHAIN_VARIANT
xtools
$ echo $XTOOLS_TOOLCHAIN_PATH
/Volumes/CrossToolNGNew/build/output/
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 07:20:24 +02:00
.. _GNU ARM Embedded: https://developer.arm.com/open-source/gnu-toolchain/gnu-rm
.. _crosstool-ng site: http://crosstool-ng.org
Copy permalink