 |
Building PWLib on Windows Craig Southeren Last updated 9 Feb 2007 |
Contents
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:
- MSVC 6, VS.net 2003, VS.net 2005 or Visual C++ 2005 Expresss Edition. Note that you cannot use the free VS.net 2003 available from Microsoft as support for configuring that compiler without the GUI has not
yet been completed. Visual C++ 2005 Expresss Edition is supported (follow the instructions for VS.net 2005)
- A copy of the PWLib source archive from the
OpenH323 SourceForge download page
or from CVS
- An archive extractor program that understand tar.gz files, and handles end of line characters correctly, like WinZIP
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
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.
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:
-
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
-
For MSVC 6, select "Options" from the "Tools" menu and add "C:\TOOLS" to the executable directory path as follows:
-
For VS.net, select "Options" from the "Tools" menu, and add " C:\TOOLS" to the executable directory path as follows:
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
Select "Tools" from the "Options" menu, and add the following directories settings as required
- Add installdir\PWLIB\INCLUDE to the Include directory list
- Add installdir\PWLIB\LIB to the Executable directory list
- Add installdir\PWLIB\LIB to the Library directory list
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 |
| 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 |
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.
- Open the file installdir\PWLIB\PWLIB.DSW
- Make sure the "File view" tab is selected in the Workspace
- Select the build type as "Win32 Release" or "Win32 Debug" in the Build toolbar
-
Right-click on "Console files" and select "Build" from the menu to build ptlibs.lib (or ptlibsd.lib if you are building the "Win32 Debug" version).
- The following should be displayed (note that your output may vary if you have different options or build environment):
--------------------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)
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:
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
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
- If present, right-click on "Console Components files" and select "Build" from the menu to build ptclib.lib (or ptclibd.lib if you are building the "Win32 Debug" version). The following should be displayed (note that your output may vary if you have different options or build environment):
--------------------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)
- Right-click on "PTLib files and select "Build" from the menu to build ptlib.dll (or ptlibd.dll if you are building the "Win32 Debug" version). The following should be displayed (note that your output may vary if you have different options or build environment). Note that MERGESYM will be automatically built the first time you build either ptlib.dll or ptlibs.dll, which may require also building the "Win32 Release" version of Console and Console Components if that was not done previously.
-------------------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
- Open the file installdir\PWLIB\PWLIB.SLN (for VS.net 2003) or
installdir\PWLIB\PWLIB_2005.SLN for VS.net 2005. Ignore any dialogs warning about projects such as "GUI.VCPROJ" not being found.
- Make sure the "Solution explorer" windows is displayed
- Select the build type as "Release" or "Debug" in the Build toolbar
-
Right-click on "Console" and select "Build" from the menu to build ptlibs.lib (or ptlibsd.lib if you are building the "Debug" version).
- The following should be displayed (note that your output may vary if you have different options or build environment):
------ 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
- If present, right-click on "Console Components" and select "Build" from the menu to build ptclib.lib (or ptclibd.lib if you are building the "Debug" version). The following should be displayed (note that your output may vary if you have different options or build environment):
------ 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
- Right-click on "PTLib" and select "Build" from the menu to build ptlib.dll (or ptlibd.dll if you are building the "Debug" version). The following should be displayed (note that your output may vary if you have different options or build environment). Note that MERGESYM will be automatically built the first time you build either ptlib.dll or ptlibs.dll, which may require also building the "Release" version of Console and Console Components if that was not done previously.
------ 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
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:
- When switching to a new compiler, it is not sufficient to use the "Clean" option to remove the compile files from the previous version. Specifically, this does not seem to remove the ".pdb" file which will
cause problems when creating DLLs.
One alternative is to delete the installdir\PWLIB\LIB directory before compiling with the new environment. This uses the least disk space, but requires a complete recompile every time compilers are switched.
My preferred option is to use different directory trees for the two different compilers, requiring different directories in the "Options" dialog for each environment. This allows switch between compilers much faster, although it requires twice the disk space. - When PWLib runs the configuration step at the beginning of building the "Console" project, each environment will occasionally find and use the wrong versions of some of Microsoft SDK libraries and include
files. To avoid this, the following environment variables can be used to prevent configure from searching for options in certain directories
Name Sample value MSVC_PWLIB_CONFIGURE_EXCLUDE_DIRS D:\Program Files\Microsoft Visual Studio .NET 2003 VSNET_PWLIB_CONFIGURE_EXCLUDE_DIRS C:\Program Files\Microsoft Visual Studio VSNET2005_PWLIB_CONFIGURE_EXCLUDE_DIRS C:\Program Files\Microsoft Visual Studio .NET 2005
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.
轉自：http://www.voxgratia.org/docs/pwlib_windows.html