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