diff --git a/doc/contribute/NEST_Contributor_Agreement.pdf b/doc/contribute/NEST_Contributor_Agreement.pdf new file mode 100644 index 0000000000..f7cd2df373 Binary files /dev/null and b/doc/contribute/NEST_Contributor_Agreement.pdf differ diff --git a/doc/contribute/coding_guidelines_cpp.rst b/doc/contribute/coding_guidelines_cpp.rst new file mode 100644 index 0000000000..a739022e9f --- /dev/null +++ b/doc/contribute/coding_guidelines_cpp.rst @@ -0,0 +1,920 @@ +NEST coding style guidelines for C++ +==================================== + +In the code review process we want to enforce a consistent coding style to +improve readability and maintainability. The article on `why code readability +matters `_ gives an +intuition about the benefits of readable code. To simplify the process we use +different tools that check compliance with our coding style and developers can +reduce the workload of the review process by checking compliance of their code +on their own. + +For Python, we enforce `PEP8 `_ formatting. + +.. contents:: On this page, you'll find + :local: + :depth: 3 + +Tooling +------- + +The code has to compile without warnings (in the default settings of the build +infrastructure). We restrict ourselves to the C++11 standard for a larger support of +compilers on various cluster systems and supercomputers. + +The `clang-format `_ tool is built +on the clang compiler frontend. It prettyprints input files in a +configurable manner, and also has Vim and Emacs integration. We supply a +:ref:`clang-format-file` to enforce some parts of the coding style. During +the code review process we check that there is no difference between the committed +files and the formatted version of the committed files: + +Developers can benefit from the tool by formatting their changes before issuing +a pull request: for fixing the formatting of a single file consider using +``clang-format -i `` on that file. For fixing more files at once +we provide a script that applies the formatting. From the source directory +call: + +.. code:: + + ./extras/format_all_c_c++_files.sh [start folder, defaults to '$PWD'] + +We use clang-format version 3.6 in the Travis CI. Older versions do not +understand all formatting options we defined in ``.clang-format``. Newer versions +lead to formatting differences to files formatted with version 3.6 even though the +same set of rules is used. + +Get ``clang-format``: +Ubuntu see `here `_: + +.. code:: + + # To retrieve the archive signature: + wget -O - http://llvm.org/apt/llvm-snapshot.gpg.key | sudo apt-key add - + + # Repository for Trusty (14.04) + sudo sh -c 'echo "deb http://llvm.org/apt/trusty/ llvm-toolchain-trusty-3.6 main" >> /etc/apt/sources.list' + + # Repositories for Precise (12.04) + sudo sh -c 'echo "\ndeb http://llvm.org/apt/precise/ llvm-toolchain-precise-3.6 main" >> /etc/apt/sources.list' + sudo sh -c 'echo "deb http://ppa.launchpad.net/ubuntu-toolchain-r/test/ubuntu precise main" >> /etc/apt/sources.list' + # make sure each 'deb ...' is on its own line in /etc/apt/sources.list + + # install clang-format with: + sudo apt-get update + sudo apt-get install libstdc++6 libllvm3.6 clang-format-3.6 + +OS X: + +* Installing ``clang-format-3.6`` from the `pre-built + binaries `_. + +Further we use `Vera++ `_, which +'is a programmable tool for verification, analysis and transformation of C++ +source code'. It enables further checks for the code complying to the coding +guidelines. We provide the :ref:`vera-profile-nest` file in the +repository (which needs to be copied/symlinked into ``vera++home>/lib/vera++/profiles/``). +We then check that there are no messages generated by the execution of the following command: + +.. code:: + + vera++ -profile nest + +Get ``vera++``: +Ubuntu: + +.. code:: + + apt-get install vera++ + +OS X: + +.. code:: + + brew install vera++ + +Or consider installing ``vera++`` from the `binary +packages `_. + +Finally, we let `cppcheck `_ statically analyse +the committed files and check for severe errors. We require cppcheck version +1.69 or later. + +.. code:: + + cppcheck --enable=all + +Get ``cppcheck``: +Ubuntu 15.10: + +.. code:: + + apt-get install cppcheck + +Earlier versions of Ubuntu do not provide a package for cppcheck 1.69. Please +follow the instructions to build cppcheck from scratch. + +OS X: + +.. code:: + + brew install cppcheck + # or + sudo port install cppcheck + +Build from scratch: + +.. code:: + + git clone https://github.com/danmar/cppcheck.git + cd cppcheck + git checkout tags/1.69 + make PREFIX=$PWD/install/ CFGDIR=$PWD/install/cfg HAVE_RULES=yes install + + # In ``.bashrc`` at install/bin to ``PATH``: + export PATH=/path/to/cppcheck/install/bin:$PATH + +Local static analysis +##################### + +We ship a script ``./extras/check_code_style.sh`` that lets you perform the +checks on all changed files as we do during the Travis CI tasks. + +.. code:: + + $ ./extras/check_code_style.sh --help + Usage: check_code_style.sh [options ...] + + Usage: ./extras/check_code_style.sh [options ...] + + This script processes C/C++ and Python source code files to verify compliance with the NEST + coding style guidelines. The checks are performed the same way as in the NEST Travis CI + build and test environment. If no file is specified, a local 'git diff' is issued to obtain + the changed files in the commit range '..'. By default, this is + 'master..head'. + + The script expects to be run from the base directory of the NEST sources, + i.e. all executions should start like: + ./extras/check_code_style.sh ... + + The setup of the tooling is explained here: + https://nest-simulator.readthedocs.io/en/latest/contribute/coding_guidelines_cpp.html + + Options: + + --help This help. + + --[i]ncremental Prompt user before each file analysis. + + --file=/path/to/file Perform the analysis on this file. + + --git-start=Git_SHA_value Hash value (Git SHA) from which Git starts the diff. + Default: --git-start=master + + --git-end=Git_SHA_value Hash value (Git SHA) at which Git ends the diff. + Default: --git-start=HEAD + + --vera++=exe The name of the VERA++ executable. + Default: --vera++=vera++ + + --cppcheck=exe The name of the CPPCHECK executable. + Default: --cppcheck=cppcheck + Note: CPPCHECK version 1.69 or later is required. + This corresponds to the version installed in + the NEST Travis CI build and test environment. + + --clang-format=exe The name of the CLANG-FORMAT executable. + Default: --clang-format=clang-format-3.6 + Note: CLANG-FORMAT version 3.6 is required. + This corresponds to the version installed in + the NEST Travis CI build and test environment. + + --pep8=exe The name of the PEP8 executable. + Default: --pep8=pep8 + + --perform-vera=on/off Turn on/off VERA++ analysis. + Default: --perform-vera=on + + --perform-cppcheck=on/off Turn on/off CPPCHECK analysis. + Default: --perform-cppcheck=off + + --perform-clang-format=on/off Turn on/off CLANG-FORMAT analysis. + Default: --perform-clang-format=on + + --perform-pep8=on/off Turn on/off PEP8 analysis. + Default: --perform-pep8=on + +Assuming you are in source directory of NEST and you want to check all changed +files between the commits ``104d47c0`` and ``d66e4465``, execute the following +line: + +.. code:: + + ./extras/check_code_style.sh --git-start=104d47c0 --git-end=d66e4465 + +General remarks and resources +############################# + +C++ language features +~~~~~~~~~~~~~~~~~~~~~ + +1. Use only ISO C++ language features. +2. Prefer ISO C++ library functions over their ISO C library equivalents. +3. Prefer ISO C++ library containers (STL). +4. Prefer C++ headers over their C equivalents. +5. Don't use ``printf`` and related functions. +6. Use C++ style cast notation (see :ref:`books`). +7. Use the ``const`` qualifier where appropriate. Use it consistently (see :ref:`books`)! +8. Use namespaces and exceptions. +9. Try to avoid static class members which need a constructor (non POD). + +Language of comments and identifiers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. All comments should be written in English. +2. All identifiers, class and function names should be in English. + +Debugging and quality control +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use the ``assert`` macro intensively to check program invariants. +Create expressive unit-tests using one of the supplied SLI and Python unit-testing +infrastructure or the C++ testing framework based on Boost. + +Compiler +~~~~~~~~ + +NEST compiles with any recent version of the `GNU C/C++ +Compiler `_ ``gcc``. Support for and limitations of other +compilers is described in the :doc:`Installation Instructions <../installation/index>` + +Online reference documents +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. `C++ Reference `_ +2. `C++ Wikibooks `_ + +.. _books: + +Books +~~~~~ + +We have found the following books to be useful. + +1. Stroustrup B (1997) The C++ Programming Language, 3rd Edition, Addison-Wesley +2. Meyers S (1997) Effective C++, 2nd Edition, Addison Wesley +3. Meyers S (1996) More Effective C++, Addison Wesley +4. Coplien J O (1992) Advanced C++ programming styles and idioms, Addison-Wesley +5. Eckle B (1995) Thinking in C++, Prentice Hall +6. Plauger P J, Stepanov A, Lee M, and Musser D R (1998) The Standard Template Library, + Comming June 1998, 1. Prentice Hall +7. Plauger P J (1995) The (draft) Standard C++ Library, Prentice Hall +8. Musser D R and Saini A (1996) STL Tutorial and Reference Guide, Addison-Wesley +9. Kernighan B and Ritchie D (1988) The C Programming Language, 2nd Edition, Prentice Hall + +Coding style +############ + +In the following the coding style guidelines are explained by example and some +parts are adopted from `Google C++ Style +Guide `_. + +The #define guard +~~~~~~~~~~~~~~~~~ + +All header files should have ``#define`` guards to prevent multiple inclusions. +The format of the symbol name should be ``_H``. The file ``iaf_cond_alpha.h`` +should have the following guard: + +.. code:: + + #ifndef IAF_COND_ALPHA_H + #define IAF_COND_ALPHA_H + ... + #endif // IAF_COND_ALPHA_H + +Order of includes +~~~~~~~~~~~~~~~~~ + +Use standard order for readability and to avoid hidden dependencies: Related +header, C library, C++ library, other libraries' .h, your project's .h. + +NEST's Makefiles add all project specific include paths to the compile +commands, thus the file ``iaf_cond_alpha.h`` should be included as: +``#include "iaf_cond_alpha.h"`` + +In ``iaf_cond_alpha.cpp``, whose main purpose is to implement ``iaf_cond_alpha.h``, +order your includes as follows: + +1. ``iaf_cond_alpha.h``. +2. C system files. +3. C++ system files. +4. Other libraries' .h files. +5. Your project's .h files. + +With the preferred ordering, if ``iaf_cond_alpha.h`` omits any necessary +includes, the build of ``iaf_cond_alpha.cpp`` will break. Thus, this rule ensures +that build breaks show up first for the people working on these files, not for +innocent people in other packages. + +Within each section the includes should be ordered alphabetically. + +You should include all the headers that define the symbols you rely upon +(except in cases of forward declaration). If you rely on symbols from ``bar.h``, +don't count on the fact that you included ``foo.h`` which (currently) includes +``bar.h``: include ``bar.h`` yourself, unless ``foo.h`` explicitly demonstrates its +intent to provide you the symbols of ``bar.h``. However, any includes present in +the related header do not need to be included again in the related cpp (i.e., +``foo.cpp`` can rely on ``foo.h``'s includes). + +For example, the includes in ``/models/iaf_cond_alpha.cpp`` might look +like this: + +.. code:: + + #include "iaf_cond_alpha.h" + + #include + #include + #include + #include + + #include "config.h" + #include "foo.h" + #include "node.h" + +Exception +********* + +Sometimes, system-specific code needs conditional includes. Such code can put +conditional includes after other includes. Of course, keep your system-specific +code small and localized. Example: + +.. code:: + + #include "iaf_cond_alpha.h" + + #include "port.h" // For LANG_CXX11. + + #ifdef LANG_CXX11 + #include + #endif // LANG_CXX11 + +Indentation, formatting and naming +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Files +***** + +Files are named in ``lower_case_under_lined`` notation. C/C++ header files have +the extension ``.h``. C implementation files have the extension ``.c``. C++ +implementation files have the extension ``.cpp``. The use of ``.cc`` is deprecated +and is only left for compatibility. + +All files in NEST start with a preamble, which contains the filename and the +NEST copyright text (see example below). + +Lines should not exceed 120 characters (clang-format). Files should not be too +long (max. 2000 lines) (vera++:L006). No trailing whitespace (clang-format). + +Folders +******* + +Use ``lower_case_under_lined`` notation for folder names. + +Variables and class members +*************************** + +In general, use meaningful, non-abbreviated names or follow naming conventions +from the neuroscience field, e.g. the membrane potential is ``V_m``. Use the +``lower_case_under_lined`` notation. Private member variables should end with an +underscore (``name_``). If applicable, the general rule is use is to use the +same notation for biophysical quantities as is used in `Dayan&Abbot, 2001 +`_. + +Constants should be defined with ``enums`` and not with ``#define``, and use the +``UPPER_CASE_UNDER_LINED`` notation: + +.. code:: + + enum StateVecElems + { + V_M = 0, + DG_EXC, + G_EXC, + DG_INH, + G_INH, + STATE_VEC_SIZE + }; + +Built-in types +************** + +All code for the NEST kernel should use the type aliases, defined in ``nest.h``. +Thus, use ``nest::float_t`` instead of ``float``. + +Functions and class methods +*************************** + +In general, use meaningful, non-abbreviated names or follow naming conventions +from the neuroscience field, e.g. the membrane potential is ``V_m``. Use the +``lower_case_under_lined`` notation. + +There should be a line-break after the method's return type (implementation +only) (clang-format). Parameters of methods should either fit into one line or +each parameter is on a separate line (clang-format). + +.. code:: + + inline void + nest::Stopwatch::print( const char* msg, + timeunit_t timeunit, + std::ostream& os ) const + { + // code + } + +Namespaces +********** + +Use ``lower_case_under_lined`` notation for namespaces. Do not use ``using namespace`` +statements in header files (vera++:T018). The closing brace of a namespace should be +followed by a comment containing the namespace statement. +Do not indent the body of namespaces (clang-format). + +.. code:: + + namespace example + { + // code + } // namespace example + +All symbols for the NEST kernel are declared in the namespace ``nest``. + +Structs and classes +******************* + +Use a ``struct`` only for passive objects that carry data; everything else is a +``class``. Use ``CamelCase`` notation for naming classes, structs and enums, e.g. +``GenericConnBuilderFactory``. Private, nested classes and structs end with an +underscore (``State_``). + +The access modifier (``public``, ``protected``, ``private``) in class definitions are +not indented (clang-format). + +Do not implement methods inside the class definition, but implement small +``inline`` methods after the class definition and other methods in the +corresponding implementation file. + +Template class declarations follow the same style as normal class declarations. +This applies in particular to inline declarations. The keyword template +followed by the list of template parameters appear on a separate line. The < +and > in template expressions have one space after and before the sign, +respectively, e.g. ``std::vector< int >`` (clang-format). + +.. code:: + + template< typename T > + class MyClass: public T + { + public: + // code + private: + // more code + }; + +Further indentation and formatting +********************************** + +Avoid committing indentation and formatting changes together with changes in +logic. Always commit these changes separately._ + +As a general rule of thumb, always indent with two spaces (clang-format). Do +not use TAB character in any source file (vera++:L002). Always use braces +around blocks of code (vera++:T019). The braces of code blocks have their own +line (clang-format). + +Control structures (``if``, ``while``, ``for``, ...) have a single space after the +keyword (clang-format / vera++:T003, T008). The parenthesis around the tests +have a space after the opening and before the closing parenthesis +(clang-format). The case labels in ``switch`` statements are not indented +(clang-format). + +.. code:: + + if ( x > 0 ) + { + // code + } + else + { + // code + } + + switch ( i ) + { + case 0: + // code + default: + // code + } + +Binary operators (`+`, `-`, `*`, `||`, `&`, ...) are surrounded by one space, e.g. +``a + b`` (clang-format). + +Unary operators have no space between operator and operand, e.g. ``-a`` +(clang-format). Do not use the negation operator `!` since it can easily be +overseen. Instead use ``not``, e.g. ``not vec.empty()`` (vera++:T012). + +There is no space between a statement and its corresponding semicolon +(clang-format): + +.. code:: + + return a + 3 ; // bad + return a + 3; // good + +Further checks performed by vera++ +********************************** + +* **F001** Source files should not use the '\r' (CR) character +* **F002** File names should be well-formed +* **L001** No trailing whitespace (clang-format) +* **L003** no leading / ending empty lines +* **L005** not to many (> 2) consecutive empty lines +* **T001** One-line comments should not have forced continuation ( ``// ... \``) +* **T002** Reserved names should not be used for preprocessor macros +* **T004** Some keywords should be immediately followed by a colon (clang-format) +* **T005** Keywords break and continue should be immediately followed by a semicolon (clang-format) +* **T006** Keywords return and throw should be immediately followed by a semicolon or a single space (clang-format) +* **T007** Semicolons should not be isolated by spaces or comments from the rest of the code (~ clang-format) +* **T010** Identifiers should not be composed of 'l' and 'O' characters only +* **T017** Unnamed namespaces are not allowed in header files + +Further transformations performed by clang-format +************************************************* + +* Align trailing comments +* Always break before multi-line strings +* Always break template declarations +* Break constructor initializers before comma +* Pointer alignment: Left +* Space before assignment operators +* Spaces before trailing comments: 1 +* Spaces in parentheses +* Spaces in square brackets + +Stopwatch example +~~~~~~~~~~~~~~~~~ + +For example, the ``stopwatch.h`` file could look like: + +.. code:: + + /* + * stopwatch.h + * + * This file is part of NEST. + * + * Copyright (C) 2004 The NEST Initiative + * + * NEST is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 2 of the License, or + * (at your option) any later version. + * + * NEST is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with NEST. If not, see . + * + */ + + #ifndef STOPWATCH_H + #define STOPWATCH_H + + // C includes: + #include + + // C++ includes: + #include + #include + + namespace nest + { + + /*********************************************************************** + * Stopwatch * + * Accumulates time between start and stop, and provides * + * the elapsed time with different time units. * + * * + * Partly inspired by com.google.common.base.Stopwatch.java * + * Not thread-safe: - Do not share stopwatches among threads. * + * - Let each thread have its own stopwatch. * + * * + * Usage example: * + * Stopwatch x; * + * x.start(); * + * // ... do computations for 15.34 sec * + * x.stop(); // only pauses stopwatch * + * x.print("Time needed "); // > Time needed 15.34 sec. * + * x.start(); // resumes stopwatch * + * // ... next computations for 11.22 sec * + * x.stop(); * + * x.print("Time needed "); // > Time needed 26,56 sec. * + * x.reset(); // reset to default values * + * x.start(); // starts the stopwatch from 0 * + * // ... computation 5.7 sec * + * x.print("Time "); // > Time 5.7 sec. * + * // ^ intermediate timing without stopping the stopwatch * + * // ... more computations 1.7643 min * + * x.stop(); * + * x.print("Time needed ", Stopwatch::MINUTES, std::cerr); * + * // > Time needed 1,8593 min. (on cerr) * + * // other units and output streams possible * + ***********************************************************************/ + class Stopwatch + { + public: + typedef size_t timestamp_t; + typedef size_t timeunit_t; + + enum + { + MICROSEC = ( timeunit_t ) 1, + MILLISEC = MICROSEC * 1000, + SECONDS = MILLISEC * 1000, + MINUTES = SECONDS * 60, + HOURS = MINUTES * 60, + DAYS = HOURS * 24 + }; + + static bool correct_timeunit( timeunit_t t ); + + /** + * Creates a stopwatch that is not running. + */ + Stopwatch() + { + reset(); + } + + /** + * Starts or resumes the stopwatch, if it is not running already. + */ + void start(); + + /** + * Stops the stopwatch, if it is not stopped already. + */ + void stop(); + + /** + * Returns, whether the stopwatch is running. + */ + bool isRunning() const; + + /** + * Returns the time elapsed between the start and stop of the + * stopwatch. If it is running, it returns the time from start + * until now. If the stopwatch is run previously, the previous + * runtime is added. If you want only the last measurment, you + * have to reset the timer, before stating the measurment. + * Does not change the running state. + */ + double elapsed( timeunit_t timeunit = SECONDS ) const; + + /** + * Returns the time elapsed between the start and stop of the + * stopwatch. If it is running, it returns the time from start + * until now. If the stopwatch is run previously, the previous + * runtime is added. If you want only the last measurment, you + * have to reset the timer, before stating the measurment. + * Does not change the running state. + * In contrast to Stopwatch::elapsed(), only the timestamp is returned, + * that is the number if microseconds as an integer. + */ + timestamp_t elapsed_timestamp() const; + + /** + * Resets the stopwatch. + */ + void reset(); + + /** + * This method prints out the currently elapsed time. + */ + void print( const char* msg = "", timeunit_t timeunit = SECONDS, std::ostream& os = std::cout ) const; + + /** + * Convenient method for writing time in seconds + * to some ostream. + */ + friend std::ostream& operator<<( std::ostream& os, const Stopwatch& stopwatch ); + + private: + #ifndef DISABLE_TIMING + timestamp_t _beg, _end; + size_t _prev_elapsed; + bool _running; + #endif + + /** + * Returns current time in microseconds since EPOCH. + */ + static timestamp_t get_timestamp(); + }; + + inline bool + Stopwatch::correct_timeunit( timeunit_t t ) + { + return t == MICROSEC || t == MILLISEC || t == SECONDS || t == MINUTES || t == HOURS || t == DAYS; + } + + inline void + nest::Stopwatch::start() + { + #ifndef DISABLE_TIMING + if ( not isRunning() ) + { + _prev_elapsed += _end - _beg; // store prev. time, if we resume + _end = _beg = get_timestamp(); // invariant: _end >= _beg + _running = true; // we start running + } + #endif + } + + inline void + nest::Stopwatch::stop() + { + #ifndef DISABLE_TIMING + if ( isRunning() ) + { + _end = get_timestamp(); // invariant: _end >= _beg + _running = false; // we stopped running + } + #endif + } + + inline bool + nest::Stopwatch::isRunning() const + { + #ifndef DISABLE_TIMING + return _running; + #else + return false; + #endif + } + + inline double + nest::Stopwatch::elapsed( timeunit_t timeunit ) const + { + #ifndef DISABLE_TIMING + assert( correct_timeunit( timeunit ) ); + return 1.0 * elapsed_timestamp() / timeunit; + #else + return 0.0; + #endif + } + + inline nest::Stopwatch::timestamp_t + nest::Stopwatch::elapsed_timestamp() const + { + #ifndef DISABLE_TIMING + if ( isRunning() ) + { + // get intermediate elapsed time; do not change _end, to be const + return get_timestamp() - _beg + _prev_elapsed; + } + else + { + // stopped before, get time of current measurment + last measurments + return _end - _beg + _prev_elapsed; + } + #else + return ( timestamp_t ) 0; + #endif + } + + inline void + nest::Stopwatch::reset() + { + #ifndef DISABLE_TIMING + _beg = 0; // invariant: _end >= _beg + _end = 0; + _prev_elapsed = 0; // erase all prev. measurments + _running = false; // of course not running. + #endif + } + + inline void + nest::Stopwatch::print( const char* msg, timeunit_t timeunit, std::ostream& os ) const + { + #ifndef DISABLE_TIMING + assert( correct_timeunit( timeunit ) ); + double e = elapsed( timeunit ); + os << msg << e; + switch ( timeunit ) + { + case MICROSEC: + os << " microsec."; + break; + case MILLISEC: + os << " millisec."; + break; + case SECONDS: + os << " sec."; + break; + case MINUTES: + os << " min."; + break; + case HOURS: + os << " h."; + break; + case DAYS: + os << " days."; + break; + } + #ifdef DEBUG + os << " (running: " << ( _running ? "true" : "false" ) << ", begin: " << _beg << ", end: " << _end + << ", diff: " << ( _end - _beg ) << ", prev: " << _prev_elapsed << ")"; + #endif + os << std::endl; + #endif + } + + inline nest::Stopwatch::timestamp_t + nest::Stopwatch::get_timestamp() + { + // works with: + // * hambach (Linux 2.6.32 x86_64) + // * JuQueen (BG/Q) + // * MacOS 10.9 + struct timeval now; + gettimeofday( &now, ( struct timezone* ) 0 ); + return ( nest::Stopwatch::timestamp_t ) now.tv_usec + + ( nest::Stopwatch::timestamp_t ) now.tv_sec * nest::Stopwatch::SECONDS; + } + + } /* namespace timer */ + #endif /* STOPWATCH_H */ + +And the corresponding ``stopwatch.cpp``: + +.. code:: + + /* + * stopwatch.cpp + * + * This file is part of NEST. + * + * Copyright (C) 2004 The NEST Initiative + * + * NEST is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 2 of the License, or + * (at your option) any later version. + * + * NEST is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with NEST. If not, see . + * + */ + + #include "stopwatch.h" + + namespace nest + { + std::ostream& operator<<( std::ostream& os, const Stopwatch& stopwatch ) + { + stopwatch.print( "", Stopwatch::SECONDS, os ); + return os; + } + } + +.. _clang-format-file: + +Clang-format configuration file +############################### + +The file ``.clang-format`` is available in the top level source +directory of NEST. It has to reside in the directory from which +``clang-format`` is run and does not have to be installed. + +.. _vera-profile-nest: + +Vera++ profile +############## + +The Vera++ profile required for testing NEST is available as +``extras/vera++.profile``. To make it available, copy this file with the +new name ``nest`` to ``/usr/lib/vera++/profiles``. The exact path might +differ depending on how you installed Vera++. Please refer to the +documentation of `Vera++ `_ in that case. diff --git a/doc/contribute/development_workflow.rst b/doc/contribute/development_workflow.rst new file mode 100644 index 0000000000..45b675b00d --- /dev/null +++ b/doc/contribute/development_workflow.rst @@ -0,0 +1,339 @@ +NEST Git workflow +================= + +.. contents:: On this page, you'll find + :local: + :depth: 2 + +Basic Git setup +--------------- + +The NEST development takes place in a repository using the Git version control system. +The following sections document the general steps required to set up a working +installation of Git. If you have Git set up already, skip to the :ref:`workflow` section. + +Installation and global setup +############################# + +1. `Install Git `_. +2. Introduce yourself to Git: + +.. code:: + + git config --global user.email you@yourdomain.example.com + git config --global user.name "Your Name Comes Here" + +Setting up your GitHub account +############################## + +The NEST source code is hosted in a public repository on +`GitHub `_. If you don’t have a GitHub +account already, please create one. + +You then need to configure your account to allow write access - please see the +`article on generating SSH keys `_ +on the `GitHub help website `_. + +.. _fork: + +Making your own copy (fork) of NEST +################################### + +This needs to be done only once. The instructions here are very similar to the +`instructions on GitHub `_, which you can refer +to for more details. This documentation includes a version specific to NEST. + +Creating your own forked copy of NEST +##################################### + +1. Login to your GitHub account. +2. Go to the `NEST source code repository `_ on GitHub. +3. Click on the ``Fork`` button. + +After a short pause, you should find yourself at the home page for your own +forked copy of NEST. + +Downloading your fork +##################### + +After forking the repository, you need to download (*clone*) it to your local computer to +work with the code. + +The following commands should do it. The next section explains the commands. + +.. code:: + + git clone git@github.com:your-user-name/nest-simulator.git + cd nest-simulator + git remote add upstream git://github.com/nest/nest-simulator.git + +Commands explained +~~~~~~~~~~~~~~~~~~ + +**Clone your fork** + +.. code:: + + git clone git@github.com:your-user-name/nest-simulator.git + +This downloads your fork to your local system. Investigate. Change directory +to your new repository: ``cd nest-simulator``. +Then ``git branch -a`` to show you all branches. You’ll get something like: + +.. code:: + + * master + remotes/origin/master + +This tells you that you are currently on the ``master`` branch, and that you +also have a ``remote`` connection to ``origin/master``. The ``master`` branch is the +default branch and this is where code that has been reviewed and tested resides. +``origin/master`` is just a copy of the ``master`` branch on your system on the ``remote``. + +What remote repository is ``remote/origin``? Try ``git remote -v`` to see the web +address for the remote. It should point to your GitHub fork. + +Next, you connect your local copy to the central +`NEST GitHub repository `_, so that you +can keep your local copy and remote fork up to date in the future. By convention, +the main source code repository is usually called ``upstream``. + +**Link your repository to the upstream repository** + +.. code:: + + cd nest-simulator + git remote add upstream git://github.com/nest/nest-simulator.git + +.. note:: + + We’ve used ``git://`` in the web address instead of ``git@``. + The ``git://`` web address is read only and ensures that you don't make any + accidental changes to the ``upstream`` repository (if you have permissions to + write to it, of course). + +Check that you have a new ``remote`` set up with ``git remote -v show``. You should +see something like this: + +.. code:: + + upstream git://github.com/nest/nest-simulator.git (fetch) + upstream git://github.com/nest/nest-simulator.git (push) + origin git@github.com:your-user-name/nest-simulator.git (fetch) + origin git@github.com:your-user-name/nest-simulator.git (push) + +.. _workflow: + +Suggested development workflow +------------------------------ + +Once you've already set up your forked copy of the NEST source code +repository, you can now start making changes to it. The following +sections document the suggested Git workflow. + +Basic workflow +############## + +In short: + +1. Start a *new branch* for each set of changes that you intend to make. See + the :ref:`feature_branch` section below. +2. Hack away! See the section that documents the :ref:`editing`. +3. When you are satisfied with your edits, push these changes to your own GitHub fork, + and open a pull request to notify the development team that you'd like + to make these changes available at the ``upstream`` repository. + The steps for this are documented in the :ref:`pull_request` section. + +This suggested workflow helps to keep the source code repository properly +organized. It also ensures that the history of changes that have been made to +the source code (called ``commit history``) remains tidy, making it easier to follow. + +.. _`feature_branch`: + +Making a new feature branch +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Before you make any changes, ensure that your local copy is up to date with the +``upstream`` repository. + +1. Go to (checkout) the default master branch + +.. code:: + + git checkout master + +2. Download (fetch) changes from upstream + +.. code:: + + git fetch upstream + +3. Update your master branch - merge any changes that have been made upstream + +.. code:: + + git merge upstream/master --ff-only + +4. Update the remote for your fork + +.. code:: + + git push origin master + +We suggest using the ``--ff-only`` flag since it ensures that a new +commit is not created when you merge the changes from ``upstream`` into your +``master`` branch. Using this minimises the occurrence of superfluous merge +commits in the commit history. + +Now that you have the latest version of the source code, create a new branch +for your work and check it out: + +.. code:: + + git checkout -b my-new-feature master + +This starts a new branch called ``my-new-feature`` from ``master``. + + +It is extremely important to work on the latest available source code. If you +work on old code, it is possible that in the meantime, someone else has +already made more changes to the same files that you have also edited. This +will result in `merge conflicts +`_ +and resolving these is extra work for both the development team and you. It +also muddles up the ``commit history`` of the source code. + +.. _editing: + +Editing workflow - command list +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Improve ``modified_file`` with your text editor/IDE. +2. Confirm what files have changed in the repository. + +.. code:: + + git status + +3. Review the changes you've made (optional). + +.. code:: + + git diff + +4. Inform Git that you want to save these changes. + +.. code:: + + git add modified_file + +5. Save these changes. + +.. code:: + + git commit + +6. Push these changes to the remote for your fork. + +.. code:: + + git push origin my-new-feature + +Editing workflow - commands explained +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Make some changes. When you feel that you've made a complete, working set of + related changes, move on to the next steps. +2. Please ensure that you have followed the coding guidelines for + C++ and SLI coding guidelines. +3. Test your changes by building the source code and running the tests. + (Usually ``cmake``, ``make``, ``make install``, ``make installcheck``. Please see the + `INSTALL `_ file for + details.) +4. Check which files have changed with ``git status``. You'll see a listing like this one: + + .. code:: + + On branch my-new-feature + Changed but not updated: + (use "git add ..." to update what will be committed) + (use "git checkout -- ..." to discard changes in working directory) + + modified: README + + Untracked files: + (use "git add ..." to include in what will be committed) + + INSTALL + no changes added to commit (use "git add" and/or "git commit -a") + +5. Compare the changes with the previous version using ``git diff``. + This brings up a simple text browser interface that highlights the difference + between your files and the previous version like this: + + .. code:: + + diff --git a/development_workflow.rst b/development_workflow.rst + index f05f0cd..e581f00 100644 + --- a/development_workflow.rst + +++ b/development_workflow.rst + @@ -8,17 +8,22 @@ layout: index + +6. Inform Git of what modified or new files you want to save (stage) using ``git add modified_file``. + This puts the files into a ``staging area``, which is a + list of files that will be added to your next commit. Only add files that have + related, complete changes. Leave files with unfinished changes for later + commits. + +7. To commit the staged files into the local copy of your repository, run + ``git commit``. Write a clear Git commit message that describes the changes + that you have made. Please read `this article `_ + on writing commit messages. If a commit fixes an open issue on the `GitHub issue + tracker `_, include + ``Fixes #issue_number`` in the commit message. GitHub finds such keywords and + closes the issue automatically when the pull request is merged. For a list of + all keywords you can use, refer to `this GitHub help + page `_. + After saving your message and closing the editor, your commit will be saved. + +8. Push the changes to your forked repository on GitHub: + + .. code:: + + git push origin my-new-feature + +Assuming you have followed the instructions in these pages, Git will create +a default link to your GitHub repository called ``origin``. In Git >= 1.7 you can +ensure that the link to origin is permanently set by using the ``--set-upstream`` +option: + +.. code:: + + git push --set-upstream origin my-new-feature + +From now on, Git will know that ``my-new-feature`` is related to the +``my-new-feature`` branch in your own GitHub repository. Subsequent push calls +are then simplified to the following: + +.. code:: + + git push + +It often happens that while you were working on your edits, new commits have +been added to ``upstream`` that affect your work. In this case, you will need to +reposition your commits on the new master. Please follow the +`git rebase `_ instructions. + +Next, we see how to create a pull request. + +.. _pull_request: + +Creating a pull request +~~~~~~~~~~~~~~~~~~~~~~~ + +When you feel your work is finished, you can create a pull request (PR). GitHub +has a nice help page that outlines the process for +`submitting pull requests `_. + +Please check out our :doc:`coding style guidelines ` and +:ref:`code review guidelines ` prior to submitting it. \ No newline at end of file diff --git a/doc/contribute/index.rst b/doc/contribute/index.rst index 412e4f1e2a..7953750777 100644 --- a/doc/contribute/index.rst +++ b/doc/contribute/index.rst @@ -5,29 +5,49 @@ NEST draws its strength from the many people that use and improve it. We are happy to consider your contributions (e.g., new models, bug or documentation fixes) for addition to the official version of NEST. +Please familiarize yourself with our: + +* :doc:`NEST Git workflow ` +* :doc:`C++ coding style guidelines ` + +In order to make sure that the NEST Initiative can manage the NEST code base in the long term, +you need to send us a completed and signed +:download:`NEST Contributor Agreement ` to transfer your +copyright to the NEST Initiative before we can merge your pull request. + Report bugs and request features -------------------------------- -If you find an error in the code or documentaton or want to suggest a feature, submit `an issue on GitHub -`_. +If you find an error in the code or documentaton or want to suggest a feature, submit +`an issue on GitHub `_. Make sure to check that your issue has not already been reported there before creating a new one. Change code or documentation ---------------------------- -You can find all the details for our development workflow on the `NEST developer space `_. - Interested in creating or editing documentation? Check out our :doc:`../documentation_workflow/index`. For making changes to the PyNEST APIs, please see our :doc:`templates_styleguides/pyapi_template`. -If you are a Vim user and require support for SLI files, please refer to our :doc:`templates_styleguides/vim_support_sli`. +If you are a Vim user and require support for SLI files, please refer to our +:doc:`templates_styleguides/vim_support_sli`. Contribute a Python example script ---------------------------------- -If you have a Python example network to contribute, please refer to our :doc:`templates_styleguides/example_template` to ensure you cover the required information. +If you have a Python example network to contribute, please refer to our +:doc:`templates_styleguides/example_template` to ensure you cover the required information. + +.. _review_guidelines: + +Code review guidelines +---------------------- + +Pull requests must be reviewed and approved by **two reviewers** prior to being merged. Please check +the **typeset documentation** as part of the review process. To learn how to test the documentation +locally offline, please check out our +:doc:`User documentation workflow <../documentation_workflow/user_documentation_workflow>`. Have a question? ---------------- diff --git a/extras/check_code_style.sh b/extras/check_code_style.sh index 2a802d389e..11ddcffdd9 100755 --- a/extras/check_code_style.sh +++ b/extras/check_code_style.sh @@ -86,7 +86,7 @@ i.e. all executions should start like: ./extras/check_code_style.sh ... The setup of the tooling is explained here: - https://nest.github.io/nest-simulator/coding_guidelines_c++ + https://nest-simulator.readthedocs.io/en/latest/contribute/coding_guidelines_cpp.html Options: