markdown/installing/on-windows.md

   1 # Installing on Windows
   2
   3 ## Supported platforms
   4
   5 * Windows XP
   6 * Windows Vista
   7 * Windows 7
   8 * Windows 8
   9 * Windows 10
  10
  11 ## Prerequisites
  12
  13 To develop applications using GStreamer for Windows you will
  14 need [Windows
  15 XP](http://windows.microsoft.com/en-US/windows/products/windows-xp) or
  16 later.
  17
  18 GStreamer binaries includes C headers (`.h`) and library files (`.lib`)
  19 valid for any version of [Microsoft Visual
  20 Studio](http://www.microsoft.com/visualstudio). For convenience,
  21 property pages (`.props`) are also included which extremely simplify
  22 creating new projects. These property pages, though, only work with
  23 [Microsoft Visual
  24 Studio 2010](http://www.microsoft.com/visualstudio/en-us/products/2010-editions)
  25 (including the free [Visual C++ Express
  26 edition](http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-cpp-express)).
  27
  28 The recommended system is
  29 [Windows 7](http://windows.microsoft.com/en-us/windows7/products/home)
  30 with [Microsoft Visual
  31 Studio 2010](http://www.microsoft.com/visualstudio/en-us/products/2010-editions) (Take
  32 a look at its [system
  33 requirements](http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-cpp-express)).
  34
  35 Installing GStreamer for 32-bits platforms requires approximately 286MB of
  36 free disk space for the runtime and 207MB for the development files.
  37
  38 Installing GStreamer for 64-bits platforms requires approximately 340MB of
  39 free disk space for the runtime and 216MB for the development files.
  40
  41 ## Download and install GStreamer binaries
  42
  43 There are 3 sets of files in GStreamer binaries:
  44
  45   - The runtime files are needed to run GStreamer applications. You
  46     probably want to distribute these files with your application (or
  47     the installer below).
  48   - The development files are **additional** files you need to create
  49     GStreamer applications.
  50   - The [Merge
  51     Modules](http://msdn.microsoft.com/en-us/library/windows/desktop/aa369820%28v=vs.85%29.aspx)
  52     files are **additional** files you can use to deploy GStreamer binaries
  53     alongside your application (see [Windows
  54     deployment](deploying/windows.md)).
  55
  56 Get  **the Runtime and Development files** installers appropriate for
  57 your architecture from here:
  58
  59 [https://gstreamer.freedesktop.org/data/pkg/windows/](https://gstreamer.freedesktop.org/data/pkg/windows/)
  60
  61 Execute the installers and choose an installation folder. The suggested
  62 default is usually OK.
  63
  64 > ![Warning](images/icons/emoticons/warning.png)
  65 >`If you plan to use Visual Studio, **close it before installing GStreamer**. The installer will define new environment variables which will not be picked up by Visual Studio if it is open.
  66
  67 > On **Windows 8** and **Windows 10**, it might be necessary to log out and log back in to your account after the installation for the newly defined environment variables to be picked up by Visual Studio.
  68
  69 It is the application's responsibility to ensure that, at runtime,
  70 GStreamer can access its libraries and plugins. It can be done by adding
  71 `%GSTREAMER_ROOT_X86%\bin` to the `%PATH%` environment variable, or
  72 by running the application from this same folder.
  73
  74 At runtime, GStreamer will look for its plugins in the following
  75 folders:
  76
  77   - `%HOMEDRIVE%%HOMEFOLDER%/.gstreamer-1.0/plugins`
  78   - `C:\gstreamer\1.0\x86\lib\gstreamer-1.0`
  79   - `<location of libgstreamer-1.0-0.dll>\..\lib\gstreamer-1.0`
  80   - `%GST_PLUGIN_PATH%`
  81
  82 So, typically, if your application can find `libgstreamer-1.0-0.dll`,
  83 it will find the GStreamer plugins, as long as the installation folder
  84 structure is unmodified. If you do change this structure in your
  85 application, then you can use the `%GST_PLUGIN_PATH%` environment
  86 variable to point GStreamer to its plugins. The plugins are initially
  87 found at `%GSTREAMER_ROOT_X86%\lib\gstreamer-1.0`.
  88
  89 Additionally, if you want to prevent GStreamer from looking in all the
  90 default folders listed above, you can set the
  91 `%GST_PLUGIN_SYSTEM_PATH%` environment variable to point where the
  92 plugins are located.
  93
  94 ## Configure your development environment
  95
  96 ### Building the tutorials
  97
  98
  99 The tutorials code, along with project files and a solution file for
 100 Visual Studio 2010, are in the
 101 [gst-docs](https://cgit.freedesktop.org/gstreamer/gst-docs/) in the
 102 `examples/tutorials` folder.
 103
 104 In order to prevent accidental modification of the original code, and to
 105 make sure Visual Studio has the necessary permissions to write the
 106 output files, copy the entire `tutorials` folder to a place of your
 107 liking, and work from there.
 108
 109 > ![Information](images/icons/emoticons/information.png)
 110 > **64-bit Users**
 111 >
 112 >Use `%GSTREAMER_ROOT_X86_64%` if you have installed GStreamer binaries for 64-bit platforms. Both GStreamer binariess (32 and 64-bit) can be installed simultaneously, and hence the separate environment variables.
 113 >
 114 >Make sure you select the Solution Configuration that matches GStreamer that you have installed: `Win32` for 32 bits or `x64` for 64 bits.
 115 >
 116 > ![Windows Install Configuration](images/WindowsInstall-Configuration.png)
 117
 118 You can fire up Visual Studio 2010 and load your copy of the
 119 `tutorials.sln` solution file (Click on the screen shots to enlarge
 120 them).
 121
 122 ![](images/WindowsInstall2.png)
 123
 124 ![](images/WindowsInstall1.png)
 125
 126 Hit **F7**, press the Build Solution button
 127 ![](images/WindowsInstall-BuildSolution.png) or go to Build →
 128 Build Solution. All projects should build without problems.
 129
 130 ### Running the tutorials
 131
 132 In order to run the tutorials, we will set the current working directory
 133 to `%GSTREAMER_ROOT_X86%`\\`bin` in the Debugging section of the
 134 project properties. **This property is not stored in the project files,
 135 so you will need to manually add it to every tutorial you want to run
 136 from within Visual Studio**. Right click on a project in the Solution
 137 Explorer, Properties → Debugging → Working Directory, and type
 138 `$(GSTREAMER_ROOT_X86)`\\`bin`
 139
 140 (The `$(...)` notation is required to access environment variables
 141 from within Visual Studio. You use the `%...%` notation from Windows
 142 Explorer)
 143
 144 You should now be able to run the tutorials.
 145
 146 ### Creating new projects manually
 147
 148 **If you want to create 64-bit applications, remember also to create x64
 149 Solution and Project configurations as
 150 explained [here](http://msdn.microsoft.com/en-us/library/9yb4317s\(v=vs.100\).aspx).**
 151
 152 #### Include the necessary GStreamer Property Sheet
 153
 154 The included property sheets make creating new projects extremely easy.
 155 In Visual Studio 2010 create a new project (Normally a `Win32
 156 Console` or `Win32 Application`). Then go to the Property Manager
 157 (View→Property Manager), right-click on your project and select “Add
 158 Existing Property Sheet...”. Navigate to
 159 `%GSTREAMER_ROOT_X86%`\\`share\vs\2010\libs` and
 160 load `gstreamer-1.0.props `
 161
 162 This property sheet contains the directories where the headers and
 163 libraries are located, and the necessary options for the compiler and
 164 linker, so you do not need to change anything else in your project.
 165
 166 If you cannot find the Property Manager, you might need to enable Expert
 167 Settings. Go to Tools → Settings → Expert Settings. Upon first
 168 installation of Visual Studio, Expert Settings are disabled by
 169 default.
 170
 171 ![](images/WindowsInstall10.png)
 172
 173 > ![Warning](images/icons/emoticons/warning.png)
 174 > **Depending on the GStreamer libraries you need to use, you will have to add more property pages, besides `gstreamer-1.0`**  (each property page corresponds to one GStreamer library).
 175 >
 176 > The tutorial's project files already contain all necessary property pages. When developing your own applications, the GStreamer documentation will tell you what library a function belongs to, and therefore, what property pages you need to add.
 177
 178 #### Remove the dependency with the Visual Studio runtime
 179
 180 At this point, you have a working environment, which you can test by
 181 running the tutorials. However, there is a last step remaining.
 182
 183 Applications built with Visual C++ 2010 depend on the Visual C++ 2010
 184 Runtime, which is a DLL that gets installed when you install Visual
 185 Studio. If you were to distribute your application, you would need to
 186 distribute this DLL with it (What is known as the [Visual C++ 2010
 187 Redistributable
 188 Package](http://www.microsoft.com/download/en/details.aspx?id=5555)).
 189 This happens with every version of Visual Studio, and the Runtime DLL is
 190 different for every version of Visual Studio.
 191
 192 Furthermore, GStreamer itself is built using a “basic” C runtime which
 193 comes in every Windows system since Windows XP, and is named
 194 `MSVCRT.DLL`. If your application and GStreamer do not use the same C
 195 Runtime, problems are bound to crop out.
 196
 197 In order to avoid these issues you must instruct your application to use
 198 the system's C Runtime. First install the [Windows Device Driver Kit
 199 Version 7.1.0](http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=11800) (DDK).
 200 When the installer asks about the features, select only “Build
 201 Environments”. Accept the suggested location for the installation, which
 202 is usually `C:\WinDDK\7600.16385.1`. This download is an ISO file, you
 203 can either burn a DVD with it (as recommended in the Microsoft site. You
 204 will need DVD burning software), mount the file in a virtual DVD device
 205 (you will need DVD virtualization software) or unpack the file as if it
 206 was a regular compressed file (you will need decompression software that
 207 understands the ISO format).
 208
 209 Then, add the `x86.props` or `x86_64.props` (for 32 or 64 bits) property
 210 sheet found in `%GSTREAMER_ROOT_X86%``\``share\vs\2010\msvc` to your
 211 project. This will make your application use the ubiquitous
 212 `MSVCRT.DLL` saving you some troubles in the future.
 213
 214 > ![Information](images/icons/emoticons/information.png)
 215 > If you did not install the WinDDK to the standard path `C:\WinDDK\7600.16385.1`, you will need to tell Visual Studio where it is. Unfortunately, there is no automated way to do this. Once you have added the `x86.props` or `x86_64.props` to your project, go to the Property Manager, expand your project and its subfolders until you find the property sheet called `config`. Double click to edit it, and select the section called “User Macros” in the list on the left. You should see a macro called `WINDOWS_DRIVER_KIT`. Double click to edit it, and set its value to the root folder where you installed the DDK. This is the folder containing a file called `samples.txt`.
 216 >
 217 >That's it. Accept the changes, right click on the `config` property sheet and select “Save”. The path to the DDK is now stored in `config.props` and you do not need to perform this operation anymore.
 218
 219 ### Creating new projects using the wizard
 220
 221 Go to File → New → Project… and you should find a template
 222 named **GStreamer Project**. It takes no parameters, and sets all
 223 necessary project settings, both for 32 and 64 bits architectures.
 224
 225 The generated project file includes the two required Property Sheets
 226 described in the previous section, so, in order to link to the correct
 227 `MSVCRT.DLL`, **you still need to install the Windows Device Driver
 228 Kit** and change the appropriate property sheets.