subprojects/gst-docs/markdown/installing/on-mac-osx.md

   1 #  Installing on Mac OS X
   2
   3 ## Supported platforms
   4
   5  *  10.6 (Snow Leopard)
   6  *  10.7 (Lion)
   7  *  10.8 (Mountain Lion)
   8  *  10.9 (Mavericks)
   9  *  10.10 (Yosemite)
  10  *  10.11 (El Capitan)
  11
  12 ## Prerequisites
  13
  14 To develop applications using the GStreamer SDK for OS X you will need
  15 OS X Snow Leopard (10.6) or later and
  16 [XCode 3.2.6](https://developer.apple.com/devcenter/mac/index.action) or
  17 later.
  18
  19 The recommended system is [macOS Sierra](http://www.apple.com/macosx/) with
  20 [XCode 8](https://developer.apple.com/xcode/)
  21
  22 ## Download and install the SDK
  23
  24 There are 3 sets of files in the SDK:
  25
  26   - The runtime files are needed to run GStreamer applications. You
  27     probably want to distribute these files with your application (or
  28     the installer below).
  29   - The development files are **additional** files you need to create
  30     GStreamer applications.
  31   - Mac OS X packages that you can use
  32     with [PackageMaker](https://developer.apple.com/library/mac/#documentation/DeveloperTools/Conceptual/PackageMakerUserGuide/Introduction/Introduction.html)
  33     to deploy GStreamer with your application
  34
  35 Get **both the runtime and the development installers** from
  36 the [GStreamer download page](https://gstreamer.freedesktop.org/download/#macos)
  37 and **please install both of them**:
  38  - The runtime installer is e.g. `gstreamer-1.0-{VERSION}-x86_64.pkg`, and
  39  - The development installer is e.g. `gstreamer-1.0-devel-{VERSION}-x86_64.pkg`
  40
  41 > ![Warning](images/icons/emoticons/warning.svg)
  42 > On Mac OS X 10.6 (Snow Leopard) you have to install Python 2.7 manually. It is included in later versions of OS X already. You can get it from [here](http://www.python.org/getit).
  43
  44 The downloads are
  45 [Installer Packages
  46 (.pkg)](http://en.wikipedia.org/wiki/Installer_%28Mac_OS_X%29).
  47
  48 Double click the package file and follow the instructions presented by
  49 the install wizard. In case the system complains about the package not
  50 being signed, you can control-click it and open to start the
  51 installation. When you do this, it will warn you, but there is an option
  52 to install anyway. Otherwise you can go to System Preferences → Security
  53 and Privacy → General and select the option to allow installation of
  54 packages from "anywhere".
  55
  56
  57 These are some paths of the GStreamer framework that you might find
  58 useful:
  59
  60   - /Library/Frameworks/GStreamer.framework/: Framework's root path
  61   - /Library/Frameworks/GStreamer.framework/Versions: path with all the
  62     versions of the framework
  63   - /Library/Frameworks/GStreamer.framework/Versions/Current: link to
  64     the current version of the framework
  65   - /Library/Frameworks/GStreamer.framework/Headers: path with the
  66     development headers
  67   - /Library/Frameworks/GStreamer.framework/Commands: link to the
  68     commands provided by the framework, such as gst-inspect-1.0 or
  69     gst-launch-1.0
  70
  71 For more information on OS X Frameworks anatomy, you can consult the
  72 following [link](https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/FrameworkAnatomy.html)
  73
  74 ## Configure your development environment
  75
  76 ### Building the tutorials
  77
  78 The tutorials code, along with project files and a solution file for
  79 them all, are in the
  80 [gst-docs](https://gitlab.freedesktop.org/gstreamer/gstreamer/-/tree/main/subprojects/gst-docs) in the
  81 `examples/tutorials` subdirectory.
  82
  83 To start building the tutorials, create a new folder in your Documents
  84 directory and copy the
  85 folder `/Library/Frameworks/GStreamer.framework/Current/share/gst-sdk/tutorials`.
  86
  87 You can fire up XCode and load the project file.
  88
  89 Press the **Run** button to build and run the first tutorial. You can
  90 switch the tutorial to build selecting one of the available schemes.
  91
  92 ### Creating new projects
  93
  94 #### XCode
  95
  96 The GStreamer binaries provide a
  97 [framework](https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Tasks/IncludingFrameworks.html)
  98 that you can drag and drop to XCode to start using it. There is a small
  99 exception to the regular use of frameworks, and you will need to manually
 100 include the headers (`/Library/Frameworks/GStreamer.framework/Headers`) and
 101 libraries (`/Library/Frameworks/GStreamer.framework/Libraries`) search path. In
 102 XCode you will need to do the following:
 103
 104   - Add `GStreamer.framework` to **General → Frameworks and Libraries**
 105   - Add the libraries path to **Build Settings → Library Search Paths**
 106   - Add the headers path to **Build Settings → System Header Search Paths**
 107   - Disable hardened runtime **Build Settings → Enable Hardened Runtime**. This
 108     is needed because the `GStreamer.framework` is not signed.
 109
 110 #### Manual compilation
 111
 112 If instead of XCode you use GCC (or CLANG) directly you can follow a similar
 113 approach by providing the header and libraries search path to the compiler and
 114 linker. Here's a very simple example to show you how:
 115
 116 Let's say we have a file `main.c` that requires GStreamer and looks like this:
 117
 118 ```
 119 #include <gst/gst.h>
 120
 121 int
 122 main(int argc, char *argv[])
 123 {
 124   gst_init(NULL, NULL);
 125
 126   return 0;
 127 }
 128 ```
 129
 130 We can compile it and link it with the following commands:
 131
 132 ```
 133 # Compile
 134 $ clang -c main.c -o main.o -I/Library/Frameworks/GStreamer.framework/Headers
 135
 136 # Link
 137 $ clang -o main main.o -L/Library/Frameworks/GStreamer.framework/Libraries -F/Library/Frameworks -framework GStreamer
 138 ```
 139
 140 Note how we use `-I/Library/Frameworks/GStreamer.framework/Headers` to specify
 141 the headers search path (same as with XCode) and in the linking step we specify
 142 `-L/Library/Frameworks/GStreamer.framework/Libraries` to indicate the libraries
 143 search path (as we also did in XCode), `-F/Library/Frameworks` to tell the
 144 linker where to find frameworks and finally `-framework GStreamer` to specify
 145 the GStreamer framework.
 146
 147 Finally, we can even inspect the generated executable and verify it's pointing
 148 to our GStreamer framework:
 149
 150 ```
 151 $ otool -L main
 152 main:
 153         @rpath/GStreamer.framework/Versions/1.0/lib/GStreamer (compatibility version 0.0.0, current version 0.0.0)
 154         /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1311.100.3)
 155 ```
 156
 157 #### Manual compilation (with pkg-config)
 158
 159 The `GStreamer.framework` also comes with some developer tools such as
 160 `pkg-config`. `pkg-config` is a tool used to query what compiler and linker
 161 flags an application requires if they want to use a certain library. So we will
 162 now build the same example we used above with `pkg-config` and asking for the
 163 required GStreamer flags.
 164
 165 ```
 166 # Tell pkg-config where to find the .pc files
 167 $ export PKG_CONFIG_PATH=/Library/Frameworks/GStreamer.framework/Versions/1.0/lib/pkgconfig
 168
 169 # We will use the pkg-config provided by the GStreamer.framework
 170 $ export PATH=/Library/Frameworks/GStreamer.framework/Versions/1.0/bin:$PATH
 171
 172 # Compile
 173 $ clang -c main.c -o main.o `pkg-config --cflags gstreamer-1.0`
 174
 175 # Link
 176 $ clang -o main main.o `pkg-config --libs gstreamer-1.0`
 177 ```
 178
 179 It's important to use the `pkg-config` provided by the `GStreamer.framework`
 180 (not the one provided by Homebrew for example), that's why we set `PATH` to find
 181 `pkg-config` from the right location.
 182
 183 Note how we have used `pkg-config --cflags gstreamer-1.0` to obtain all the
 184 compilation flags and then `pkg-config --libs gstreamer-1.0` to get all the
 185 linker flags.
 186
 187 The commands above should have generated an executable that, as before, we can
 188 inspect:
 189
 190 ```
 191 $ otool -L main
 192 main:
 193         @rpath/libgstreamer-1.0.0.dylib (compatibility version 2101.0.0, current version 2101.0.0)
 194         @rpath/libgobject-2.0.0.dylib (compatibility version 6201.0.0, current version 6201.6.0)
 195         @rpath/libglib-2.0.0.dylib (compatibility version 6201.0.0, current version 6201.6.0)
 196         @rpath/libintl.8.dylib (compatibility version 10.0.0, current version 10.5.0)
 197         /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1311.100.3)
 198 ```
 199
 200 You can see how the dependencies are different from the ones we saw above. The
 201 reason is because in this case we have linked directly to the GStreamer
 202 libraries included in the framework instead of the framework itself (there's a
 203 slight difference there).