From 34cc82bb39edc5ad4cb83b1e8fbf5d50f854ecbf Mon Sep 17 00:00:00 2001 From: frog Date: Fri, 24 Sep 2004 11:43:17 +0000 Subject: [PATCH] * DEVELOPPER spread out in Doc/Website/Developpers.html, CodingStyle.html, DeveloppersPython.html * INSTALL nows refers to Doc/Website/Installation.html --- AUTHORS | 14 +- ChangeLog | 20 +++ DEVELOPPER | 386 +---------------------------------------------------- INSTALL | 25 +--- 4 files changed, 33 insertions(+), 412 deletions(-) diff --git a/AUTHORS b/AUTHORS index 7473337f..8e8a127b 100644 --- a/AUTHORS +++ b/AUTHORS @@ -1,7 +1,7 @@ -Florez Leonardo -Frog -Malaterre Mathieu -Olart Emmanuel -Regrain Benoit -Roux Jean-Pierre -Luis Ibanez +Florez Leonardo (Creatis/Theralis) +Ibanez Luis (Kitware) +Malaterre Mathieu (Kitware) +Olart Emmanuel (Theralys) +Regrain Benoit (Creatis) +Roux Jean-Pierre (Creatis) +Boix Eric (Creatis) diff --git a/ChangeLog b/ChangeLog index 9735dfad..109f22af 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,23 @@ +2004-09-24 Eric Boix + * Added Doc/Website/CodingStyle.html, Developpers.html, + DeveloppersPython.html, GdcmDataCvs.html and + DownloadVersion0_1.html, DownloadVersion0_3.html. + * Some Doc/*.txt Doxygen files (which do not really concern the + documentation itself, but the website) moved to html and + placed in directory Doc/Website: + - Doc/DoxyDevelInstal.txt moved to Doc/Website/Developpers.html + - Doc/DoxyInstallation.txt moved to Doc/Website/Installation.html + - Doc/DoxyIntroduction.txt included in Doc/Website/Main.html + * Doc/DoxyfileDeveloppers, DoxyfileUsers, Makefile.am oldies removed. + * CMakeLists.txt changed accordingly. + * DEVELOPPER spread out in Doc/Website/Developpers.html, CodingStyle.html, + DeveloppersPython.html + * INSTALL nows refers to Doc/Website/Installation.html + +2004-09-23 Eric Boix + * Added Doc/Website directory, that contains a first raw version + of gdcm Web site. + 2004-09-23 Jean-Pierre Roux * FIX In order not to be poluted any longer by casting problems, the member VoidArea of gdcmBinEntry is now uint8_t* (instead of void *) diff --git a/DEVELOPPER b/DEVELOPPER index 37af3d44..b0c1b158 100644 --- a/DEVELOPPER +++ b/DEVELOPPER @@ -1,385 +1 @@ -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 - instead of #include ). - - 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 ------------------------------------------------- -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). ------------------------------------------------- +The entry point is Doc/Website/Developpers.html diff --git a/INSTALL b/INSTALL index 52971796..922c4ae0 100644 --- a/INSTALL +++ b/INSTALL @@ -1,19 +1,10 @@ ################################################### -For the impatient: - * cvs -d:pserver:anonymous@cvs.creatis.insa-lyon.fr:2402/cvs/public login - answer anonymous - * cvs -d:pserver:anonymous@cvs.creatis.insa-lyon.fr:2402/cvs/public co gdcm - * cd gdcm - * ./autogen.sh (--enable-python --enable-vtk --enable-doc) - * make - * make install - -# As of May 2004, cmake has taken over the world^W autotools, therefore you'll - need to grab a recent version from : - - http://cmake.org (later than 1.8.3) +The installation documentation entry point is Doc/Website/Installation.html +################################################### +As of May 2004, cmake has taken over the world^W autotools, therefore +you'll need to grab a recent version from: http://cmake.org (later than 1.8.3) - Then install instruction are: + Then install instruction are: * cvs -d:pserver:anonymous@cvs.creatis.insa-lyon.fr:2402/cvs/public login answer anonymous * cvs -d:pserver:anonymous@cvs.creatis.insa-lyon.fr:2402/cvs/public co gdcm @@ -25,10 +16,4 @@ For the impatient: * make * make install -################################################### -The full documentation for installation is available at - http://www.creatis.insa-lyon.fr/Public/Gdcm/html.developper/DoxyInstallation.html -################################################### -The documentation can also be found in the Doc sub-directory. Please refer to -README file within Doc. -- 2.45.0