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