Creating new files

When new files are to be added to VMD , for any of the different subdirectories, the following steps should be followed:

1. Once an initial version of the file is ready, it must be formatted properly to conform to the standards used by files similar to it, i.e., to be similar to other .h files if the file is a C/C++ header. The rules for formatting each type of file are given in the following section.
2. If RCS is being used, then after formatting for almost all cases the file must be put in the RCS system. The only type of files which should NOT be placed in the RCS are the following:
   • Binary executable files, i.e., binary executable files which are in the bin directory.
   • Image files used for the documentation, i.e., which are in the doc/pictures directory. There is a single copy of these files, which cannot work with RCS due to the way RCS stores files internally.
   • Libraries, including the library archive file and the library header files. These should all be in a single place, and all users should simply have a link from their working lib directory to the single official VMD lib directory.
   To put a file in RCS, follow the steps in section 2.2.
3. Once placed in the RCS, the configure script must be updated, if necessary, to include the name of the new file in the appropriate list. For example, if a new C++ object is being added and there are two new files newobj.C and newobj.h, the names of these files would go into the lists of VMD C++ source code and header files in the configure script.

File formats

There are several types of files which may be added to the whole set of VMD working files. This section describes how to format them, and where to put them.

Many types of files (particularly, C/C++/Fortran source code or header files, Latex documentation files, and shell script files) require an RCS header at the beginning of the file. This header should be placed at the very beginning, before any other text in the file. It consists of a set of comment lines which describe the name, purpose, and history of revisions to the file. This is done by using RCS keywords embedded in the comments, which are replaced by the proper values when the file is checked out, and by having a section in the comments for a basic description of the purpose of the file. Templates of RCS headers for each of the different file types which require them are provided in the directory RCS. When a new file is created, a copy of the relevant header template should be placed at the top of the file, and the file description inserted as comments in the section of the template provided for this purpose. The descriptions below of how to format each file also describe the name of the RCS template to use.

• Documentation text files
  

  The documentation for VMD is in Latex, and files should have a .tex extension. The files should all be placed in the doc directory, be put in the RCS, and have the RCS header RCS/RCSheader.tex prepended.

• Documentation image files
  

  Image files for the documentation should be placed in the directory doc/pictures, which should be a link to a directory writable by all people working on VMD . These files are NOT to be placed in the RCS, due to the problems with how RCS stores files.

• Source code files
  

  All source code files, either C, C++, or Fortran, should be placed in the src directory, along with all header files. These files should be entered into the RCS; a copy of the RCS template RCS/RCSheader.h should go at the start of header files, and a copy of RCS/RCSheader.c should be placed at the start of C and C++ source files. Fortran files should begin with a copy of the file RCS/RCSheader.f.

  All header files should bracket their text between a #ifndef ... #endif pair, and define a macro to indicate the header file has been processed. For example, right after the RCS header should come the text

  #ifndef DISPLAYDEVICE_H
  #define DISPLAYDEVICE_H
  
  #endif

• Shell script files
  

  Files which are sh or csh scripts should be placed, most likely, in either the main working directory or the bin directory. These should be entered into the RCS, and have the RCS header RCS/RCSheader.make placed at the beginning. When adding such files to the RCS, care must be taken to have the comment leader for the RCS file set properly. This is done by using the command-line switch

  -c"# "

  added to the options to the rcs program (described in section 2.2).

• Data files
  

  Files which contain data or configuration parameters needed by VMD \ should be placed in the data directory, and be put in the RCS. In most cases, the "#" symbol is the comment character, and so they can have the same type of RCS header as used for shell scripts. This is true, for example, for the file data/.vmdrc, which is in the RCS.