1## Linux portable binary release 2 3This tutorial is based on information collected from those two sources: 4 5* http://freegamedev.net/wiki/Portable_binaries 6* http://www.cmake.org/Wiki/CMake_RPATH_handling 7 8There are several ways to provide portable binaries for Linux-based operating 9systems. Here we chose to bundle the shared libraries needed by OpenDungeons 10in the tree, using a relative library path (RPATH) set to $ORIGIN/lib (i.e. a 11./lib subdirectory next to the main binary). 12Some core shared libraries must not be bundled however, such as glibc, gcc, 13GL, pthread, ld, etc. 14 15An important factor when building portable binaries is that the system glibc 16must be at least as old as the one of the oldest distribution that we want to 17support. In other words, we can expect glibc to be forwards-compatible but not 18backwards-compatible, so a binary built against e.g. glibc 2.20 will probably 19not run on a system with glibc 2.17. 20 21For OpenDungeons 0.4.9, we built the binaries under Mageia 3 with glibc 2.17. 22This was not the oldest release available at that time (Debian Wheezy had 23glibc 2.13), but it had the advantage of being old enough for most users and 24recent enough to build OD's dependencies without trouble. OD is also still in 25alpha, so we don't have to make sure that the portable binaries will run on 26any system now and in the coming 10 years. 27 28### Preparing the build environment 29 30You will first need to install the chosen "old" release, either on a real 31partition, in a virtual machine or in a chroot. To install a Mageia chroot 32using urpmi on a Mageia system, see: https://wiki.mageia.org/en/Chroot 33 34Then, build and install those core OD dependencies: 35 36* OGRE >= 1.9.0 37* OIS >= 1.3 38* SFML >= 2.1 39* CEGUI >= 0.8.0 (make sure to build and install OGRE and OIS before building 40CEGUI) 41 42Depending on the chosen target system, some additional dependencies might be 43needed to build the OD dependencies. 44It might also be needed to build a recent version of boost locally if the 45system's boost is not compatible with OGRE. Boost 1.53.0 from Mageia 3 was 46sufficient for OD 0.4.9. 47 48### Building the portable binary release 49 50In short: run the script located in dist/portable: 51 52 * ```build-portable-binary.sh``` 53 54Note that the scripts must be run from the root of the source directory (i.e. 55the directory that holds the source folder and various data folders). The 56first script can be run with arguments which are passed directly to the CMake 57call. 58 59The following sections give explanations about the steps performed in the 60script. 61 62#### 1. Building OpenDungeons with a RPATH 63 64This is done by setting the install RPATH to $ORIGIN/lib{32,64} (with the $ 65properly escaped in the CMake call) using the CMAKE_INSTALL_RPATH variable. 66Since we won't use ```make install``` to generate the portable archive, we 67also tell CMake to use the install RPATH even for the output of the build 68step (if not, it only writes the RPATH when installing the binary). In the 69end, we initialise the OD build with: 70 71``` 72cmake -DCMAKE_SKIP_BUILD_RPATH=FALSE \ 73 -DCMAKE_BUILD_WITH_INSTALL_RPATH=TRUE \ 74 -DCMAKE_INSTALL_RPATH="\$ORIGIN/lib$archsuffix" 75``` 76 77Since we don't use the install step, we must also strip the binary from the 78debug symbols ourselves. 79 80#### 2. Bundling the needed shared libraries 81 82We can list the libraries needed by the OD binary using ```ldd```. The given 83list gives references formatted this way: 84 85``` 86libOgreMain.so.1.9.0 => /lib64/libOgreMain.so.1.9.0 (0x00007f2d122b4000) 87libboost_system.so.1.55.0 => /lib64/libboost_system.so.1.55.0 88(0x00007f2d120b0000) 89``` 90 91Therefore we process the third word of these lines to get the path to the 92library, and copy it in the ./lib{32,64} directory that we set as the RPATH. 93 94Before that, we remove all libraries that we do not want to bundle using sed. 95The NOBUNDLE string in the 2nd script lists those variables. It might have to 96be adapted if we notice that some core libraries at the system still get 97bundled, or if some non-bundled libraries would actually be necessary. 98 99The script also handles bundling the OGRE and CEGUI plugins that are needed to 100run OD. This part might need editing if we start using different plugins in 101future releases. 102 103#### 3. Creating the portable binary tarball 104 105After step 2., the portable binary is ready, we just have to clean up the 106stuff that players do not need (source code, CMake scripts, build directory, 107etc.) and (optionally) put everything in a neat bzip-compressed tarball. 108 109The tarball can be made for one arch (thus containing the arch in the dirname, 110like "Linux32" or "Linux64") or for both arches (thus being simply named 111"Linux"). 112