The following describes how libraries and tools should be organised in a file hierarchy.
Organisation of libraries:
A library named foo is located in the directory libraries/foo.
Each library directory has the following directory structure:
Sub-directory | Contents |
---|---|
build | Library build files such as a Jamfile |
doc | Documentation (HTML) files |
example | Sample program files |
include | Header files |
src | Source files which must be compiled to build the library |
test | Regression or other test programs or scripts |
Include files belonging to library foo must be placed in the directory include/mcrl2/foo. Optionally a header file include/mcrl2/foo/foo.h may be added, that contains include directives for the most commonly used header files in include/mcrl2/foo.
Library code is put in the namespace mcrl2. If needed, a library foo can use its own namespace mcrl2::foo.
Organisation of tools:
A tool named foo is located in the directory tools/foo.
Each tool directory has the following directory structure:
Sub-directory | Contents |
---|---|
doc | Documentation (HTML) files |
test | Regression or other test programs or scripts |
Build files, source files and include files are located in the tool directory itself.
Reusable code must be put in a library, not in a tool!
Note
Some of these guidelines were taken from http://www.boost.org/more/lib_guide.htm.
Except for third party software, every header and source file should adhere to the following guidelines.
Every file should start with a preamble containing author names and links to copying and license information. The preamble should be formatted as follows, where AUTHORS stands for the names of the authors:
// Author(s): AUTHORS
//
// Copyright: see the accompanying file COPYING or copy at
// https://github.com/mCRL2org/mCRL2/blob/master/COPYING
//
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE_1_0.txt or copy at
// http://www.boost.org/LICENSE_1_0.txt)
The following naming conventions regarding filenames should be used:
The following naming conventions regarding file contents should be used:
MCRL2_
.The following guidelines are specific to header files (based on http://www.boost.org/more/header.htm):
The following is a sample header:
// Author(s): AUTHORS
//
// Copyright: see the accompanying file COPYING or copy at
// https://github.com/mCRL2org/mCRL2/blob/master/COPYING
//
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE_1_0.txt or copy at
// http://www.boost.org/LICENSE_1_0.txt)
//
/// \file FILE_NAME
/// \brief BRIEF_DESCRIPTION
#ifndef MCRL2_MY_CLASS_H
#define MCRL2_MY_CLASS_H
namespace mcrl2 {
class my_class
{
public:
void f();
private:
int x;
};
} // namespace
#endif // MCRL2_MY_CLASS_H
Use exceptions to report errors where appropriate, and write code that is safe in the face of exceptions.
Aim for ISO Standard C++. That means making effective use of the standard features of the language, and avoiding non-standard compiler extensions. It also means using the C++ Standard Library where applicable.
Provide a regression test program or programs.
Provide sample programs or confidence tests so potential users can see how to use your library.
The source code must compile on the actively supported platforms and supported build tools on those platforms.
When committing changes, the following guidelines should be adhered to:
This page describes the documentation guidelines for tools and libraries.
Tool documentation should consists of help information and a user manual. The help information is described in the tool interface guidelines, the user manual is described here.
The tool use manual is automatically generated from the help description of the tool, provided that the tool uses the Tool classes. We therefore require that all tools use the tool classes.
Library documentation should consist of a user manual and reference manual. Both should be available on the library documentation page.
The library user manual provides an informal explanation of the library and its use. It should consist of the following sections (in that order):
Written by AUTHORS
.
where AUTHORS
stands for the names of the authors.Report bugs at our issue tracking system <http://www.mcrl2.org/issuetracker>
.The library reference manual provides a technical specification of the library. It should consist of an explanation of all used elements in the public interface. This manual should be automatically generated from the library code using Doxygen comments. The current convention is that only documented code will be displayed, unless the internal command is included in the Doxygen comment. Library code located in a detail sub-directory is considered to be no part of the public interface, and no documentation is generated for this code.
Doxygen documentation should specified as follows:
In the above specified documentation, the following Doxygen special commands should be used:
The following documentation guidelines apply to both tools and libraries.
All tools and libraries should acknowledge authors of used or “inspirational” code. This does include but is certainly not limited to fulfilling license requirements. Acknowledgements are required in the following cases:
However, things regarded as common knowledge are excluded from the latter two requirements.
Besides these requirements, authors of the mCRL2 toolset are highly encouraged to add references to related work (similar to adding related work in a paper).
Some examples to illustrate:
We distinguish three types of acknowledgements:
Some examples to illustrate:
Where to acknowledge and to what extent: