Skip to content

Commit

Permalink
docs: Add Troubleshooting page
Browse files Browse the repository at this point in the history
  • Loading branch information
JonathonReinhart committed Nov 26, 2021
1 parent 0bf64c7 commit 4c3d7c6
Show file tree
Hide file tree
Showing 2 changed files with 46 additions and 0 deletions.
1 change: 1 addition & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -11,4 +11,5 @@ anywhere, just like a static executable.
introduction
installation
usage
troubleshooting
changelog
45 changes: 45 additions & 0 deletions docs/troubleshooting.rst
Original file line number Diff line number Diff line change
@@ -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 <https://sourceware.org/gdb/onlinedocs/gdb/Forks.html>`_.

To get a backtrace::

$ gdb --args ./myprog.sx
set follow-fork-mode child
r
(segfault)
bt -full

0 comments on commit 4c3d7c6

Please sign in to comment.