• View
• Edit
• History
• Print

Building PTLib on Windows

Contents

1. Introduction
2. Prerequisites
3. Download and install the PTLib source code
4. Open the solution file
5. Install GNU bison
6. Configure directories
7. Install optional packages
8. Build the PTLIB Static project
9. Build the PTLIB DLL project
10. Tailoring the configure search path
11. Notes on Windows Mobile

1. Introduction

This document provides a thorough description of the building PTLib for Visual Studio on Windows.

Support for MSVC 6 is no longer maintained as it is very old and contains bugs that cause many problems. While Windows 2000 may work for builds and running executables, it is expected that at least Windows XP would be used and no gurantees are made the future versions.

2. Prerequisites

You will need the following:

• VS.net 2003, VS.net 2005, Visual C++ 2005 Express Edition, VS.net 2008 or Visual C++ 2008 Express Edition.
  • Note that you cannot use the free VS.net 2003 available from Microsoft as building without the IDE is not supported.
• If using SVN download, Tortoise SVN is highly recommended.
• There are a number of optional downloads for extra features, for example OpenSSL. PTLib will automatically detect if these are installed and compile the system accordingly.

3. Download and install the PTLib source code

Download and extract the PTLib source code. For the purposes of this document, the directory that contains PTLib will be indicated as installdir\PTLIB

The PTLib source may be downloaded as a ZIP file from the SourceForge download page or you may download it using Subversion

4. Open the solution file

If you are using VS.net 2003, open the ptlib.sln solution file.

If you are using VS.net 2005, open the ptlib_2005.sln solution file.

If you are using VS.net 2008, open the ptlib_2008.sln solution file.

The solution contains the following projects:

• configure
• Hello World DLL
• MergeSym
• PTLib DLL
• PTLib Static

5. Install GNU bison

The GNU Bison tool is required to compile PTLib.

GNU flex is not required by most users, but will be necessary if you need to recompile the "asnparser" utility for modifying the ASN files supplied with OPAL. We provide both tools as it is simpler to provide both together than separately.

Precompiled versions of these tools are provided here and are installed as follows:

• Unzip the precompiled tools into "C:\". This will create "C:\TOOLS" containing "FLEX.EXE", "BISON.EXE", and "C:\TOOLS\SHARE" containing "BISON.SIMPLE" and "BISON.HAIRY".

IMPORTANT NOTE: Don't be tempted to install bison and flex into a directory other than C:\TOOLS. It can be done, but it's not easy and not worth the effort.

6. Configure directories

Once Visual Studio is started, select "Tools" from the "Options" menu, then open the "Projects and Solutions" element in the tree on the left, and finally select the "VC++ Directories" entry. Add the following directories settings:

• Add C:\TOOLS to the Executable directory list
• Add installdir\PTLIB\LIB to the Executable directory list
• Add installdir\PTLIB\INCLUDE to the Include directory list
• Add installdir\PTLIB\LIB to the Library directory list

7. Install optional packages

The PTLib build process will automatically detect many packages that are installed on the host system. Before starting the build process, select and install the packages from the list below that are needed:

• OpenSSL - Provides support for encryption and authentication. We recommend using a pre-packaged binary distribution such as the one available from Shining Light Productions
• Expat - Provides support for XML. This library must be available if Voice XML (VXML) and XMPP functions are required. We recommend using a pre-packaged binary such as the ones available from the Expat SourceForge site.
• OpenLDAP - Provides support for the LDAP protocol as used by ILS and other network services. OpenLDAP requires OpenSSL to be installed. Detailed build instructions for OpenLDAP can be found here, or you can use use | these precompiled binaries
• SDL - Provides for support for fast drawing of video into windows. See the SDL home page for more information.
• Microsoft Speech API Provides text-to-speech functions. See the Microsoft information page for more information. Compiling Microsoft Speech API with Visual C++ 2005 requires some modifications to the "SpHelper.h" SAPI include file. See this thread in the Microsoft forum on this subject.
• DNS resolver This is required for the resolution of DNS MX and SRV records. The later versions of VS.net includes support for the DNS resolver, and this will be detected automatically by the PTLib configure process.
• IPV6 - VS.net includes support for IPv6, and this should be detected automatically by the PTLib configure process.

8. Build the PTLib Static project

Build the PTLib Static project to create a static code library containing all of the PTLib code. In Release mode, this will build the ptlibs.lib file. In Debug mode, this will build the ptlibsd.lib file.

Note that the first step of the build is the execution of the configure program which searches for optional components that may be installed on the host system.

