Debian Codegraph @

subprojects/meson-docs/docs/markdown/Creating-Linux-binaries.md

raw
1 ---
2 short-description: Creating universal Linux binaries
3 ...
4
5 # Creating Linux binaries
6
7 Creating Linux binaries that can be downloaded and run on any distro
8 (like .dmg packages for OSX or .exe installers for Windows) has
9 traditionally been difficult. This is even more tricky if you want to
10 use modern compilers and features, which is especially desired in game
11 development. There is still no simple turn-key solution for this
12 problem but with a bit of setup it can be relatively straightforward.
13
14 ## Installing system and GCC
15
16 First you need to do a fresh operating system install. You can use
17 spare hardware, VirtualBox, cloud or whatever you want. Note that the
18 distro you install must be *at least as old* as the oldest release you
19 wish to support. Debian stable is usually a good choice, though
20 immediately after its release you might want to use Debian oldstable
21 or the previous Ubuntu LTS. The oldest supported version of CentOS is
22 also a good choice.
23
24 Once you have installed the system, you need to install
25 build-dependencies for GCC. In Debian-based distros this can be done
26 with the following commands:
27
28 ```console
29 $ apt-get build-dep g++
30 $ apt-get install pkg-config libgmp-dev libmpfr-dev libmpc-dev
31 ```
32
33 Then create a `src` subdirectory in your home directory. Copy-paste
34 the following into `install_gcc.sh` and execute it.
35
36 ```bash
37 #!/bin/sh
38
39 wget ftp://ftp.fu-berlin.de/unix/languages/gcc/releases/gcc-4.9.2/gcc-4.9.2.tar.bz2
40 tar xf gcc-4.9.2.tar.bz2
41
42 mkdir objdir
43 cd objdir
44 ../gcc-4.9.2/configure --disable-bootstrap --prefix=${HOME}/devroot \
45 --disable-multilib --enable-languages=c,c++
46 make -j 4
47 make install-strip
48 ln -s gcc ${HOME}/devroot/bin/cc
49 ```
50
51 Then finally add the following lines to your `.bashrc`.
52
53 ```console
54 $ export LD_LIBRARY_PATH=${HOME}/devroot/lib
55 $ export PATH=${HOME}/devroot/bin:$PATH
56 $ export PKG_CONFIG_PATH=${HOME}/devroot/lib/pkgconfig
57 ```
58
59 Log out and back in and now your build environment is ready to use.
60
61 ## Adding other tools
62
63 Old distros might have too old versions of some tools. For Meson this
64 could include Python 3 and Ninja. If this is the case you need to
65 download, build and install new versions into `~/devroot` in the usual
66 way.
67
68 ## Adding dependencies
69
70 You want to embed and statically link every dependency you can
71 (especially C++ dependencies). Meson's [Wrap package
72 manager](Wrap-dependency-system-manual.md) might be of use here. This
73 is equivalent to what you would do on Windows, OSX, Android etc.
74 Sometimes static linking is not possible. In these cases you need to
75 copy the .so files inside your package. Let's use SDL2 as an example.
76 First we download and install it as usual giving it our custom install
77 prefix (that is, `./configure --prefix=${HOME}/devroot`). This makes
78 Meson's dependency detector pick it up automatically.
79
80 ## Building and installing
81
82 Building happens in much the same way as normally. There are just two
83 things to note. First, you must tell GCC to link the C++ standard
84 library statically. If you don't then your app is guaranteed to break
85 as different distros have binary-incompatible C++ libraries. The
86 second thing is that you need to point your install prefix to some
87 empty staging area. Here's the Meson command to do that:
88
89 ```console
90 $ LDFLAGS=-static-libstdc++ meson --prefix=/tmp/myapp <other args>
91 ```
92
93 The aim is to put the executable in `/tmp/myapp/bin` and shared
94 libraries to `/tmp/myapp/lib`. The next thing you need is the
95 embedder. It takes your dependencies (in this case only
96 `libSDL2-2.0.so.0`) and copies them in the lib directory. Depending on
97 your use case you can either copy the files by hand or write a script
98 that parses the output of `ldd binary_file`. Be sure not to copy
99 system libraries (`libc`, `libpthread`, `libm` etc). For an example,
100 see the [sample
101 project](https://github.com/jpakkane/meson/tree/master/manual%20tests/4%20standalone%20binaries).
102
103 Make the script run during install with this:
104
105 ```meson
106 [[#meson.add_install_script]]('linux_bundler.sh')
107 ```
108
109 ## Final steps
110
111 If you try to run the program now it will most likely fail to start or
112 crashes. The reason for this is that the system does not know that the
113 executable needs libraries from the `lib` directory. The solution for
114 this is a simple wrapper script. Create a script called `myapp.sh`
115 with the following content:
116
117 ```bash
118 #!/bin/bash
119
120 cd "${0%/*}"
121 export LD_LIBRARY_PATH="$(pwd)/lib"
122 bin/myapp
123 ```
124
125 Install it with this Meson snippet:
126
127 ```meson
128 [[#install_data]]('myapp.sh', install_dir : '.')
129 ```
130
131 And now you are done. Zip up your `/tmp/myapp` directory and you have
132 a working binary ready for deployment. To run the program, just unzip
133 the file and run `myapp.sh`.