From 2730fe62d5d0af59d49bc2d8fe703753331aacf2 Mon Sep 17 00:00:00 2001 From: Khem Raj Date: Tue, 22 Sep 2020 17:44:15 -0700 Subject: README: Update documentation Few knobs have changed and has not been yet reflected in README Signed-off-by: Khem Raj --- README.md | 61 ++++++++++++++++++++++++++++++++++++------------------------- 1 file changed, 36 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 3990731..95cb5f8 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ bitbake-layers add-layer ../meta-clang Check `conf/bblayers.conf` to see that meta-clang is added to layer mix e.g. -# Default Compiler Switch +# Default Compiler Note that by default gcc will remain the system compiler, however if you wish clang to be the default compiler then set @@ -47,45 +47,56 @@ you can select clang per recipe too by writing bbappends for them containing ```shell TOOLCHAIN = "clang" ``` +also look at `conf/nonclangable.conf` for list of recipes which do not yet fully +build with clang -# Default C++ Standard Library Switch +# Default Compiler Runtime -Note that by default clang libc++ is default C++ standard library, however if you wish -to keep GNU libstdc++ to be the default then set +Default is to use GNU runtime `RUNTIME = "gnu"` which consists of libgcc, libstdc++ to provide C/C++ +runtime support. However its possible to use LLVM runtime to replace it where +compile-rt, llvm libunwind, and libc++ are used to provide C/C++ runtime, while +GNU runtime works with both GCC and Clang, LLVM runtime is only tested with Clang +compiler, Switching to use LLVM runtime is done via a config metadata knob ```shell -LIBCPLUSPLUS = "" +RUNTIME = "llvm" ``` -in `local.conf`. -You can select libstdc++ per package too by writing bbappends for them containing +RUNTIME variable influences individual runtime elements and can be set explcitly as well +e.g. `LIBCPLUSPLUS` `COMPILER_RT` and `UNWINDLIB` -```shell -LIBCPLUSPLUS_toolchain-clang_pn- = "" -``` +Please note that this will still use crt files from GNU compiler always, while llvm now +do provide crt files, they have not been yet intergrated into toolchain -# Default Compiler Runtime ( Compiler-rt + libc++ ) +# Default C++ Standard Library Switch -By default, clang build from meta-clang uses clang runtime ( compiler-rt + libc++ + libunwind ) out of box -However, it is possible to switch to using gcc runtime as default, In order to do that -following settings are needed in site configurations e.g. in `local.conf` +Using RUNTIME bariable will select which C++ runtime is used, however it can be overridden +if needed to by modifying `LIBCPLUSPLUS` variable, usually defaults used by `RUNTIME` is +best fit. e.g. below we select LLVM C++ as default C++ runtime. ```shell -TOOLCHAIN ?= "clang" -LIBCPLUSPLUS = "" -COMPILER_RT = "" -UNWINDLIB = "" +LIBCPLUSPLUS = "--stdlib=libc++" +``` + +in `local.conf`. +You can select libstdc++ per package too by writing bbappends for them containing +```shell +LIBCPLUSPLUS_toolchain-clang_pn- = "--stdlibc=libc++" ``` +Defaults are chosen to be GNU for maximum compatibility with existing GNU systems. Its always +good to use single runtime on a system, mixing runtimes can cause complications during +compilation as well as runtime. However, its upto distribution policies to decide which runtime +to use. -# Removing clang from generated SDK toolchain +# Adding clang in generated SDK toolchain -clang based cross compiler is automatically included into the generated SDK using `bitbake meta-toolchain` or -`bitbake -cpopulate_sdk ` in circumstanced where clang is not expected to be part of SDK, then reset `CLANGSDK` -variable in `local.conf` +clang based cross compiler is not included into the generated SDK using `bitbake meta-toolchain` or +`bitbake -cpopulate_sdk ` if clang is expected to be part of SDK, add `CLANGSDK = "1"` +in `local.conf` ```shell -CLANGSDK = "" +CLANGSDK = "1" ``` # Building @@ -104,7 +115,7 @@ $ runqemu nographic # Limitations Few components do not build with clang, if you have a component to add to that list -simply add it to conf/nonclangable.inc e.g. +simply add it to `conf/nonclangable.inc` e.g. ```shell TOOLCHAIN_pn- = "gcc" @@ -112,7 +123,7 @@ TOOLCHAIN_pn- = "gcc" and OE will start using gcc to cross compile that recipe. -And if a component does not build with libc++, you can add it to `conf/nonclangable.inc` e.g. +if a component does not build with libc++, you can add it to `conf/nonclangable.inc` e.g. ```shell CXX_remove_pn-_toolchain-clang = " -stdlib=libc++ " -- cgit v1.2.3-54-g00ecf