This file contains notes, hints and information of interest for those developers wishing to compile Password Safe for Windows. Linux developers should read the file README.LINUX.DEVELOPERS.md.
With Visual Studio 2015, Microsoft released the free Community Edition and it supports their MFC (Microsoft's Foundation Classes), unlike the previous Express editions, enabling Password Safe to be built using it. They have also released the same edition with the new Visual Studio 2017 (see note below re: minimum installation requirements for Visual Studio 2017).
To summarise: The 'official' version of Password Safe on Windows platforms is based on MFC (Microsoft's Foundation Classes), and uses Microsoft's XML parser. This corresponds to the Release 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 2015 and 2017 projects have been updated to be able to generate the 64-bit versions of both the MFC and wxWidgets Password Safe executable. This has only been tested on a 64-bit Windows environment with the VC14 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\vc140_lib' corresponding to the current 'lib\vc140_lib' for the 32-bit versions.
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:
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 wxWidgets builds. You should not have to select them individually as selecting the main Password Safe 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 Password Safe solution (pwsafe-14.sln) and the wxWidgets configurations if using the wxWidgets Password Safe solution (pwsafe_wx-14.sln).
After downloading the installation a stub from Microsoft (vs_Community.exe), on executing it, you are offered a number of development environments and, after selection, a number of optional items. Obviously, you can include a larger number of options than are required to build Password Safe if you perform other developement projects.
For Password Safe the following are required:
Microsoft has a number of numbering systems.
However, for Visual Studio 2017, Microsoft decided to change this. Although, one would expect the complier version for this edition to be 15, Microsoft decided to make it 14.1 and so the Platform Toolset has a value of 141. In addition, it decided to set the variable _MSC_VER to 1910. Furthermore, if and when they release VS2017 Update 1, the value of _MSC_VER will change to 1911 etc. for Update 2, 3 .... They say that this is to allow developers to decide what new features an update provides to include in their project.
Password Safe doesn't use the actual value of _MSC_VER and only in 2 files (as of March 2017), although pugixml (used to parse the application preferences from the configuration file) does check that that it is greater than 1300 or 1600 and so the new value of this pre-processor variable should not affect Password Safe.
To keep with Password Safe numbering, the VS2017 solution and project files will be named with suffix "15" even though the projects will refer to Platform Toolset of 141 internally. The Platform Toolset will be incremented as and when Microsoft release updates to VS2017. In general, we keep which-ever Visual Studio version we use fully up to date to ensure bugs that affect the quality of the generated application are fixed, rather than to utilise new features.
The source code for Password Safe 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 git client's configuration file as follows:
In the file ".gitconfig"
[core] autocrlf = true safecrlf = warn
(This file under "C:\Users\<username>\" on Windows 7 and later. If using TortoiseGit client under Windows, this can be accessed by right clicking a file, selecting TortoiseGit and then select Settings from the menu. Within the "Git" setting "Config source", select the "Global" radio button and then set the "AutoCrlf" checkbox and set "SafeCrlf" to "warn". Alternatively, you can click the button "Edit global .gitconfig" to change the file manually).
For Windows, when installing "Git for Windows" (required by TortoiseGit and most other Git clients), ensure that you select "Checkout as-is, Commit as-is" to prevent incorrect line endings.
The Windows version of Password Safe can be built using Microsoft Visual Studio 2015 (C++ compiler for Password Safe ('VC14') and C# compiler if you wish to re-generate the Virtual Keyboard data, which is not normally necessary).
The main (top level) Microsoft Visual Studio 2015 solution file is pwsafe-14.sln.
In order to build the Windows version of Password Safe, you need to install the following freely available components, in addition to 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 VS2015 and VS2017, WDK V8.1 should be used. This is normally installed as part of the Visual Studio installation.
Originally, Password Safe used Microsoft's XML library for XML parsing and validation. For portability, we're now support the Xerces XML libraries, which are also available for non-Windows platforms. We recommend the latest version (currently 3.1.4 as of March 2017). For VS2015 (VC14), you will need to copy and modify the directory ..\xerces-c-3.1.4\projects\Win32\VC12 to ..\xerces-c-3.1.4\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. See note below re: building Xerces XML libraries with Visual Studio 2017.
It is important that you have the Xerces libraries built with the same version of Visual Studio as you are using to build Password Safe. You will receive numerous error messages during the link stage if they are not the same. The same applies to the wxWidgets library if building that version of Password Safe under Windows.
To determine which XML library to use while building Password Safe, we've defined a pre-processor 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 two valid values of the USE_XML_LIBRARY variable are "MSXML" and "XERCES" corresponding to the two different implementations. For wxWidgets builds, only XERCES will be possible.
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.
Google Test (gtest) is a popular unit
testing framework for C++ programs. PasswordSafe uses this
framework in the 'coretest' project for unit and regression
testing of the core functionality.
The recommended way to use gtest is via the Cmake build:
Generating the .sln file using cmake will add the gtest project under
PasswordSafe and support building the 'coretest' project that uses it
for unit tests of the core library.
It is possible to build gtest externally and link coretest into the
gtest library. This requires setting up the compilation flags on
gtest to match those used by PasswordSafe, and 'pointing'
PasswordSafe to the include files and libraries via the
configure-NN.vbs script
We have provided Visual Studio 2017 solution and project files to build the necessary Xerces libraries under Windows. They are in a zip file in the Misc/Xerces 3.1.4 subdirectory. Please follow the instructions in the Notes.txt file. Note: the Xerces solution has a large number of projects - most are not needed. Once the solution is loaded, the only project that needs to be built is "XercesLib". There are multiple configurations available but, again, the only configurations required are: "Static Debug" and "Static Release" for platforms x86 and x64. The resulting libraries should be moved into the directories specified in the UserVariables-15.props file. The x86 Static Debug and Static Release versions should be in the same x86 directory and x64 Static Debug and Static Release versions should in the same x64 directory.
The wxWidgets is used for the non-Windows User Interface but it can also be used under Windows. After downloading from the wxWidgets web site (currently V3.0.2), there are solution and project files up to Visual Studio 2013. However, we have provided a solution and associated project files for Visual Studio 2017 in the Misc/wxWidgets_VS_Updates directory. Please follow the instructions in the Notes.txt file in that directory.
You will need to build the Debug and Release versions for x86 and x64. The resulting libraries
will then need to be copied to a different location (or their directory names renamed from vc_lib and vc_64_lib to vc150_lib and vc150_64_lib respectively. Previous wxWidgets generation was via a batch command but Microsoft has not implemented the System Environment variable for VS2017 that would allow this to be used.
MSI installer files for the x86 and x64 platforms can be created using the Wix Toolset. The current version is 3.10. The Wix Toolset is available at http://wixtoolset.org/releases/
To build the MSI files, open a command prompt and change to the root directory of your source tree. Run the following command.
install\windows\BuildWixInstall.bat
This will build MSI files for both x86 and x64 platforms in the root directory. The program version specified in version.mfc will be applied to the .msi file.
pwsafe.msi pwsafe64.msi
You can build the files individually this way.
install\windows\BuildWixInstall.bat x86 install\windows\BuildWixInstall.bat x64
If you need to work on the Wix script (.wxs file), you can find it in the install\windows directory.
pwsafe-template.wxs
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 Password Safe" 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!):
*** End of Developer Notes ***