contributing/debug: new page.

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,63 @@
+# 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.