GNU Arm Embedded toolchain deprecation

[stephanosio]

Preface

GNU Arm Embedded toolchain has been a popular choice by many because most Zephyr users are developing for Arm-based SoCs and it has been the go-to toolchain for bare metal Arm development for years; in fact, the Zephyr documentation even endorses this toolchain for non-Linux users to some degree.

Now that the Zephyr SDK toolchains are available for all three major operating systems (i.e. Linux, macOS and Windows), there is no need to use a third-party provided GNU toolchain such as the GNU Arm Embedded, and the Zephyr SDK should become the default and recommended toolchain so as to ensure the best compatibility and developer experience.

Proposed change

1. Remove any endorsements of the GNU Arm Embedded toolchain in the Zephyr documentation.
2. Mention that the Zephyr SDK is recommended over the GNU Arm Embedded anywhere it is mentioned in the documentation.
3. Stop including GNU Arm Embedded toolchain as part of the CI/Developer Docker image.

Note that we are not declaring the GNU Arm Embedded toolchain to be unsupported at this time; we are simply no longer endorsing it, and instead recommending the Zephyr SDK for building Arm binaries on all operating systems.

Additional context

#43843 (comment)

The GNU Arm Embedded toolchain has not had major incompatibility issues until now because the Zephyr SDK tried to align with the GNU Arm Embedded as much as possible; but, that is no longer going to be possible as we start implementing more features like those described in zephyrproject-rtos/sdk-ng#350.

#43843 (comment)

as we start implementing zephyrproject-rtos/sdk-ng#350 in order to support more advanced C/C++ features, we will need to start telling its users "if you want to use this feature, you must use the Zephyr SDK," in which case we might as well just tell them to use the Zephyr SDK in the first place, unless they have a very good reason not to, and avoid using the GNU Arm Embedded.

[stephanosio]

cc @tejlmand @carlescufi

[galak]

cc @nashif

[galak]

I don't think this makes sense, there is a still a large install base, silicon vendors shipping GNU ARM embedded, etc. I don't think we should remove any "endorsements" or such for it.

Should possible bring this up for TSC discussion.

[stephanosio]

As far as I am aware, the only reason we were recommending/endorsing the GNU Arm Embedded toolchain until now was that it was available on all three major operating systems (Linux, macOS and Windows) whereas the Zephyr SDK was not -- we had no option but to recommend it for non-Linux users, but that is no longer the case with the new SDK.

GNU Arm Embedded is a GNU toolchain distribution, so is the Zephyr SDK but with the custom features to better support Zephyr. With the Zephyr SDK available on all three OSes, there is really no reason to use the GNU Arm Embedded anymore.

