Difference between revisions of "Standards for File Organization"

Revision as of 07:21, 15 February 2015

Directory Structure

Files for a single component should be stored in a directory named after the component, e.g. protoComponent. Note that we keep the leading letter in lowercase since this directory refers to a component, not a class (in which case, in most conventions, the leading letter would be in uppercase).

This directory should have three sub-directories: src, app, and config (see figure below).

The src directory contains the *.c, *.cpp, and *.h files.

The app directory contains the *.xml XML robot application files.

The config directory contains the configuration file, named after the component and with a .ini extension. For example, protoComponent.ini. Other resources, e.g. image files should also be placed in the config directory.

Filename Roots and Extensions

All files should have the same root, reflecting computational purpose of the component, e.g. protoComponent.

Source code files for C and C++ should use a .c and .cpp extension, respectively. Header files should have a .h extension in both cases.

File Organization

Source Files

Normally, there are three different types of source code file in any given project. These are the interface, implementation, and application files.

In a Component-Based Software Engineering (CBSE) project, such as DREAM, the source code application file is replaced by the application script file or application XML file that runs the various components and connects them together in a working system.

The interface file is a header file with the class declarations and method prototype declarations but no method implementations (C++) or the function prototype declarations (C).

The implementation file contains the source code for the implementation of each class method (C++) or the source code of each function (C). General purpose functions might eventually be placed in a library.

In DREAM, for YARP modules we further separate the implementation into three files.

• The first source code file — e.g. protoComponentMain.cpp — contains the main() function that instantiates the module object and calls the runModule method to effect the configuration, coordination, computation, and communication for that component.

• The second source code file — e.g. protoComponentConfiguration.cpp — contains the code that handles the component’s configuration and coordination functionality.

• The third source code file — e.g. protoComponentComputation.cpp — contains the code that handles the component’s computation and communication functionality.

In summary, the implementation of a typical component will comprise four files. Using the protoComponent component as an example, these are:

protoComponent.h 
protoComponentMain.cpp
protoComponentConfiguration.cpp 
protoComponentComputation.cpp

All four should be placed in the src directory.

Application Files

The app directory should contain at least one XML application file. It should be named after the component but with the suffix TEST, for example protoComponentTEST.xml. This application file will be used to validate that the component works correctly and will be used to test the component when it is being submitted for integration. Instructions on how to run the test should be included in a README.txt file in the same directory.

Configuration Files

Each component must have an associated configuration file, named after the component, e.g protoComponent.ini. It is stored in the config directory.

The configuration file contains the key-value pairs that set the component parameters. For readability, each key-value pair should be written on a separate line.