|
1 | 1 | # Building Linux software into a prefix |
2 | 2 |
|
3 | | -If, instead of using a pre-made Game engine package like Unity, you prefer picking a few libraries here and there and mix them in your own way, you might reach a point where you want to build your own versions of those libraries, so that you may bundle them with your game. |
| 3 | +If, instead of using a pre-made game engine package like Unity, you prefer picking a few libraries and mixing them in your own way, you might reach a point where you want to build your own versions of those libraries so that you can bundle them with your game. |
4 | 4 |
|
5 | 5 | _See the _[_Distributing Linux builds_](../integrating/platforms/linux.md)_ page of this book_ |
6 | 6 |
|
7 | | -## autotools \(./configure && make\) |
8 | | - |
9 | | -The most common form under which open-source software is distributed is probably using autotools. |
| 7 | +## What is a prefix? |
10 | 8 |
|
11 | | -Their idea of a build process is in three steps: |
12 | | - |
13 | | -```bash |
14 | | -# gather information about the system, paths, dependencies |
15 | | -$ ./configure |
| 9 | +When you install software on Linux, files are placed into a directory hierarchy called the prefix. The default prefix is usually `/usr` or `/usr/local`, which means: |
16 | 10 |
|
17 | | -# compile and link binary objects |
18 | | -$ make |
19 | | - |
20 | | -# copy production files to the prefix |
21 | | -$ sudo make install |
22 | | -``` |
23 | | - |
24 | | -The default prefix is usually `/usr`, or `/usr/local`, which means: |
25 | | - |
26 | | -* Binaries are installed in `/usr/bin/` \(or `/usr/local/bin`\) |
| 11 | +* Binaries are installed in `/usr/bin/` |
27 | 12 | * Libraries are installed in `/usr/lib/` |
28 | | -* Data files are installed in `/usr/share` |
| 13 | +* Data files are installed in `/usr/share/` |
29 | 14 | * ...and so on |
30 | 15 |
|
31 | | -The only reason `sudo` is required for the install step is because the default prefix is a system-wide directory that can only be written to by privileged users \(like root\). |
| 16 | +By specifying your own prefix, you can install a library into an unprivileged, user-owned directory, ready for bundling with your game. Building each library into its own prefix makes it clear which files belong to which library. |
| 17 | + |
| 18 | +For the purpose of [bundling your libraries](../integrating/platforms/linux.md), you would copy the files from your prefix's `lib/` directory into your game's bundled library folder. |
32 | 19 |
|
33 | | -However, you can simply specify your own prefix, so that the built library is installed into an unprivileged, user-owned directory, ready for bundling with your games. |
| 20 | +## CMake |
34 | 21 |
|
35 | | -With autotools, you can specify the prefix in the configure phase, with the `--prefix` flag: |
| 22 | +CMake is the most common build system for open-source C/C++ libraries. The recommended build process uses an out-of-tree build directory: |
36 | 23 |
|
37 | 24 | ```bash |
38 | | -$ ./configure --prefix=$HOME/myprefix/sdl2 |
39 | | - |
40 | | -# and then, make && make install, as usual |
| 25 | +$ cmake -B build -DCMAKE_INSTALL_PREFIX=$HOME/myprefix/chipmunk2d |
| 26 | +$ cmake --build build |
| 27 | +$ cmake --install build |
41 | 28 | ``` |
42 | 29 |
|
43 | | -_Note: _`--prefix`_ usually has to be an absolute path._ |
44 | | - |
45 | | -Building each library in its own prefix is a good habit: it makes it immediately cleary which files belong to which library. |
| 30 | +## Meson |
46 | 31 |
|
47 | | -For the purpose of [bundling your libraries](../integrating/platforms/linux.md), in this example, one would copy all files in `$HOME/myprefix/sdl2/lib/` to their bundled library folder. |
| 32 | +[Meson](https://mesonbuild.com/) is used by many Linux libraries, particularly in the freedesktop/GNOME ecosystem. It always uses out-of-tree builds: |
48 | 33 |
|
49 | | -## CMake |
| 34 | +```bash |
| 35 | +$ meson setup build --prefix=$HOME/myprefix/my-library |
| 36 | +$ meson compile -C build |
| 37 | +$ meson install -C build |
| 38 | +``` |
50 | 39 |
|
51 | | -_This section assumes that you have read the _`autotools`_ section above, which contains some fundamentals about prefixes and how software is built on Linux._ |
| 40 | +## autotools \(./configure && make\) |
52 | 41 |
|
53 | | -The usual CMake build process goes like this: |
| 42 | +Some older libraries still use autotools. The build process is: |
54 | 43 |
|
55 | | -``` |
56 | | -$ cmake . |
| 44 | +```bash |
| 45 | +$ ./configure --prefix=$HOME/myprefix/sdl2 |
57 | 46 | $ make |
58 | 47 | $ make install |
59 | 48 | ``` |
60 | 49 |
|
61 | | -You can specify the installation prefix by setting the [`CMAKE_INSTALL_PREFIX`](https://cmake.org/cmake/help/v3.0/variable/CMAKE_INSTALL_PREFIX.html) variable: |
62 | | - |
63 | | -``` |
64 | | -$ cmake . -DCMAKE_INSTALL_PREFIX=$HOME/myprefix/chipmunk2d |
65 | | -``` |
66 | | - |
67 | | -## Appendix to the appendix 1: Why build your own software? |
68 | | - |
69 | | -There are many good reasons to build your own software. First of all, because running someone else's binary is a security risk — it can get very hard to tell what a binary is going to actually do just by looking at it, and monitoring it isn't entirely failsafe either. |
70 | | - |
71 | | -In an ideal world, everybody would: |
72 | | - |
73 | | -* Read the entire source code of all the software they use |
74 | | -* Compile their own version of it |
75 | | - |
76 | | -_Note: this would assume they're also able to read and comprehend their compiler's source code, to prevent attacks like the _[_Ken Thompson Hack \(1984\)_](http://programmers.stackexchange.com/questions/184874/is-ken-thompsons-compiler-hack-still-a-threat) |
77 | | - |
78 | | -Since most people have barely enough patience to learn how to properly use well-packaged software, this is impractical, so what the world does instead is download packaged software from sources they trust, like their Linux distribution official repositories. |
79 | | - |
80 | | -This is part of the reason why maintaining a Linux distribution is so much work: package maintainers have to work around the clock to maintain a strict set of rules, audit packages for potential security problems, and apply both security and compatibility patches in a timely manner. |
81 | | - |
82 | | -As a result, some packaged versions of certain software ends up diverging significantly from the original \(`upstream`\) version, for example because of the security policy of a certain Linux distribution, or its filesystem hierarchy, that differs slightly from the expectations of the software's author. |
83 | | - |
84 | | -For these reasons, copying libraries straight out of `/usr/lib` and into your game's bundle is not always the best of ideas, since they may rely on a particular behavior that other distributions do not adhere to. |
85 | | - |
86 | | -There is another compelling reason to build your own version of software: on occasion, you may find a bug in the libraries you use. Sometimes, with a little luck and lot of persistence, you'll find what causes it before the maintainer, you might even have a _works-for-me_ solution that you really need to ship your game, but the maintainer doesn't want to merge right now \(for valid reasons\). |
87 | | - |
88 | | -If you build your own libraries, you can simply make and distribute the change yourself, not having to wait for the maintainer and packagers to catch up with you. This flexibility doesn't exist in the closed-source, 'all-in-one' world. |
89 | | - |
90 | | -## Appendix to the appendix 2: Out-of-tree builds |
91 | | - |
92 | | -Both autotools and CMake allow \(when configured correctly\) out-of-tree builds. What does that mean? When building, we have three kinds of assets: |
93 | | - |
94 | | -* Source files \(downloaded and unpacked\) |
95 | | -* Temporary files \(binary objects, etc. not yet linked or stripped\) |
96 | | -* Distribution files \(executables, libraries\) |
97 | | - |
98 | | -When running the `./configure && make && make install` steps every other guide recommends, source files and temporary files live in the same folder. Temporary files can sometimes be removed with `make clean`, `make distclean` or `make mrproper`, but not always. |
99 | | - |
100 | | -The cleanest way to separate those is to build libraries in a separate directory, like so: |
| 50 | +_Note: _`--prefix`_ usually has to be an absolute path._ |
101 | 51 |
|
102 | | -``` |
103 | | -$ mkdir my-library-build |
104 | | -$ ls |
105 | | -my-library-source |
106 | | -my-library-build |
| 52 | +For a cleaner setup, you can do an out-of-tree build by running configure from a separate directory: |
107 | 53 |
|
108 | | -$ cd my-library-build |
| 54 | +```bash |
| 55 | +$ mkdir build && cd build |
109 | 56 | $ ../my-library-source/configure --prefix=$HOME/myprefix/my-library |
110 | 57 | $ make |
111 | 58 | $ make install |
112 | 59 | ``` |
113 | 60 |
|
114 | | -With this method, the `my-library-source` folder isn't touched at all. |
115 | | - |
116 | | -CMake allows doing the same: |
117 | | - |
118 | | -``` |
119 | | -$ mkdir my-library-build |
120 | | -$ ls |
121 | | -my-library-source |
122 | | -my-library-build |
123 | | -
|
124 | | -$ cd my-library-build |
125 | | -$ cmake ../my-library-source -DCMAKE_INSTALL_PREFIX=$HOME/myprefix/my-library |
126 | | -$ make |
127 | | -$ make install |
128 | | -``` |
| 61 | +This keeps the source directory untouched. |
129 | 62 |
|
130 | | -_Caveat: like every setting ever, some libraries will sometimes support one but not the other, or the other way around. Some autotools-based libraries will assume you're building in-tree and will fail to find some files otherwise, |
131 | | -whereas some CMake-based libraries will require you to do an out-of-tree build to prevent overwriting files._ |
| 63 | +## Why build your own libraries? |
132 | 64 |
|
133 | | -_Like every situation ever, the correct course of action is to apply patience and forgiveness, because software is hard._ |
| 65 | +Copying libraries straight out of `/usr/lib` and into your game's bundle is not always the best idea. Distribution-packaged libraries may have patches or configuration specific to that distribution that cause them to behave differently elsewhere. |
134 | 66 |
|
| 67 | +Building from source also gives you flexibility: if you find a bug in a library you depend on, you can apply a fix and ship it yourself without waiting for the upstream maintainer and distribution packagers to catch up. |
0 commit comments