From dcfe5718a2d99e04e90897e8ebb4097e8828ea54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89rico=20Rolim?= Date: Wed, 2 Dec 2020 02:27:20 -0300 Subject: [PATCH 1/3] contributing/void-docs: remove folder with one file. Just use a void-docs.md file directly. --- src/SUMMARY.md | 2 +- src/contributing/{void-docs/index.md => void-docs.md} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename src/contributing/{void-docs/index.md => void-docs.md} (100%) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 9bccd5190..4b471e1ef 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -76,4 +76,4 @@ - [Common Issues](./xbps/troubleshooting/common-issues.md) - [Static XBPS](./xbps/troubleshooting/static.md) - [Contributing](./contributing/index.md) - - [Contributing To void-docs](./contributing/void-docs/index.md) + - [Contributing To void-docs](./contributing/void-docs.md) diff --git a/src/contributing/void-docs/index.md b/src/contributing/void-docs.md similarity index 100% rename from src/contributing/void-docs/index.md rename to src/contributing/void-docs.md From 7055019917a555c6f41fadb755c8bc05c55a95e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89rico=20Rolim?= Date: Wed, 2 Dec 2020 03:14:10 -0300 Subject: [PATCH 2/3] contributing/debug: new page. --- src/SUMMARY.md | 1 + src/contributing/debug.md | 67 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+) create mode 100644 src/contributing/debug.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 4b471e1ef..e89a05d4a 100644 --- a/src/SUMMARY.md +++ b/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) diff --git a/src/contributing/debug.md b/src/contributing/debug.md new file mode 100644 index 000000000..c6aae1332 --- /dev/null +++ b/src/contributing/debug.md @@ -0,0 +1,67 @@ +# 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 you can 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 + +It is possible the program's output tells you why it errors out, so you can try +to run it in a terminal. For example: + +- Python programs complain loudly about missing modules or resources. +- If you're using a compiled binary, and it can't find the libraries it depends + on, your dynamic linker will tell you about it. + +## 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. You should attempt to reinstall all the packages +listed in this step, using the `-f` flag for +[xbps-install(1)](https://man.voidlinux.org/xbps-install.1). For example: + +``` +# xbps-pkgdb -a +ERROR: p7zip: hash mismatch for /usr/bin/7z. +ERROR: p7zip: files check FAILED. +# xbps-install -f p7zip +``` + +After this is done, you should check if the issue persists. + +## 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 but that it expects to exist. + +## Debug the program NEEDS WORK + +If a look at `strace` wasn't enough, it is possible to use a debugger like +[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. +To use the Debuginfod server, you need to export the `DEBUGINFOD_URLS` +environment variable with a value of `https://debugingod.s.voidlinux.org` or +`https://debuginfod.elfutils.org/`. + +GDB is especially useful when an application crashes abnormally, since it will +stop execution at that point, and you can gather relevant information there. The +syntax for using `gdb` is shown below, including the Debuginfod variable: + +``` +$ DEBUGINFOD_URLS="https://debugingod.s.voidlinux.org" gdb --args [arguments] +``` + +Inside GDB, a usual session will run the following commands: + +- `run` to start the application; +- `set logging on`, to create a `gdb.txt` file which can be shared easily; +- `backtrace`, to show the function calls made until the application got to that + place; +- `quit`, to close `gdb`. From 63270997255e710d0c168882b33fd5ff3d80ef4b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89rico=20Rolim?= Date: Wed, 2 Dec 2020 03:14:24 -0300 Subject: [PATCH 3/3] contributing/index: add more information and debug.md. --- src/contributing/index.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/src/contributing/index.md b/src/contributing/index.md index 285e39f7d..add4a4974 100644 --- a/src/contributing/index.md +++ b/src/contributing/index.md @@ -2,13 +2,21 @@ There's more to running a distribution than just writing code. -To contribute to the Void packages repository, start by reading the +If you fix an issue with a package, the solution can be added to the official +package repository, and new packages and updates are also welcome! To contribute +to the Void packages repository, start by reading the [CONTRIBUTING](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md) document in the void-packages GitHub repository. -To contribute to this Handbook, read -[CONTRIBUTING](https://github.com/void-linux/void-docs/blob/master/CONTRIBUTING.md) -in the void-docs repository. +If you are unable to fix a package yourself, make sure to [open an +issue](https://github.com/void-linux/void-packages/issues/new) in the +void-packages repository. This gives the problem visibility, which can greatly +speed up a fix. Remember to check the existing issues for your problem! There +are also some [things you can do to assist in finding the problem](./debug.md). + +This Handbook doesn't (yet!) contain all the important Void-specific +information. To contribute to it see the [void-docs specific +page](./void-docs.md). If you have any questions, feel free to ask them via IRC in #voidlinux on irc.freenode.net, or in [the voidlinux