1  # The problem
 2  
 3  Some projects require newer C++ standards to build them. To keep the glibc
 4  dependency low you can build a newer GCC version on an older distro and use it
 5  to compile the project. This project however will now require a newer version of
 6  the `libstdc++.so.6` library than available on that distro.
 7  Blindly bundling `libstdc++.so.6` however will in most cases break compatibility
 8  with distros that have a newer library version installed into their system than
 9  the bundled one.
10  
11  By the way, while this is primarily an issue with `libstdc++.so.6` in some cases
12  this might also occur with `libgcc_s.so.1`. That's because both libraries are
13  part of GCC.
14  
15  
16  # The solution
17  
18  You would have to know the library version of the host system and decide whether
19  to use a bundled library or not before the application is started. This is
20  exactly what the `checkrt` tool does. It will search for a bundled `libstdc++.so.6`
21  and `libgcc_s.so.1` library inside sub-directories next to it. If found it will
22  compare their internal versions with the ones found on the system and return a
23  path that can be prepended to `LD_LIBRARY_PATH`.
24  
25  
26  # Usage
27  
28  Compile by running `make` inside the `src` directory.
29  Inside your AppDir create the directory `usr/optional/`
30  and put the binary `checkrt` inside there. Execute `usr/optional/checkrt --copy-libraries`
31  to bundle your system's `libstdc++.so.6` and `libgcc_s.so.1` libraries.
32  Use the provided AppRun script or write/modify your own. `checkrt` will either
33  return a path that can be added to `LD_LIBRARY_PATH` or an empty string.
34  Error messages, help and verbosity will always be returned to stderr.
35  
36  
37  # exec.so
38  
39  You might also want to bundle `exec.so` inside `usr/optional/`. This library is
40  intended to restore the environment of the AppImage to its parent. This is done
41  to avoid library clashing of bundled libraries with external processes, e.g. when
42  running the web browser.
43  
44  The intended usage is as follows:
45  
46  1. This library is injected to the dynamic loader through LD_PRELOAD
47     automatically in AppRun **only** if `usr/optional/exec.so` exists: 
48     e.g `LD_PRELOAD=$APPDIR/usr/optional/exec.so My.AppImage`
49  
50  2. This library will intercept calls to new processes and will detect whether
51     those calls are for binaries within the AppImage bundle or external ones.
52  
53  3. In case it's an internal process, it will not change anything.
54     In case it's an external process, it will restore the environment of
55     the AppImage parent by reading `/proc/[pid]/environ`.
56     This is the conservative approach taken.
57