Difference between revisions of "Developer's Corner"

From Eigen
Jump to: navigation, search
(Code Quality)
Line 119: Line 119:
  
  
== Submitting patches ==
+
== Submitting patches (svn) ==
  
 
Make sure your local checkout is up to date:
 
Make sure your local checkout is up to date:
Line 139: Line 139:
  
  
== Backporting bugfixes ==
+
== Backporting bugfixes (svn) ==
 
Current development always occurs in trunk (/trunk/kdesupport/eigen2) which will become the next stable branch (e.g., 2.1). Whenever we fix a bug in trunk, if we want the bugfix to appear in the next release of the current stable branch (e.g., 2.0.x), we need to manually backport that fix to the 2.0 branch. For that you need to have a checkout of both trunk (in path/to/trunk) and stable branch (path/to/branch). Then the recipes is:
 
Current development always occurs in trunk (/trunk/kdesupport/eigen2) which will become the next stable branch (e.g., 2.1). Whenever we fix a bug in trunk, if we want the bugfix to appear in the next release of the current stable branch (e.g., 2.0.x), we need to manually backport that fix to the 2.0 branch. For that you need to have a checkout of both trunk (in path/to/trunk) and stable branch (path/to/branch). Then the recipes is:
 
* First, commit your fix to the trunk. Note down the revision number, call it N.
 
* First, commit your fix to the trunk. Note down the revision number, call it N.
Line 148: Line 148:
 
   $ svn ci
 
   $ svn ci
 
* Start your commit message with: "Backporting commit N" and a small explanation.
 
* Start your commit message with: "Backporting commit N" and a small explanation.
 +
 +
 +
= Mercurial workflow =
 +
 +
== Basic usage ==
 +
 +
Getting the source:
 +
  $ hg clone <central-repo>
 +
 +
Local commit:
 +
  $ hg commit
 +
 +
Pushing the local changes to central repo:
 +
  $ hg push <central-repo>
 +
 +
Merge changes from another branch:
 +
  $ hg pull <repo>  # pull changesets from <repo>
 +
  $ hg merge        # merge the new tip from <repo> into our working directory
 +
  $ hg parents      # see the revisions that have been merged into the working directory
 +
  $ hg commit        # commit the result of the merge
 +
 +
== Pushing many local commits as a single one ==
 +
 +
== Backporting bugfixes ==
 +
 +
== Make a new release ==
  
 
= Documentation tips =
 
= Documentation tips =

Revision as of 08:02, 2 May 2009

Code Quality

Nightly build reports:

To know more about krazy code checker, please check this page: http://techbase.kde.org/Development/Tutorials/Code_Checking.


Submitting test suite reports

To submit reports to the dashboard:

  • Create a folder and get the last testsuite.cmake script:
 mkdir cdash
 cd cdash
 svn cat svn://anonsvn.kde.org/home/kde/trunk/kdesupport/eigen2/test/testsuite.cmake > testsuite.cmake
  • run the testsuite:
 ctest -VV -S testsuite.cmake,EIGEN_BUILD_STRING=fedora-10-`uname -m`-gcc-4.3.2,EIGEN_CXX=g++-4.3,EIGEN_MODE=Experimental

Of course, change the value of the variable to match your system. The full list of options with description is available in the testsuite.cmake file.

Then you can check the results on the Eigen's project page of cdash.org: http://my.cdash.org/index.php?project=Eigen.

For further information, check theses web pages:

Eigen hacking

Coding rules

