# Developer Notes

This file contains notes, hints and information of interest to people who wish to compile the Windows version of PasswordSafe.

### Contents

1. Software Requirements
2. XML Processing
3. Minidumps

### Software Requirements

The Windows version of PasswordSafe is currently built using Microsoft Visual Studio 2005 and 2008. People have also reported success in building PasswordSafe using Visual Studio Express (free edition), but that configuration is not described here.

In order to build the Windows version of Password Safe, you need to install the following freely available components, in addition to Visual Studio:

- Microsoft's Windows SDK. If you have installed Visual Studio 2008, it will have installed a Windows SDK V6.0A and you do not have to install another SDK. If you haven't installed VS2008, then please select either of the following versions:
  - "Windows Vista Update & .NET 3.0 SDK" [V6.1.6000.16384.10 dated February 2007] - known as V6.0.
  - "Windows Server 2008 and .NET Framework 3.5" [V6.0.6001.18000.367 dated February 2008] - known as V6.1.
  All three of these replace the old "Platform SDK" and support Operating Systems: Vista and Windows XP; and Development Environments: Visual Studio 2005 & 2008. Later versions support Windows 7 but not Visual Studio 2005. At this time, Password Safe does not use any facilities or functions that are not supported by Windows XP and Visual Studio 2005.
  By default, the SDKs are installed in directory "C:\Program Files\Microsoft SDKs\Windows\NNN", where NNN is '6.0', '6.0A' or '6.1'. See note below.
- To complie and produce the Help files (.chm) then Microsoft's HTML Help Workshop is required. Note however that the headers and libraries necessary for compiling Password Safe itself are included in the Windows SDK mentioned above.
- Tortoise SVN Client (for updating the revision number within Password Safe's version details)
- For XML Support, one or more of the following is needed (see the XML processing section for more details):
  - Headers and libraries to support Microsoft's XML V6.0 are included in the Windows SDK mentioned above and do not need to be installed separately.
  - Expat's V2.0.1 XML Library
  - Xerces V3.0.1 XML Library

SDK NOTE: In order to compile Password Safe using MFC (Microsoft's Foundation Classes), the Microsoft Windows SDK's 'include' and 'lib' directories must be added to the directories supplied by Visual Studio 2005. This is achieved in VS2005 via Tools > Options > Project and Solutions > VC++ directories > Include files and Library files. They can be added at the end of each appropriate set using the directory you specified during installion (the defaults are: "C:\Program Files\Microsoft SDKs\Windows\NNN\Include" and "C:\Program Files\Microsoft SDKs\Windows\NNN\Lib", where NNN is 6.0, 6.0A or 6.1 as noted above). The Microsoft Visual Studio Registration Tool only adds the .Net libraries and not those needed for Password Safe. It is recommended that you get SDK V6.1 and you place them above the libraries supplied with Visual Studio e.g. "$(VCInstallDir)PlatformSDK\include" and "$(VCInstallDir)PlatformSDK\lib" otherwise you may get warning messages compiling source members using BlockInput.

Compiling using Visual Studio: If you're using Microsoft's Visual Studio, the file "UserVariables.vsprops" must exist and point to the directories where the non-"Windows SDK" components have been installed. The solution will not open correctly without this file being present. For your convenience, we've included a simple Visual Basic script, "configure.vbs", that you can run to generate the "UserVariables.vsprops" file with the correct values.

### XML Processing

Originally, PasswordSafe used Microsoft's XML library for XML parsing and validation. For portability, we're now working on support for the Expat and Xerces XML libraries, which are available for non-Windows platforms. See their web sites for more information. Note: Xerces V3.0.0 at revision 707374 or greater is needed to correct a memory leak processing password history entries (we recommend the latest version - currently 3.0.1 as of September 2009).

To determine which XML library to use while building PasswordSafe, we've defined a preprocessor variable (USE_XML_LIBRARY). If NOT defined, the compiled Password Safe will not process XML files (databases or filter definitions in XML format). Filters within a database will be treated as 'Unknown Fields' and will remain unchanged so that other versions of Password Safe that do support XML parsing can still use them. Note, however, that the application will be able to write XML files.

The three valid values of the USE_XML_LIBRARY variable are "EXPAT", "MSXML" and "XERCES" corresponding to the three different implementations.

Password Safe uses SAX2 processing for both Microsoft's and the Xerces' XML Parsers, which are full validating parsers and require the presence of the appropriate XSD Schema file (included in the distribution and in the "xml" sub-directory, to process either file or filter imports. This ensures that the data eventually hitting the SAX2 content handlers is correct and just needs placing in the appropriate fields.

Expat is a non-validating XML Parser and uses its own API rather than SAX2. Note: SAX2 is only an official standard for Java XML processing, although many C supporting parsers also support this interface. Because Expat is non-validating, code is being added directly into Password Safe to perform this validation, so that the program and its databases are not corrupted by poorly formed XML or incorrect data within the XML file.

Note: As of 1 December 2008, the additional validation code for Expat and non-Unicode versions of all three implementations are in progress. Work is also needed to ensure that error processing is correct and that associated messages are produced correctly.

### Minidump Production

In order to help debug user problems when Windows justs says "there has been an error", a "Windows Unhandled Fault Handler" has been added. This will create a minidump, which can then be used to find where the error took place and, hopefully, why.

An extra "extended" Command Line flag of "--testdump" has been introduced for two reasons. Firstly, it allows the developer to test the minidump process, which is only available in the Release version of the executable and, secondly, allows the translators to check that the error screen displays as they wish.

Note to Translators: the error screen is a basic Windows function and has a fixed width. This is the reason why the minidump file name and directory have been split onto separate lines.

Note: Extended flags start with two minus signs ('--') and must be specified in full - i.e. no abbreviations. They are not displayed in the Usage notes for the normal users and no error message or display is shown if they are not recognised.

With this flag set, there will appear an extra button in the bottom right hand corner of the "About PasswordSafe" dialog. Click it, and a minidump should be produced.

In order to process the minimdump, either the free Microsoft Windbg program can be used (see Microsoft's site for details), or Visual Studio (VS) can be used. In the latter case (and probably the former too!):

1. You need the source corresponding to the failing release version. This should be available from SourceForge web site either in the normal Download section or from the Subversion repository, based on the revision number associated with that release. Without the corresponding source, VS can only show Windows source and line numbes in PasswordSafe source. With the corresponding source, VS can show you the exact line in PasswordSafe where the error took place and also the other statements within PasswordSafe as you follow the stack trace.
2. You need the Program Debug Database (pwsafe.pdb) associated with the failing release. This is not normally uploaded to the SourceForge web site with the release package. It is large (~11.5MB or ~3MB compressed). Since this must correspond to the PasswordSafe executable that had the error, maybe this and, possibly, the associated Link Map can be uploaded to a Developers section on this web site to aid all developers.
3. You should probably maintain the directory structure of the project as described in the source downloaded from SourceForge and place the Program Debug Database file in the '..\src\bin\releasem' directory.
4. Save the user's minidump file on your PC. Use VS to Open this as a Project (e.g. File->Open->Project/Solution).
5. In the Debugging Options, specify the directory containing the corresponding PDB file. (Go to: Tools->Options->Debugging->Symbols and add this directory in the section entitled "Symbol file (.pdb) locations:").
6. Press F5 to start debugging, and away you go.