2
% PSI Programmer's Manual
4
% SVN Revision Control Section
8
% Modified by TDC, December 2002
9
% Updated from CVS to SVN, April 2007
12
The subversion control system (SVN) (\htmladdnormallink{{\tt
13
subversion.tigris.org}}{http://subversion.tigris.org/}) provides a
14
convenient means by which programmers may obtain the latest (or any
15
previous) version of the \PSIthree\ source from the main repository or
16
a branch version, add new code to the source tree or modify existing
17
\PSIthree\ modules, and then make changes and additions available to
18
other programmers by checking the modifications back into the main
19
repository. SVN also provides a ``safety net'' in that any erroneous
20
modifications to the code may be easily removed once they have been
21
identified. This section describes how to use SVN to access and
22
modify the \PSIthree\ source code. (Note that compilation and
23
installation instructions are given in a separate document.)
25
The main repository for the \PSIthree\ Source code is currently
26
maintained by the Crawford group at Virginia Tech. To check out the
27
code, one must first obtain an SVN account by emailing
28
\htmladdnormallink{{\tt crawdad@vt.edu}}{mailto:crawdad@vt.edu}.
29
After you have a login-id and password, you are now ready to access
30
the repository via a secure, SSL-based WebDAV connection, but first
31
you must decide which version of the code you need.
33
The PSI3 SVN repository contains three top-level directories:
35
\item {\tt trunk}: The main development area.
36
\item {\tt branches}: Release branches and private development
37
branches are stored here.
38
\item {\tt tags:} Snapshots of the repository corresponding to public
39
releases are stored here and should {\em never} be modified.
41
If you have a PSI3 SVN account, you can peruse these directories if
42
you like by pointing web browser to:
45
{\tt https://sirius.chem.vt.edu/svn/psi3/}
47
\subsection{\PSIthree\ SVN Policies: Which Branch Should I Use?}
48
\label{section:branches}
50
The \PSIthree\ repository is comprised of a main trunk and several
51
release branches. The branch you should use depends on the sort of
52
work you plan for the codes:
54
\item For any piece of code already in the most recent release, bug
55
fixes (defined as anything that doesn't add functionality ---
56
including documentation updates) should be made {\em only} on the
57
most recent stable release branch.
58
\item The main trunk is reserved for development of new functionality.
59
This allows us to keep new, possibly unstable code away from public
60
access until the code is ready.
61
\item Code that you do not want to put into next major release of
62
\PSIthree\ should be put onto a separate branch off the main
63
trunk. You will be solely responsible for maintenance of the new
64
branch, so you should read the SVN manual before attempting this.
67
\noindent Fig.~\ref{Fig:svn} provides a schematic of the SVN
68
revision-control structure and branch labeling. Two release branches
69
are shown, the current stable branch, named {\tt psi-3-3}, and a
70
planned future release, to be named {\tt psi-3-4}. The tags on the
71
branches indicate release points, where bugs have been fixed and the
72
code has been or will be exported for public distribution. As soon as
73
a release branch is created, we generate a tag so that we may make
74
updates to that version of the code without affecting other branches
75
or the main trunk. The dotted lines in the figure indicate merge
76
points: before each public release, changes made to the code on the
77
stable release branch will be merged into the main trunk.
79
% We have adopted the convention that the first tag on a new release
80
% branch will be given the suffix, {\tt -rc-1}, for ``release candidate
81
% 1'' (i.e., a numbered beta release). Subsequent tags for new released
82
% on the same branch will be updated with {\tt -rc-2}, {\tt -rc-3}, etc.
83
% Once the code is appropriately stable to be beyond beta status,
84
% release tags will be given the suffix, {\tt -0}, {\tt -1}, etc.,
85
% indicating patch levels.
90
\epsfig{file=svn.eps,height=3.5cm}
92
\caption{\PSIthree\ SVN branch structure with examples of branch- and
93
release-tag labelling.}
97
\noindent A frequently encountered problem is what to do about bug fixes
98
that are necessary for uninterrupted code development of the code on the
99
main trunk. As Rule 1 of the above policy states, all bug fixes of the code
100
already in the recent stable release must go on the corresponding branch,
101
not on the main trunk. The next step depends on the severity of the bug:
103
\item If the bug fix is critical and potentially affects every
104
developer of the code on the main trunk, then \PSIthree\
105
administrators should be notified of the fix. If deemed necessary,
106
appropriate steps to create a new patch release will be made. Once
107
the next patch release is created then the bug fixes will be merged
108
onto the main trunk. If the bug fix doesn't warrant an immediate
109
new patch release, then you can incorporate the bug fix into your
110
local copy of the main trunk code manually or using SVN merge
111
features. This will allow you to continue development until next
112
patch release is created and the bug fix is incorporated into the
113
main trunk code in the repository. However you should {\em never}
114
merge such changes into the main trunk yourself.
115
\item If the bug fix is not critical (e.g. a documentation
116
update/fix), then you should wait until next patch release when it
117
will be merged into the main trunk automatically.
121
The following are some of the most commonly used SVN commands for checking
122
out and updating working copies of the \PSIthree\ source code.
125
$\bullet$ To checkout a working copy of the head of the main trunk:
127
{\tt svn co https://sirius.chem.vt.edu/svn/psi3/trunk/ psi3}
130
$\bullet$ To check out a working copy of the head of a specific release branch,
131
e.g., the branch labelled {\tt psi-3-3}:
133
{\tt svn co https://sirius.chem.vt.edu/svn/psi3/branches/psi-3-3 psi3}
135
\noindent Note that subsequent {\tt svn update} commands in this
136
working copy will provide updates only on the chosen branch. Note
137
also that after you have checked out a fresh working copy of the code
138
you must run the {\tt autoconf} command to generate a {\tt configure}
139
script for building the code. (See the installation manual for
140
configuration, compilation, and testing instructions.)
142
\noindent For each of the above commands, the working copy of your
143
code will be placed in the directory \file{psi3}, regardless of your
144
choice of branch. In this manual, we will refer to this directory
145
from now on as {\tt \$PSI3}. Subsequent SVN commands are usually run
146
within this top-level directory.
149
$\bullet$ To update your current working copy to include the latest revisions:
154
Notes: (a) This will update only the revisions on your current branch;
155
(b) The old {\tt -d} and {\tt -P} flags required by CVS are not necessary with SVN.
158
$\bullet$ To convert your working copy to the head of a specific branch:
160
{\tt svn switch https://sirius.chem.vt.edu/svn/psi3/branches/psi-3-3}
163
$\bullet$ To convert your working copy to the head of the main trunk:
165
{\tt svn switch https://sirius.chem.vt.edu/svn/psi3/trunk/}
168
$\bullet$ To find out what branch your working copy is on, run this in your
169
top-level \PSIthree\ source directory:
171
{\tt svn info | grep URL}
174
This will return the SVN directory from which your working copy was
178
{\tt URL: https://sirius.chem.vt.edu/svn/psi3/branches/psi-3-3}
181
Some words of advice:
183
\item Most SVN commands are reasonably safe,
185
\item Unlike CVS, you shouldn't use {\tt svn update} to see the status
186
of your working copy. With SVN you should use {\tt svn status} to
187
see if you've modified any files or directories. If you want a
188
direct comparison with the repository, you should use {\tt svn status -u}.
189
\item Read the SVN manual. Seriously.
191
\htmladdnormallink{{\tt
192
http://svnbook.red-bean.com/en/1.2/svn-book.html}}{http://svnbook.red-bean.com/en/1.2/svn-book.html}
194
\item If you're about to start some significant development or bug-fixes,
195
first update your working copy to the latest version on your branch.
196
In addition, if you do development over a long period of time (say weeks to
197
months) on a specific module or modules, be sure to run a {\tt svn status -u}
198
occasionally. In can be {\em very} frustrating to try to check in lots
199
of changes, only to find out that the \PSIthree\ has changed dramatically
200
since your last update.
203
\subsection{Checking in altered \PSIthree\ binaries or libraries}
205
If you have changes to Psi binaries or libraries which already exist, one
206
of two series of steps is necessary to check these changes in to the main
207
repository. The first series may be followed if all changes have been made
208
only to files which already exist in the current version. The second series
209
should be followed if new files must be added to the code in the repository.
212
\item No new files need to be added to the repository. We will use
213
\library{libciomr} as an example.
215
\item {\tt cd \$PSI3/src/lib/libciomr}
216
\item {\tt svn ci -m ``Put comments here.''}
218
\item New files must be added to the repository. Again, we use
220
as an example. Suppose the new file is named \file{great\_code.c} .
222
\item {\tt cd \$PSI3/src/lib/libciomr}
223
\item {\tt svn add great\_code.c}
224
\item {\tt svn ci -m ``Put comments here.''}
228
The \file{svn ci} command in both of these sequences will examine all
229
of the code in the current \file{libciomr} directory against the
230
current version of the code in the main repository. Any files which
231
have been altered (and for which no conflicts with newer versions
232
exist!) will be identified and checked in to the main repository (as
233
well as the new file in the second situation).
235
SVN requires that you include a comment on your changes. However,
236
unlike CVS, SVN prefers that you put your comments on the command-line
237
rather than editing a text file. I prefer the CVS way, but this is a
238
minor pain compared to all the advantages of SVN, in my opinion.
240
\subsection{Adding entirely new code to the main \PSIthree\ repository}
243
If the programmer is adding a new executable module or library to the
244
\PSIthree\ repository, a number of important conventions should be followed:
247
\item Since such changes almost always involve additional functionality,
248
new modules or libraries should be added only on the main SVN trunk.
249
See section \ref{section:branches} for additional information.
251
\item The directory containing the new code should be given a name
252
that matches the name of the installed code (e.g. if the code will
253
be installed as \module{newcode}, the directory containing the code
254
should be named \file{newcode}). New executable modules must be
255
placed in \shellvar{\$PSI3}\file{/src/bin} and libraries in
256
\shellvar{\$PSI3}\file{/src/lib} of the user's working copy.
258
\item The Makefile should be converted to an input file for the
259
configure script (\file{Makefile.in} --- see any of the current
260
\PSIthree\ binaries for an example) and should follow the
261
conventions set up in all of the current \PSIthree\
262
\file{Makefiles}. This includes use of \file{MakeVars} and
265
\item New binaries should be added to the list contained in
266
\shellvar{\$PSI3}\file{/src/bin/Makefile.in} so that they will be
267
compiled automatically when a full compilation of the \PSIthree\
268
distribution occurs. This step is included in the sequence below.
270
\item A documentation page should be included with the new code (see
271
section \ref{Documentation} for more information). As a general
272
rule, if the code is not ready to have a documentation page, it is
273
not ready to be installed in \PSIthree.
275
\item The \file{configure.ac} file must be altered so that users may
276
check out copies of the new code and so that the \file{configure}
277
script will know to create the Makefile for the new code. These
278
steps are included in the sequence below.
282
Assume the new code is an executable module and is named
283
\module{great\_code}. The directory containing the new code must
284
contain only those files which are to be checked in to the repository!
285
Then the following steps will check in a new piece of code to the main
289
\item {\tt cd \$PSI3/src/bin}
290
\item {\tt svn add great\_code}
291
\item {\tt svn ci -m ``Put comments here.''}
292
\item {\tt cd \$PSI3}
293
\item Edit \file{configure.ac} and add \file{great\_code} to the list.
294
\item {\tt svn ci configure.ac -m ``Put comments here.''}
296
\item {\tt cd \$PSI3/src/bin}
297
\item Edit \file{Makefile.in} and add \file{great\_code} to the list.
298
\item {\tt svn ci Makefile.in -m ``Put comments here.''}
300
At this point, all of the code has been properly checked in, but you
301
should also test to make sure that the code can be checked out by
302
other programmers, and that it will compile correctly. The following
303
steps will store your personal version of the code, check out the new
304
code, and test-compile it:
306
\item {\tt cd \$PSI3/src/bin}
307
\item {\tt mv great\_code great\_code.bak}
308
\item {\tt cd \$PSI3/..}
309
\item {\tt svn update}
310
\item {\tt cd \$objdir}
311
\item {\tt \$PSI3/configure -}{\tt -prefix=\$prefix}
312
\item {\tt cd src/bin/great\_code}
313
\item {\tt make install}
315
(Note that \$prefix and \$objdir to the installation and compilation
316
directories defined in the \PSIthree\ installation instructions.)
317
Your original version of the code remains under \file{great\_code.bak},
318
but should be no longer necessary if the above steps work. Note that it is
319
necessary to re-run \file{configure} explicitly, instead of just running
320
\file{config.status}, because the latter contains no information about
323
\subsection{Updating checked out code}
325
If the code in the main repository has been altered, other users' working
326
copies will of course not automatically be updated. In general, it is
327
only necessary to execute the following steps in order to completely update
328
your working copy of the code:
331
\item {\tt cd \$PSI3}
332
\item {\tt svn update}
335
This will examine each entry in your working copy and compare it to
336
the most recent version in the main repository. When the file in the
337
main repository is more recent, your version of the code will be
338
updated. If you have made changes to your version, but the version in
339
the main repository has not changed, the altered code will be
340
identified to you with an ``M''. If you have made changes to your
341
version of the code, and one or more newer versions have been updated
342
in the main repository, SVN will examine the two versions and attempt
343
to merge them -- this process often reveals conflicts, however, and is
344
sometimes unsuccessful. You will be notified of any conflicts that
345
arise (labelled with a ``C'') and you must resolve them manually.
347
If new directories have been added to the repository, the update above
348
will automatically add them to your working copy. However, you may
349
need to re-run {\tt autoconf} and configure ({\tt
350
\$objdir/config.status --recheck} is a convenient command) to be
351
able to build the new code.
353
\subsection{Removing code from the repository}
354
If alterations of libraries or binaries under Psi involves the deletion of
355
source code files from the code, these must be explicitly removed through SVN.
357
The following steps will remove a source code file named \file{bad\_code.F}
358
from a binary module named \module{great\_code}:
360
\item {\tt cd \$PSI3/src/bin/great\_code}
361
\item {\tt svn remove bad\_code.F}
362
\item {\tt svn ci -m ``Put comments here.''}
365
\subsection{Checking out older versions of the code}
366
It is sometimes necessary to check out older versions of a piece of code.
367
Assume we wish to check out an old version of \PSIdetci. If this
368
is the case, the following steps will do this:
370
\item {\tt cd \$PSI3/src/bin/detci}
371
\item {\tt svn co --revision \{2002-02-17\}}
374
This will check the main repository and provide you with the code as
375
it stood exactly on February 2nd, 2002.
377
\subsection{Examining the revision history}
378
It can be very useful to use cvs to see what recent changes have been
379
made to the code. Anytime one checks in a new version of a file, SVN
380
requires the user to provide comments on the changes with the {\tt -m}
381
flag. These comments go into a log information that may be easily
382
accessed through SVN. To see what changes have been made recently to
383
the file \file{detci.cc}, one would go into the \file{detci} source
388
Checking the log files is a very useful way to see what recent changes might
389
be causing new problems with the code.
391
\subsection{The structure of the \PSIthree\ Source Tree}
394
Your working copy of the \PSIthree\ source code includes a number of
395
important subdirectories:
398
\item \shellvar{\$PSI3}\file{/lib} -- Source files for
399
OS-independent ``library'' data. This includes the main basis set
400
data file (\file{pbasis.dat}) and the \PSIthree\ program execution
401
control file (\file{psi.dat}), among others. These files are
402
installed in \file{\$prefix/share}.
404
\item \shellvar{\$PSI3}\file{/include} -- Source files for
405
OS-independent header files, including \file{physconst.h} (whose
406
contents should be obvious from its name), \file{psifiles.h}, and
407
\file{ccfiles.h}, among others. These files are installed in
410
\item \shellvar{\$PSI3}\file{/src/util} -- Source code for the utility
411
program \module{tocprint}. (Note that the \module{tmpl} module is
412
no longer used and will eventually disappear.)
414
\item \shellvar{\$PSI3}\file{/src/lib} -- Source code for the
415
libraries, including \library{libpsio}, \library{libipv1},
416
\library{libchkpt}, etc. The include files from the library
417
source are used directly during the compilation of PSI to
418
avoid problems associated with incomplete installations. Some
419
include files are architecture-dependent and go in an include
420
subdirectory of the compilation (object) directory.
422
\item \shellvar{\$PSI3}\file{/src/lib} -- Source code for the
426
After compilation and installation, the \file{\$prefix} directory
427
contains the executable codes and other necessary files. {\bf NB:}
428
The files in this area should never be directly modified; rather, the
429
working copy should be modified and the \PSIthree\ \file{Makefile}
430
hierarchy should handle installation of any changes. The structure of
431
the installation area is:
434
\item \file{\$prefix/bin} -- The main executable directory. This
435
directory must be in your path in order for the driver program,
436
\module{psi3}, to find the modules.
438
\item \file{\$prefix/lib} -- The \PSIthree\ code libraries. (NB: The
439
description of \PSIthree\ \file{Makefiles} later in this manual will
440
explain how to use the libraries.)
442
\item \file{\$prefix/include} -- Header files. These are not actually
443
used during the compilation of PSI but are useful for inclusion by
444
external programs because they are all in the same directory.
446
\item \file{\$prefix/share} -- OS-independent data files, including
447
basis set information. (Do not edit this file directly; any changes
448
you make can be overwritten by subsequent {\tt make} commands.)
450
\item \file{\$prefix/doc} -- \PSIthree\ documentation, including
451
installation, programmer, and user manuals.
added
removed
doc/progman/svn.tex
