3 This page explains how to deploy GStreamer along your application. There
4 are different mechanisms, which have been reviewed in [](deploying-your-application.md). The details for some
5 of the mechanisms are given here, and more options might be added to
6 this documentation in the future.
8 **FIXME: PackageMaker is dead we need a new solution **
12 This is the easiest way to deploy GStreamer, although most of the time
13 it installs unnecessary files which grow the size of the installer and
14 the target drive free space requirements. Since GStreamer might be shared
15 among all applications that use it, though, the extra space requirements
18 With PackageMaker, simply add GStreamer **runtime ** disk image
19 ([the same one you used to install the runtime in your development
20 machine](installing-on-mac-osx.md)) inside your installer
21 package and create a post-install script that mounts the disk image and
22 installs GStreamer package. You can use the following example, where you
23 should replace `$INSTALL_PATH` with the path where your installer copied
24 GStreamer's disk image files (the `/tmp` directory is good place to
25 install it as it will be removed at the end of the installation):
28 hdiutil attach $INSTALL_PATH/gstreamer-1.0-1.8.1-x86_64-packages.dmg
29 cd /Volumes/gstreamer-1.0-1.8.1-x86_64/
30 installer -pkg gstreamer-1.0-1.8.1-x86_64.pkg -target "/"
31 hdiutil detach /Volumes/gstreamer-1.0-1.8.1-x86_64/
32 rm $INSTALL_PATH/gstreamer-1.0-1.8.1-x86_64-packages.dmg
35 ## Private deployment of GStreamer
37 You can decide to distribute a private copy of GStreamer with your
38 application, although it's not the recommended method. In this case,
39 simply copy the framework to the application's Frameworks folder as
40 defined in the [bundle programming
41 guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/BundleTypes/BundleTypes.html#//apple_ref/doc/uid/10000123i-CH101-SW19):
44 cp -r /Library/Frameworks/GStreamer.framework ~/MyApp.app/Contents/Frameworks
47 Note that you can have several versions of GStreamer, and targeting
48 different architectures, installed in the system. Make sure you only
49 copy the version you need and that you update accordingly the link
50 `GStreamer.framework/Version/Current`:
53 $ ls -l Frameworks/GStreamer.framework/Version/Current
54 lrwxr-xr-x 1 fluendo staff 21 Jun 5 18:46 Frameworks/GStreamer.framework/Versions/Current -> ../Versions/0.10/x86
57 Since GStreamer will be relocated, you will need to follow the
58 instructions on how to relocate GStreamer at the end of this page.
60 ## Deploy only necessary files, by manually picking them
62 On the other side of the spectrum, if you want to reduce the space
63 requirements (and installer size) to the maximum, you can manually
64 choose which GStreamer libraries to deploy. Unfortunately, you are on
65 your own on this road, besides using the object file displaying tool:
66 [otool](https://developer.apple.com/library/mac/#documentation/darwin/reference/manpages/man1/otool.1.html).
67 Being a similar technique to deploying a private copy of GStreamer, keep
68 in mind that you should relocate GStreamer too, as explained at the end of
71 Bear also in mind that GStreamer is modular in nature. Plug-ins are
72 loaded depending on the media that is being played, so, if you do not
73 know in advance what files you are going to play, you do not know which
74 plugins and shared libraries you need to deploy.
76 ## Deploy only necessary packages, using the provided ones
78 This will produce a smaller installer than deploying complete
79 GStreamer, without the added burden of having to manually pick each
80 library. You just need to know which packages your application requires.
82 | Package name | Dependencies | Licenses | Description |
83 |--------------|--------------|----------|-------------|
84 | base-system-1.0 | |JPEG, FreeType, BSD-like, LGPL, LGPL-2+, LGPL-2.1, LibPNG and MIT | Base system dependencies |
85 | gstreamer-1.0-capture | gstreamer-1.0-core, gstreamer-1.0-encoding | LGPL and LGPL-2+ | GStreamer plugins for capture |
86 | gstreamer-1.0-codecs | base-crypto, gstreamer-1.0-core | BSD, Jasper-2.0, BSD-like, LGPL, LGPL-2, LGPL-2+, LGPL-2.1 and LGPL-2.1+ | GStreamer codecs |
87 | gstreamer-1.0-codecs-gpl | gstreamer-1.0-core | BSD-like, LGPL, LGPL-2+ and LGPL-2.1+ | GStreamer codecs under the GPL license and/or with patents issues |
88 | gstreamer-1.0-core | base-system-1.0 | LGPL and LGPL-2+ | GStreamer core |
89 | gstreamer-1.0-dvd | gstreamer-1.0-core | GPL-2+, LGPL and LGPL-2+ | GStreamer DVD support |
90 | gstreamer-1.0-effects | gstreamer-1.0-core | LGPL and LGPL-2+ | GStreamer effects and instrumentation plugins |
91 | gstreamer-1.0-net | base-crypto, gstreamer-1.0-core | GPL-3, LGPL, LGPL-2+, LGPL-2.1+ and LGPL-3+ | GStreamer plugins for network protocols |
92 | gstreamer-1.0-playback | gstreamer-1.0-core | LGPL and LGPL-2+ | GStreamer plugins for playback |
93 | gstreamer-1.0-system | gstreamer-1.0-core | LGPL, LGPL-2+ and LGPL-2.1+ | GStreamer system plugins |
94 | gstreamer-1.0-visualizers | gstreamer-1.0-core | LGPL and LGPL-2+ | GStreamer visualization plugins |
95 | gstreamer-1.0-encoding | gstreamer-1.0-core, gstreamer-1.0-playback | LGPL and LGPL2+ | GStreamer plugins for encoding |
96 | gstreamer-1.0-editing | gstreamer-1.0-core, gstreamer-1.0-devtools | LGPL and LGPL2+ | GStreamer libraries and plugins for non linear editing |
97 | gstreamer-1.0-devtools | gstreamer-1.0-core | LGPL and LGPL2+ | GStreamer developers tools |
98 | gstreamer-1.0-libav | gstreamer-1.0-core | LGPL and LGPL2+ | GStreamer plugins wrapping ffmpeg |
99 | gstreamer-1.0-net-restricted | base-crypto, gstreamer-1.0-core | LGPL and LGPL2+ | GStreamer plugins for network protocols with potential patent issues in some countries |
100 | gstreamer-1.0-codecs-restricted | gstreamer-1.0-core | LGPL and LGPL2+ | GStreamer restricted codecs with potential patent issues in some countries |
101 | base-crypto | base-system-1.0 | LGPL and LGPL2+ | Cryptographic libraries |
105 ## Relocation of GStreamer in OS X
107 In some situations we might need to relocate GStreamer, moving it to a
108 different place in the file system, like for instance when we are
109 shipping a private copy of GStreamer with our application.
111 ### Location of dependent dynamic libraries.
113 On Darwin operating systems, the dynamic linker doesn't locate dependent
114 dynamic libraries using their leaf name, but instead it uses full paths,
115 which makes it harder to relocate them as explained in the DYNAMIC
116 LIBRARY LOADING section of
117 [dyld](https://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man1/dyld.1.html)'s
120 > Unlike many other operating systems, Darwin does not locate dependent
121 > dynamic libraries via their leaf file name. Instead the full path to
122 > each dylib is used (e.g. /usr/lib/libSystem.B.dylib). But there are
123 > times when a full path is not appropriate; for instance, may want your
124 > binaries to be installable in anywhere on the disk.
126 We can get the list of paths used by an object file to locate its
127 dependent dynamic libraries
128 using [otool](https://developer.apple.com/library/mac/#documentation/darwin/reference/manpages/man1/otool.1.html):
131 $ otool -L /Library/Frameworks/GStreamer.framework/Commands/gst-launch-1.0
132 /Library/Frameworks/GStreamer.framework/Commands/gst-launch-1.0:
133 /System/Library/Frameworks/CoreFoundation.framework/Versions/A/CoreFoundation (compatibility version 150.0.0, current version 550.43.0)
134 /Library/Frameworks/GStreamer.framework/Versions/0.10/x86/lib/libgstreamer-1.0.0.dylib (compatibility version 31.0.0, current version 31.0.0)
135 /Library/Frameworks/GStreamer.framework/Versions/0.10/x86/lib/libxml2.2.dylib (compatibility version 10.0.0, current version 10.8.0)
139 As you might have already noticed, if we move GStreamer to a different
140 folder, it will stop working because the runtime linker won't be able to
141 find `gstreamer-1.0` in the previous location
142 `/Library/Frameworks/GStreamer.framework/Versions/0.10/x86/lib/libgstreamer-1.0.0.dylib`.
144 This full path is extracted from the dynamic library ***install name***
145 , a path that is used by the linker to determine its location. The
146 install name of a library can be retrieved with
147 [otool](https://developer.apple.com/library/mac/#documentation/darwin/reference/manpages/man1/otool.1.html) too:
150 $ otool -D /Library/Frameworks/GStreamer.framework/Libraries/libgstreamer-1.0.dylib
151 /Library/Frameworks/GStreamer.framework/Libraries/libgstreamer-1.0.dylib:
152 /Library/Frameworks/GStreamer.framework/Versions/0.10/x86/lib/libgstreamer-1.0.0.dylib
155 Any object file that links to the dynamic library `gstreamer-1.0` will
157 path `/Library/Frameworks/GStreamer.framework/Versions/0.10/x86/lib/libgstreamer-1.0.0.dylib` to
158 locate it, as we saw previously with `gst-launch-1.0`.
160 Since working exclusively with full paths wouldn't let us install our
161 binaries anywhere in the path, the linker provides a mechanism of string
162 substitution, adding three variables that can be used as a path prefix.
163 At runtime the linker will replace them with the generated path for the
164 prefix. These variables are `@executable_path`,
165 `@loader_path` and `@rpath`, described in depth in the DYNAMIC LIBRARY
167 of [dyld](https://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man1/dyld.1.html)'s
170 For our purpose we will use the `@executable_path` variable, which is
171 replaced with a fixed path, the path to the directory containing the
172 main executable: `/Applications/MyApp.app/Contents/MacOS`.
173 The `@loader_path` variable can't be used in our scope, because it will
174 be replaced with the path to the directory containing the mach-o binary
175 that loaded the dynamic library, which can vary.
177 Therefore, in order to relocate GStreamer we will need to replace all
179 containing `/Library/Frameworks/GStreamer.framework/` with `@executable_path/../Frameworks/GStreamer.framework/`, which
181 the [install\_name\_tool](http://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man1/install_name_tool.1.html)
184 ### Relocation of the binaries
186 As mentioned in the previous section, we can use
187 the `install_name_tool` in combination with `otool` to list all paths
188 for dependant dynamic libraries and modify them to use the new location.
189 However GStreamer has a huge list of binaries and doing it manually would
190 be a painful task. That's why a simple relocation script is provided
191 which you can find in cerbero's repository
192 (`cerbero/tools/osxrelocator.py`). This scripts takes 3 parameters:
194 1. `directory`: the directory to parse looking for binaries
195 2. `old_prefix`: the old prefix we want to change (eg:
196 `/Library/Frameworks/GStreamer.framework`)
197 3. `new_prefix`: the new prefix we want to use
198 (eg: `@executable_path/../Frameworks/GStreamer.framework/`)
200 When looking for binaries to fix, we will run the script in the
205 $ osxrelocator.py MyApp.app/Contents/Frameworks/GStreamer.framework/Versions/Current/lib /Library/Frameworks/GStreamer.framework/ @executable_path/../Frameworks/GStreamer.framework/ -r
206 $ osxrelocator.py MyApp.app/Contents/Frameworks/GStreamer.framework/Versions/Current/libexec /Library/Frameworks/GStreamer.framework/ @executable_path/../Frameworks/GStreamer.framework/ -r
207 $ osxrelocator.py MyApp.app/Contents/Frameworks/GStreamer.framework/Versions/Current/bin /Library/Frameworks/GStreamer.framework/ @executable_path/../Frameworks/GStreamer.framework/ -r
208 $ osxrelocator.py MyApp.app/Contents/MacOS /Library/Frameworks/GStreamer.framework/ @executable_path/../Frameworks/GStreamer.framework/ -r
211 ### Adjusting environment variables with the new paths
213 The application also needs to set the following environment variables to
214 help other libraries finding resources in the new
217 - `GST_PLUGIN_SYSTEM_PATH=/Applications/MyApp.app/Contents/Frameworks/GStreamer.framework/Versions/Current/lib/gstreamer-1.0`
218 - `GST_PLUGIN_SCANNER=/Applications/MyApp.app/Contents/Frameworks/GStreamer.framework/Versions/Current/libexec/gstreamer-1.0/gst-plugin-scanner`
219 - `GTK_PATH=/Applications/MyApp.app/Contents/Frameworks/GStreamer.framework/Versions/Current/`
220 - `GIO_EXTRA_MODULES=/Applications/MyApp.app/Contents/Frameworks/GStreamer.framework/Versions/Current/lib/gio/modules`
222 You can use the following functions:
224 - C: [putenv("VAR=/foo/bar")](http://linux.die.net/man/3/putenv)
226 - Python: [os.environ\['VAR'\] =
227 '/foo/var'](http://docs.python.org/library/os.html)