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. The directory containing the new code should be given a name which 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.

2. 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.

3. 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.

4. 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.

5. The configure.in 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. cvs add great_code
3. Answer ``y'' when CVS asks if you wish to create the new directory in the repository.
4. cd great_code
5. cvs add *
6. cvs ci
7. Edit the comments file that CVS provides.
8. cd $PSI3
9. Edit configure.in and add great_code to the list.
10. cvs ci
11. Edit the comments file that CVS provides.
12. autoconf
13. cd $PSI3/src/bin
14. Edit Makefile.in and add great_code to the list.
15. cvs ci
16. Edit the comments file that CVS provides.

At this point, all of the code has been properly checked in. However, you must 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. cvs co $PSI3/src/bin/great_code
5. cd $objdir
6. $PSI3/configure -prefix=$prefix -verbose
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.