Also as we start introducing more Zephyr-specific features to the toolchains (zephyrproject-rtos/sdk-ng#350), the users of the GNU Arm Embedded toolchain will not be able to take advantage of the features that would have been available if they were using the Zephyr SDK toolchains.

In that sense, it only makes sense to start deprecating third-party GNU toolchain distributions such as the GNU Arm Embedded.

p.s. as I noted above, "we are not declaring the GNU Arm Embedded toolchain to be unsupported at this time." The proposal is to no longer endorse/recommend it, and to direct its users towards the Zephyr SDK.

[tejlmand]

in fact, the Zephyr documentation even endorses this toolchain for non-Linux users to some degree.

where ?
The closest to any kind of endorsement I find is this:
https://docs.zephyrproject.org/latest/guides/beyond-GSG.html#gs-toolchain

While the Zephyr SDK includes standard tool chains for all supported architectures, there are also customized alternatives as described in these documents. (If you’re not sure which to use, check your specific board-level documentation. If you’re targeting an Arm Cortex-M board, for example, GNU Arm Embedded is a safe bet.)

but I don't consider this an endorsement, cause it's just an example of a customized alternative.
Although I'm fine with that sentence not referring to any specific toolchain.

1. Remove any endorsements of the GNU Arm Embedded toolchain in the Zephyr documentation.

When making such statement, could you please provide some links to places in the docs where we endorse GNU Arm Embedded ?

2. Mention that the Zephyr SDK is recommended over the GNU Arm Embedded anywhere it is mentioned in the documentation.

Again, where do we do this ?
Also, why should we recommend any specific toolchain ?

Let's keep the text here neutral, which I already think it is.
https://docs.zephyrproject.org/latest/guides/beyond-GSG.html#set-up-a-toolchain

and then update this part:

You can install the Zephyr SDK to get toolchains for all supported architectures. Otherwise, you can install other toolchains in the usual way for your operating system: with installer programs or system package managers, by downloading and extracting a zip archive, etc.

by simply removing the Linux system part.

Also this can be updated with Zephyr SDK as a possibility on all OS'es.
https://docs.zephyrproject.org/latest/getting_started/index.html#install-a-toolchain

[stephanosio]

While the Zephyr SDK includes standard tool chains for all supported architectures, there are also customized alternatives as described in these documents. (If you’re not sure which to use, check your specific board-level documentation. If you’re targeting an Arm Cortex-M board, for example, GNU Arm Embedded is a safe bet.)

but I don't consider this an endorsement, cause it's just an example of a customized alternative.

Saying something is a "safe bet" sounds like an implied endorsement to me.

3. Mention that the Zephyr SDK is recommended over the GNU Arm Embedded anywhere it is mentioned in the documentation.

Again, where do we do this ?

I am suggesting to do that where GNU Arm Embedded is mentioned, so I am not sure what you mean by "where do we do this?"

Also, why should we recommend any specific toolchain ?

#43843 (comment)

and then update this part:

already done in #43008

[nashif]

deprecation is a bit too strong and the title of this issue is misleading.
If we have been recommending this toolchain where zephyr sdk did not work before as an alternative, we could stop doing that, however this toolchain and other 3rd party toolchains and hopefully more toolchains in the future should still be supported, referenced and mentioned in the documentation as before.

only difference now, you do not have to use this toolchain or any other toolchain when build on mac and windows. So the result of all of this should be just a tweak to the documentation where applicable, but not "deprecation".

[stephanosio]

I am not suggesting to deprecate third-party non-GNU toolchains such as Arm Compiler, ARC MetaWare, IAR, etc.

What I am suggesting is to discourage people from using (i.e. deprecate) the third-party provided GNU toolchains such as the GNU Arm Embedded, ESP-IDF GNU Toolchain, etc. that offer no real benefits over the Zephyr SDK GNU toolchains, and instead recommend people to use the Zephyr SDK whenever possible.

The third-party GNU toolchains, including the GNU Arm Embedded toolchain in the foreseeable future, have the configurations and/or patches that are different to/may be incompatible with the Zephyr, leading to various build and run-time issues -- this eventually leads to bad developer experience.

The GNU Arm Embedded toolchain has not had major incompatibility issues until now because the Zephyr SDK tried to align with the GNU Arm Embedded as much as possible; but, that is no longer going to be possible as we start implementing more features like those described in zephyrproject-rtos/sdk-ng#350.

The ESP-IDF GNU Toolchain is a good example -- it has different patches and build configurations to the Zephyr SDK GNU Toolchains leading to various incompatibilities and build issues:

#33876
#38978
#34767
#22722 (comment)
(and the list goes on)

[carlescufi]

Adding the TSC label to get a better idea of the usage of GCC-based, 3rd-party non-commercial toolchains among the vendors.

[stephanosio]

FYI, in case of the ESP-IDF GNU toolchain, we have added the ESP32 support in the Zephyr SDK to replace the ESP-IDF GNU toolchain so that users are no longer greeted by the build failures and broken C/C++ features.

Although that is currently not the case for the GNU Arm Embedded, as we start implementing zephyrproject-rtos/sdk-ng#350 in order to support more advanced C/C++ features, we will need to start telling its users "if you want to use this feature, you must use the Zephyr SDK," in which case we might as well just tell them to use the Zephyr SDK in the first place, unless they have a very good reason not to, and avoid using the GNU Arm Embedded.

Note that the features described in zephyrproject-rtos/sdk-ng#350 require Zephyr-specific toolchain-level modifications and cannot be supported on third-party GNU toolchains, unless they specifically build their toolchains targeting Zephyr (i.e. --target=(arch)-(vendor)-zephyr instead of --target=(arch)-(vendor)-elf aka. bare-metal).

[nashif]

where in the current documentation this toolchain is being endorsed?

[stephanosio]

where in the current documentation this toolchain is being endorsed?

@nashif See below:

1. The Beyond GSG used to say GNU Arm Embedded is "a safe bet", but that has been removed.
2. The Application Development tells users to install the GNU Arm Embedded toolchain for debugging with Eclipse. We can tell users to install the Zephyr SDK instead now.
3. The sample ZephyrBuildConfig.cmake on the Zephyr CMake Package has code for "Default[-ing] to GNU Arm Embedded toolchain if no toolchain is set." That should be the Zephyr SDK now.

Also, we have been directing many non-Linux users towards the GNU Arm Embedded toolchain on Discord (Slack) and other communication channels. We should be telling users to use the Zephyr SDK now.

[nashif]

1. The Beyond GSG used to say GNU Arm Embedded is "a safe bet", but that has been removed.

I do not see any endorsements in there, this toolchain is just being listed as a 3rd party among many others.

The Application Development tells users to install the GNU Arm Embedded toolchain for debugging with Eclipse. We can tell users to install the Zephyr SDK instead now.

Also not an endorsement. the documentation is for windows, so this could be changed to point to the zephyr SDK if we adapt the instructions and verify that all works

3. The sample ZephyrBuildConfig.cmake on the Zephyr CMake Package has code for "Default[-ing] to GNU Arm Embedded toolchain if no toolchain is set." That should be the Zephyr SDK now.

With the new SDK, let's not default to anything else.

The changes above do not count as deprecation, we just tweak our docs for the new reality of having a multi platform SDK, if someone wants to use other compilers, they should still be able to do that just like before.

[stephanosio]

I do not see any endorsements in there

I should have stated "implied endorsements" or just "recommendations" (why would anybody pick one thing out of many things if they were not recommending/endorsing it in some way?)

And, regardless of the wording in the documentation, as a matter of fact, we have been recommending the GNU Arm Embedded for non-Linux users who are building for ARM targets.

With the new SDK, let's not default to anything else.
The changes above do not count as deprecation, we just tweak our docs for the new reality of having a multi platform SDK,

Yes, that is the no. 1 of the proposed changes above.

if someone wants to use other compilers, they should still be able to do that just like before.

Yes, as I pointed out multiple times above, I am not suggesting to stop supporting any of the existing toolchains, including the third-party GNU toolchains.

What I am proposing is to deprecate or express disapproval of the third-party provided GNU toolchains for the reasons detailed in #43843 (comment) and #43843 (comment) by means of implementing no. 2 and no. 3 of the proposed changes.

[nashif]

hat I am proposing is to deprecate or express disapproval of the third-party provided GNU toolchains for the reasons detailed in #43843 (comment) and #43843 (comment) by means of implementing no. 2 and no. 3 of the proposed changes.

but why? Those are toolchains that are supported for various reasons, not only to bridge the gap on windows and macOS. Why do we need to "deprecate" or change anything about those toolchains being supported by Zephyr.

The text in the docs:

While the Zephyr SDK includes standard toolchains for all supported architectures, there are also customized alternatives as described in these documents. (If you’re not sure which to use, check your specific board-level documentation.)

does not need to be changed IMO, and should remain as is, I do not think we should change anything here or talk about "deprecation".

Maybe I am missing something here, maybe you should submit a PR to show how you want to do the deprecation, that would make it clearer I guess. :)

