= Getting Started: Building for Microsoft Windows =
[[TracNav(Getting-Started/TOC)]]


This page describes how to use Microsoft Visual Studio to build pjsip libraries:

[[PageOutline(2-3,,inline)]]

  Note: You can also build for Windows using GNU tools such mingw. Follow the steps in [wiki:Getting-Started/Autoconf Getting Started: Building with GNU Tools/Autoconf].

  Note: For buiding DLLs, please see [wiki:FAQ#dll this question on FAQ].

== Build Preparation for Windows ==


 1. [wiki:Getting-Started/Download-Source Get the source code], if you haven't already.
 1. '''It is important that you create a config_site.h as described in [wiki:Getting-Started/Build-Preparation Build Preparation]'''

== Requirements ==

=== Tools and SDKs ===

The Visual Studio based project files can be used with one of the following tools:

    * ~~Microsoft Visual Studio 6,~~ (no longer supported since 2.0)
    * ~~Microsoft Visual Studio .NET 2002,~~
    * ~~Microsoft Visual Studio .NET 2003,~~
    * Microsoft Visual Studio/C++ 2005 (including Express edition),
    * Microsoft Visual Studio 2008. You may need to fix the [wiki:FAQ#vs2008 IP Helper API header bug]. Follow the instructions for Visual Studio 2005.
    * Microsoft Visual Studio 2012. Tested on Professional version, untested on Express version.
    * '''Note:''' Microsoft Visual Studio 2010 '''is currently unsupported'''.
      - This is because Visual Studio 2010 importer for our VS2005 solution files is broken. Use Visual Studio 2012 instead.
      - Workaround tips: [http://lists.pjsip.org/pipermail/pjsip_lists.pjsip.org/2012-February/014139.html #1] [http://lists.pjsip.org/pipermail/pjsip_lists.pjsip.org/2013-April/016083.html #2]

In addition, the following SDK's are needed:

    * Essential for other than Windows 8/Visual Studio 2012: DirectX SDK (tested with DirectX version 8 and 9). After installing DirectX, add the paths to the include files and the library to Visual Studio.
    * Optional if not using Visual Studio 2008: Platform SDK (tested with Platform SDK for Windows Server 2003 SP1).
    * Optional: OpenSSL development kit is needed if TLS support is wanted. Learn more: [wiki:Getting-Started/Installing-OpenSSL-Windows Installing OpenSSL Libraries on Windows].

  Note: The new Platform SDK is still needed for Visual Studio 6, although VS6 comes with its own Platform SDK. The new Platform SDK is needed for Iphlpapi.[h|lib] for the new PJNATH library.

=== Video support (2.0 and above only) ===

==== Additional requirements ====

 1. !DirectShow SDK, included in Windows SDK. The minimum component required within the SDK is ''Windows Development Headers and Libraris'' and ''Samples''. As there are several versions of SDK we found they have different issues:
   a. If you don't need Windows 7 features, the recommended SDK is [http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ff6467e6-5bba-4bf5-b562-9199be864d29 Windows SDK Update for Windows Vista]. This is because it doesn't have [wiki:FAQ#vs2008 IP Helper API header bug].
   a. If you need Windows 7 features then use [http://www.microsoft.com/downloads/en/confirmation.aspx?FamilyID=6B6C21D2-2006-4AFA-9702-529FA782D63B Windows SDK for Windows 7 and .NET Framework 4] and follow the instructions on [wiki:FAQ#vs2008 fixing IP Helper API header bug]. Also if you are using Visual Studio 2005 then you will need to patch it using [http://support.microsoft.com/kb/949009/ MS Knowledge Base 949009]
 1. [http://www.libsdl.org/ SDL] '''version 2.0''' or '''version 1.3''' 
    - Note that this is the newer and not yet released SDL library, hence most likely it won't be installed by default on your system. You can download the SDL 2.0 source snapshot or from the Mercurial repository from http://www.libsdl.org/hg.php.
    - SDL 1.3 is sometimes under {{{SDL}}} sub-directory of SDL 2.0.
    - SDL sources comes with VS project settings, under {{{VisualC}}} sub-directory
 1. [http://ffmpeg.org/ ffmpeg] development library. We tested with ffmpeg version ranging from 0.5.1 (from circa 2009) to 0.10. 
    - Note that for H.264 support, you need newer releases (October 2011 onwards), and it needs libz too.
    - You may be able to use the binary distributions (such as from [http://ffmpeg.zeranoe.com/builds/ Zeranoe] - get the 'dev' builds). It compiles fine, however we haven't tested them thoroughly.
    - Otherwise, get [http://www.mingw.org/wiki/MSYS MSYS|MinGW] for building libx264 and ffmpeg, and also its [http://www.mingw.org/wiki/InstallationHOWTOforMinGW gcc compiler suite]. Note:
       - It is recommended to use gcc 4 or above to build ffmpeg.
       - To avoid problems, put MSYS, libx264, and ffmpeg in folders that do not contain space, e.g: {{{C:\msys, C:\devlib\ffmpeg}}}.
       - To use ffmpeg with VS, {{{inttypes.h}}} and {{{stdint.h}}} will be needed, check [https://code.google.com/p/msinttypes/downloads/detail?name=msinttypes-r26.zip&can=2&q= here].
    - In MSYS, build with at least:
      {{{
$ ./configure --enable-shared --disable-static --enable-memalign-hack
                      # add other options if needed, e.g: optimization, install dir, search path 
                      # particularly CFLAGS and LDFLAGS for x264
                      # to enable H264, add "--enable-gpl --enable-libx264"
$ make && make install
      }}}
 1. Optional for H.264: [http://www.videolan.org/developers/x264.html libx264]. We tested with the latest from git (as of October 2011). In MSYS console:
     {{{
$ ./configure --enable-static      # add options if needed, e.g: optimization, install dir, search path
$ make && make install-lib-static  # default install dir is /usr/local
      }}}
 1. Optional: [http://qt-project.org/downloads/ Qt development SDK] for building the [wiki:Video_Users_Guide#vidgui video GUI sample]. We tested with version 4.6 or later.
    - without this you can still enjoy video with pjsua console application

==== Additional configuration ====
 1. Add include and library paths for the required components:
    a. !DirectShow SDK
    a. SDL
    a. ffmpeg
 1. Add these to your {{{config_site.h}}}:
{{{
#define PJMEDIA_HAS_VIDEO	        1
#define PJMEDIA_HAS_FFMPEG	        1
#define PJMEDIA_VIDEO_DEV_HAS_SDL       1
#define PJMEDIA_VIDEO_DEV_HAS_DSHOW     1
}}}

=== Host requirements ===

For the host, the following are required:

    * Windows NT, 2000, XP, 2003, Vista, Windows 7, or later ,
    * Windows 95/98 should work too, but this has not been tested,
    * Sufficient amount of RAM for the build process.

== Building the Projects ==

Follow the steps below to build the libraries/application using Visual Studio:

   1. ~~For Visual Studio 6/2002/2003: open {{{pjproject.dsw}}} workspace file.~~ (No longer supported since pjsip 2.0)
   1. For Visual Studio 8 (VS 2005): open {{{pjproject-vs8.sln}}} solution file.
   1. For Visual Studio 9 (VS 2008): open {{{pjproject-vs8.sln}}} solution file. One-time conversion of projects to VS 2008 format will done automatically.
   1. For Visual Studio 11 (VS 2012): open {{{pjproject-vs8.sln}}} solution file. One-time conversion of projects to VS 2012 format will done automatically.
     1. Warnings about Windows Mobile projects/configurations can be safely ignored, VS 2012 does not support Windows Mobile
     1. Additional tips from [http://lists.pjsip.org/pipermail/pjsip_lists.pjsip.org/2012-December/015574.html pjsip mailing list]
   1. Set '''pjsua''' as Active or Startup Project.
   1. Set '''Win32''' as the platform.
      1. Currently we are still encountering issues with 64-bit builds, therefore it is not yet supported.
   1. Select '''Debug''' or '''Release''' build as appropriate.
   1. Build the project. This will build '''pjsua''' application and all libraries needed by '''pjsua'''.
   1. After successful build, the pjsua application will be placed in pjsip-apps/bin directory, and the libraries in lib directory under each projects.

To build the samples:

   1. (Still using the same workspace)
   2. Set samples project as Active Project
   3. Select Debug or Release build as appropriate. See [wiki:Getting-Started/Visual-Studio-Build-Configuration Visual Studio Build Configuration] page for explanation of each provided build configuration
   4. Build the project. This will build all sample applications and all libraries needed.
   5. After successful build, the sample applications will be placed in pjsip-apps/bin/samples directory, and the libraries in lib directory under each projects.

== Debugging Sample Applications ==

Sample applications are built using Samples.mak makefile, therefore it is difficult to setup debugging session in Visual Studio for these applications. To solve this issue, the pjsip_apps workspace contain one project called sample_debug which can be used to debug a sample application.

To setup debugging using sample_debug project:

   1. Set sample_debug project as Active Project
   2. Edit debug.c file inside this project.
   3. Modify the #include line to include the particular sample application to debug
   4. Select Debug build.
   5. Build and debug the project.

== Next: Using pjproject libraries for your own application ==

   1. Put these include directories in the include search path of your project:
          * pjlib/include
          * pjlib-util/include
          * pjnath/include
          * pjmedia/include
          * pjsip/include
   2. Put the combined library directory '''lib''' (located in the root directory of pjproject source code) in the library search path
   3. Include the relevant PJ header files in the application source file. For example, using these would include ALL APIs exported by PJ:
{{{
         #include <pjlib.h>
         #include <pjlib-util.h>
         #include <pjnath.h>
         #include <pjsip.h>
         #include <pjsip_ua.h>
         #include <pjsip_simple.h>
         #include <pjsua-lib/pjsua.h>
         #include <pjmedia.h>
         #include <pjmedia-codec.h>
}}}
      (Note: the documentation of the relevant libraries should say which header files should be included to get the declaration of the APIs).
   4. Declare PJ_WIN32=1 macro in the project settings (declaring the macro in the source file may not be sufficient).
          * For Windows Mobile applications build with Visual C++, we need to declare PJ_WIN32_WINCE=1 macro in the project settings.
 
    5. Link with the main pjproject library {{{libpjproject}}}. It includes all the libraries provided. Note: the actual library names will be appended with the target name and the build configuration. For example: The actual library names will look like libpjproject-i386-win32-vc6-debug.lib depending on whether we are building the Debug or Release version of the library.


   6. Link with system specific libraries such as: wsock32.lib, ws2_32.lib, ole32.lib, dsound.lib

   7. If you want to use video API see [wiki:Video_Users_Guide Video User's Guide]   

== Crash problem on Win32 ==

Please see [wiki:crash-problem this page] for troubleshooting crash problem on Win32.

== Windows 98 Support ==

Please see [wiki:Windows98_Support this page] to make PJSIP works on Windows 95 and windows 98.