1# Using picolibc as an embedded source
2
3For projects where deterministic builds, reproduceability and traceability is important, it is possible to embed the entire picolibc library as a meson subproject into the source directory of the main project. The benefit is that git submodules and meson subprojects work nicely together, and it is possible to lock down the libc version together with the source tree.
4
5For more information on the meson subproject feature, refer to the documentation at : https://mesonbuild.com/Subprojects.html
6
7## Adding picolibc as a subproject
8
9First you need to add picolibc as a git submodule:
10
11  ```
12  mkdir subprojects
13  git submodule add https://github.com/keith-packard/picolibc subprojects/picolibc
14  ```
15
16Your source directory could now look something like this:
17
18  ```
19  subprojects/
20    picolibc/
21    otherlib/
22  src/
23    main.c
24  meson.build
25  ```
26
27## Add dependency to meson.build
28
29First of all, when using picolibc as an embedded source, you should not specify -specs=picolibc.specs in the c_args.
30
31Next you will need to include the dependency in your meson.build file:
32
33  ```
34  dependencies += dependency('picolibc', fallback: ['picolibc', 'picolibc_dep'])
35  ```
36
37In order to avoid linker conflicts with any compiler bundled c-library, use the following link flags (also see the warning below):
38
39  ```
40  link_args += '-nolibc'
41  link_args += '-lgcc'
42  ```
43
44Finally use the dependency and linker arguments on your executable
45
46  ```
47  exec = executable('myproject.elf', sources, dependencies: dependencies, link_args: link_args)
48  ```
49
50## Warning: Remove bundled libc (newlib)
51
52As of today there is no option in gcc to ignore the bundled c-library. The development version GCC 9.0 will have an `-nolibc` option that we are waiting for. So currently the only way to avoid including the headers of the bundled library is to use the `-nostdinc` option. However, this also removes all the include directories, including the headers for libgcc, which we want. And i have found no good poartable way of re-adding the libgcc include header path.
53
54So until a better solution appears, it is best to uninstall the c-library if possible. On Debian/Ubuntu, the gcc-arm-none-eabi and libnewlib-arm-none-eabi are separate packages, so just uninstall libnewlib and any conflict is avoided.
55
56You can run a command in order to check which standard paths are included with your GCC:
57
58  ```
59  echo | arm-none-eabi-gcc -E -Wp,-v -
60    /usr/lib/gcc/arm-none-eabi/7.3.1/include
61    /usr/lib/gcc/arm-none-eabi/7.3.1/include-fixed
62    /usr/lib/gcc/arm-none-eabi/7.3.1/../../../arm-none-eabi/include <-- This is newlib (configured through ubuntu /etc/alternatives)
63
64  sudo apt remove libnewlib-arm-none-eabi libnewlib-dev
65
66  echo | arm-none-eabi-gcc -E -Wp,-v -
67    /usr/lib/gcc/arm-none-eabi/7.3.1/include
68    /usr/lib/gcc/arm-none-eabi/7.3.1/include-fixed
69
70