Difference between revisions of "Standards for File Organization"

From David Vernon's Wiki
Jump to: navigation, search
(→‎Source Files)
(→‎Directory Structure)
 
(13 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
== Directory Structure ==
 
== Directory Structure ==
−
Files for a single component should be stored in a directory named after the component, e.g. <code>protoComponent</code>. 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).
+
The directory containing the CINDY cognitive architecture implementation comprises six subdirectories:
  
−
This directory should have three sub-directories: <code>src</code>, <code>app</code>, and <code>config</code> (see figure below). 
+
* <code>app</code>
 +
* <code>build</code>
 +
* <code>bin</code>
 +
* <code>components</code>
 +
* <code>config</code>
 +
* <code>lib</code>
  
−
The src directory contains the <code>*.c</code>, <code>*.cpp</code>, and <code>*.h</code> files.
+
The app directory contains contains the <code>*.xml</code> XML application files for the entire cognitive architecture, i.e. applications that deploy many components.
  
−
The app directory contains the <code>*.xml</code> XML robot application files.
+
The build directory contains the files that are use to compile the component executables. In particular, it contains the CINDY.sln solution file that is used to compile the project.
  
−
The config directory contains the configuration file, named after the component and with a <code>.ini</code> extension. For example, <code>protoComponent.ini</code>. Other resources, e.g. image files should also be placed in the <code>config</code> directory.
+
The executables are placed in the bin directory by the CINDY.sln file after compilation and linking.
  
−
[[File:directory_structure.png]]
+
The components file contains the source code for all the individual components.  Each component has a sub-directory of its own. This is named after the component, e.g. <code>protoComponent</code>. 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).
  
−
<center><strong>Logical Directory Structure of the DREAM Repository</strong></center>
+
In turn, each component sub-directory has three sub-sub-directories: <code>src</code>, <code>app</code>, and <code>config</code>. 
  
−
=== Filename Roots and Extensions ===
+
# The src directory contains the <code>*.c</code>, <code>*.cpp</code>, and <code>*.h</code> files.
 +
# The app directory contains the <code>*.xml</code> XML application files that are used to test this particular component.
 +
# The config directory contains the configuration file, named after the component and with a <code>.ini</code> extension. For example, <code>protoComponent.ini</code>. Other resources, e.g. image files are also be placed in the <code>config</code> directory.
 +
 
 +
On the other hand, there is also a config subdirectory of the main CINDY directory.  Like the app directory at this level, it contains the configuration files for these global system applications.
 +
 
 +
The bin lib subdirectory contains the various CINDY libraries.
 +
 
 +
== Filename Roots and Extensions ==
 
All files should have the same root, reflecting computational purpose of the component, e.g. <code>protoComponent</code>.
 
All files should have the same root, reflecting computational purpose of the component, e.g. <code>protoComponent</code>.
  
 
Source code files for C and C++ should use a <code>.c</code> and <code>.cpp</code> extension, respectively. Header files should have a <code>.h</code> extension in both cases.
 
Source code files for C and C++ should use a <code>.c</code> and <code>.cpp</code> extension, respectively. Header files should have a <code>.h</code> extension in both cases.
 +
  
 
== File Organization ==
 
== File Organization ==
  
 
===Source Files===
 
===Source Files===
−
Normally, there are three different types of source code file in any given project. These are the interface, implementation, and application 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.
−
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).
Line 31: Line 44:
 
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.
  
 +
In CINDY, for YARP modules we further separate the implementation into three files.
  
−
In DREAM, for YARP modules we further separate the implementation into three files.
+
* 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 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 third source code file — e.g. <code>protoComponentComputation.cpp</code> — contains the code that handles the component’s computation and communication 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.
+
−
 
+
  
 
In summary, the implementation of a typical component will comprise four files. Using the <code>protoComponent</code> component as an example, these are:
 
In summary, the implementation of a typical component will comprise four files. Using the <code>protoComponent</code> component as an example, these are:
Line 58: Line 68:
  
 
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.
 +
 +
 +
----
 +
Return to [[The CINDY Cognitive Architecture]] main page.

Latest revision as of 03:37, 17 February 2015

Directory Structure

The directory containing the CINDY cognitive architecture implementation comprises six subdirectories:

  • app
  • build
  • bin
  • components
  • config
  • lib

The app directory contains contains the *.xml XML application files for the entire cognitive architecture, i.e. applications that deploy many components.

The build directory contains the files that are use to compile the component executables. In particular, it contains the CINDY.sln solution file that is used to compile the project.

The executables are placed in the bin directory by the CINDY.sln file after compilation and linking.

The components file contains the source code for all the individual components. Each component has a sub-directory of its own. This is 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).

In turn, each component sub-directory has three sub-sub-directories: src, app, and config.

  1. The src directory contains the *.c, *.cpp, and *.h files.
  2. The app directory contains the *.xml XML application files that are used to test this particular component.
  3. 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 are also be placed in the config directory.

On the other hand, there is also a config subdirectory of the main CINDY directory. Like the app directory at this level, it contains the configuration files for these global system applications.

The bin lib subdirectory contains the various CINDY libraries.

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 CINDY, 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.


Return to The CINDY Cognitive Architecture main page.

Retrieved from "http://www.vernon.eu/w/index.php?title=Standards_for_File_Organization&oldid=611"