| 1 |
--- |
| 2 |
short-description: Tools to create OS X packages |
| 3 |
... |
| 4 |
|
| 5 |
# Creating OSX packages |
| 6 |
|
| 7 |
Meson does not have native support for building OSX packages but it |
| 8 |
does provide all the tools you need to create one yourself. The reason |
| 9 |
for this is that it is a very hard task to write a system that |
| 10 |
provides for all the different ways to do that but it is very easy to |
| 11 |
write simple scripts for each application. |
| 12 |
|
| 13 |
Sample code for this can be found in [the Meson manual test |
| 14 |
suite](https://github.com/jpakkane/meson/tree/master/manual%20tests/4%20standalone%20binaries). |
| 15 |
|
| 16 |
## Creating an app bundle |
| 17 |
|
| 18 |
OSX app bundles are actually extremely simple. They are just a |
| 19 |
directory of files in a certain format. All the details you need to |
| 20 |
know are on [this |
| 21 |
page](https://stackoverflow.com/questions/1596945/building-osx-app-bundle) |
| 22 |
and it is highly recommended that you read it first. |
| 23 |
|
| 24 |
Let's assume that we are creating our app bundle into |
| 25 |
`/tmp/myapp.app`. Suppose we have one executable, so we need to |
| 26 |
install that into `Contents/MacOS`. If we define the executable like |
| 27 |
this: |
| 28 |
|
| 29 |
```meson |
| 30 |
executable('myapp', 'foo1.c', ..., install : true) |
| 31 |
``` |
| 32 |
|
| 33 |
then we just need to initialize our build tree with this command: |
| 34 |
|
| 35 |
```console |
| 36 |
$ meson --prefix=/tmp/myapp.app \ |
| 37 |
--bindir=Contents/MacOS \ |
| 38 |
builddir \ |
| 39 |
<other flags you might need> |
| 40 |
``` |
| 41 |
|
| 42 |
Now when we do `meson install` the bundle is properly staged. If you |
| 43 |
have any resource files or data, you need to install them into |
| 44 |
`Contents/Resources` either by custom install commands or specifying |
| 45 |
more install paths to the Meson command. |
| 46 |
|
| 47 |
Next we need to install an `Info.plist` file and an icon. For those we |
| 48 |
need the following two Meson definitions. |
| 49 |
|
| 50 |
```meson |
| 51 |
install_data('myapp.icns', install_dir : 'Contents/Resources') |
| 52 |
install_data('Info.plist', install_dir : 'Contents') |
| 53 |
``` |
| 54 |
|
| 55 |
The format of `Info.plist` can be found in the link or the sample |
| 56 |
project linked above. The simplest way to get an icon in the `icns` |
| 57 |
format is to save your image as a tiff an then use the `tiff2icns` helper |
| 58 |
application that comes with XCode. |
| 59 |
|
| 60 |
Some applications assume that the working directory of the app process |
| 61 |
is the same where the binary executable is. If this is the case for |
| 62 |
you, then you need to create a wrapper script that looks like this: |
| 63 |
|
| 64 |
```bash |
| 65 |
#!/bin/bash |
| 66 |
|
| 67 |
cd "${0%/*}" |
| 68 |
./myapp |
| 69 |
``` |
| 70 |
|
| 71 |
install it with this: |
| 72 |
|
| 73 |
```meson |
| 74 |
install_data('myapp.sh', install_dir : 'Contents/MacOS') |
| 75 |
``` |
| 76 |
|
| 77 |
and make sure that you specify `myapp.sh` as the executable to run in |
| 78 |
your `Info.plist`. |
| 79 |
|
| 80 |
If you are not using any external libraries, this is all you need to |
| 81 |
do. You now have a full app bundle in `/tmp/myapp.app` that you can |
| 82 |
use. |
| 83 |
|
| 84 |
### External libraries |
| 85 |
|
| 86 |
Most applications use third party frameworks and libraries. |
| 87 |
If it is the case for your project, you need to add them to |
| 88 |
the bundle so it will work on other peoples' machines. |
| 89 |
|
| 90 |
As an example we are going to use the [SDL2](https://libsdl.org/) |
| 91 |
framework. In order to bundle it in our app, we first specify an |
| 92 |
installer script to run. |
| 93 |
|
| 94 |
```meson |
| 95 |
[[#meson.add_install_script]]('install_script.sh') |
| 96 |
``` |
| 97 |
|
| 98 |
The install script does two things. First it copies the whole |
| 99 |
framework into our bundle. |
| 100 |
|
| 101 |
```console |
| 102 |
$ mkdir -p ${MESON_INSTALL_PREFIX}/Contents/Frameworks |
| 103 |
$ cp -R /Library/Frameworks/SDL2.framework \ |
| 104 |
${MESON_INSTALL_PREFIX}/Contents/Frameworks |
| 105 |
``` |
| 106 |
|
| 107 |
Then it needs to alter the library search path of our |
| 108 |
executable(s). This tells OSX that the libraries your app needs are |
| 109 |
inside your bundle. In the case of SDL2, the invocation goes like |
| 110 |
this: |
| 111 |
|
| 112 |
```console |
| 113 |
$ install_name_tool -change @rpath/SDL2.framework/Versions/A/SDL2 \ |
| 114 |
@executable_path/../FrameWorks/SDL2.framework/Versions/A/SDL2 \ |
| 115 |
${MESON_INSTALL_PREFIX}/Contents/MacOS/myapp |
| 116 |
``` |
| 117 |
|
| 118 |
This is the part of OSX app bundling that you must always do |
| 119 |
manually. OSX dependencies come in many shapes and forms and |
| 120 |
unfortunately there is no reliable automatic way to determine how each |
| 121 |
dependency should be handled. Frameworks go to the `Frameworks` |
| 122 |
directory while plain `.dylib` files usually go to |
| 123 |
`Contents/Resources/lib` (but you can put them wherever you like). To |
| 124 |
get this done you have to check what your program links against with |
| 125 |
`otool -L /path/to/binary` and manually add the copy and fix steps to |
| 126 |
your install script. Do not copy system libraries inside your bundle, |
| 127 |
though. |
| 128 |
|
| 129 |
After this you have a fully working, self-contained OSX app bundle |
| 130 |
ready for distribution. |
| 131 |
|
| 132 |
#### Qt |
| 133 |
|
| 134 |
Qt offers a [deployment tool](https://doc.qt.io/qt-5/macos-deployment.html#macdeploy), |
| 135 |
called `macdeployqt`, that automates bundling Qt's libraries in your application folder and |
| 136 |
optionally create the final `.dmg` installer |
| 137 |
|
| 138 |
```console |
| 139 |
# cd into the folder that contains the `myapp.app` folder |
| 140 |
macdeployqt myapp.app -executable=myapp.app/Contents/MacOS/myapp |
| 141 |
``` |
| 142 |
|
| 143 |
This copies the needed Qt libraries to the correct subfolders within `myapp.app`. |
| 144 |
The `-executable=myapp.app/Contents/MacOS/myapp` argument is |
| 145 |
to automatically alter the search path of the executable |
| 146 |
`myapp.app/Contents/MacOS/myapp` for the Qt libraries. One can also pass the `-dmg` |
| 147 |
argument to create a `.dmg` installer from the updated `myapp.app` folder. |
| 148 |
More information is available on the tool's documentation page. |
| 149 |
|
| 150 |
## Creating a .dmg installer |
| 151 |
|
| 152 |
A .dmg installer is similarly quite simple, at its core it is |
| 153 |
basically a fancy compressed archive. A good description can be found |
| 154 |
on [this page](https://el-tramo.be/guides/fancy-dmg/). Please read it |
| 155 |
and create a template image file according to its instructions. |
| 156 |
|
| 157 |
The actual process of creating the installer is very simple: you mount |
| 158 |
the template image, copy your app bundle in it, unmount it and convert |
| 159 |
the image into a compressed archive. The actual commands to do this |
| 160 |
are not particularly interesting, feel free to steal them from either |
| 161 |
the linked page above or from the sample script in Meson's test suite. |
| 162 |
|
| 163 |
## Putting it all together |
| 164 |
|
| 165 |
There are many ways to put the .dmg installer together and different |
| 166 |
people will do it in different ways. The linked sample code does it by |
| 167 |
having two different scripts. This separates the different pieces |
| 168 |
generating the installer into logical pieces. |
| 169 |
|
| 170 |
`install_script.sh` only deals with embedding dependencies and fixing |
| 171 |
the library paths. |
| 172 |
|
| 173 |
`build_osx_installer.sh` sets up the build with the proper paths, |
| 174 |
compiles, installs and generates the .dmg package. |
| 175 |
|
| 176 |
The main reasoning here is that in order to build a complete OSX |
| 177 |
installer package from source, all you need to do is to cd into the |
| 178 |
source tree and run `./build_osx_installer.sh`. To build packages on |
| 179 |
other platforms you would write scripts such as |
| 180 |
`build_windows_installer.bat` and so on. |