Debian Codegraph @

subprojects/meson-docs/docs/markdown/Creating-OSX-packages.md

raw
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.