doc: update more details about STDCLIB support for gcc/clang

Signed-off-by: Huaqi Fang <[email protected]>

doc/source/changelog.rst

@@ -41,7 +41,7 @@ This is release version ``0.5.0-dev`` of Nuclei SDK.
 
   - Add bench reset/sample/stop/stat and get usecyc/sumcyc/lpcnt APIs in NMSIS Core
   - Add more CSRs such as Zc/Stack Check in riscv_encoding.h
-  - Rename NMSIS DSP/NN library name to match gcc 13 changes, eg. b -> zba_zbb_zbc_zbs
+  - Rename NMSIS DSP/NN library name to match gcc 13 changes, eg. b -> zba_zbb_zbc_zbs, so the library name changed a lot
   - Add IAR compiler support in NMSIS Core
   - No more bitmanip extension intrinsic header <rvintrin.h> for gcc13
   - Fix __RV_CLAMP macro and add __MACHINE/SUPERVISOR/USER_INTERRUPT macros
@@ -71,15 +71,17 @@ This is release version ``0.5.0-dev`` of Nuclei SDK.
   - Fix semihost not working when link with semihost library
   - Add support for gcc 13, clang 17, terapines zcc toolchain using TOOLCHAIN make variable, eg. TOOLCHAIN=nuclei_gnu for gnu gcc toolchain, TOOLCHAIN=nuclei_llvm for llvm toolchain, TOOLCHAIN=terapines for terapines zcc toolchain
   - Add support for libncrt v3.0.0, which spilt libncrt into 3 parts, the c library part, fileops part, and heapops part, so **NCRTHEAP** and **NCRTIO** makefile variable are added to support new version of libncrt
-  - To support both gcc, clang, zcc, now we no longer use ``--specs=nano.specs`` like options, since clang don't support it, we directly link the required library according to the library type you want to use
+  - To support both gcc, clang, zcc, now we no longer use ``--specs=nano.specs`` like ``--specs=`` gcc only options, since clang don't support it, we directly link the required libraries according to the library type you want to use in Makefile, group all the required libraries using ``--start-group archives --end-group`` of linker option, see https://sourceware.org/binutils/docs/ld/Options.html, but when using Nuclei Studio, the Eclipse CDT based IDE didn't provided a good way to do library group, here is an issue tracking it, see https://github.com/eclipse-embed-cdt/eclipse-plugins/issues/592
+    - And also now we defaultly enabled ``-nodefaultlibs`` option to not use any standard system libraries when linking, so we need to specify the system libraries we want to use during linking, which is the best way to support both gcc and clang toolchain.
+  - When using libncrt library, this is no need to link with other libgcc library, c library or math library, such as gcc libgcc library(``-lgcc``), newlib c library(``-lc/-lc_nano``) and math library(``-lm``), the c and math features are also provided in libncrt library
+  - When using Nuclei Studio with imported Nuclei SDK NPK package, you might meet with undefined reference issue during link 
   - The use of ARCH_EXT is changed for new toolchain, eg. you can't pass ARCH_EXT=bp to represent b/p extension, instead you need to pass ARCH_EXT=_zba_zbb_zbc_zbs_xxldspn1x
   - Show CC/CXX/GDB when make showflags
   - Add u900 series cores support
   - No longer support gd32vf103 soc run on qemu
   - Add extra ``-fomit-frame-pointer -fno-shrink-wrap-separate`` options for Zc extension to enable zcmp instruction generation
   - Extra CPU_SERIES macro is passed such (200/300/600/900) during compiling for benchmark examples
   - When you want to select different nmsis library arch, please use **NMSIS_LIB_ARCH** make variable, see demo_dsp as example
-  - When using libncrt library, this is no need to link with other libgcc library, c library or math library, such as gcc libgcc library(``-lgcc``), newlib c library(``-lc/-lc_nano``) and math library(``-lm``), the c and math features are also provided in libncrt library.
 
 * Tools
 

doc/source/develop/buildsystem.rst

@@ -1072,7 +1072,7 @@ STDCLIB
 ~~~~~~~
 
 **STDCLIB** variable is used to select which standard c runtime library will be used.
-If not defined, the default value will be ``newlib_small``.
+If not defined, the default value will be ``newlib_nano``.
 
 In Nuclei GNU Toolchain, we destributed newlib/newlib-nano/Nuclei c runtime library,
 so user can select different c runtime library according to their requirement.
