diff --git a/docs/index.rst b/docs/index.rst index a43e811..f43435e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,4 +11,5 @@ anywhere, just like a static executable. introduction installation usage + troubleshooting changelog diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst new file mode 100644 index 0000000..c6a3fe3 --- /dev/null +++ b/docs/troubleshooting.rst @@ -0,0 +1,45 @@ +Troubleshooting +=============== + +StaticX has to do some weird things in order to work. Thus, you might run into +trouble. + +Run-time problems +----------------- +If, after bundling an application using StaticX, the resulting executable is +crashing due to symbol issues or segfaults: + +Debug build +~~~~~~~~~~~ +The first step is to use the ``--debug`` flag when bundling:: + + $ staticx --debug myprog myprog.sx + +This option will: + +- Set loglevel to ``DEBUG`` while building the program +- Use a debug variant of the bootloader which: + + - Adds debug output (to stderr) + - Includes DWARF debug info + +.. note:: + + Please include all debugging information if you open an issue. + + +GDB +~~~ +If your program segfaults, you can run it under GDB. + +Before giving the ``r`` command to run your program, use +``set follow-fork-mode child`` so GDB +`follows the child process `_. + +To get a backtrace:: + + $ gdb --args ./myprog.sx + set follow-fork-mode child + r + (segfault) + bt -full