diff --git a/CHANGELOG.md b/CHANGELOG.md index b502d2b..c46a3d8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Change Log All notable changes to this project will be documented in this file. -This project adheres to [Semantic Versioning](http://semver.org/). +This project adheres to [Semantic Versioning](https://semver.org/). ## [Unreleased] ### Changed diff --git a/docs/Makefile b/docs/Makefile index d4bb2cb..2b19293 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -18,3 +18,11 @@ help: # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + + +# Check external links +LINKCHECKDIR = $(BUILDDIR)/linkcheck + +.PHONY: checklinks +checklinks: + $(SPHINXBUILD) -b linkcheck $(SPHINXOPTS) "$(SOURCEDIR)" "$(LINKCHECKDIR)" diff --git a/docs/index.rst b/docs/index.rst index a43e811..882fa3a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,4 +11,6 @@ anywhere, just like a static executable. introduction installation usage + troubleshooting + rpath changelog diff --git a/docs/installation.rst b/docs/installation.rst index 240597e..c5d030b 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -49,5 +49,5 @@ Or:: BOOTLOADER_CC=/usr/local/musl/bin/musl-gcc pip3 install . -.. _PyPI: https://pypi.python.org/pypi/staticx +.. _PyPI: https://pypi.org/project/staticx/ .. _musl libc: https://www.musl-libc.org/ diff --git a/docs/rpath.rst b/docs/rpath.rst new file mode 100644 index 0000000..385af18 --- /dev/null +++ b/docs/rpath.rst @@ -0,0 +1,81 @@ +Unsupported ``RPATH``/``RUNPATH`` +================================= + +You might be here because you encountered an error like this:: + + staticx: Unsupported PyInstaller input + + One or more libraries included in the PyInstaller archive uses unsupported RPATH/RUNPATH tags: + + /tmp/staticx-pyi-5ys8gizg/libbar.so: DT_RUNPATH='/bogus/absolute/path' + /tmp/staticx-pyi-5ys8gizg/libfoo.so: DT_RUNPATH='/bogus/absolute/path' + +This page will attempt to explain the problem. + + +What are ``RPATH`` / ``RUNPATH``? +--------------------------------- +``RPATH`` and ``RUNPATH`` are a feature of the GNU dynamic linker/loader. These +are entries in the ``.dynamic`` section which allow a dynamic executable or +library to augment or override the preconfigured library path list of the +dynamic loader (``ld.so``). + +See also: `RPATH on Wikipedia `_ + + +Why are ``RPATH`` / ``RUNPATH`` problematic? +-------------------------------------------- +These options can circumvent StaticX's ability to maintain positive control of +the library search path used by ``ld.so``. By doing so, they can allow +target-system libraries to be undesirably loaded, possibly causing symbol +errors or runtime crashes. After all, StaticX's *modus operandi* is to only +execute code included in the bundled archive. + +Since StaticX works by setting ``RPATH`` on the bundled user executable, there +is no need for any of the bundled libraries to use ``RPATH``/``RUNPATH``. +Because of this, StaticX will *strip* ``RPATH``/``RUNPATH`` entries from any +library added to the archive. However, StaticX **cannot** modify libraries +which are already included in the archive of a PyInstaller application. + +``RPATH`` +~~~~~~~~~ +``RPATH`` is allowed in PyInstaller-included libraries as long as the path is +relative to ``$ORIGIN`` (the directory where the dynamic executable lives). + +If StaticX is complaining about ``RPATH``, it is probably because the library +is referencing an absolute path (e.g. ``/usr/local/lib``). + +``RUNPATH`` +~~~~~~~~~~~ +``RUNPATH`` is even more problematic, because it causes ``ld.so`` to +**completely disregard** the ``RPATH`` set by the StaticX bootloader at program +launch. For this reason, ``RUNPATH`` is always forbidden. + +Unfortunately, this problem is becoming more common since GNU ``ld`` now +defaults to emitting ``RUNPATH`` when the ``-rpath`` option is given. + + +So what do I do now? +-------------------- +Unfortunately, fixing a problematic PyInstaller-generated executable is not +straightforward. The goal is to remove the problematic libraries or replace +them with builds which do not use ``RUNPATH``. (A build which uses ``RPATH`` +is probably acceptable, see above.) + +One can sometimes fix this problem by adding ``--disable-new-dtags`` to +``CFLAGS`` when building/installing a Python package which uses native +extensions. The best way to do this is to install them from source into a +virtual environment. + + + +References +---------- + +* The underlying issue was originally described in `#169`_. +* The auditing check which emits this error was added in `#173`_, + and updated in `#208`_. + +.. _#169: https://github.com/JonathonReinhart/staticx/issues/169 +.. _#173: https://github.com/JonathonReinhart/staticx/pull/173 +.. _#208: https://github.com/JonathonReinhart/staticx/pull/208 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 diff --git a/docs/usage.rst b/docs/usage.rst index b153492..52b9381 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -29,6 +29,9 @@ Options: Options: DEBUG,INFO,WARNING,ERROR,CRITICAL + --debug Set loglevel to DEBUG and use a debug version of the + bootloader + -V, --version Show StaticX version and exit