Directory Structure (Next) Build System (Next)

The PSCF directory contains a variety of different types of files with distinct file name suffixes.

Source code files

All C++ code files associated with a given class or set of functions are placed in the same directory and have the same base name, with different file name suffixes. The name of a file that contains C++ code for a single class or class template almost always has a base name that is the same as the class name, with a file name suffix that indicates the file type. All namespace and class names upper space camel capitalization, in which the first letter of each word in a name is capitalized.

PSCF uses the following file name suffixes for C++ and CUDA C++ files:

Pattern	Purpose
*.h	C++ header file
*.tpp	implementation of a class template
*.cpp	compilable C++ source file
*.cu	compilable CUDA C++ source file

These different types of file are discussed in more detail below.

Header Files*: Header files, with suffix .h, may be included into other C++ files using a C/C++ preprocessor #include directive, and are never directly compiled by the build system.

Compilable Source Files*: Files with file name suffix *.cpp and *.cu are compiled and linked by the build system, and may never be included into other files. Compilable source files that contain and include only standard C++ code may be given file suffix .cpp. Compilable source files that contain or include any CUDA C++ code must instead use file suffix .cu. Different makefile pattern rules are used to compile files with filename suffix .cpp and .cu, using different compilers, using the NVIDIA nvcc compiler to compile files with file suffix .cu.

Compilable *.cpp and *.cu source files usually contain definitions of non-inlined functions that are declared in header file with the same base name. A compilable source file whose base name is the same as a class name normally contains definitions of non-inline member functions of that class.

Template implementation files:* Files with suffix .tpp, known as template implementation files, normally contain either the member functions of a class template or definitions of set of global function templates. There are two different types of class templates, for which the associated template implementation files are treated somewhat differently by the build system:

"Standard" or "Implicit" class templates are designed to rely on the usual mechanism of implicit instantiation. Any *.tpp template implementation file associated with a implicit class template must be included into the associated header file near the end of the header file.
"Explicit" class templates are templates for which all required specializations must be explicitly instantiated. Any *.tpp template implementation file for such an "explicit" template must be include the associated *.h header file and must be included into one or more associated *.cpp or *.cu files that contain explicit instantiation definitions.

Usage patterns and file conventions for class templates in PSCF are discussed in more detail elsewhere.

Build system files

The PSCF build system is based on the unix "make" command, and uses several types of file that are placed in the src and bld directories. The following table list two types of file that are part of this build system:

Pattern	Purpose
makefile	makefile (instructions for the make command)
*.mk	makefile fragment (included by other makefiles)

Immediately after the PSCF repository is cloned, almost every subdirectory of the src directory will contain both a makefile and a makefile fragment named sources.mk. The sources.mk file defines a list of all of compilable *.cpp and/or *.cu source files in that directory. Each namespace-level directories of src will also contain an additional makefile fragments named patterns.mk that defines pattern rules for compilation of source files in that directory.

After the configure script has been run, the src and bld directory will each contain an additional makefile fragment named config.mk, while the bld directory and each namespace-level subdirectory of the bld directory will contain a makefile.

The PSCF build system is discussed in detail on the following page.

Documentation files

The PSCF web manual is constructed using the doxgen documentation utility. This utility extracts API documentation from source code files, and also incorporates manual pages that are constructed from separate files.

Files that contain the contents of a web manual page have file names that end with file name suffix .dox. The main manual pages are *.dox files that are located in the docs/manual directory. Some other files that are used by doxygen also appear in the src/ directory alongside the source code files.

The following two file name suffixes are used for files that are used by doxygen to construct a web manual:

Pattern	Purpose
*.dox	doxygen web manual page
*.mod	doxygen topic module definition

Each files with file name suffix .mod defines one of the doxygen "Topic" modules that is used to create the hierarchical presentation of class API documentation that is accessible via the "Topics" tab at the top of every web manual page.

Most of the *.dox files that appear in the src directory contain the contents manual pages that provide additional information for users about a particular class or class template. The name of a file that contains the content of such a manual page usually has a prefix that is the same the name of the class or class template (which is also used as a prefix for the associated source code files) followed by a suffix .dox. Each such web manual page usually describe the syntax of the parameter file block associated with a class, and may also provide information about algorithm or mathematical conventions that a user would need to understand in order to write the parameter file block and choose appropriate values for parameters. The resulting user-oriented web manual pages do not contain the API documentation that is extracted from comments in the source code, which doxygen uses to create a separate API documentation page for each class or class template. The user documentation page and the API documentation page for each class or class template are usually accessible to one another via html links.

Directory Structure (Prev) Developer Information (Up) Build System (Next)