contributing/debug: new page.

Author: ericonr

src/SUMMARY.md

@@ -77,3 +77,4 @@
       - [Static XBPS](./xbps/troubleshooting/static.md)
 - [Contributing](./contributing/index.md)
    - [Contributing To void-docs](./contributing/void-docs.md)
+   - [Troubleshooting Packages](./contributing/debug.md)

src/contributing/debug.md

@@ -0,0 +1,66 @@
+# Troubleshooting badly behaving apps
+
+Despite the best efforts of Void Linux maintainers, it is possible that you will
+have issues with packages from the official repositories. On such cases, there
+are some steps to follow in order to provide as complete a bug report as
+possible.
+
+Some of these steps can even help you find the cause of the issue yourself!
+
+## Look at error messages attentively THIS NEEDS WORK
+
+Python programs, for example, complain loudly about missing modules and other
+issues like that. If you're using a compiled binary, and it's missing libraries
+for some reason, your dynamic linker should tell you as well.
+
+## Check for issues in the package database
+
+You can use the `-a` flag for
+[xbps-pkgdb(1)](https://man.voidlinux.org/xbps-pkgdb.1) to run a complete check
+on all systems packages, which can detect any files that may have been altered
+when they shouldn't have been. For any of the files listed in this step, you
+should attempt to reinstall them with the `-f` flag for
+[xbps-install(1)](https://man.voidlinux.org/xbps-install.1). An example can be
+seen below:
+
+```
+# xbps-pkgdb -a
+ERROR: p7zip: hash mismatch for /usr/bin/7z.
+ERROR: p7zip: files check FAILED.
+# xbps-install -f p7zip
+```
+
+After this is done, check if the issue persists. It should be noted that issues
+like this can indicate hardware issues in your storage media or RAM.
+
+## Strace the program
+
+If the issue is caused by a program, you can run it under the
+[strace(1)](https://man.voidlinux.org/strace.1) utility to check if it's trying,
+for example, to access files that don't exist, and their programmer didn't
+implement a proper fallback or error message.
+
+## Debug the program NEEDS WORK
+
+If a look at `strace` wasn't enough, it may be possible to use the GNU debugger,
+[gdb(1)](https://man.voidlinux.org/gdb.1), to step through the program's
+execution. You can [install debug packages](../xbps/repositories/index.md) or
+use Void's [Debuginfod](https://sourceware.org/elfutils/Debuginfod.html) server.
+GDB is especially useful when an application crashes with `SIGABRT` or `SIGSEGV`
+(see [signal(7)](https://man.voidlinux.org/signal.7), since it will stop
+execution at that point and you can print a backtrace showing all the function
+calls that lead to that place. An example using the Debuginfod server is show
+below:
+
+```
+$ DEBUGINFOD_URLS="https://debugingod.s.voidlinux.org" gdb --args <program> [arguments]
+```
+
+Inside GDB, some useful commands are:
+
+- `set logging on`, which creates a `gdb.txt` file which can be shared easily;
+- `backtrace`, which shows the function calls made until the application got to
+   that place;
+- `info threads`, which shows information about threads in the program;
+- `break <function>`, which puts a breakpoint in a function that you may think
+   is suspect.