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

62 lines
2.5 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
.. _other_x_compilers:
Other Cross Compilers
######################
This toolchain variant is borrowed from the Linux kernel build system's
mechanism of using a :envvar:`CROSS_COMPILE` environment variable to set up a
GNU-based cross toolchain.
Examples of such "other cross compilers" are cross toolchains that your Linux
distribution packaged, that you compiled on your own, or that you downloaded
from the net. Unlike toolchains specifically listed in
:ref:`third_party_x_compilers`, the Zephyr build system may not have been
tested with them, and doesn't officially support them. (Nonetheless, the
toolchain set-up mechanism itself is supported.)
Follow these steps to use one of these toolchains.
#. Install a cross compiler suitable for your host and target systems.
For example, you might install the ``gcc-arm-none-eabi`` package on
Debian-based Linux systems, or ``arm-none-eabi-newlib`` on Fedora or Red
Hat:
.. code-block:: console
# On Debian or Ubuntu
sudo apt-get install gcc-arm-none-eabi
# On Fedora or Red Hat
sudo dnf install arm-none-eabi-newlib
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 ``cross-compile``.
- Set :envvar:`CROSS_COMPILE` to the common path prefix which your
toolchain's binaries have, e.g. the path to the directory containing the
compiler binaries plus the target triplet and trailing dash.
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:`CROSS_COMPILE` value 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
cross-compile
$ echo $CROSS_COMPILE
/usr/bin/arm-none-eabi-
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
kconfig: Drop support for specifying CROSS_COMPILE through Kconfig When we move DT infront of Kconfig we are going to need access to a C toolchain before Kconfig is evaluated. This means it will not be possible to specify the toolchain used through Kconfig. To deal with this we ... Drop support for specifying CROSS_COMPILE through Kconfig. Still available is the ability to specify CROSS_COMPILE through the environment or through a CMake variable. Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
2018-11-19 14:50:42 +01:00
You can also set ``CROSS_COMPILE`` as a CMake variable.
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
When using this option, all of your toolchain binaries must reside in the same
directory and have a common file name prefix. The ``CROSS_COMPILE`` variable
is set to the directory concatenated with the file name prefix. In the Debian
example above, the ``gcc-arm-none-eabi`` package installs binaries such as
``arm-none-eabi-gcc`` and ``arm-none-eabi-ld`` in directory ``/usr/bin/``, so
the common prefix is ``/usr/bin/arm-none-eabi-`` (including the trailing dash,
``-``). If your toolchain is installed in ``/opt/mytoolchain/bin`` with binary
names based on target triplet ``myarch-none-elf``, ``CROSS_COMPILE`` would be
set to ``/opt/mytoolchain/bin/myarch-none-elf-``.
Copy permalink