@@ -1082,6 +1082,19 @@ Newlib is a simple ANSI C library, math library, available for both RV32 and RV6
 Nuclei C runtime library is a highly optimized c library designed for deeply embedded user cases,
 can provided smaller code size and highly optimized floating point support compared to Newlib.
 
+From 0.5.0 release, to support both gcc and clang compiler, we decided not to use ``--specs=`` option to
+select system library, instead of that, we start to use ``--nodefaultlibs`` options, and link the required
+system libraries by the ``STDCLIB`` variable choice, so need to link desired libraries such as:
+
+* ``-lgcc``: a standard library (linked by default, excluded by -nodefaultlibs) that provides internal subroutines to overcome shortcomings of particular machines, see https://gcc.gnu.org/onlinedocs/gccint/Libgcc.html.
+* ``-lgcov``: a library used to test coverage program, known as ``gcov/gprof``, see https://gcc.gnu.org/onlinedocs/gcc/Gcov.html
+* ``-lc/-lc_nano``: newlib c library or newlib nano c library, see https://sourceware.org/newlib/docs.html
+* ``-lm``: newlib math library, see https://sourceware.org/newlib/libm.html
+* ``-lstdc++``: gnu standard c++ library, see https://gcc.gnu.org/onlinedocs/libstdc++
+* ``-lsemihost``: riscv semihosting library which implement a set of standard I/O and file I/O operations, see https://github.com/riscv-mcu/riscv-newlib/tree/nuclei/newlib-4.3.0/libgloss/riscv
+* ``-lnosys``: a set of stub functions which implement a set of standard I/O operations but does nothing, and when link with it, it will throw link warning, see https://github.com/riscv-mcu/riscv-newlib/blob/nuclei/newlib-4.3.0/libgloss/libnosys
+* ``-lncrt_pico/-lncrt_nano/-lncrt_small/-lncrt_balanced/-lncrt_fast``: Nuclei libncrt library, it provides pico/nano/small/balanced/fast variant to provide standard c library, math library, and libgcc library features, and need to use together with ``-lheapops_minimal/-lheapops_basic/-lheapops_realtime`` heap operation API, and ``-lfileops_uart/-lfileops_semi/-lfileops_rtt`` file io operation API, when using this libncrt library, please don't link ``-lgcc -lc_nano/-lc -lm -lsemihost -lnosys``, and it also can't link with ``-lstdc++``
+
 .. list-table:: Available STDCLIB choices
    :widths: 10 70
    :header-rows: 1

doc/source/faq.rst

@@ -208,6 +208,15 @@ When you are using libncrt library, and linked with ``-lm``, you may face below
 You can fix it by not link ``-lm`` library, since libncrt library already provided math library feature, so
 no need to link this math library.
 
+undefined reference to fclose/sprintf similar API provided in system libraries
+------------------------------------------------------------------------------
+
+From 0.5.0 release, we no longer use ``--specs=`` option to select library we want to use, and we also passed
+``-nodefaultlibs`` options to not use standard system libraries, this changes are made to support both gcc and clang
+toolchain, so in Nuclei SDK build system, we control the needed system libraries to be linked as required by ``STDCLIB`` make variable, for details, please check ``Build/toolchain/*.mk`` makefiles, and also we use linker's group
+libraries feature ``--start-group archives --end-group`` to repeatly search undefined reference in the group libraries,
+but this feature is not enabled in Eclipse CDT based IDE like Nuclei Studio, which undefined reference is searched in the order of library specified on the command line, so you may meet issue like undefined fclose reference even you linked newlib nano c library ``-lc_nano`` if the library order is not good, so to fix this issue, you may need to place
+the library in a good order and need to repeatly link it, such as ``-lgcc -lc_nano -lm -lsemihost -lgcov -lgcc -lc_nano``, and also we have opened an issue to track it, see https://github.com/eclipse-embed-cdt/eclipse-plugins/issues/592
 
 .. _debugger kit manual: https://www.nucleisys.com/theme/package/Nuclei_FPGA_DebugKit_Intro.pdf
 .. _ftdi_device_desc: http://openocd.org/doc/html/Debug-Adapter-Configuration.html