Specifications for software development organization

Written by Angel Sinigersky
First Version 1.0 - 15.04.2004, Current Version: 1.1, 04.06.2008

Directory tree structure

 

Every new development of a library or an application begins with creating the following directory tree:

 

 

Explaination of each directory’s purpose follows:

 

Directory in tree

Explaination

bin

Resulting executable files (*.exe, a.out) and dynamic link libraries (*.dll, *.so) are being output to this directory. Debug version is distinguished from the release version using a ‘D’ suffix in the file name. Example: LibraryD.dll – debug version; Library.dll – release version.

data

Application or library specific custom data is stored here.

doc

Directory for documentation of the project.

include

Main directory for includable header files. Files are to be stored in the subdirectories (see next).

include\(LibOrAppName)

Interface (public) header files (*.h) are placed in this directory. These include files are available to the users of the library (rarely the application) to compile their code.

include\internal

Internal (private) header files (*.h) used only within the project. Headers should be, whenever possible, separated from the public headers.

include\mod

Directory to store Fortran 90 module files (*.mod)

intermediate\Debug

Intermediate files (i.e. *.obj) for a debug compilation. If conflicts avoiding necessary, “Debug” could contain subdirectories for different project portions.

intermediate\Release

Intermediate files (i.e. *.obj) for a release compilation. Same remarks like for “Debug”.

lib

Directory to store the *.lib or *.a files ready for linking to an executable module. Debug version is distinguished from the release version using a ‘D’ suffix in the file name. Example: LibraryD.lib – debug version; Library.lib – release version.

prj

Project files and/or makefiles stored here. Exception is made for the Visual Studio solution file (*.sln), which is to be placed in the project root directory, as well as the main “Makefile”.

source

Main sources directory containing *.cpp, *.f90 files and any other compilable files. It is advised to group the source files into sub directories (denoted as “Sources Group x” in the illustration above) according to their purpose. If local libraries are implemented within an application, these must have separate subdirectories for their sources.

tests\auto

The scripts and executables necessary to run the automated tests of the library/application are stored here.

tests\Test 1
tests\Test 2

etc.

Small test implementation projects reside in these subdirectories. The projects and their subdirectories, respectively, could be named like the part of functionality they test. Any implementations needed for the automatic tests are stored in subdirectories. The Visual Studio solution (*.sln) file for all tests (if existent) is to be placed under the “tests” directory.

 

A universal library tree like the one described above can be placed into an arbitrary directory on the disk. In order to assure flexibility of the location of the library and to make library version switching and testing easier, an environment variable can be defined containing the root directory of the library. The name of the environment variable follows the convention:

 

One could then easily switch to a new version of the library, say 2.34, by changing the value of the environment variable to “MYFIRSTLIBRARY_ROOT=/dir/MyLibrary_2.34”

and by placing a new library tree into “MyLibrary_2.34”. In this way, no change to any projects that use the library is needed. On the other hand, projects that use the library should use the following additional include and library paths:

 

include:          $(MYFIRSTLIBRARY_ROOT)/include

library:            $(MYFIRSTLIBRARY_ROOT)/lib

 

Actual header includes in the source code look like:

 

#include “MyLibrary/LibraryHeader1.h”

 

The linker must be aware of linking “MyLibrary.lib” (release) or “MyLibraryD.lib” (debug) along.