[r5083]: tags / V3_23 / README.WINDOWS.DEVELOPERS.html Maximize Restore History

Download this file

README.WINDOWS.DEVELOPERS.html    270 lines (247 with data), 13.8 kB

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
<!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 to
people who wish to compile the Windows version of PasswordSafe.</p>
<h3>Contents</h3>
<ol>
<li><a href="#Software_Requirements">Software Requirements</a></li>
<li><a href="#XML_Processing">XML Processing</a></li>
<li><a href="#Minidump_Production">Minidumps</a></li>
</ol>
<h3><a name="Software_Requirements"></a>Software Requirements</h3>
<h4>Getting Source code</h4>
<p>The source code for PasswordSafe may be downloaded as a zip file, or retrieved
from the Subversion repository at <a href="https://passwordsafe.svn.sourceforge.net/svnroot/passwordsafe/trunk/pwsafe/pwsafe">
https://passwordsafe.svn.sourceforge.net/svnroot/passwordsafe/trunk/pwsafe/pwsafe</a>
using a subversion client. Currently (early 2010), the Windows version
is built using Microsoft's development tools as described <a href="#Windows_Build">below</a>.
A Linux build is also in early stages of development, as described in the
<a href="#Linux_Build">Linux Build</a> section.<br>
If you're going to commit code to the repository, please set your subversion client's
configuration file as follows:<br>
<p>In the "[miscellany]" section, ensure the following variable is set to 'yes':
<pre>
enable-auto-props = yes
</pre>
</p>
<p>In the "[auto-props]" section, add the following if not already there:
<pre>
*.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
</pre>
</p>
<p>(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).</p>
<h4><a name="Windows_Build"></a>Windows Build</h4>
<p>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.</p>
<p>In order to build the Windows version of PasswordSafe, 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>. 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:
<ul>
<li>"Windows Vista Update &amp; .NET 3.0 SDK"
[V6.1.6000.16384.10 dated February 2007] - known as V6.0.</li>
<li>"Windows Server 2008 and .NET Framework 3.5"
[V6.0.6001.18000.367 dated February 2008] - known as V6.1.</li>
<li>"Windows 7 and .NET Framework 3.5 SP1
[V6.1.7600.16385 dated August 2009] - known as V7.0.</li>
</ul>
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 <b>but not</b>
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.
<br>
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'.
<u>See note below.</u></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 PasswordSafe itself are included in the
Windows SDK mentioned above.</li>
<li>A subversion client, such as <a href="http://tortoisesvn.net/downloads">
Tortoise SVN Client</a> (for updating the revision number within PasswordSafe'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://expat.sourceforge.net/">Expat's V2.0.1
XML Library</a></li>
<li><a target="_blank" href="http://xerces.apache.org/xerces-c/">Xerces
V3.1.0 XML Library</a></li>
</ul>
</li>
</ul>
<p><b>SDK NOTE:</b> In order to compile PasswordSafe 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 &gt; Options &gt; Project and Solutions
&gt; VC++ directories &gt; 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. <b>It is
recommended that you get SDK V6.1 <u>and</u> 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.</b></p>
<p><b>Compiling using Visual Studio:</b> If you're using Microsoft's Visual
Studio, the file "UserVariables.vsprops" <b><u><i>must</i></u></b> exist
and point to 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>. 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.</p>
<h4><a name="Linux_Build"></a>Linux Build</h4>
<p>The Linux version of PasswordSafe is currently in pre-Alpha state. It is
being built under Debian 5.0 (Lenny), and uses uuid-dev and
libwxgtk2.8-dev for building, as well as g++ and GNU make.</p>
<h3><a name="XML_Processing"></a>XML Processing</h3>
<p>Originally, PasswordSafe used Microsoft's XML library for XML parsing and
validation. For portability, we're now working on support for the
<a href="http://expat.sourceforge.net/" target="_blank">Expat</a>
and <a href="http://xerces.apache.org/xerces-c/" target="_blank">Xerces</a> 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).</p>
<p>To determine which XML library to use while building PasswordSafe,
we've defined a pre-processor variable (USE_XML_LIBRARY). If <u>NOT</u>
defined, the compiled PasswordSafe <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 PasswordSafe that do support XML parsing can still
use them. Note, however, that the application will be able to write XML files.</p>
<p>The three valid values of the USE_XML_LIBRARY variable are "EXPAT",
"MSXML" and "XERCES" corresponding to the three different implementations.</p>
<p>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.</p>
<p>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 PasswordSafe
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.</p>
<p>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.</p>
<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: 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.</u></p>
<p>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.</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
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.</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 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.</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 '..\src\bin\releasem' 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>
<br>
<br>
<br>
</body>
</html>