Organization - pronobis/rocs GitHub Wiki

Functional Organization

ROCS is organized into modules. Each module consists of components and applications which can be enabled or disabled during the build process. Moreover, ROCS provides test applications which can be used to perform automatic tests.

Code Structure

Structuring Code in Different Programming Languages

C++

C++ has the notion of namespaces. It also uses directory structure to organize the include files and libraries.
Namespaces are independent from the directory structure.
Namespace names are lower-case.
Namespaces can be nested
The include paths and the library names do not have to reflect the namespace structure.

Java

The package is Java's mechanism for managing namespaces. A package is a collection of related classes and interfaces providing access privileges and namespace management.
Java packages are namespaces.
The names of Java packages should be all lower case and consist of one or more identifiers, separated by dots (periods), such as one.two.three.
If you want the contents of several Java source code files to be part of a package called one.two.three, then the following line of code must be the first non-comment line in each of those files: package one.two.three;
All files in a given package must be located in a single sub-directory corresponding to the package name, and the package name will be "translated" to a directory path on the local system (with each dot becoming a separator character between portions of the path). For example, on a Unix or Linux system the class files of the package one.two.three must be stored at a location like this /rest_of_path/one/two/three. In addition, the part of the path down to one/two/three (or one\two\three) must be part of the classpath for the given system.

Python

Packages are a way of structuring Python’s module namespace by using “dotted module names”.
For example, the module name A.B designates a sub-module named B in a package named A.
Packages can have sub-packages.
Packages are defined by the filesystem directory structure e.g. A.B will correspond to path A/B

Matlab

MATLAB has a notion of packages which can be nested and include both classes and functions.
Packages are not supported for classes created prior to MATLAB Version 7.6
Packages are special folders that can contain class folders, function and class definition files, and other packages.
Package folders always begin with the + character. For example, +mypack, +mypack/pkfcn.m, +mypack/@myClass

Octave

There might be support for the matlab packages soon, or can always be hacked.
See http://octave.1599824.n4.nabble.com/namespace-support-td1638758.html

Structuring code in ROCS

The following naming convention should be used for everything in ROCS: rocs::module::component. This allows to uniquely identify a component within a module and ROCS as a whole. In other words, all libraries, include paths, namespaces, packages etc. must contain all this information.

C++

To be compatible with other programming languages that build namespaces based on directory structure, each C++ module should be in its own namespace and directory.
We will have namespace rocs { namespace module {} }
The organization of the include files will reflect that: e.g. rocs/module/File.hpp
The name of the module library will reflect that: e.g. rocs_module.so

Directory Structure

Sources

The following directory structure is implemented in source package of ROCS:

${ROCS_SRC_ROOT}
- cmake - CMake build system macros
- config - Configuration files
- data - Data files for testing ROCS
- doc - Documentation
  - dox - General Doxygen documentation files
- src/<module> - Sources of a ROCS module
  - dox - Doxygen documentation of the module
  - cpp - C++ code of the module
    - rocs/<module> - C++ code of the module library
    - apps/<app> - C++ code of the module apps
    - tests/<test_app> - C++ code of the module test apps
  - python - Python code of the module
    - rocs/<module> - Python code of the module library
    - apps/<app> - Python code of the module apps
    - tests/<test_app> - Python code of the module test apps
  - matlab - Matlab code of the module
    - +rocs/+<module> - Matlab code of the module library
    - apps/<app> - Matlab code of the module apps
    - tests/<test_app> - Matlab code of the module test apps
  - octave - Octave code of the module
    - +rocs/+<module> - Octave code of the module library
    - apps/<app> - Octave code of the module apps
    - tests/<test_app> - Octave code of the module test apps
  - java - Java code of the module
    - rocs/<module> - Java code of the module library
    - apps/<app> - Java code of the module apps
    - tests/<test_app> - Java code of the module test apps
- thirdparty - Third-party ROCS dependencies including into the framework.

Installed Files

The following directory structure is used for built and installed files:

${ROCS_DIR}
- bin - The executable files of the ROCS applications. The name of each application starts with rocs-.
- config - Configuration files
- data - Data files for testing ROCS
- doc - Documentation of ROCS
  - html - HTML documentation
- include/rocs/<module> - ROCS include files for a specific module
- lib - Binary libraries for the C++ code. There is one C++ library for each module called librocs_<module>.
  - python/rocs/<module> - Python module files stored as a Python package
  - matlab/+rocs/+<module> - Matlab module files stored as a Matlab package
  - octave/+rocs/+<module> - Octave module files
  - java/rocs/<module> - Java module classes
- test - Sources of the test applications
  - cpp/<test_app> - Source of a C++ test application
  - python/<test_app> - Source of a Python test application
  - matlab/<test_app> - Source of a Matlab test application
  - octave/<test_app> - Source of a Matlab test application
  - java/<test_app> - Source of a Matlab test application

CMake Build System Variables and Options

Internal Variables

Paths
- ROCS_SRC_ROOT - Path to the root of the ROCS source directory.
- ROCS_DIR - Path to the directory where ROCS should be installed.
- ROCS_SRC_DOC - Path to the directory containing sources of the documentation.
- ROCS_SRC_CMAKE - Path to the directory containing cmake source files.
- ROCS_SRC_CONFIG - Path to the directory containing config files.
- ROCS_SRC_DATA - Path to the directory containing data files.
- ROCS_SRC_TEST - Path to the directory containing sources of all test apps.
- ROCS_SRC_MODULES - Path to the directory containing sources of all modules.
- ROCS_SRC_THIRDPARTY - Path to the directory containing sources of all thirdparty apps.
Info
- INSTALL_TO_SRC_ROOT - If true, ROCS is being installed to @ROCS_SRC_ROOT@
- INSIDE_ROCS - When defined, scripts know they are executed from within ROCS source tree.
Building
- ROCS_BUILD_DOC - If true, documentation should be built
- ROCS_BUILD_TEST - If true, tests should be built
- ROCS_BUILD_GPL - If true, GPL components should be built
- ROCS_BUILD_QTGUI - If true, Qt GUI should be built
- ROCS_BUILD_MODULE_<MODULE_NAME> - If true, the module should be built. If component selection is performed, this enables the always available components.
- ROCS_BUILD_MODULE_<MODULE_NAME>_APPS - If true, the module apps should be built. If component selection is performed, this enables the apps related to the always available components.
- ROCS_BUILD_MODULE_<MODULE_NAME>_<COMPONENT_NAME> - If true, the component of the module should be built.
- ROCS_BUILD_MODULE_<MODULE_NAME>_<COMPONENT_NAME>_APPS - If true, the apps related to the component of the module should be built.
- ROCS_BUILD_THIRDPARTY_<THIRDPARTY_CODE> - If true, the third party code should be built.
External dependencies
- ROCS_FIND_<EXTERNAL_DEP> - If true, the external dependency should be found.
- <EXTERNAL_DEP>_LIBRARIES - Paths to the libraries of the external dependency.
Useful, when included into larger projects
- ROCS_DONT_DEFINE_OPTIONS - If true, ROCS is not defining any of the build options which can be set as regular variables.
Other
- ROCS_MAX_DEBUG_LEVEL - Sets the maximal debug level compiled into ROCS.

Some variables are prefixed with ROCS_. This is useful when ROCS is included into a larger project.

Build Options

ROCS_BUILD_DOC
ROCS_BUILD_GPL
ROCS_BUILD_QTGUI
USE_INTERNAL_BOOST
USE_MODULE_<MODULE_NAME>
USE_MODULE_<MODULE_NAME>_<COMPONENT_NAME>
USE_MODULE_<MODULE_NAME>_APPS
USE_MODULE_<MODULE_NAME>_<COMPONENT_NAME>_APPS
USE_FUNC_<FUNCTIONALITY>
USE_FUNC_<FUNCTIONALITY>_APPS
ROCS_DIR
CMAKE_BUILD_TYPE
ROCS_MAX_DEBUG_LEVEL

In general, the USE_ should be used by the users to decide which functionality should be turned on. Then, proper ROCS_BUILD_ variables are defined which determine what is actually built (e.g. the functionality might require multiple modules or there might be interdependencies between modules). The component interdependencies are resolved automatically.