Difference between revisions of "Standards for File Organization"
(→Source Files) |
(→File Organization) |
||
Line 26: | Line 26: | ||
In a Component-Based Software Engineering (CBSE) project, 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. | In a Component-Based Software Engineering (CBSE) project, 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 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. | 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. | ||
Line 36: | Line 38: | ||
The first source code file — e.g. <code>protoComponentMain.cpp</code> — contains the <code> main()</code> function that instantiates the module object and calls the <code>runModule</code> method to effect the configuration, coordination, computation, and communication for that component. | The first source code file — e.g. <code>protoComponentMain.cpp</code> — contains the <code> main()</code> function that instantiates the module object and calls the <code>runModule</code> method to effect the configuration, coordination, computation, and communication for that component. | ||
+ | |||
The second source code file — e.g. <code>protoComponentConfiguration.cpp</code> — contains the code that handles the component’s configuration and coordination functionality. | The second source code file — e.g. <code>protoComponentConfiguration.cpp</code> — contains the code that handles the component’s configuration and coordination functionality. | ||
+ | |||
The third source code file — e.g. <code>protoComponentComputation.cpp</code> — contains the code that handles the component’s computation and communication functionality. | The third source code file — e.g. <code>protoComponentComputation.cpp</code> — contains the code that handles the component’s computation and communication functionality. | ||
Line 56: | Line 60: | ||
=== Configuration Files === | === Configuration Files === | ||
Each component must have an associated configuration file, named after the component, e.g <code>protoComponent.ini</code>. It is stored in the config directory. | Each component must have an associated configuration file, named after the component, e.g <code>protoComponent.ini</code>. 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. | 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. |
Revision as of 02:43, 5 November 2014
Contents
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, 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.