Building PWLib on Windows
Craig Southeren
Last updated 9 Feb 2007

Contents

           1. Introduction
           2. Prequisites
           3. Download and install the PWLib source code
           4. Pre-compilation steps
           4a. Install GNU Bison
           4b. Check Visual C++  header files (MSVC 6 only)
           5. Configure directories
           6. Install optional packages used by PWLib
           7. Compiling
           7a. MSVC 6
           7b. VS.net 2003 and VS.net 2005 
           8. Compiling ASNParser
           9. Using MSVC 6, VS.net 2003 and VS.net 2006 on the same system
           10. Making the debugger show the value of PWLib types
           11. Using VS.net from the command line
Change history

1. Introduction

The process for building PWLib on Windows has been made substantially simpler since the build instructions on the OpenH323 site were written. This document provides a thorough description of the compilation process for both MSVC 6 and VS.net 2003  


2. Prerequisites

You will need the following to compile PWLib from source code:


3. Download and install the PWLib source code 

Download and extract the PWLib source code from the OpenH323 SourceForge download page. If extracting the source from an archive, it is important to use program that can correctly handle tar.gz files can correctly process end of line characters. We strongly recommend WinZIP - other programs may not correct process end of line characters and will cause problems in later stages.

For the purposes of this document, the directory that contains PWLIB will be indicated as installdir\PWLIB


4. Precompilation steps

There are several steps that need to be performed prior to compiling PWLib for the first time. Once finished, you will not need to do these again.  

4a. Install GNU bison

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

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

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

 

4b. Check Visual C++ header files

If you are only using Visual Studio.NET 2003 or VS.net 2005, then please continue to step 5 as this section only applies to the  MSVC 6 environment. 

There are several major defects in the STL header files shipped with MSVC 6. These defects are sufficient to crash programs (like PWLib) that rely on the correct behaviour of global static variables. Fortunately, the original authors of the STL libraries for MSVC have published new versions of the files necessary to correct the worst of these problems.

PWLib includes a program that checks the MSVC 6 header files installed on your system, and can upgrade the files if required. To run this program, find the file  installdir/MSVC_UPGRADE.BAT and run it by double-clicking on it. If your archive does not have this file, then download and unzip the upgrade package separately from http://www.voxgratia.org/releases/msvc6chk.zip and run the msvc6chk program with the command "msvc6chk upgrade".

You will see a screen similar to the following: 

PWLIB File Upgrader v1.0
Copyright (C) 2004 by Post Increment

WARNING: the following file requires upgrading:
C:\Program Files\Microsoft Visual Studio\VC98\INCLUDE\XTREE

