Memo for gcc flags added.

[gdcm.git] / DEVELOPPER

The following comments are intended for core gdcm developpers.

* Compiling gdcm:
  - Checkout the sources to an arbitrary directory noted GDCM (e.g. ~/cvs/gdcm).
  - Checkout the test images to an arbitrary directory noted GDCMDATA
    (e.g. ~/cvs/gdcm/gdcmData).
  - Optionally create a temporary installation directory GDCMINSTALL e.g.
    mkdir /tmp/gdcminstall
  - Create a target directory GDCMBIN e.g.
    mkdir /tmp/gdcmbin
  - Configure cmake from GDCMBIN:
    cd GDCMBIN
    ccmake GDCM
      * Toggle and adjust the required options and parameters, mainly
        -- GDCM_DATA_ROOT should be set to GDCMDATA
        -- CMAKE_INSTALL_PREFIX (equivalent of --prefix of the autotools)
           should be set to GDCMINSTALL
        -- CMAKE_BUILD_TYPE set to Debug or Release
        -- GDCM_DOXYGEN 
        -- GDCM_VTK When this option is on VTK_DIR might require manual
           configuration
        -- GDCM_WRAP_PYTHON
        -- CMAKE_CXX_FLAGS (when working with gcc of course) should be set to
           -g -O0 -Wall -W -Wshadow -Wunused-variable -Wunused-parameter
           -Wunused-function -Wunused -Wno-system-headers -Wno-deprecated
           -Woverloaded-virtual
           (this is to avoid spurious problems with overloading)
      * Configure cmake: hit c
      * Generate the makefiles (or dsw): hit g
  - Compile gdcm
    make  
  - Run the tests manually (optional):
    Caveat: if you run the tests before installing, you NEED to positionate
            the environment variable GDCM_DICT_PATH to GDCM/Dicts e.g.
            export GDCM_DICT_PATH=~/cvs/gdcm/Dicts
    Assuming your cwd is GDCMBIN, three modes are then available:
    -- 1/ acces to a by number:
          ./Test/gdcmCxxTests
    -- 2/ acces to a test by it's name, by passing it as argument to
          gdcmCxxTests e.g.
          ./Test/gdcmCxxTests hashtest
    -- 3/ launch all the full test suite (again we assume cwd is GDCMBIN):
          ctest
          This is equivalent to "make test".
          Note: ctest supports the argument filtering with regexp and
                the verbose mode e.g.
                   ctest -R print -V
                proposes the tests containing "print" in their name and
                makes a verbose output. For other options refer to the
                documentation at http://www.cmake.org.

* Sending the result to kitware's dashboard (optional)
  ctest -D Experimental
  The results should appear in
     http://public.kitware.com/dashboard.php?name=public
     under the name of your machine (uname), but for ease of use you can
     change the SITE variable in your CMakeCache.txt to something more 
     accurate such as: GDCM-my_machine_name. The entry will then be within 
     the "Experimental Builds" entry.

* Install gdcm (as specified by CMAKE_INSTALL_PREFIX)
  make install
  Note: the dictionaries used by gdcm are now located in
        CMAKE_INSTALL_PREFIX + /share/ (i.e. GDCMINSTALL + /share/ if you
        followed the above instructions).

* Python related section.
  Depending on the cmake flags you used in order to compile gdcm could
  be wrapped in two ways:
  - the first python wrappers of gdcm uses Swig (http://www.swig.org). These
    are the one generated when using autogen.sh --enable-python. 
    The entry point here is the file gdcmPython/gdcm.i which uses the
    Swig syntax. As the last lines of this file (the ones starting
    with the %include directive) only some classes are wrapped for python.
    In theory only the library interface (basically the classes gdcmHeader
    and gdcmFile) should be wrapped, but the time being some additional
    classes are added (just to make sure those classes are Swig compatible:
    swig is here used as some link checker!?).
    Since gdcm is written in C++, Swig will produce two different outputs:
      -- some C based low level wrapper (see gdcmPython/gdcm_wrap.c)
      -- some Python based object oriented so called "shadow classes" (see
         file gdcmPython/gdcm.py)
    We also added the file gdcmPython/__init__.py which is the one that
    actually gets loaded when one uses the gdcmPython Python package.
    The file __init__.py loads the Swig generated shadow classes (gdcm.py)
    but will only re-export the interface of gdcm which corresponds to
    the lines :
       gdcmHeader = gdcm.gdcmHeader
       gdcmDictSet = gdcm.gdcmDictSet
       gdcmFile = gdcm.gdcmFile
       [etc.]
    Hence this whole Swig wrapping process is quite odd since we shall
    wrap more classes (%include in swig.i) that eventually get exported to
    the final user by gdcmPython/__init__.py.
  - the second python wrappers uses the vtk (http://public.kitware.com/VTK/)
    native wrappers i.e. the binary vtkWrapPython. But it should be noticed
    that the purpose is here a bit different than the one of the Swig
    generated Python wrappers. When using vtkWrapPython the goal is to
    wrap a single vtk class namely vtkGdcmReader as defined in files
    vtk/vtkGdcmReader.h and vtk/vtkGdcmReader.cxx (and of course those
    files are hand made vtk oriented wrappers of gdcm).
    Those wrappers are the one generated when using
       autogen.sh --enable-python --enable-vtk
  - In order to understand the difference between both wrappers you should 
    compare both demo scripts gdcmPython/demo/vtkGdcmDemo.py and
    gdcmPython/demo/vtkGdcmReader.py. The first one only uses the
    Swig wrapped classes ("from gdcmPython import gdcmHeader') as opposed
    to vtkGdcmReader.py which also uses vtkWrapPython wrapped classes
    ("from gdcmPython.vtkgdcmPython import *").
    
------------------------------------------------------------------------------
gdcm coding style and religious/agnostic beliefs (proposition)
   
* Introduction:
   The following coding style intends to ease the work of developpers
   themselves but also of users who will study, maintain, fix, and extend
   the code. Any bread crumbs that you can drop in the way of explanatory
   names and comments will go a long way towards helping other readers and
   developers.
   Keep in mind that to a large extent the structure of code directly
   expresses its implementation.

* Language:
 - C++ (for the kernel) and Python (for the wrappers).
 - all the names (variables, members, methods, functions) and comments
   should be based on English. Documentation, guides, web site and other
   informations should be in English.
   Make sure you use correct (basic) English and complete, grammatically
   correct sentences for comments and documentation.

* General layout:
 - Each line of code should take no more than 79 characters. Break the code
   across multiple lines as necessary. 
 - Methods and functions should keep a reasonable number of lines when
   possible (a typical editor displays 50 lines). Avoid code duplication.
   Always prefer creating a new method or function to duplication.
   A high indentation level generally suggests the need for a new
   method or function.
 - All the code should be properly indented. The appropriate indentation
   level is three spaces for each level of indentation. DO NOT USE TABS.
   Set up your editor to insert spaces. Using tabs may look good in your
   editor but will wreak havoc in others, or in external tools (e.g. side
   by side diffs).
 - The declaration of variables within classes, methods, and functions
   should be one declaration per line. Provide them with default values
   and don't rely on compilers for default initialization.

* Naming conventions:
 - Generalities:
   In general, names are constructued by using case change to indicate
   separate words, as in ImageDataSize (standing for "image data size").
   Underscores are not used. Variable names are chosen carefully with the
   intention to convey the meaning behind the code. Names are generally
   spelled out; use of abbreviations is discouraged.
   [Note: abbreviation are allowable when in common use, and should be in
    uppercase as in LUT or RGBA.]
   While this does result in long names, it self-documents the code.
 - Naming Files:
   Files should have the same name as the class, with a "gdcm" prepended.
   Header files are named .h, while implementation files are named either
   .cxx or .txx, depending on whether they are implementations of templated
   classes. For example, the class gdcm::Document is declared and defined
   in the files gdcmDocument.h and gdcmDocument.cxx.
 - Naming Class Data Members, Methods, and Functions:
   Class data members are named beginning with a capital letter as in
   GroupPixel.
   Global functions and class methods, either static or class members, are
   named beginning with a capital letter, as in GetImageDataSize().
 - Naming Local Variables:
   Local variables begin in lowercase. There is more flexibility in the
   naming of local variables although they still should convey some
   semantics.

* Classes:
 - Don't use the inline keyword when defining an inline function
   within a class definition.
 - Do not repeat the virtual keyword when overriding virtual base methods
   in declaration of subclasses:
     class A 
     {
        virtual void foo(...);
     };
     class B: public A
     {
        void foo(...);          // and not: virtual void foo(...);
     };
 - The public, protected, private declarations should be at the
   same indent level as the class. Use
     class A 
     {
     private:
        void foo(...);
     public:
        void bar(...);
     };
 - Method and functions devoided of arguments should not use the void
   notation. Use
     SomeType Header::GetPixelData()
   and not
     SomeType Header::GetPixelData(void).

* Use of braces:
 - Braces must be used to delimit the scope of an if, for, while, switch, or
   other control structure. Braces are placed on a line by themselves, and
   at the same indentation level as the control structure to which they
   belong:
      for (i=0; * i<3; i++)
      {
         ...
      }
   or when using an if:
      if ( condition )
      {
         ...
      }
      else if ( other condition )
      {
         ...
      }
      else
      {
         ....
      }
   You can choose to use braces on a line with a code block when
   the block consists of a single line:
      if ( condition ) { foo=1; }
      else if ( condition2 ) { foo=3; }
      else { return; }
   or
      for (i=0; i<3; ++i) {x[i]=0.0;}
   Methods and functions should follow the same usage of braces:
      void File::ParsePixelData()
      {
         ...
      }

* Special layout:
 - Avoid code mixed with comments on a single line. Instead, prepend the
   logical blocks of code with the concerned comments.
 - Use parantheses around conditions e.g. with an if statement: 
      if ( someLocalVariable == 2 ) { ... }
 - Add spaces around parantheses, or braces. Use
      if ( someLocalVariable == 2 ) { ClassMenber += 1; }
   and not
      if (someLocalVariable == 2) {ClassMenber += 1;}
 - Add spaces around each side of the assignement operator, and
   around binary operators used in boolean expression. Use
      someLocalVariable = ClassMember * 2;
      if ( someLocalVariable == 2 || ClassMember == 2 ) ...
   and not
      someLocalVariable=ClassMember*2;
      if ( someLocalVariable==2||ClassMember==2 ) ...

* Miscelaneous:
 - Don't use underscores. Don't use tabs. Don't use control characters
   like ^M. Anyhow, cvs is configured to reject such commits.
 - Comments should be in C++ style ("// ...", two slashes, per line). Don't
   use C style comments ("/* ... */").
 - The last line of a file should terminate with "\n".
 - Returned arguments of methods and functions should not be wrapped with
   parantheses. Use 
      return iter->second;
   but do not use
      return ( iter->second );

* Debugging and Verbose modes:
   Never use std::cout. Instead use the gdcmDebug class through the
   global instance dbg. Example:
      #include "gdcmDebug.h"
      ...
      {
         dbg.Verbose(3, "Local function name: entering.");
         ...
      }
    will send the message to std::cout when dbg.Debug() is called
    in your main.

* Documentation:
   The Doxygen open-source system is used to generate on-line documentation.
   Doxygen requires the embedding of simple comments in the code which is in
   turn extracted and formatted into documentation. See
      http://www.stack.nl/ dimitri/doxygen/
   for more information about Doxygen.
 - Documenting a class:
   Classes should be documented using the class and brief doxygen commands,
   followed by the detailed class description:
      /**
       * \class Header
       * \brief Header acts as container of Dicom elements of an image.
       *
       * Detailed description of the class is provided here
       * ...
       */
   The key here is that the comment starts with /**, each subsequent line has
   an aligned *, and the comment block terminates with a */.
 - Documenting class members and inline methods:
   All the members and the inline methods should be documented within
   the class declaration as shown in the following example:
      class Header
      {
         /// True when parsing was succefull. False otherwise.
         bool Readable = false;

         /// \brief The number of lines of the image as interpreted from
         /// the various elements encountered at header parsing.
         int NumberOfLines = -1;

         /// Predicate implemented as accessor around \ref Readable.
         bool IsReadable() { return Readable; }
      };
 - Documenting a Method:
   Methods should be documented using the following comment block style
   as shown in the following example:

      /**
       * \brief  Within the Dicom Elements (parsed with the public and private
       *         dictionaries), look for the element value representation of
       *         a given tag.
       * @param  group Group number of the searched tag.
       * @param  element Element number of the searched tag.
       * @return Corresponding element value representation when it exists,
       *         and the string "gdcm::Unfound" otherwise.
       */
      std::string Document::GetEntryByNumber(guint16 group, guint16 element)
      {
         ...
      }

* External includes and C style:
 - Only the C++ standard library and the STL includes should be used.
   When including don't use the .h extension (use #include <iostream>
   instead of #include <iostream.h>).
 - Don't use the C standard library. Don't include stdio.h, ctype.h...
   Don't use printf(), sprinf(), FILE*...
 - Don't use the NULL notation (either as macro, or as const int NULL=0).
   A pointer that doesn't refer to an object should simply be defined as
      DataPointer* MyDataPointer = 0;

* Basic types:
 - Assume T is a given type. When declaring or defining with the 
   "pointer to T" notation, the * character must be adjacent to
   the type and not the variable. That is use
      T* foo = 0;
   and not 
      T *foo = 0;
 - Always define a typedef for a new type and be consistent in usage.
   Use
      typedef Header* HeaderPointer;
      HeaderPointer MyHeaderPointer;
 - One notorious counter example for non using C style inclusion concerns
   exact-width integers (since there seem to be no equivalent for C++).
   When using exact-width integers use the typedef names defined by
   the Basic ISO C99: 7.18 Integer types i.e.
      int8_t     int16_t     int32_t     int64_t (signed integers)
   and
      uint8_t    uint16_t    uint32_t    uint64_t (unsigned integers).
   Conversion table is then:
    unsigned char       -> uint8_t;
    unsigned short      -> uint16_t;
    unsigned int        -> uint32_t;
    unsigned long       -> uint32_t;
    unsigned long long  -> uint64_t;
    (signed) char       -> int8_t; 
    short               -> int16_t; 
    int                 -> int32_t; 
    long                -> int32_t; 
    long long           -> int64_t;
   Hence do not use declarations like "unsigned int".
   With g++, accessing those typedef is achieved by the following
      #include <stdint.h>
------------------------------------------------
CVS policy
* All the commits should be atomic. They must preserve the compilation
  in order to prevent checkouts with broken code.
* All the commits must correspond to a stade of the code where ctest
  runs and has no failing subtest. Always run ctest before commiting.
  Note: * you can start ctest in verbose mode through the command
             ctest -V >& log
        * you can start a single test through ctest with
             ctest -R FailingTestName -V >& log
------------------------------------------------
Compiler flags policy:
 When working with gcc please use the flags specified in DEVELOPPER file
 (in order to avoid difficult overloading problems).
------------------------------------------------