Source Code Organisation

Source code management refers to the standard procedure of organising source code files into different subdirectories according to type and purpose.

Code is normally organised into packets or units referred to as a project or a package. Once a project or package is identified it is given a software code name e.g. the control software for the NCCS can be grouped together under the code name nccs, another example is the plotting package from Caltech code named pgplot.

Every project must have it own directory structure and the same root directory. In this document we will refer to this as the ~project directory.

Source code should be organised in identical subdirectory tree structures with respect to the root directory. This facilitates the task of program developers and installers. A proposed subdirectory tree structure is :

                            ~project
                                |
                                |
  -----------------------------------------------------------
  |        |       |       |        |            |          |
  |        |       |       |        |            |          |
README    bin     doc   include    lib          src     subproject    
           |               |        |            |          |
           |               |        |            |          |
         --------         RCS   --------        RCS   -------------
         |      |               |      |              | | | | | | |
         |      |               |      |
       linux   sun4           linux   sun4

Where the different subdirectories refer to the following :

• ~project is the root directory for the project,
• README contains a description of the project and a brief description of the source code which can be found in this directory tree,
• bin contains the binaries (if any) of the sources; a separate subdirectory exists for each platform supported e.g. in the case of HartRAO this will be linux and sun4,
• doc contains all documentation related to this project e.g. white papers, users guide, porting guides, man pages etc.,
• lib contains all libraries generated and maintained by the project; a separate subdirectory exists for each platform supported e.g. in the case of HartRAO this will be linux and sun4,
• src is used for storing all source files; the golden rule is ``one source file for all platforms supported'', differences between platforms are managed by conditional statements,
• ~subproject is used for setting up a sub-project inside the main project, sub-projects have the identical subdirectory tree structure as the main project, there can be more than one sub-project,

The project root directory should be stored on file server accessible by all member of the project. In the case of HartRAO this could be bootes:/usr/local/project. Alternatively for a very big project it might be worthwhile creating a dedicated project directory in the /home area e.g. for the NCCS project a root directory /home/nccs coould be created on bootes.

All members of a project must belong to a common group. For a medium to large project a special group should be created for the project (usually with the same name as the project). The root directory and all subdirectories must have read, write and execute permission for all members of the project group. Files must have read permission for the group.