Getting Started: Building for Microsoft Windows

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

1. Build Preparation
2. Requirements
3. Building the Projects
4. Debugging Sample Applications
5. Next: Using pjproject libraries for your own application

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

Build Preparation

1. It is important that you create a config_site.h as described in Build Preparation
2. Get the source code, if you haven't already.

Requirements

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

• Microsoft Visual Studio 6,
• Microsoft Visual Studio .NET 2002,
• Microsoft Visual Studio .NET 2003,
• Microsoft Visual C++ 2005 (including Express edition),
• Microsoft Visual Studio 2008 may work, but not tested specifically. Follow the instructions for Visual Studio 2005.

In addition, the following SDK's are needed:

• Platform SDK (tested with Platform SDK for Windows Server 2003 SP1).
• DirectX SDK (tested with DirectX version 8 and 9),
• OpenSSL development kit (optional) is needed if TLS support is wanted. Learn more: 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.

For the host, the following are required:

• Windows NT, 2000, XP, 2003, 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.
2. For Visual Studio 8 (VS 2005): open pjproject-vs8.sln solution file.
3. Set pjsua as Active Project.
4. Select Debug or Release build as appropriate.
5. Build the project. This will build pjsua application and all libraries needed by pjsua.
6. 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 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

Regardless of the build system being used, the following tasks are normally needed to be done in order to build application to use PJSIP and PJMEDIA:

1. Put these include directories in the include search path:
   • pjlib/include
   • pjlib-util/include
   • pjnath/include
   • pjmedia/include
   • pjsip/include
2. Put the combined library directory lib 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 the OS macros.
   • For Windows applications built with Visual Studio, we need to 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.
   • For GNU build system/autoconf based build system, we need to declare PJ_AUTOCONF=1 macro when compiling the applications.

(Note: the old PJ build system requires declaring the target processor with PJ_M_XXX=1 macro, but this has been made obsolete. The target processor will be detected from compiler's predefined macro by pjlib/config.h file).

5. Link with the appropriate PJ libraries. The following libraries will need to be included in the library link specifications:

pjlib

Base library used by all libraries.

pjlib-util

Auxiliary library containing scanner, XML, STUN, MD5, getopt, etc, used by the SIP and media stack.

pjnath

NAT helper library (STUN, TURN, ICE).

pjsip

SIP core stack library.

pjsip-ua

SIP user agent library containing INVITE session, call transfer, client registration, etc.

pjsip-simple

SIP SIMPLE library for base event framework, presence, instant messaging, etc.

pjsua

High level SIP UA library, combining SIP and media stack into high-level easy to use API.

pjmedia

The media framework.

pjmedia-codec

Container library for various codecs such as GSM, Speex, and iLBC.

Note: the actual library names will be appended with the target name and the build configuration. For example:

For Visual Studio builds

The actual library names will look like pjlib-i386-win32-vc6-debug.lib, pjlib-i386-win32-vc6-release.lib, etc., depending on whether we are building the Debug or Release version of the library.

An easier way to link with the libraries is to include PJ project files in the workspace, and to configure project dependencies so that the application depends on the PJ libraries. This way, we don't need to manually add each PJ libraries to the input library file specification, since VS will automatically link the dependency libraries with the application.

For Windows Mobile builds

Unfortunately the PJ libraries built for Windows Mobile will not be placed in the usual lib directory, but rather under the output directory under build/wince-evc4 project directory.

An easier way to link with the libraries is to include PJ project files in the workspace, and to configure project dependencies so that the application depends on the PJ libraries. This way, we don't need to manually add each PJ libraries to the input library file specification, since VS will automatically link the dependency libraries with the application.

For GNU builds

Use the template Makefile below (as described in Building Application using PJSIP with GNU Tools): # Modify this to point to the PJSIP location. PJBASE=/home/myself/pjproject-0.5.10.2

include $(PJBASE)/build.mak

CC = $(APP_CC) LDFLAGS = $(APP_LDFLAGS) LDLIBS = $(APP_LDLIBS) CFLAGS = $(APP_CFLAGS) CPPFLAGS= ${CFLAGS}

# If your application is in a file named myapp.cpp or myapp.c # this is the line you will need to build the binary. all: myapp

myapp: myapp.cpp

$(CC) -o $@ $< $(CPPFLAGS) $(LDFLAGS) $(LDLIBS)

clean:

rm -f myapp.o myapp

6.

Link with system spesific libraries:

Windows

Add (among other things): wsock32.lib, ws2_32.lib, ole32.lib, dsound.lib

Linux, *nix, *BSD

Add (among other things): '-lpthread -lm' (at least). If you use the template Makefile above, these would have been added by PJ.

MacOS X

Add (among other things): '-framework CoreAudio? -lpthread -lm'. If you use the template Makefile above, these would have been added by PJ.