The files presented here are copyright ⌐ 1995-2000 by P.J. Plauger.
All rights reserved. They are for use only in conjunction with a valid
license for Microsoft Visual C++ V5.0 or V6.0. Microsoft Corporation is in
no way involved with the production or release of these files. The files are
offered on an `as is' basis. DINKUMWARE, LTD. AND P.J. PLAUGER MAKE NO
REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THESE FILES, EITHER
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
DINKUMWARE, LTD. AND P.J. PLAUGER SHALL NOT BE LIABLE FOR ANY DAMAGES
SUFFERED BY LICENSEE AS A RESULT OF USING THESE FILES.

Upgrade file (y/n) ?

Press "y" to perform the upgrade of the MSVC header file. The following will be displayed:

Upgrade file (y/n) ? y
The following files have been upgraded
C:\Program Files\Microsoft Visual Studio\VC98\INCLUDE\XTREE
The previous version of the file has been renamed to
C:\Program Files\Microsoft Visual Studio\VC98\INCLUDE\XTREE.backup

You may be asked to upgrade several different files - we recommend upgrading them all unless you have a very good reason for not doing so.

If your files are already upgraded, you will see the following:

PWLIB File Upgrader v1.0
Copyright (C) 2004 by Post Increment
C:\Program Files\Microsoft Visual Studio\VC98\INCLUDE\XTREE already upgraded
Press any key to continue . . .

For more information on these upgrades, see http://www.dinkumware.com/vc_fixes.html. Note that a copy of the upgrade program provided with PWLib can be dowloaded from http://www.voxgratia.org/releases/msvc6chk.zip


5. Configure directories 

Select "Tools" from the "Options" menu, and add the following directories settings as required


6. Install optional packages used by PWLib

The PWLib build process will automatically detect 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 precompiled binaries below

Home page: http://www.openldap.org
CVS Location (new project files only): pwlib/tools/openldap-2.1.17-win32.zip
Precompiled library: openldap-2.1.17_bin.zip

SDL Provides for support for fast drawing of video into windows. See the SDL home page for more information
IPV6 VS.net already includes support for IPv6, and this will be detected automatically by the PWLib configure process
Support for IPV6 under MSVC 6 is available for  Windows 2000 and Windows XP. Details can be found on this page
MicroSoft Speech API Provides text-to-speech functions
See the Microsoft home page at http://www.microsoft.com/speech/download/sdk51 
DNS resolver This is required for the resolution of DNS MX and SRV records. 
VS.net already includes support for the DNS resolver, and this will be detected automatically by the PWLib configure process
To easiest way to get DNS resolver support with MSVC 6 is to install the Platform SDK

7. Compiling 

Regardless of the environment you are using, there are three different projects that can be built as either Debug or Release versions:

Name Description Debug version Release version
Console basic PWLib library as a static library ptlibsd.lib ptlibs.lib
PTLib basic PWLib library as a DLL  ptlibd.lib &
ptlibd.dll
ptlib.lib &
ptlib.dll
Console Components contains additional PWLib features. 
Only available as a static library
(this project was removed in releases of 
ptclibd.lib ptclib.lib

If you are using a release of PWLib prior to August 2006, there will also have another project:

Name Description Debug version Release version
Console Components contains additional PWLib features. 
Only available as a static library
(this project was removed in releases of 
ptclibd.lib ptclib.lib

The static libraries can be built independently, but building the DLLs requires building the "MERGESYM" utility first which depends on the Release version of the libraries.

7a. MSVC 6


--------------------Configuration: Console - Win32 Release--------------------
Configuring Build Options
PWLIB File Upgrader v1.0
Copyright (C) 2004 by Post Increment
C:\Program Files\Microsoft Visual Studio\VC98\INCLUDE\XTREE already upgraded
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:\
Located DNS Resolver at C:\Program Files\Microsoft Visual Studio\VC98\
Searching D:\
Located Cyrus SASL at D:\cyrus-sasl-2.1.12\
Located Open SSL at D:\openssl-0.9.7\
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 disabled
QoS Support disabled
Simple DirectMedia Layer disabled
Configuration completed.
Performing Custom Build Step on ..\common\getdate.y
../common/getdate.y contains 8 shift/reduce conflicts and 18 reduce/reduce conflicts.
Compiling...
assert.cxx
Compiling...
collect.cxx
contain.cxx
ethsock.cxx

     ...lines deleted....

regexec.c
regfree.c
Generating Code...
Creating library...

ptlibd.lib - 0 error(s), 1 warning(s)

IMPORTANT TIP #1

If you install the Microsoft Platform SDK, you may see the following:

Compiling...
assert.cxx
C:/Program Files/Microsoft SDK/include/winsock2.h(1218) : error C2061: syntax error : identifier 'DWORD_PTR'
C:/Program Files/Microsoft SDK/include/winsock2.h(1262) : error C2146: syntax error : missing ';' before identifier 'Key'
C:/Program Files/Microsoft SDK/include/winsock2.h(1262) : error C2501: 'ULONG_PTR' : missing storage-class or type specifiers
....

If this occurs, select "Options" from the "Tools" menu and ensure that the include and lib directories for the Platform SDK are before the VC98 include directories as follows:

 

IMPORTANT TIP #2

The compile may stop with the following message:

--------------------Configuration: Console - Win32 Release--------------------
Configuring Build Options
PWLIB File Upgrader v1.0
Copyright (C) 2004 by Post Increment
WARNING: the following file requires upgrading:
C:\Program Files\Microsoft Visual Studio\VC98\INCLUDE\XTREE
Please run "msvc6chk upgrade" to upgrade this file
Error executing c:\winnt\system32\cmd.exe.

ptlibs.lib - 1 error(s), 1 warning(s)

If this occurs, please re-read and re-run section 4b on upgrading the MSVC 6 header files

IMPORTANT TIP #3

If configure finds options in directories not belonging to other compilers, such as Cygwin,  MSys,  VS.net 2003 or VS.net 2005 then please read the section 4.32 of the Opal/OpenH323 FAQ  on how to tailor the configure search path   

--------------------Configuration: Console Components - Win32 Release--------------------
Compiling...
Cypher.cxx
Compiling...
Asner.cxx
delaychan.cxx
dtmf.cxx

   ...lines deleted...

Compiling...
ptts.cxx
Creating library...

ptclib.lib - 0 error(s), 0 warning(s)

-------------------Configuration: MergeSym - Win32 Release--------------------
Compiling...
MergeSym.cxx
Linking...
LINK : warning LNK4089: all references to "MPR.dll" discarded by /OPT:REF
LINK : warning LNK4089: all references to "SHELL32.dll" discarded by /OPT:REF
LINK : warning LNK4089: all references to "comdlg32.dll" discarded by /OPT:REF
Copying symbol merge utility to pwlib/lib directory.
--------------------Configuration: PTLib - Win32 Release--------------------
Merging exported library symbols
MergeSym version 1.4.0 on Windows 2000 by Equivalence
No changes to symbols.
Compiling resources...
Compiling...
dllmain.cxx
Linking...
Creating library ..\..\..\Lib/PTLib.lib and object ..\..\..\Lib/PTLib.exp
Extracting debug symbols
REBASE: Total Size of mapping 0x000d0000
REBASE: Range 0x10000000 -0x100d0000

PTLib.dll - 0 error(s), 3 warning(s)

7b. VS.net 2003 and VS.net 2005


------ Build started: Project: Console, 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:\pwlib\Lib\Debug\BuildLog.htm"
Console - 0 error(s), 1 warning(s)

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

IMPORTANT TIP

If configure finds options in directories not belonging to other compilers, such as Cygwin,  MSys,  MSVC 6, or VS.net 2005 then please  read the section 4.32 of the Opal/OpenH323 FAQ  on how to tailor the configure search path 

------ Build started: Project: Console Components, Configuration: Release Win32 ------
Compiling...
cypher.cxx
Compiling...
xmpp_roster.cxx
xmpp_muc.cxx
   ...lines deleted...
ptts.cxx
Creating library...
Build log was saved at "file://d:\pwlib\Lib\Debug\BuildLog.htm"
Console Components - 0 error(s), 0 warning(s)

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

------ Build started: Project: MergeSym, Configuration: Release Win32 ------
Compiling...
MergeSym.cxx
Linking...
Copying symbol merge utility to pwlib/lib directory.
Build log was saved at "file://d:\pwlib\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:\pwlib\Lib\Release\BuildLog.htm"
PTLib - 0 error(s), 0 warning(s)

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


8. Compiling ASNParser

If you are using PWLib 1.7/OpenH323 1.4 or later, or Janus patch 4, then you can skip this step.

If you are using PWLib 1.6/OpenH323 1.13 or earlier, or are not using Janus patch 4 or later, then you will need to compile the release mode version of ASN Parser which is provided as part of PWLib.  Without this, you will encounter like those shown below when compiling OpenH323:

This program cannot be run in DOS mode.
Error executing c:\windows\system32\cmd.exe.
 
asnparser.exe - 1 error(s), 0 warning(s)

To compile the ASN Parser, right click on the "ASNParser" project and Select "Build".


9. Using MSVC 6, VS.net 2003 and VS.net 2005 on the same system

It is possible to have compile PWLib with MSVC 6 and VS.net 2003 or VS.net 2005 on the same system, provided you know about several tricks:

Note that the configure.exe supplied prior to PWLib 1.7/OpenH323 1.14 does not support these variables.:


10. Making the debugger show the value of PWLib types

It is possible to make the MSVC and VS.net debuggers show the value of PWLib types either in hover text or in watch lists, as show below:

 

To do this, locate the file AUTOEXP.DAT for your environment as follows:

MSVC 6 C:\Program Files\Microsoft Visual Studio\Common\MSDev98\Bin\autoexp.dat
VS.net 2003 C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\Packages\Debugger\autoexp.dat
Visual C++ Express C:\Program Files\Microsoft Visual Studio 8\Common7\Packages\Debugger\autoexp.dat

For MSVC 6, open the file in a text editor and add the following lines to the end of the file: 

; for PTLib
PObject =<,t>
PString =<theArray,s>
PCharArray =<theArray,s>
PContainer=<,t> size=<reference->size> ref=<reference->count>
PAbstractArray =<,t> size=<reference->size> ref=<reference->count>
PArrayObjects =<,t> size=<theArray->reference->size> ref=<reference->count>
PIPSocket::Address = <v.four.S_un.S_un_b.s_b1,u>.<v.four.S_un.S_un_b.s_b2,u>.<v.four.S_un.S_un_b.s_b3,u>.<v.four.S_un.S_un_b.s_b4,u>
PTimeInterval = <milliseconds>
PTime = <theTime>

For VS.net, make sure these lines above are added before the [hresult] section, so that it looks as follows:

; for PTLib
PObject =<,t>
PString =<theArray,s>
PCharArray =<theArray,s>
PContainer=<,t> size=<reference->size> ref=<reference->count>
PAbstractArray =<,t> size=<reference->size> ref=<reference->count>
PArrayObjects =<,t> size=<theArray->reference->size> ref=<reference->count>
PIPSocket::Address = <v.four.S_un.S_un_b.s_b1,u>.<v.four.S_un.S_un_b.s_b2,u>.<v.four.S_un.S_un_b.s_b3,u>.<v.four.S_un.S_un_b.s_b4,u>
PTimeInterval = <milliseconds>
PTime = <theTime>

; This section lets you define your own errors for the HRESULT display.
; You need to list the error code in unsigned decimal, followed by the message.
; Changes will take effect the next time you redisplay the variable.
[hresult]
;1234=my custom error code

Restart MSVC or VS.net, and the values of PWLib variables will now be displayed in the debugger.


11.Using VS.net from the command line

The VS.net compiler can be invoked from the command line without the GUI using the "devenv" program with the /build option. To do this, open a command window using the "Open Visual Studio .NET 2003 Command Prompt" shortcut or open a normal command window and execute the correct "vcvars32.bat" file.

The following command shows how to build the "Console"  project in Debug mode using the pwlib.sln solution file:

devenv /build Debug /project "Console" pwlib.sln

The following command will build all of the pwlib projects in Debug mode using the pwlib.sln solution file:

devenv /build Debug pwlib.sln


Change History

9 Feb 2007 Craig Southeren Added location of autoexp.dat on VC++ Express
23 July 2006 Craig Southeren Changed to reflect removal of ptclib in latest builds
29 June 2006 Craig Southeren Added information on pre-packaged binaries for OpenSSL and Expat
26 June 2006 Craig Southeren Added tip#3 on configure search paths and info on VS.net 2005
24 May 2006 Craig Southeren Added note to 4a on not installing bison/flex in directories other than C:\TOOLS. Thanks to Jayme Pechan
3 October 2005 Craig Southeren Fixed up typos in static/dynamic library names
15 February 2005 Craig Southeren Added info on promoting lib directory when using the platform SDK with MSVC
16 November 2004 Craig Southeren Added command line build information  
1 November 2004 Craig Southeren Updated to OpenSSL 0.9.7.e  
25 September 2004 Craig Southeren Fixed bad link to OpenSSL build instructions 
25 August 2004 Craig Southeren Added information on not installing bison into a path containing spaces
16 August 2004 Craig Southeren Added information on downloading msvc6chk separately if needed
Added notes on options included with VS.net
11 July 2004 Craig Southeren Added information on using MSVC6 and VS.net on same system prior to PWLIB 1.7
Added information on compiling ASNParser
3 July 2004 Craig Southeren Added information on MSVC 6 header upgrades
11 June 2004 Craig Southeren Fixed download links
10 June 2004 Craig Southeren Fixed locations of images
10 June 2004 Craig Southeren Initial version

Copyright 2003-2007 by Post Increment A.B.N 95 856 785 279
All Rights Reserved
All trademarks and copyrights on this page are owned by their respective owners.