Adding entirely new code to the main PSI3 repository

If the programmer is adding a new executable module or library to the PSI3 repository, a number of important conventions should be followed:

1. Since such changes almost always involve additional functionality, new modules or libraries should be added only on the main SVN trunk. See section 2.1 for additional information.

2. The directory containing the new code should be given a name that matches the name of the installed code (e.g. if the code will be installed as newcode, the directory containing the code should be named newcode). New executable modules must be placed in $PSI3/src/bin and libraries in $PSI3/src/lib of the user's working copy.

3. The Makefile should be converted to an input file for the configure script (Makefile.in -- see any of the current PSI3 binaries for an example) and should follow the conventions set up in all of the current PSI3 Makefiles. This includes use of MakeVars and MakeRules.

4. New binaries should be added to the list contained in $PSI3/src/bin/Makefile.in so that they will be compiled automatically when a full compilation of the PSI3 distribution occurs. This step is included in the sequence below.

5. A documentation page should be included with the new code (see section 8 for more information). As a general rule, if the code is not ready to have a documentation page, it is not ready to be installed in PSI3.

6. The configure.ac file must be altered so that users may check out copies of the new code and so that the configure script will know to create the Makefile for the new code. These steps are included in the sequence below.

Assume the new code is an executable module and is named great_code. The directory containing the new code must contain only those files which are to be checked in to the repository! Then the following steps will check in a new piece of code to the main repository:

1. cd $PSI3/src/bin
2. svn add great_code
3. svn ci -m ``Put comments here.''
4. cd $PSI3
5. Edit configure.ac and add great_code to the list.
6. svn ci configure.ac -m ``Put comments here.''
7. autoconf
8. cd $PSI3/src/bin
9. Edit Makefile.in and add great_code to the list.
10. svn ci Makefile.in -m ``Put comments here.''

At this point, all of the code has been properly checked in, but you should also test to make sure that the code can be checked out by other programmers, and that it will compile correctly. The following steps will store your personal version of the code, check out the new code, and test-compile it:

1. cd $PSI3/src/bin
2. mv great_code great_code.bak
3. cd $PSI3/..
4. svn update
5. cd $objdir
6. $PSI3/configure --prefix=$prefix
7. cd src/bin/great_code
8. make install

(Note that $prefix and $objdir to the installation and compilation directories defined in the PSI3 installation instructions.) Your original version of the code remains under great_code.bak, but should be no longer necessary if the above steps work. Note that it is necessary to re-run configure explicitly, instead of just running config.status, because the latter contains no information about the new code.