[stephanosio]

but why? Those are toolchains that are supported for various reasons, not only to bridge the gap on windows and macOS. Why do we need to "deprecate" or change anything about those toolchains being supported by Zephyr.

Have you read #43843 (comment) and #43843 (comment)?

The GNU Arm Embedded toolchain has not had major incompatibility issues until now because the Zephyr SDK tried to align with the GNU Arm Embedded as much as possible; but, that is no longer going to be possible as we start implementing more features like those described in zephyrproject-rtos/sdk-ng#350.

as we start implementing zephyrproject-rtos/sdk-ng#350 in order to support more advanced C/C++ features, we will need to start telling its users "if you want to use this feature, you must use the Zephyr SDK," in which case we might as well just tell them to use the Zephyr SDK in the first place, unless they have a very good reason not to, and avoid using the GNU Arm Embedded.

[tejlmand]

3. The sample ZephyrBuildConfig.cmake on the Zephyr CMake Package has code for "Default[-ing] to GNU Arm Embedded toolchain if no toolchain is set." That should be the Zephyr SDK now.

With the new SDK, let's not default to anything else.

@stephanosio please do not take a snippet out of context.
This snippet is from the section: https://docs.zephyrproject.org/latest/build/zephyr_cmake_package.html#zephyr-build-configuration-cmake-package

