I really appreciate that these steps are included in the documentation. I made some mistakes and other parts I didn't understand why it would be necessary and maybe could be clarified.

3.30.13. Debugging With the GNU Project Debugger (GDB) Remotely

I think the tip "install debug (-dbg) packages for the applications you are going to debug." belongs to section "3.30.14. Debugging with the GNU Project Debugger (GDB) on the Target".

1) Configure your build system to construct the companion debug filesystem:

Is this necessary if you build and use the SDK?  I think the SDK already includes debug files without setting these values.  IMAGE_GEN_DEBUGFS isn't in the reference guide so it's hard to know what it is supposed to do.

2) Configure the system to include gdbserver in the target filesystem:

Mention the following also includes the debugger
EXTRA_IMAGE_FEATURES_append = " tools-debug"

4) Set up the debugfs

Not necessary when using the SDK as it has sources in it? But when not using the SDK untaring the wrong file system like "core-image-minimal-initramfs-genericx86-64-dbg.tar.bz2" can happen.  I did this the first time through and it took awhile for me to understand the mistake I made. Maybe just a note to prevent new users from making the stupid mistake I made.

There is a typo in the documentation "build-dir/tmp-glibc/deploy/images/machine/image.rootfs.tar.bz2". "tmp-glibc" should just be "tmp".


5) Set up GDB

Modify the sentence to read "Sourcing the environment file puts the SDK in your PATH environment variable and sets $GDB to the SDK's debugger".  gdb by itself is the host tool.

7) Debug a program:

"set substitute-path /usr/src/debug debugfs/usr/src/debug".  I don't know what circumstances this works with but not with any application I tried debugging.  With a fresh Poky build all applications I tried debugging uses relative paths.  "substitue-path" doesn't work with files that start with relative paths (there doesn't seem to be a way for gdb to strip relative paths (https://stackoverflow.com/questions/37330688/how-can-i-set-a-gdb-source-mapping-for-a-relative-path).

For example debugging less:
(gdb) l
68	../less-551/main.c: No such file or directory.


But the "dir" command does work when adding the programs build directory as a base directory to use.  This seems to be primarily the case when something is built with autotools with a separate build directory.  The file path is relative from the build folder to the source folder.  

8) Deploying without a full image rebuild:

When using "devtool modify recipe" and "devtool build recipe" the "-src" package and folder is empty.  I guess this is due to using external sources.  Again for this to work with gdb I had to use the "dir" command so that the sources could be found.  Also maybe the SDK manual should point to these sections in "Deploy the Build Output" if you need to perform debugging.

The major problem I had was trying to find a front-end to gdb that worked.  I don't know what the problem is but the debugger keeps having issues with a failure.  When using VS Code or Eclipse with the debugger in Jethro worked fine but with Zeus I keep seeing the error and it kills the debug session:

warning: Unable to find dynamic linker breakpoint function.
GDB will be unable to debug shared library initializers
and track explicitly loaded dynamic code. 

I mention this because local.conf has "eclipse-debug" but I didn't understand from the documentation if it was still relevant as eclipse support was said to be removed.

I eventually found that gdbgui works without any problems with the debugger that is built with Yocto. I guess that gdb has a builtin interface called tui but it is disabled.