diff --git a/README.md b/README.md index 0a712d1..c3c1721 100644 --- a/README.md +++ b/README.md @@ -343,3 +343,52 @@ following GDB command to cover the preemption signal(s) affecting your task's ex ``` (gdb) handle SIGALRM nopass ``` + + +Troubleshooting +--------------- +**My distribution ships a version of glibc that is newer than 2.33. What should I do?** + +Such versions are untested. If you do not encounter any obvious issues, great! Otherwise, no need +to modify your installation; instead, just follow the steps under _Building glibc from source_ above +to build version 2.33. When linking your executable, you will want to use GCC's `-Wl,-I` switch +(`-Clink-arg=-Wl,-I` in the case of rustc) to specify the newly-symlinked dynamic linker as the +program's interpreter. If you are building the program using Cargo and its source is located in +tree or you have symlinked its `.cargo` to this repository's folder of the same name, passing the +flag should happen automatically. Note that, if you get any version errors when running the +resulting binary, you may need to add a further `-L` and the path to the `lib` directory generated +by the glibc `install` target to your linker flags and rebuild. + +**My distribution ships a version of elfutils that is newer than 0.176. What should I do?** + +It probably does! The easiest thing to do is to downgrade the package. For instance, if using +Debian, download (at least) the following binary packages from https://snapshot.debian.org: +`libasm1`, `libasm-dev`, `libdw1`, `libelf1`, and `libelf-dev`. Put the packages into a new +directory, `cd` into it, and run `apt -s install ./*.deb`. If it shows any dependency errors, +download additional packages to address them and add them to the directory; you will probably need +`gdb` version 9.2-1, `libpython3.8`, `libpython3.8-minimal`, and `libpython3.8-stdlib`. Then +perform the downgrade by running `sudo apt install ./*.deb`. + +**I get the assertion: `ELF64_ST_TYPE(st->st_info) != STT_GNU_IFUNC)`!** + +This appears to occur on some Ubuntu systems because of the way Canonical packages zlib (`libz.so`). +The easiest workaround is to grab a closely matching package version from +https://packages.debian.org and extract the shared library file. Then either export the +`$LD_LIBRARY_PATH` environment variable to the path to its containing folder when executing your +application, or just place the shared library in the `lib` directory generated by glibc's `install` +target if/when you built it from source. + +**I get some other error at some point.** + +Start by rerunning `./configure` to clean the build. Make sure it finds all the dependencies. Look +back at _System requirements_ and verify that you are not on a `cargo` version affected by the +regression, and that you have the described wrapper script in your `$PATH` if you have a +sufficiently new version of `bindgen` (a shell alias will not suffice). + +Next, try building _libgotcha_ in isolation. Just `cd` into `external/libgotcha` and type `make` +(without passing `-j`). If you get errors here, go back to the previous paragraph, pinch yourself, +and check all that one more time. + +If you get this far, try building _libinger_ without per--preemptive function thread-local variables +by passing `--features notls` to your Cargo command. If you are still stuck, see whether you can +trace the source of the error using any of the techniques under _Debugging tips_ above.