Developer Notes

This file contains notes, hints and information of interest for those developers wishing to compile PasswordSafe for Windows. Linux developers should read the file README.LINUX.DEVELOPERS.txt.

Contents

  1. Introduction
  2. Software Requirements
  3. XML Processing
  4. Gtest
  5. Minidumps

Introduction

There are several 'degrees of freedom' for Windows developers:

  1. Development tools: Microsoft's Visual Studio 2013 (referred to as 'VS2013' below) is currently the main development environment, and pwsafe-12.sln is the main toplevel "solution" file (the 12 refers to the version of the C++ compiler). Visual Studio 2012 (referred to as 'VS2012' below) is also still maintained. Its solution and project files have a suffix of "-11" corresponding to the version of the C++ compiler (VC11).
  2. pwsafe_wx-12.sln is used to build the wxWidgets version under Windows, although this version is not formally supported under Windows (but see the note re: Visual Express below). Note: the wxWidgets library must be built with the same version of Visual Studio as being used to build PasswordSafe or you will receive numerous compatibility error messages during the link phase.
  3. Previous versions i.e. Visual Studio 2005 (MSVS8) and 2010 (MSVS10) are no longer maintained but their solution and project files have been retained in the "old-sln" directory. See note below for Visual Express users.
  4. User interface library: The currently supported version of PasswordSafe for Windows is built upon MFC (Microsoft's Foundation Classes). The wxWidgets version, which provides cross platform support can also be built on Windows and corresponds to that used on other platforms i.e. Linux and MAC OS. Note that the wxWidgets version in all environments does not support all features supported by the Windows MFC version, for example, different alphabet virtual keyboards. If you depend on such features, you should stick to the standard MFC build.
  5. XML support: As PasswordSafe provides XML import/export capabilities, it can be configured to use one of several XML parsers (or none). The currently supported version of PasswordSafe for Windows is built using the Microsoft XML parser.

Note regarding Visual Express: The MFC version of PasswordSafe cannot be built using Visual Express, as Microsoft does not provide MFC support in this product. It should, however, be possible to build the wxWidgets version.

To summarise: The 'official' version of PasswordSafe on Windows platforms is based on MFC (Microsoft's Foundation Classes), and uses Microsoft's XML parser. This corresponds to the ReleaseM configuration in the build environment, i.e., the release build using Microsoft's XML parser. This will build the required DLLs using their Release configuration (pws_at.dll for AutoType support and pws_osk.dll for the Virtual Keyboard) and the base resource DLL (pwsafe_base.dll used to create non-English language support).

The Visual Studio 2012 and 2013 projects have been updated to be able to generate the 64-bit versions of both the MFC and wxWidgets. This has only been tested on a 64-bit Windows environment with the VC10 64-bit compiler. It has not been tested on a 32-bit Windows environment with a cross-compiler. For wxWidgets, you will need the 64-bit static libraries and they should be placed in a new directory 'lib64\vc_lib' corresponding to the current 'lib\vc_lib' for the 32-bit versions. If you continue to use VS2005, you should put the static libraries built by it in '\lib\vc8_lib'.

For each Configuration there is an associated platform. Unfortunately, Visual Studio adds all defined platforms to all defined configurations even if a particular combination is not valid. The supported combinations are:

No other combinations are supported or have been tested.

The current MFC configurations are:

The current wxWidgets configurations are:

Note that the core and os project files contain all of the above projects, even if you are only selecting one of the MFC or the wxWidget builds. You should not have to select them individually as selecting the main PasswordSafe configuration will select the correct configuration for these projects. You should also be careful not to select all configurations in the Visual Studio Batch Build process either to build, rebuild or clean all configurations. Only select MFC configurations if using the MFC PasswordSafe solution (pwsafe-12.sln) and the wxWidgets configurations if using the wxWidgets PasswordSafe solution (pwsafe_wx-12.sln).

Software Requirements

Getting Source code

The source code for PasswordSafe may be downloaded as a zip file, or retrieved from the git repository via
git clone https://github.com/pwsafe/pwsafe.git
Currently, the Windows version is built using Microsoft's development tools as described below.

If you're going to commit code to the repository, please set your subversion client's configuration file as follows:

In the "[miscellany]" section, ensure the following variable is set to 'yes':

  enable-auto-props = yes

In the "[auto-props]" section, add the following if not already there:

  *.c = svn:eol-style=native
  *.cmd = svn:eol-style=native;svn:mime-type=text/plain
  *.cpp = svn:eol-style=native
  *.cs = svn:eol-style=native
  *.csproj = svn:eol-style=native
  *.dsp = svn:eol-style=CRLF
  *.dsw = svn:eol-style=CRLF
  *.h = svn:eol-style=native
  *.hhc = svn:eol-style=native
  *.hhk = svn:eol-style=native
  *.hpp = svn:eol-style=native
  *.html = svn:eol-style=native;svn:mime-type=text/html
  *.ico = svn:mime-type=image/x-icon
  *.in = svn:eol-style=native
  *.inc = svn:eol-style=native
  *.ini = svn:eol-style=native
  *.iss = svn:eol-style=native
  *.jpg = svn:mime-type=image/jpeg
  *.js = svn:eol-style=native
  *.linux = svn:eol-style=native
  *.manifest = svn:eol-style=CRLF
  *.nsi = svn:eol-style=CRLF
  *.pjd = svn:eol-style=native
  *.pl = svn:eol-style=native
  *.png = svn:mime-type=image/png
  *.po = svn:eol-style=native
  *.rc = svn:eol-style=native
  *.rc2 = svn:eol-style=native
  *.resx = svn:eol-style=native
  *.sh = svn:eol-style=native;svn:executable
  *.sln = svn:eol-style=CRLF
  *.txt = svn:eol-style=native;svn:mime-type=text/plain
  *.vbs = svn:eol-style=native
  *.vcproj = svn:eol-style=CRLF
  *.windows = svn:eol-style=native
  *.wxs = svn:eol-style=native
  *.xml = svn:eol-style=native;svn:mime-type=text/xml
  *.xpm = svn:mime-type=image/x-xpm
  *.xsd = svn:eol-style=native
  *.xsl = svn:eol-style=native
  LICENSE = svn:eol-style=native;svn:mime-type=text/plain
  Makefile = svn:eol-style=native;svn:mime-type=text/plain
  README = svn:eol-style=native;svn:mime-type=text/plain

(This file is ~/.subversion/config for Linux, and under Documents and Settings\user\Application Data\Subversion\config on Windows. If using Tortoise SVN client under Windows, this can be accessed by right clicking a file, selecting Tortoise SVN and then select Settings from the menu and using the Edit button in the General Settings panel).

Windows Build

The Windows version of PasswordSafe can be built using Microsoft Visual Studio 2013 (C++ compiler for PaswordSafe ('VC12') and C# compiler if you wish to re-generate the Virtual Keyboard data, which is not normally necessary). The Visual Studio Express compiler does not support Microsoft's Foundation Classes, which are used extensively within the current official Windows version. Visual Studio 2012 / VC11 is also supported, although no longer the main development environment.

The main (toplevel) Microsoft Visual Studio 2013 solution file is pwsafe-12.sln.

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

SDK & WDK NOTE: In order to compile PasswordSafe using MFC, the Microsoft Windows SDK's 'include' and 'lib' directories must be added to the directories supplied by Visual Studio. In addition, since the implementation of support for the YubiKey hardware, the Windows Driver Kit must also be installed and its libraries made available to Visual Studio. For VS2012, WDK 7.1A is required and, for VS2013, WDK V8.1A. Note due to an incompatibility between WDK 7.1A and SDK 7.1 for VS2012, an include file must be deleted from the installed WDK V7.1A (see the Readme.txt file in the src/os/windows/yubi directory for more details). This is not required if using VS2013 and WDK 8.1.

Compiling using Visual Studio: If you're using Microsoft's Visual Studio, the file "UserVariables-12.props" for VS2013, or "UserVariables-15.props" for VS2015 must exist and describe 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 simple Visual Basic scripts, "configure-12.vbs" and "configure-14.vbs" for VS2013 ans VS2015, respectively, in the src/ui/Windows directory (src/ui/wxWidgets directory for the wxWidgets builds), that you can run to generate the above file with the correct values. These script will also prompt for the location of the 64-bit Xerces libraries for 64-bit builds. When migrating from VS2013 to VS2015, ensure that you run the configure-14.vbs in order to add the location of the Windows Driver Kit for a successful build of the YubiKey library.

XML Processing

Originally, PasswordSafe used Microsoft's XML library for XML parsing and validation. For portability, we're now support the Xerces XML libraries, which are available for non-Windows platforms. We recommend the latest version (currently 3.1.3 as of April 2016). For VS2015 (VC14), you will need to copy and modify the directory ..\xerces-c-3.1.3\projects\Win32\VC12 to ..\xerces-c-3.1.3\projects\Win32\VC14 and open the solution file xerces-all.sln in subdirectory xerces-all and let VS2015 convert the project. You only need to build the project "Static Debug" and/or "Static Release" configurations of project XercesLib. Note: for 64-bit Xerces builds, you must use the 64-bit versions of the Xerces libraries.

It is important that you have the Xerces libraries built with the same version of Visual Studio as you are using to build PasswordSafe. You will receive numerous error messages during the link stage if they are not the same. The same applies to the wxWidgest library if building that version of PasswordSafe under Windows.

To determine which XML library to use while building PasswordSafe, we've defined a pre-processor variable (USE_XML_LIBRARY). If NOT defined, the compiled PasswordSafe 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 PasswordSafe that do support XML parsing can still use them. Note, however, that the application will be able to write XML files.

The two valid values of the USE_XML_LIBRARY variable are "MSXML" and "XERCES" corresponding to the three different implementations. For wxWidgets builds, only XERCES will be possible but they are still under development (as of August 2010).

PasswordSafe 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.

Gtest framework

The following instructions were written for version 1.7.0 of gtest.

PasswordSafe uses the gtest framework in the DebugM build - specifically the DebugM build of the coretest project.

To generate the required library, open gtest.sln in the "msvc" sub-directory in the gtest directory.

You only need to build the Debug version of gtest library (gtestd.lib) in the gtest project of the solution "gtest.sln". PasswordSafe does not use the "gtest-md.sln" solution nor following projects in gtest.sln:

  1. gtest_main
  2. gtest_prod_test
  3. gtest_unittest

The following changes should be made to the (converted) project file:

  1. Configuration Properties: General: (where NN is 12 for VS2013 & 14 for VS2015)
  2. Configuration Properties: C/C++: General
  3. Configuration Properties: C/C++: Output Files

Please remember to (re-)run the PasswordSafe configure-12.vbs or configure-14.vbs script to set the necessary gtest include and library directories. These would normally be the subdirectories "include" and either "build-vc12" or "build-vc14" of the "gtest-1.7.0" directory.

Note: you can also make the similar changes to those above in the projects not used by PasswordSafe in gtest.sln if you wish to run the gtest Test programs.

Minidump Production (Windows only)

In order to help debug user problems when Windows just 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, an extra button will appear in the bottom right hand corner of the "About PasswordSafe" dialog. Click it, and a minidump should be produced.

In order to process the minidump, 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 numbers 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.

No Longer Maintained Visual Studio Development Environments (Windows only)

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:

All these replace the old "Platform SDK" and support Operating Systems: Vista and Windows XP; and Development Environments: Visual Studio 2005 and 2008. However, V7.0 and later support Windows 7 but not Visual Studio 2005. At this time, PasswordSafe 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', '6.1' or '7.0'. See note below.

SDK NOTE: In order to compile PasswordSafe using MFC, the Microsoft Windows SDK's 'include' and 'lib' directories must be added to the directories supplied by Visual Studio. 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 installation (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, 6.1 or 7.0 as noted above). The Microsoft Visual Studio Registration Tool only adds the .Net libraries and not those needed for PasswordSafe. 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.

*** End of Developer Notes ***