diff --git a/docs/Dev.rst b/docs/Dev.rst
index aa25b86..56581df 100755
--- a/docs/Dev.rst
+++ b/docs/Dev.rst
@@ -1,338 +1,344 @@
=============================
Developing the RoSA Framework
=============================
.. contents::
:local:
This document provides information that might be useful for contributing to
RoSA. Please also consult :doc:`Build`.
.. _Dev_Source_Directory:
The Source Directory
====================
The source directory consists of the following subdirectories:
`cmake`
Contains files used for configuring the `CMake Project`_.
`docs`
Contains `Documentation`_-related files.
`examples`
Contains `Examples`_ on using the public API.
`include/rosa`
Contains the RoSA public API -- that is the interface of RoSA `Libraries`_.
The directory `include` is to be used as include directory and RoSA header
files are to be included in C++ sources as `"rosa/"`.
`lib`
Contains the implementation of the RoSA public API -- that is the
implementation of RoSA `Libraries`_.
`tools`
Contains `Tools`_ based on RoSA features.
Software Sources
================
The section describes the `Logical Structure`_ of the software sources and what
`Coding Standards`_ are supposed to be followed for the implementation.
Logical Structure
-----------------
Various features provided by RoSA are sorted into different `Libraries`_.
`Examples`_ and `Tools`_ using those `Libraries`_ are separated from the
implementation of the RoSA features into different directories.
Libraries
~~~~~~~~~
The framework consists of separate libraries providing different features. The
public interfaces for RoSA libraries are defined in `include/rosa`, while
corresponding implementation is in `lib`. Each library has its own subdirectory
in the mentioned directories.
RoSA provides the following libraries:
`config`
Provides information on the configuration used to build the framework, e.g.,
version number, log level, assertions, and debugging.
`support`
Provides general features -- template metaprograms dealing with types, for
instance -- for implementing other libraries.
`core`
Provides the basic RoSA features, like systems managing agents passing
messages.
`agent`
Provides features to be used for implementing agents.
.. _Library_Dependencies:
Dependencies
''''''''''''
The following table summarizes dependencies among libraries.
A marking in a row denotes that the library in the beginning of the row depends
on the library in the head of the given column.
+---------+--------+---------+------+-------+
| | config | support | core | agent |
+=========+========+=========+======+=======+
| config | | | | |
+---------+--------+---------+------+-------+
| support | | | | |
+---------+--------+---------+------+-------+
| core | | × | | |
+---------+--------+---------+------+-------+
| agent | | | | |
+---------+--------+---------+------+-------+
Examples
~~~~~~~~
Some simple samples are provided in `examples` to demonstrate how to to use
different parts of the RoSA API.
Tools
~~~~~
Tools, programs based on the RoSA libraries, are implemented in `tools`.
.. _Coding_Standards:
Coding Standards
----------------
RoSA is implemented in standard *C++14* code. All the software sources are to
be written in accordance to the `LLVM Coding Standards`_.
Documentation Comments
~~~~~~~~~~~~~~~~~~~~~~
It is important to remember to document source code using `doxygen comments`_
as `API Documentation`_ is generated directly from sources.
Note that the syntax of documentation comments is checked during compilation --
at least when using a GCC-compatible compiler.
Whenever you work on a source file, make sure your name is in the author-list
defined in the header comment of the file. Each author should be defined with a
separate `\\author` command so that recent authors come first. Authors not
participating in further development of a file anymore may be marked with the
period of their contribution.
If declarations belonging to a namespace are spread to more than one source
-files, document the namespace in `include/rosa/config/namespaces.h`. Otherwise,
-document the namespace in the only file in which entities of the namespace are
-declared.
+files, document the namespace in a separate `namespace.h` in the directory
+belonging to the library. Otherwise, document the namespace in the only file in
+which entities of the namespace are declared.
Header Files
~~~~~~~~~~~~
Follow the recommendations on public and private header files and the usage of
`#include` from the `LLVM Coding Standards`_.
Use `.h` and `.hpp` extensions to indicate the content of the header file:
* header files containing any *definition* -- template or inline definition --
or including another header file with `.hpp` extension have `.hpp` extension;
* header files containing only *declarations* and including only header files
with `.h` extension have `.h` extension.
+It may happen that a header file does not need any corresponding implementation
+in a `.cpp` file. Nevertheless, do create a corresponding `.cpp` file which only
+includes the header file in this case. That makes sure that the header file is
+compiled and hence checked for errors, and also a corresponding entry in the
+compilation database is generated.
+
Checking and Enforcing the Coding Standards
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The tools `clang-tidy `_ and
`clang-format `_ can be used to
check and enforce the coding standards. The two tools are integrated into the
CMake project, refer to CMake variables
:ref:`ROSA_ENABLE_CLANG_TIDY ` and
:ref:`ROSA_INCLUDE_CLANG_FORMAT `.
Note that there may be situations when `clang-tidy` checks result in false
positives -- for example, for some cases of the order of `#include` directives.
One can order `clang-tidy` to suppress warnings for a line of code by marking
that line with::
// NOLINT
It may be preferred to diverge from the standard formatting -- for example for
the sake of readability of static definition of arrays following some
structure. One can disable `clang-format` for some lines of code by designating
a range with two special comments as::
// clang-format off
... clang-format is disabled here ...
// clang-format on
Documentation
=============
The RoSA Framework is delivered with two kinds of documentation: `General
Documentation`_ and `API Documentation`_, generation of both of which is
integrated into the CMake project.
References between the two documentations are relative addresses corresponding
to the directory structure of the
:ref:`generated documentation `.
General Documentation
---------------------
General documentation is written as
`reStructuredText `_ compiled with
`Sphinx `_. For build integration, refer to the
CMake variable :ref:`ROSA_ENABLE_SPHINX `.
Documentation files are located in `docs` with extension `.rst`. The main
page of the documentation is `docs/index.rst`. Configuration for building the
documentation is `docs/conf.py`.
The directory `docs/CommandGuide` contains documentation for each separate
tool. Those pages are included in the HTML documentation via
`docs/CommandGuide/index.rst`. Moreover, man pages can be generated from those
tool documentation pages.
API Documentation
-----------------
API documentation is directly generated from sources with
`Doxygen `_. For build integration, refer to the CMake
variable :ref:`ROSA_ENABLE_DOXYGEN `.
The main page used for the API documentation is `docs/doxygen-mainpage.dox`.
Configuration for generating the API documentation is `docs/doxygen.cfg.in`.
.. _CMake Project:
Managing the CMake Project
==========================
This section briefly summarizes when and how to modify CMake files during
the development process. No general discussion on CMake features is provided
here.
When modifying `Documentation`_, no need to update the CMake files.
Software
--------
One needs to modify the CMake files only if source files are to be added or
removed from the project. Here follows some typical scenarios.
Source Files
~~~~~~~~~~~~
Each library and executable target has its own directory and its own definition
as a file called `CMakeLists.txt` in that directory.
When adding or removing a source file -- both headers and `.cpp` files -- to a
library or executable, locate the corresponding `CMakeLists.txt` file. The file
is typically in the same directory where the file to be added or removed is
located. Except for header files of the public API, for which the corresponding
CMake target is defined in a `lib` subdirectory corresponding to the library the
header files belongs to.
Update the source list in the argument of the `add_library` or `add_executable`
command in the `CMakeLists.txt`, for libraries and executables, respectively.
A library and executable may use features provided by another library. Such a
dependency is to be defined in the `CMakeLists.txt` file of the dependent
target by using the `ROSA_add_library_dependencies` command.
CMake Libraries
~~~~~~~~~~~~~~~
When adding or removing a library, add or remove the corresponding directories
from `include` and `lib`, and also update `lib/CMakeLists.txt` by adding or
removing a `add_subdirectory` command for the library.
When defining a new library, the new subdirectory under `lib` needs to contain a
`CMakeLists.txt`, which needs to contain at least an `add_library` command
defining the name of the library and the source files belonging to it.
CMake Executables
~~~~~~~~~~~~~~~~~
When adding or removing an executable, add or remove the corresponding
directory from `examples` or `tools`, and also update `CMakeLists.txt` in the
containing directory as for libraries.
When defining a new executable, the new subdirectory needs to contain a
`CMakeLists.txt`, which needs to contain at least an `add_executable` command
defining the name of the executable and the source files belonging to it.
.. _Dev Managing Sources:
Managing Sources
================
Consider the followings before committing changes to the repository:
* your code complies with the `Coding Standards`_ as much as possible;
* your code is well documented;
* your code is not bloated with unusued code and/or comments;
* your changes do not break building and executing the framework:
* test all of the supported platforms if possible,
* look into the generated documentation if you have edited
`General Documentation`_;
* you do not pollute the repository with unused and generated files.
When committing changes to the repository, provide a concise log message with
your commit.
Miscellaneous Concerns
======================
Using YCM
---------
If you happen to use `YCM `_, just
make a copy of the provided `ycm_extra_conf.py.template` file as
`.ycm_extra_conf.py` in the RoSA source directory, and set the following two
variables in it:
`compilation_database_folder`
the absolute path of your build directory
`extra_system_include_dirs`
any system include directory which might not be searched by `libclang` [1]_.
You probably want compile with Clang if you use YCM, so run CMake with
environment variables `CC=clang` and `CXX=clang++` set.
Also note that header files in the `include` directory are compiled for YCM with
the compiler flags of a corresponding source file in the `lib` directory, if
any. Header files in other locations are supposed to have a corresponding source
file in the same directory.
Notes
~~~~~
* If the project's include directory (`include/rosa`) would ever be changed,
then the YCM configuration file needs to be adjusted accordingly.
----
.. [1] See: https://github.com/Valloric/YouCompleteMe/issues/303; use the
following command to figure out the used system directories:
echo | clang -std=c++11 -v -E -x c++ -
.. _`LLVM Coding Standards`: http://llvm.org/docs/CodingStandards.html
.. _`doxygen comments`: http://llvm.org/docs/CodingStandards.html#doxygen-use-in-documentation-comments
diff --git a/include/rosa/config/namespaces.h b/include/rosa/agent/namespace.h
similarity index 57%
rename from include/rosa/config/namespaces.h
rename to include/rosa/agent/namespace.h
index c7f12f3..88c3482 100755
--- a/include/rosa/config/namespaces.h
+++ b/include/rosa/agent/namespace.h
@@ -1,30 +1,28 @@
-//===-- rosa/config/namespaces.h --------------------------------*- C++ -*-===//
+//===-- rosa/agent/namespace.h ----------------------------------*- C++ -*-===//
//
// The RoSA Framework
//
//===----------------------------------------------------------------------===//
///
-/// \file rosa/config/namespaces.h
+/// \file rosa/agent/namespace.h
///
/// \author David Juhasz (david.juhasz@tuwien.ac.at)
///
/// \date 2017
///
-/// \brief Documentation for namespaces that are scattered into more then one
-/// header file.
+/// \brief Documentation for namespace \c rosa::agent.
///
//===----------------------------------------------------------------------===//
-#ifndef ROSA_CONFIG_NAMESPACES_H
-#define ROSA_CONFIG_NAMESPACES_H
+#ifndef ROSA_AGENT_NAMESPACE_H
+#define ROSA_AGENT_NAMESPACE_H
-/// Base namespace used by the RoSA framework.
namespace rosa {
/// Contains facilities that are supposed to be useful for implementing
/// *agents*.
namespace agent {}
} // End namespace rosa
-#endif // ROSA_CONFIG_NAMESPACES_H
+#endif // ROSA_AGENT_NAMESPACE_H
diff --git a/lib/config/namespaces.cpp b/include/rosa/config/namespace.h
similarity index 51%
copy from lib/config/namespaces.cpp
copy to include/rosa/config/namespace.h
index 562f129..ce87454 100755
--- a/lib/config/namespaces.cpp
+++ b/include/rosa/config/namespace.h
@@ -1,20 +1,23 @@
-//===-- config/namespaces.cpp -----------------------------------*- C++ -*-===//
+//===-- rosa/config/namespace.h ---------------------------------*- C++ -*-===//
//
// The RoSA Framework
//
//===----------------------------------------------------------------------===//
///
-/// \file config/namespaces.cpp
+/// \file rosa/config/namespace.h
///
/// \author David Juhasz (david.juhasz@tuwien.ac.at)
///
/// \date 2017
///
-/// \brief Placeholder for rosa/config/namespaces.h.
-///
-/// \note Empty implementation, source file here to have a compile database
-/// entry for rosa/config/namespaces.h.
+/// \brief Documentation for the namespace \c rosa.
///
//===----------------------------------------------------------------------===//
-#include "rosa/config/namespaces.h"
+#ifndef ROSA_CONFIG_NAMESPACE_H
+#define ROSA_CONFIG_NAMESPACE_H
+
+/// Base namespace used by the RoSA framework.
+namespace rosa {}
+
+#endif // ROSA_CONFIG_NAMESPACE_H
diff --git a/lib/agent/CMakeLists.txt b/lib/agent/CMakeLists.txt
index dd135e4..7a4c03d 100644
--- a/lib/agent/CMakeLists.txt
+++ b/lib/agent/CMakeLists.txt
@@ -1,12 +1,14 @@
set(LIB_INCLUDE_DIR ${ROSA_MAIN_INCLUDE_DIR}/rosa/agent)
add_library(ROSAAgent
+ ${LIB_INCLUDE_DIR}/namespace.h
+ namespace.cpp
${LIB_INCLUDE_DIR}/Module.h
Module.cpp
${LIB_INCLUDE_DIR}/Abstraction.hpp
Abstraction.cpp
${LIB_INCLUDE_DIR}/History.hpp
History.cpp
${LIB_INCLUDE_DIR}/Confidence.hpp
Confidence.cpp
)
diff --git a/lib/config/namespaces.cpp b/lib/agent/namespace.cpp
similarity index 63%
copy from lib/config/namespaces.cpp
copy to lib/agent/namespace.cpp
index 562f129..cfac9b9 100755
--- a/lib/config/namespaces.cpp
+++ b/lib/agent/namespace.cpp
@@ -1,20 +1,20 @@
-//===-- config/namespaces.cpp -----------------------------------*- C++ -*-===//
+//===-- agent/namespace.cpp -------------------------------------*- C++ -*-===//
//
// The RoSA Framework
//
//===----------------------------------------------------------------------===//
///
-/// \file config/namespaces.cpp
+/// \file agent/namespace.cpp
///
/// \author David Juhasz (david.juhasz@tuwien.ac.at)
///
/// \date 2017
///
-/// \brief Placeholder for rosa/config/namespaces.h.
+/// \brief Implementation for rosa/agent/namespace.h.
///
/// \note Empty implementation, source file here to have a compile database
-/// entry for rosa/config/namespaces.h.
+/// entry for rosa/agent/namespace.h.
///
//===----------------------------------------------------------------------===//
-#include "rosa/config/namespaces.h"
+#include "rosa/agent/namespace.h"
diff --git a/lib/config/CMakeLists.txt b/lib/config/CMakeLists.txt
index 5e57422..9e51146 100644
--- a/lib/config/CMakeLists.txt
+++ b/lib/config/CMakeLists.txt
@@ -1,14 +1,14 @@
set(LIB_INCLUDE_DIR ${ROSA_MAIN_INCLUDE_DIR}/rosa/config)
set(LIB_GEN_INCLUDE_DIR ${ROSA_INCLUDE_DIR}/rosa/config)
add_library(ROSAConfig
${LIB_GEN_INCLUDE_DIR}/rosa_config.h
- ${LIB_INCLUDE_DIR}/namespaces.h
- namespaces.cpp
+ ${LIB_INCLUDE_DIR}/namespace.h
+ namespace.cpp
${LIB_INCLUDE_DIR}/project_path.hpp
project_path.cpp
${LIB_INCLUDE_DIR}/config.h
config.cpp
${LIB_INCLUDE_DIR}/version.h
version.cpp
)
diff --git a/lib/config/namespaces.cpp b/lib/config/namespace.cpp
similarity index 63%
rename from lib/config/namespaces.cpp
rename to lib/config/namespace.cpp
index 562f129..2cd14c1 100755
--- a/lib/config/namespaces.cpp
+++ b/lib/config/namespace.cpp
@@ -1,20 +1,20 @@
-//===-- config/namespaces.cpp -----------------------------------*- C++ -*-===//
+//===-- config/namespace.cpp ------------------------------------*- C++ -*-===//
//
// The RoSA Framework
//
//===----------------------------------------------------------------------===//
///
-/// \file config/namespaces.cpp
+/// \file config/namespace.cpp
///
/// \author David Juhasz (david.juhasz@tuwien.ac.at)
///
/// \date 2017
///
-/// \brief Placeholder for rosa/config/namespaces.h.
+/// \brief Placeholder for rosa/config/namespace.h.
///
/// \note Empty implementation, source file here to have a compile database
-/// entry for rosa/config/namespaces.h.
+/// entry for rosa/config/namespace.h.
///
//===----------------------------------------------------------------------===//
-#include "rosa/config/namespaces.h"
+#include "rosa/config/namespace.h"