We are not very strict about coding rules, however the trends are:

  • indentation with 2 spaces (no tabs !)
  • the best is to show a typical example of a public class:
 template<typename MatrixType
 class NameOfTheClass
 {
     typedef typename MatrixType::Scalar Scalar;
   public:
     // public functions start with lower case:
     Scalar nameOfTheFunction(int i) const;
     // public static functions start with upper case:
     static NameOfTheClass* Create(const MatrixType& mat);
   protected:
     // member attributes start with m_:
     Scalar m_attributeName;
     MatrixType m_matrix;
 };
 
 template<typename MatrixType> typename MatrixType::Scalar
 NameOfTheClass<MatrixType>::nameOfTheFunction(int i) const
 {
   Scalar res = 0;
   if(i>0)
   {
     for(int j=0; i<m_matrix.cols(); ++j,++i)
       res = ei_hypot(res, m_matrix.coeff(i,j));
   }
   else
   {
     j = 0;
     while (i<m_matrix.rows())
     {
       res = ei_hypot(res, m_matrix.coeff(i,j));
       ++i;
       ++j;
     }
   }
   return res;
 }
  • global functions and class/struct reserved for internal use start with ei_, eg:
 struct ei_assign_selector;
  • favor explicit names rather than short ones

Running the unit tests

The unit tests are managed by the pair cmake/ctest. Typically one proceeds as follow:

  $ mkdir build
  $ cd build
  $ cmake path_to_eigen2 -DEIGEN_BUILD_TESTS=on

From this point you can:

  • build all tests: make
  • run a specific test: ./test/test_name_of_the_test (e.g., ./test/test_geo_quaternion)
  • (build and) run all tests: ctest
  • (build and) run all tests with more feedback: ctest -V
  • (build and) run all tests matching a regular expression with feedback: ctest -V -R <regexp> (e.g., to run all tests of the geometry module: ctest -V -R geo)

Note that the unit tests of the unsupported modules are built in the unsupported/test sub-folder.

For more information, please check the cmake and ctest documentations.


Writing unit tests

If you want to add a simple test of small feature highly related to an existing unit test, then simply extend the existing one. Otherwise, you have to create a new unit test. Let's call it mytest.

  • Create a new file mytest.cpp in the eigen2/test (or eigen2/unsupported/test) folder.
  • Your file must start by including the file main.h and define a function test_mytest:
  #include <main.h>
  void test_mytest()
  {
    /* ... */
  }
  • If you don't know how to fill the blank, have a look at the other unit test files in eigen2/test.
  • Add it to the respective CMakeLists.txt file by adding the line:
  ei_add_test(mytest)
  • Do not forget to add it to svn: svn add test/mytest.cpp
  • Finally, you can compile and run it from your build directory:
  $ make test_mytest
  $ ctest -V -R mytest

Advanced: The macro ei_add_test takes two optional arguments:

  • The first one specifies additional compile flags.
  • The second one contains the additional libraries to link with.


Submitting patches (svn)

Make sure your local checkout is up to date:

  $ cd path_to_eigen2
  $ svn up 

If your patch contains new files, make svn know about them:

  svn add path_to_new_file1 path_to_new_file2 ...

Check your patch by running:

  $ svn status
  $ svn diff | kompare -o -

Note that the last command requires kompare, but it can be easily adapted to any diff viewer.

Finally, create the patch file:

  $ svn diff > mypatch.diff

and send it to the mailing list.


Backporting bugfixes (svn)

Current development always occurs in trunk (/trunk/kdesupport/eigen2) which will become the next stable branch (e.g., 2.1). Whenever we fix a bug in trunk, if we want the bugfix to appear in the next release of the current stable branch (e.g., 2.0.x), we need to manually backport that fix to the 2.0 branch. For that you need to have a checkout of both trunk (in path/to/trunk) and stable branch (path/to/branch). Then the recipes is:

  • First, commit your fix to the trunk. Note down the revision number, call it N.
  • Then do:
 $ cd path/to/branch
 $ svn up
 $ svn merge -cN path/to/trunk
 $ svn ci
  • Start your commit message with: "Backporting commit N" and a small explanation.


Mercurial workflow

Basic usage

Getting the source:

 $ hg clone <central-repo>

Local commit:

 $ hg commit

Pushing the local changes to central repo:

 $ hg push <central-repo>

Merge changes from another branch:

 $ hg pull <repo>   # pull changesets from <repo>
 $ hg merge         # merge the new tip from <repo> into our working directory
 $ hg parents       # see the revisions that have been merged into the working directory
 $ hg commit        # commit the result of the merge

Pushing many local commits as a single one

Backporting bugfixes

Make a new release

Documentation tips