Zephyr Build Configuration CMake package

The Zephyr Build Configuration CMake package provides a possibility for a Zephyr based project to control Zephyr build settings in a generic way.

so this is an example on how users can override what Zephyr does per default.
Zephyr defaults to Zephyr SDK, so there is no point in showing users how they can default to Zephyr SDK, cause that is what we already do.
Instead we should show users how they can default to something else.
Of course we could use FOO compiler but why not use an actual toolchain supported by Zephyr, such as GNU arm embedded.

[stephanosio]

so this is an example on how users can override what Zephyr does per default.
Zephyr defaults to Zephyr SDK, so there is no point in showing users how they can default to Zephyr SDK, cause that is what we already do.

This could very well be an example showing how to use Zephyr SDK from a non-standard installation path without registering in the package registry, or using a custom QEMU with the Zephyr SDK.

If we really wanted to show an example of a different toolchain usage, a non-GNU toolchain like Arm Compiler or MetaWare would be a better choice.

[tejlmand]

This could very well be an example showing how to use Zephyr SDK from a non-standard installation path without registering in the package registry, or using a custom QEMU with the Zephyr SDK.

When we already has better mechanisms in place for handling and detecting the Zephyr SDK then I see little value is using Zephyr SDK for such example. Especially cause you don't need to set ZEPHYR_TOOLCHAIN_VARIANT to zephyr even if you place it somewhere completely different.

If we really wanted to show an example of a different toolchain usage, a non-GNU toolchain like Arm Compiler or MetaWare would be a better choice.

I'm fine with changing it to a different toolchain, I see no problem in that.
Main reason for using GNU arm embedded in the example back then was the fact that arm is a major arch in Zephyr, and Zephyr SDK wasn't available on Windows. So Windows users building for arm archs would be using gnu arm embedded.

I'm mainly pointing out the purpose of the example, and that purpose should be kept, and I don't believe using Zephyr SDK in the example makes sense, but another toolchain could make more sense now than gnu arm embedded.

[zephyrbot]

Hi @stephanosio,

This issue, marked as an RFC, was opened a while ago and did not get any traction. Please confirm the issue is correctly assigned and re-assign it otherwise.

Please take a moment to review if the issue is still relevant to the project. If it is, please provide feedback and direction on how to move forward. If it is not, has already been addressed, is a duplicate, or is no longer relevant, please close it with a short comment explaining the reason.

Thanks!