text: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  <html>
  <head>
  <title>Readme For Developers</title>
  </head>
  
  <body>
  
  <h1>Developer Notes</h1>
  
  <p>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
  <a href="README.LINUX.DEVELOPERS.md">README.LINUX.DEVELOPERS.md</a>.</p>
   
  <h3>Contents</h3>
  
  <ol>
  <li><a href="#Introduction">Introduction</a></li>
  <li><a href="README.WINDOWS.DEVELOPERS.html#InstallingVS2017">Installing Microsoft Visual Studio 2017
  Community Edition</a></li>
  <li><a href="README.WINDOWS.DEVELOPERS.html#Versions">Microsoft Visual Studio Numbering Systems</a></li>
  <li><a href="README.WINDOWS.DEVELOPERS.html#Software_Requirements">Software Requirements</a></li>
  <li><a href="README.WINDOWS.DEVELOPERS.html#Windows_Build">Building the Windows Version of Password Safe</a></li>
  <li><a href="README.WINDOWS.DEVELOPERS.html#XML_Processing">XML Processing</a></li>
  <li><a href="README.WINDOWS.DEVELOPERS.html#Gtest">Gtest</a></li>
  <li><a href="README.WINDOWS.DEVELOPERS.html#Xerces">Building Xerces XML Parser for Windows</a></li>
  <li><a href="README.WINDOWS.DEVELOPERS.html#wxWidgets">Bulding the wxWidgets User Interface for Windows</a></li>
  <li><a href="README.WINDOWS.DEVELOPERS.html#Wix_MSI_Installer">Wix MSI Installer</a></li>
  <li><a href="README.WINDOWS.DEVELOPERS.html#Minidump_Production">Minidumps</a></li>
  </ol>
  
  <h3><a name="Introduction"></a>Introduction</h3>
  <p>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 <a href="#InstallingVS2017">note</a>
  below re: minimum installation requirements for Visual Studio 2017).</p>
  <ol>
  <li>Development tools: Microsoft's Visual Studio <i>2015</i> (referred to as 'VS2015' below)
  is currently the main development environment, and pwsafe-14.sln is the main top level "solution"
  file (the <em>14</em> refers to the version of the C++ compiler).</li>
  <li>The new Visual Studio 2017 solution and project files (referred to as 'VS2017' below) have also
  been provided but Password Safe is not currently being built using this for official releases.
  The associated files end with <i>15</i> (see <a href="#Versions">note</a> below re: Microsoft's insane
  numbering system).</li>
  <li>pwsafe_wx-14.sln is used to build the wxWidgets version under Windows, although this build is not
  formally supported. Note: the wxWidgets library must be built with the same version of
  Visual Studio as being used to build Password Safe or you will receive numerous compatibility
  error messages during the link phase.</li>
  <li>The current version of wxWidgets for Windows is 3.0.2</li>
  <li>Previous versions of Visual Studio, i.e., Visual Studio 2005 (MSVS8), 2010 (MSVS10), 2012 (MSVC11) and 2013 (MSVS12)
  are no longer maintained, but their solution and project files have been retained in the "old-sln"
  directory. <i>Note, however, that they are no longer able to build the current MFC or wxWidgets versions
  of Password Safe due to the use of newer C++11 and C++14 features within the code.</i></li>
  <li>User interface library: The currently supported version of Password Safe 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.</li>
  <li>XML support: As Password Safe provides XML import/export capabilities, it
  can be configured to use one of several XML parsers (or none).
  The currently supported version of Password Safe for the MFC Windows build is the
  Microsoft XML parser. </li>
  </ol>
  
  <p>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 <i>Release</i>
  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).</p>
  
  <p>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. <b>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.</b> 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.</i></p>
  
  <p>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:</p>
  <ul>
  <li>If the Configuration name <i>does not</i> end with '64', only platform "Win32" is supported.</li>
  <li>If the Configuration name <i>does</i> end with '64', only platform "x64" is supported.</li>
  </ul>
  <b><i>No other combinations are supported or have been tested.</i></b>
  
  <p>The current MFC configurations are:</p>
  
  <ul>
  <li>32-bit versions - platform Win32:</li>
  <ul>
  <li><b>Debug</b> - builds the debug version using the Microsoft XML parser and the required DLLs
  (pws_at_D.dll and pws_osk_D.dll).</li>
  <li><b>Release</b> - builds the release version using the Microsoft XML parser and the required DLLs
  (pws_at.dll and pws_osk.dll). This will also contain the base language DLL used to generate I18N
  support.</li>
  </ul>
  
  <li>64-bit versions - platform x64:</li>
  <ul>
  <li><b>Debug64</b> - builds the debug version using the Microsoft XML parser and the required DLLs
  (pws_at_D.dll and pws_osk_D.dll).</li>
  <li><b>Release64</b> - builds the release version using the Microsoft XML parser and the required DLLs
  (pws_at.dll and pws_osk.dll). This will also contain the base language DLL used to generate I18N
  support.</li>
  </ul>
  </ul>
  
  <p>The current wxWidgets configurations are:</p>
  
  <ul>
  <li>32-bit versions - platform Win32:</li>
  <ul>
  <li><b>Debugwx</b> - builds the debug version using the Xerces XML parser</li>
  <li><b>Releasewx</b> - builds the release version using the Xerces XML parser</li>
  </ul>
  
  <li>64-bit versions - platform x64:</li>
  <ul>
  <li><b>Debugwx64</b> - builds the debug version using the Xerces XML parser</li>
  <li><b>Releasewx64</b> - builds the release version using the Xerces XML parser</li>
  </ul>
  </ul>
  
  <p>Note that the core and os project files contain <i>all</i> 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. <i>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).</i></p>
  
  <h3><a name="InstallingVS2017"></a>Installing Microsoft Visual Studio 2017
  Community Edition</h3>
  
  <p>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.</p>
  
  <p>For Password Safe the following are <u>required</u>:<br>
  <ul>
  <li>Desktop developmentent with C++</lI>
  <li><i>Additional required</i> "optional" features</li>
  <ul>
  <li>Visual C++ ATL Support</li>
  <li>Windows 8.1 SDK and UCRT SDK</li>
  <li>MFC and ATL support (x86 and x64)</li>
  </ul>
  </ul>
  
  <h3><a name="Versions"></a>Microsoft Visual Studio Numbering Systems</h3>
  <p>Microsoft has a number of numbering systems.</p>
  </ul>
  <li>First there is the year in which they released the Visual Studio edition
  e.g. 2008, 2010, 2012, 2013 and 2015.</li>
  <li>Next there is the compiler version. In general, this is one less than the
  year i.e. for Visual Studio 2015, the compiler version is 14.</li>
  <li>Next there is the "Platform Toolset" value within the project files and
  these are the compiler version * 10 i.e. 140 for VS2015.</li>
  <li>Lastly, there is the level of the compiler defined by pre-processor variable
  _MSC_VER and it has values:
  <ul>
  <li>1700 for VS2012 VC11</li>
  <li>1800 for VS2013 VC12</li>
  <li>1900 for VS2015 VC14</li>
  </ui>
  </ul>
  <p>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.</p>
  
  <p>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.
  
  <p>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.</p>
  
  <h3><a name="Software_Requirements"></a>Software Requirements</h3>
  
  <h3>Getting Source code</h3>
  
  <p>The source code for Password Safe may be downloaded as
  a <a href="https://github.com/pwsafe/pwsafe/archive/master.zip">zip
  file</a>, or retrieved from the git repository via
  "git&nbsp;clone&nbsp;https://github.com/pwsafe/pwsafe.git".</p>
  
  <p>Currently, the Windows version is built using Microsoft's
  development tools as described <a href="#Windows_Build">below</a>.</p> 
  
  <p>If you're going to commit code to the repository, please set your git client's
  configuration file as follows:</p>
  
  <p>In the file ".gitconfig"</p>
  <pre>
  [core]
  	autocrlf = true
  	safecrlf = warn
  </pre>
  
  <p>(This file under "C:\Users\&lt;<i>username</i>&gt;\" 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".
  <i>Alternatively</i>, you can click the button "Edit global .gitconfig" to change the file
  manually).</p>
  
  <p>For Windows, when installing "Git for Windows" (required by TortoiseGit and most other Git clients),
  <u>ensure</u> that you select "Checkout as-is, Commit as-is" to prevent incorrect line endings.</p>
  
  <h3><a name="Windows_Build"></a>Building the Windows Version of Password Safe</h3>
  
  <p>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).</p>
  
  <p>The main (top level) Microsoft Visual Studio 2015 solution file is pwsafe-14.sln.</p>
  
  <p>In order to build the Windows version of Password Safe, you
  need to install the following freely available components, in addition to
  Visual Studio:</p>
  <ul>
  <li><a href="http://msdn.microsoft.com/en-us/windows/dd146047.aspx">
  Microsoft's Windows SDK</a>. For VS2015 and VS2017, you should use version V8.1, which
  can be installed as part of the Visual Studio istallation.</li>
  <li>To compile and produce the Help files (.chm) then
  <a href="http://www.microsoft.com/downloads/details.aspx?FamilyID=00535334-%0D%0Ac8a6-452f-9aa0-d597d16580cc&amp;DisplayLang=en">
  Microsoft's HTML Help Workshop</a> is required. Note however that the headers and
  libraries necessary for compiling Password Safe itself are included in the
  Windows SDK mentioned above.</li>
  <li>A git client, such as <a href="https://code.google.com/p/tortoisegit/wiki/Download">
  Tortoise git Client</a> (for updating the revision number within Password Safe's
  version details)</li>
  <li>For XML Support, one or more of the following is needed (see the
  <a href="#XML_Processing"> XML processing section</a> for more details):
  <ul>
  <li>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.</li>
  <li><a target="_blank" href="http://xerces.apache.org/xerces-c/">Xerces
  V3.1.4 XML Library</a></li>
  </ul>
  </li>
  <li> For unit testing, Google's <a target="_blank"
  href="http://code.google.com/p/googletest">gtest 1.7.0</a>
  library is used. This is only used to build the Debug version of the src/test project,
  which may be disabled if desired.
  </ul>
  
  <p>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.</p>
  
  <h4>Compiling using Visual Studio:</h4>
  <ul>
  <li>If you're using Microsoft's Visual Studio, the file "UserVariables-14.props"
  for VS2015, or "UserVariables-15.props" for VS2017 <b><u><i>must</i></u></b> exist
  and describe the directories where the non-"Windows SDK" components have been
  installed. <b><u><i>The solution will not open correctly without this file being
  present</i></u></b>.</li>
  <li>For your convenience, we've included simple Visual Basic scripts, "configure-14.vbs"
  and "configure-15.vbs" for VS2015 and VS2017, 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 scripts <b><u>must</u></b>
  be run via "cscript" in a Command Prompt window in their directory. These scripts will
  also prompt for the location of the 64-bit Xerces libraries for 64-bit builds.
  <u>If you are not going to build the wxWidgets version, you can accept the default
  location of both wxWidgets and Xerces XML processor and you do <b>not</b> have to
  install either of these software libraries <b>nor</b> generate their libraries.</u></li>
  <li><b>When migrating from previous versions to VS2015 or VS2017, ensure that you
  run the configure-14.vbs or configure-15.vbs in order to add the location of the
  Windows Driver Kit for a successful build of the YubiKey library.</b></li>
  </ul>
  
  <h3><a name="XML_Processing"></a>XML Processing</h3>
  
  <p>Originally, Password Safe used Microsoft's XML library for XML parsing and
  validation. For portability, we're now support the
  <a href="http://xerces.apache.org/xerces-c/" target="_blank">Xerces</a> 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.
  <b>Note: for 64-bit Xerces builds, you must use the 64-bit versions of the Xerces libraries.</b>
  See <a href="#Xerces">note</a> below re: building Xerces XML libraries with
  Visual Studio 2017.</p>
  
  <p><b>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.</b></p>
  
  <p>To determine which XML library to use while building Password Safe,
  we've defined a pre-processor variable (USE_XML_LIBRARY). If <u>NOT</u>
  defined, the compiled Password Safe <u>will not process XML files</u>
  (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.</p>
  
  <p>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.</p>
  
  <p>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.</p>
  
  <h3><a name="Gtest"></a> Gtest framework</h3>
  <p><a href="https://github.com/google/googletest"
        target="_blank">Google Test (gtest)</a> 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.<br/>
    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.<br/>
    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</p>
  
  <h3><a name="Xerces"></a> Building Xerces XML Parser for Windows</h3>
  
  <p>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 <b>only</b> project that needs to be built is
  "XercesLib". There are multiple configurations available but, again, the <b>only</b>
  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.<p>
  
  <h3><a name="wxWidgets"></a>Bulding the wxWidgets User Interface for Windows</h3>
  
  <p>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.</p>
  
  <p>You will need to build the Debug and Release versions for x86 and x64. The resulting libraries<p>
  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.</p>
  
  <h3><a name="Wix MSI Installer"></a>Wix MSI Installer (Windows only)</h3>
  
  <p>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 
  <a href="http://wixtoolset.org/releases/">http://wixtoolset.org/releases/</a></p>
  
  <p>To build the MSI files, open a command prompt and change to the root directory of 
  your source tree. Run the following command.</p>
  
  <pre>
   install\windows\BuildWixInstall.bat
  </pre>
  
  <p>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.</p>
  
  <pre>
   pwsafe.msi
   pwsafe64.msi
  </pre>
  
  <p>You can build the files individually this way.</p>
  
  <pre>
   install\windows\BuildWixInstall.bat x86
   install\windows\BuildWixInstall.bat x64
  </pre>
  
  <p>If you need to work on the Wix script (.wxs file), you can find it in the
  install\windows directory.</p>
  <pre>
   pwsafe-template.wxs
  </pre>
  
  <h3><a name="Minidump_Production"></a>Minidump Production (Windows only)</h3>
  
  <p>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.</p>
  
  <p>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.</p>
  
  <p><u>Note to Translators:</u> 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.</p>
  
  <p><u>Note:</u> 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.</p>
  
  <p>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.</p>
  
  <p>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!):</p>
  <ol>
  <li>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
  Password Safe source. With the corresponding source, VS can show you the
  exact line in Password Safe where the error took place and also the other
  statements within Password Safe as you follow the stack trace.</li>
  <li>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 Password Safe 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.</li>
  <li>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 '..\build\bin\pwsafe\release' directory.</li>
  <li>Save the user's minidump file on your PC. Use VS to Open this <u>as
  a Project</u> (e.g. File-&gt;Open-&gt;Project/Solution).</li>
  <li>In the Debugging Options, specify the directory containing the corresponding
  PDB file. (Go to: Tools-&gt;Options-&gt;Debugging-&gt;Symbols and add
  this directory in the section entitled "Symbol file (.pdb)
  locations:").</li>
  <li>Press F5 to start debugging, and away you go.</li>
  </ol>
  
  <p><b>*** End of Developer Notes ***</b></p>
  
  <br>
  <br>
  <br>
  </body>
  </html>
  