sdk-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](sdk-windows-deployment.md)).
  55
  56 Get  **the Runtime and Development files** installers appropriate for
  57 your architecture from here:
  58
  59 **FIXME: Add links **
  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 The tutorial's code, along with project files and a solution file for
  99 Visual Studio 2010 are all included in the GStreamer binaries, in
 100 the `%GSTREAMER_ROOT_X86%``\share\gst-sdk\tutorials` folder.
 101
 102 `%GSTREAMER_ROOT_X86%` is an environment variable that the installer
 103 defined for you, and points to the installation folder of GStreamer binaries.
 104
 105 In order to prevent accidental modification of the original code, and to
 106 make sure Visual Studio has the necessary permissions to write the
 107 output files, copy the entire `tutorials` folder to a place of your
 108 liking, and work from there.
 109
 110 > ![Information](images/icons/emoticons/information.png)
 111 > **64-bit Users**
 112 >
 113 >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.
 114 >
 115 >Make sure you select the Solution Configuration that matches GStreamer that you have installed: `Win32` for 32 bits or `x64` for 64 bits.
 116 >
 117 > ![Windows Install Configuration](attachments/WindowsInstall-Configuration.png)
 118
 119 You can fire up Visual Studio 2010 and load your copy of the
 120 `tutorials.sln` solution file (Click on the screen shots to enlarge
 121 them).
 122
 123 ![](attachments/WindowsInstall2.png)
 124
 125 ![](attachments/WindowsInstall1.png)
 126
 127 Hit **F7**, press the Build Solution button
 128 ![](attachments/WindowsInstall-BuildSolution.png) or go to Build →
 129 Build Solution. All projects should build without problems.
 130
 131 ### Running the tutorials
 132
 133 In order to run the tutorials, we will set the current working directory
 134 to `%GSTREAMER_ROOT_X86%`\\`bin` in the Debugging section of the
 135 project properties. **This property is not stored in the project files,
 136 so you will need to manually add it to every tutorial you want to run
 137 from within Visual Studio**. Right click on a project in the Solution
 138 Explorer, Properties → Debugging → Working Directory, and type
 139 `$(GSTREAMER_ROOT_X86)`\\`bin`
 140
 141 (The `$(...)` notation is required to access environment variables
 142 from within Visual Studio. You use the `%...%` notation from Windows
 143 Explorer)
 144
 145 You should now be able to run the tutorials.
 146
 147 ### Creating new projects manually
 148
 149 **If you want to create 64-bit applications, remember also to create x64
 150 Solution and Project configurations as
 151 explained [here](http://msdn.microsoft.com/en-us/library/9yb4317s\(v=vs.100\).aspx).**
 152
 153 #### Include the necessary GStreamer Property Sheet
 154
 155 The included property sheets make creating new projects extremely easy.
 156 In Visual Studio 2010 create a new project (Normally a `Win32
 157 Console` or `Win32 Application`). Then go to the Property Manager
 158 (View→Property Manager), right-click on your project and select “Add
 159 Existing Property Sheet...”. Navigate to
 160 `%GSTREAMER_ROOT_X86%`\\`share\vs\2010\libs` and
 161 load `gstreamer-1.0.props `
 162
 163 This property sheet contains the directories where the headers and
 164 libraries are located, and the necessary options for the compiler and
 165 linker, so you do not need to change anything else in your project.
 166
 167 If you cannot find the Property Manager, you might need to enable Expert
 168 Settings. Go to Tools → Settings → Expert Settings. Upon first
 169 installation of Visual Studio, Expert Settings are disabled by
 170 default.
 171
 172 ![](attachments/WindowsInstall10.png)
 173
 174 > ![Warning](images/icons/emoticons/warning.png)
 175 > **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).
 176 >
 177 > 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.
 178
 179 #### Remove the dependency with the Visual Studio runtime
 180
 181 At this point, you have a working environment, which you can test by
 182 running the tutorials. However, there is a last step remaining.
 183
 184 Applications built with Visual C++ 2010 depend on the Visual C++ 2010
 185 Runtime, which is a DLL that gets installed when you install Visual
 186 Studio. If you were to distribute your application, you would need to
 187 distribute this DLL with it (What is known as the [Visual C++ 2010
 188 Redistributable
 189 Package](http://www.microsoft.com/download/en/details.aspx?id=5555)).
 190 This happens with every version of Visual Studio, and the Runtime DLL is
 191 different for every version of Visual Studio.
 192
 193 Furthermore, GStreamer itself is built using a “basic” C runtime which
 194 comes in every Windows system since Windows XP, and is named
 195 `MSVCRT.DLL`. If your application and GStreamer do not use the same C
 196 Runtime, problems are bound to crop out.
 197
 198 In order to avoid these issues you must instruct your application to use
 199 the system's C Runtime. First install the [Windows Device Driver Kit
 200 Version 7.1.0](http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=11800) (DDK).
 201 When the installer asks about the features, select only “Build
 202 Environments”. Accept the suggested location for the installation, which
 203 is usually `C:\WinDDK\7600.16385.1`. This download is an ISO file, you
 204 can either burn a DVD with it (as recommended in the Microsoft site. You
 205 will need DVD burning software), mount the file in a virtual DVD device
 206 (you will need DVD virtualization software) or unpack the file as if it
 207 was a regular compressed file (you will need decompression software that
 208 understands the ISO format).
 209
 210 Then, add the `x86.props` or `x86_64.props` (for 32 or 64 bits) property
 211 sheet found in `%GSTREAMER_ROOT_X86%``\``share\vs\2010\msvc` to your
 212 project. This will make your application use the ubiquitous
 213 `MSVCRT.DLL` saving you some troubles in the future.
 214
 215 > ![Information](images/icons/emoticons/information.png)
 216 > 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`.
 217 >
 218 >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.
 219
 220 ### Creating new projects using the wizard
 221
 222 Go to File → New → Project… and you should find a template
 223 named **GStreamer Project**. It takes no parameters, and sets all
 224 necessary project settings, both for 32 and 64 bits architectures.
 225
 226 The generated project file includes the two required Property Sheets
 227 described in the previous section, so, in order to link to the correct
 228 `MSVCRT.DLL`, **you still need to install the Windows Device Driver
 229 Kit** and change the appropriate property sheets.