tmodifying-pism.rst - pism - [fork] customized build of PISM, the parallel ice sheet model (tillflux branch)
 (HTM) git clone git://src.adamsgaard.dk/pism
 (DIR) Log
 (DIR) Files
 (DIR) Refs
 (DIR) LICENSE
       ---
       tmodifying-pism.rst (2015B)
       ---
            1 .. include:: ../../global.txt
            2 
            3 .. _sec-code-modifications:
            4 
            5 Managing source code modifications
            6 ----------------------------------
            7 
            8 "Practical usage" may include editing the source code to extend, fix or replace parts of
            9 PISM.
           10 
           11 We provide both user-level (this manual) and developer-level documentation. Please see
           12 source code browsers at |pism-docs| for the latter.
           13 
           14 - To use your (modified) version of PISM, you will need to follow the compilation from
           15   sources instructions in the :ref:`Installation Manual <sec-installation>`.
           16 
           17 - It is a good idea to enable "debugging" settings when modifying PISM.
           18 
           19   Benefits include
           20 
           21   - better error messages during compilation,
           22   - a number of sanity checks that are disabled by default,
           23   - the ability to use debuggers such as ``gdb`` or ``lldb``.
           24 
           25   Set ``CMAKE_BUILD_TYPE`` to "Debug" in ``ccmake`` to enable debugging settings, then run
           26   ``make`` to re-compile.
           27 
           28   .. warning::
           29 
           30      Debugging settings disable code optimization, making PISM significantly slower.
           31      Please make sure that ``CMAKE_BUILD_TYPE`` is set to "Release" and ``Pism_DEBUG`` is
           32      set to "OFF" when compiling PISM for "real" runs.
           33 
           34 - We find it very useful to be able to check if a recent source code change broke
           35   something. PISM comes with "regression tests", which check if certain parts of PISM
           36   perform the way they should.\ [#]_
           37 
           38   Run "``make test``" in the build directory to run PISM's regression tests.
           39 
           40   Note, though, that while a test failure usually means that the new code needs more work,
           41   passing all the tests does not guarantee that everything works as it should. We are
           42   constantly adding new tests, but so far only a subset of PISM's functionality can be
           43   tested automatically.
           44 
           45 - We strongly recommend using a version control system to manage code changes. Not only is
           46   it safer than the alternative, it is also more efficient.
           47 
           48 .. rubric:: Footnotes
           49 
           50 .. [#] This automates running verification tests described in section :ref:`sec-verif`,
           51        for example.