From 92756ed691e3ad3bd6687361c3aef1d10f8368c1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bernhard=20Rosenkr=C3=A4nzer?=
 <bernhard.rosenkraenzer.ext@huawei.com>
Date: Fri, 29 Jul 2022 04:22:48 +0200
Subject: [PATCH] docs: Document gcc and clang toolchains
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document gcc and clang as supported toolchains, and how to
switch between them

Signed-off-by: Bernhard Rosenkränzer <bernhard.rosenkraenzer.ext@huawei.com>
---
 docs/index.rst      |  6 ++++
 docs/toolchains.rst | 75 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+)
 create mode 100644 docs/toolchains.rst

diff --git a/docs/index.rst b/docs/index.rst
index 4f7bc2c7..7baa6191 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -37,6 +37,12 @@ Build System Guide
    supported-technologies/openthread
    supported-technologies/containers
 
+.. toctree::
+   :caption: Supported Toolchains
+   :maxdepth: 2
+
+   toolchains
+
 .. toctree::
    :caption: Troubleshoot
    :maxdepth: 2
diff --git a/docs/toolchains.rst b/docs/toolchains.rst
new file mode 100644
index 00000000..844ccfa6
--- /dev/null
+++ b/docs/toolchains.rst
@@ -0,0 +1,75 @@
+.. SPDX-FileCopyrightText: Huawei Inc.
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+.. include:: definitions.rst
+
+.. _Toolchains:
+
+Toolchains
+##########
+
+|main_project_name| provides and supports both gcc based and clang/LLVM based toolchains.
+
+
+.. contents:: 
+    :depth: 2
+
+gcc
+***
+|main_project_name|'s gcc toolchain is based on GNU binutils 2.38 and gcc 12.1.
+|main_project_name|'s 2.0 branch may move to newer gcc releases within the gcc 12 branch
+(12.2, 12.3, ...), but will stay on the gcc 12 branch.
+Post-2.0 releases of |main_project_name| will likely update to new major versions.
+
+To select gcc, edit `conf/local.conf` and add:
+.. code-block:: sh
+
+   TOOLCHAIN="gcc"
+
+clang
+*****
+|main_project_name|'s clang toolchain is based on LLVM 14.0.6, including lld.
+|main_project_name|'s 2.0 branch may move to newer clang releases within the llvm 14 branch,
+(14.0.7, ...) but will stay on the llvm 14 branch.
+Post-2.0 releases of |main_project_name| will likely update to new major versions.
+
+To select clang, edit `conf/local.conf` and add:
+.. code-block:: sh
+
+   TOOLCHAIN="clang"
+
+You may also want to add:
+.. code-block:: sh
+
+   RUNTIME="llvm"
+
+`RUNTIME="llvm"` enables the use of additional LLVM components over their gcc counterparts:
+`compiler-rt` replaces `libgcc`, `libc++` replaces `libstdc++` and the LLVM version of
+`libunwind` is preferred.
+
+`libc++` and `libstdc++` are (almost) fully source level compatible, but not binary compatibile.
+You can't link an application using one to a library using the other. It is therefore recommended
+to use the same C++ library for all packages in the system.
+
+Which one to use
+****************
+Since different compilers optimize differently, there is some code that will perform better
+when built with clang while there is other code that will perform better when built with gcc.
+
+If you're adding your own code to |main_project_name|, you may want to try both toolchains and
+compare their performance on your code.
+
+If you're using the Linux kernel, both toolchains have been tested for a long time and will
+work.
+
+If you're using the Zephyr kernel, gcc is officially supported by the upstream project while
+clang support is considered experimental.
+
+If you need `OpenHarmony` compatibility, you have to use clang and the LLVM runtime. In that
+case, you need to add this to `conf/local.conf`:
+
+.. code-block:: sh
+
+   TOOLCHAIN="clang"
+   RUNTIME="llvm"
-- 
GitLab