[[TOC(Debugging/Newlib , depth=3)]]

= Debugging An RSB Built Newlib =

The RSB builds Newlib when building GCC as a single source tree with full debug information. This debugging information does not effect the size of the executable on your target hardware yet it does provide you with information you may need to debug the way you are using Newlib or a possible bug in Newlib.

If you reach a call to Newlib and you `step` the debugger it will step into the Newlib function however there often is no source available becaues the RSB cleans the source away after building the tools plus the path to the source is a relative path based on how GCC built Newlib. For example stepping into the function `regcomp` you might see:

{{{
gdb) s
regcomp (preg=preg@entry=0x2a4ee0, pattern=0x2a5554 "test_regex_.*", cflags=cflags@entry=1) at ../../../../../../gcc-6-20160609/newlib/libc/posix/regcomp.c:192
192     ../../../../../../gcc-6-20160609/newlib/libc/posix/regcomp.c: No such file or directory.
}}}

To make the source code available to the debugger you need to unpack the Newlib source used by the RSB and you need to tell the debugger where find it. 

My RSB is located at `/opt/work/chris/rtems/rsb/rtems-source-builder.git` and the source used to build the tools is under the `rtems/source` in the RSB.

The version of Newlib source to use is embedded into the GCC version string:

{{{
$ /opt/work/rtems/4.12/bin/i386-rtems4.12-gcc --version
i386-rtems4.12-gcc (GCC) 6.1.1 20160609 (RTEMS 4.12, RSB c476de6150f39afdf142c6f4420c59ba2f1aa2fe-modified, Newlib 2.4.0.20160527)
Copyright (C) 2016 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
}}}

The Newlib version is `Newlib 2.4.0.20160527` so the source is `newlib-2.4.0.20160527.tar.gz`.

Change directory to a location on the host machine GDB is running on and create a directory to unpack the Newlib source. Create the directory and unpack the source:

{{{
$ cd /opt/work/chris/rtems
$ mkdir src
$ tar zxf /opt/work/chris/rtems/rsb/rtems-source-builder.git/rtems/sources/newlib-2.4.0.20160527.tar.gz
}}}

Create the specific GCC and Newlib directories GCC was built with the debugger printed out and link to the newlib source:

{{{
$ mkdir gcc-6-20160609
$ cd gcc-6-20160609
$ ln -s ../newlib-2.4.0.20160527/newlib newlib
$ cd ..
}}}

Create the internal work directories GCC had when the source was built. You can see these in the path as `../../../../../..`:

{{{
$ mkdir -p 1/2/3/4/5/6
}}}

You now have a path the debugger can reference and find the source. Add to the GDB source search path using the `dir` command:

{{{
(gdb) dir /opt/work/chris/rtems/src/1/2/3/4/5/6
Source directories searched: /opt/work/chris/rtems/src/1/2/3/4/5/6:$cdir:$cwd
(gdb) l
187     int                             /* 0 success, otherwise REG_something */
188     regcomp(preg, pattern, cflags)
189     regex_t *__restrict preg;
190     const char *__restrict pattern;
191     int cflags;
192     {
193             struct parse pa;
194             struct re_guts *g;
195             struct parse *p = &pa;
196             int i;
}}}

You will now have the Newlib available in the debugger.