IMPORTANT TIP: If configure finds options in directories not belonging to other compilers, such as Cygwin, MSys, MSVC 6, or the wrong version of VS.net, then please read section 10 "Tailoring the configure search path" below on how to tailor the configure search path

The compiler output will be similar to the belows (it will vary depending on options or build environment).

        ------ Build started: Project: PTLib, Configuration: Release Win32 ------
        Configuring Build Options
        Located Open LDAP at D:\openldap\
        Located Expat XML at D:\expat\
        Located Speech API at D:\Program Files\Microsoft Speech SDK 5.1\
        Searching C:\
        Searching D:\
        Located Cyrus SASL at D:\cyrus-sasl-2.1.12\
        Located Open SSL at D:\openssl-0.9.7\
        Located DNS Resolver at D:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\PlatformSDK\
        Located IPv6 Support at D:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\PlatformSDK\Include\
        Located QoS Support at D:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\PlatformSDK\Include\
        Searching E:\
        Byte Order set to PLITTLE_ENDIAN
        Semaphore Support enabled
        DNS Resolver enabled
        Cyrus SASL enabled
        Open LDAP enabled
        Open SSL enabled
        Expat XML enabled
        Speech API enabled
        IPv6 Support enabled
        QoS Support enabled
        Simple DirectMedia Layer disabled
        Memory check switch read enabled
        Configuration completed.
        Performing Custom Build Step
        ../common/getdate.y contains 8 shift/reduce conflicts and 18 reduce/reduce conflicts.
        Compiling...
        assert.cxx
        Compiling...
        notifier_ext.cxx
        mail.cxx

            ...lines deleted...

        Generating Code...
        getdate_tab.c
        Creating library...
        Build log was saved at "file://d:\ptlib\Lib\Debug\BuildLog.htm"
        Console - 0 error(s), 1 warning(s)

        ---------------------- Done ----------------------
        Build: 1 succeeded, 0 failed, 0 skipped

9. Build the PTLib DLL project

Build the PTLib DLL project to create a DLL code library containing all of the PTLib code. In Release mode, this will build the ptlib.dll file. In Debug mode, this will build the ptlibd.dll file.

NOTE: the Release version of the MergeSym project must be built before building PTLib DLL. Generally this will happen automatically through the solution dependencies, however if this does not occur and you get an error such as:

    'MergeSym' is not recognized as an internal or external command, operable program or batch file.

then right click on MergeSym project and build it manually.

The compiler output will be similar to the belows (it will vary depending on options or build environment).

        ------ Build started: Project: MergeSym, Configuration: Release Win32 ------
        Compiling...
        MergeSym.cxx
        Linking...
        Copying symbol merge utility to ptlib/lib directory.
        Build log was saved at "file://d:\ptlib\tools\MergeSym\Release\BuildLog.htm"
        MergeSym - 0 error(s), 0 warning(s)

        ------ Build started: Project: PTLib, Configuration: Release Win32 ------
        Performing Custom Build Step
        MergeSym version 1.4.0 on Windows 2000 by Equivalence
        No changes to symbols.
        Compiling...
        dllmain.cxx
        Compiling resources...
        Linking...
        Creating library .\..\..\..\Lib/PTLib.lib and object .\..\..\..\Lib/PTLib.exp
        Extracting debug symbols
        REBASE: Total Size of mapping 0x00000000000d0000
        REBASE: Range 0x0000000010000000 -0x00000000100d0000
        Build log was saved at "file://d:\ptlib\Lib\Release\BuildLog.htm"
        PTLib - 0 error(s), 0 warning(s)

        ---------------------- Done ----------------------
        Build: 3 succeeded, 0 failed, 0 skipped

10. Tailoring the configure search path

Occasionally, configure will incorrectly identify the location of installed packages, leading to compilation problems.

The most common reason is having multiple versions of Visual Studio installed at the same time, or using Cygwin headers, or using libraries from the Windows Mobile version of Visual Studio.

If you have compilation errors, check the .../ptlib/include/ptbuildopts.h file and look for where there are lines starting with #pragma include_alias(), the path included in that command should look sensible.

This problem is solved by setting environment variables to identify paths that should not be searched.

11. Notes on Windows Mobile

Windows Mobile 5.0 and 6.x are supported via Visual Studio 2005 only.

It is expected that the user knows how to get, and install, the SDK's for Windows Mobile, which is beyond the scope of this document!

When configuring directories as in step 6 above, you have to configure all the different Platform types. You use the same include directories as for Win32, however, for the library directories you should use: