READMEDEV.org 3.27 KB
Newer Older
1 2 3 4 5 6 7 8 9 10
#+TITLE: README for developers
#+LANGUAGE:  en
#+OPTIONS: H:3 num:t \n:nil @:t ::t |:t _:nil ^:nil -:t f:t *:t <:t
#+OPTIONS: TeX:t LaTeX:t skip:nil d:nil pri:nil tags:not-in-toc html-style:nil

This page is dedicated to rules and conventions that Chameleon's
developers must follow and that should be read by contributors.

* Gitlab flow: how to contribute to Chameleon

11
  Please read and follow guidelines given in the [[file:CONTRIBUTING.org][CONTRIBUTING file]].
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28

** Update submodules

   Chameleon git project depends on a "submodule" git, located in
   cmake_modules/morse_cmake and hosted here
   https://gitlab.inria.fr/solverstack/morse_cmake.

   To update this submodule to the last development state, follow
   these steps:

   #+begin_src sh
   git submodule update --remote cmake_modules/morse_cmake
   git commit cmake_modules/morse_cmake -m "update morse_cmake submodule"
   git push --recurse-submodules=check
   #+end_src

* Documentation
29
  <<sec:doc>>
30 31
** Generate the documentation

32
*** Prerequisites
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56

     To generate the documentation you need to have [[http://www.stack.nl/~dimitri/doxygen/][Doxygen]] and
     [[https://www.gnu.org/software/texinfo/][Texinfo]] installed on your system.

     For example, on Debian systems:
     #+begin_src sh
     sudo apt install doxygen texinfo
     #+end_src

*** configure + make documentation

    Enter into the Chameleon's source root directory and configure
    with *CHAMELEON_ENABLE_DOCS=ON*, then generate the documentation
    with ~make docs~

    #+begin_src sh
    cd chameleon
    mkdir build && cd build
    cmake .. -DCHAMELEON_ENABLE_DOCS=ON
    make docs
    #+end_src

** Rules about source code documentation

57
   Please refer to this file for the documentation guidelines [[file:docs/doxygen/README.org][README]].
58 59 60

* Naming and writting conventions

61 62
  Chameleon library started as an extension of the PLASMA library so
  that code naming and writting conventions should follow [[https://bitbucket.org/icl/plasma][PLASMA]] ones.
63 64 65 66 67 68 69

* Packaging

   A Chameleon's release is a source package, of the form
   chameleon-major.minor.patch.tar.gz, which:
   1) has been properly tested,
   2) contains a generated documentation corresponding to the released version,
70 71
   3) has an up-to-date ChangeLog file,
   4) is published on internet.
72 73 74 75 76 77 78 79 80 81

** Test Chameleon before packaging

   TODO - Write the way we could systematically test Chameleon before
   packaging, for example writting a script (generated from this
   org-mode file) to be used on PlaFRIM plus some specific ctest
   tests.

** Source tarball generation

82 83
   This step requires to generate the [[sec:doc][documentation]].

84 85 86 87 88 89
   #+begin_src sh
   export CHAMELEON_ROOT=/path/to/chameleon/sources/to/be/released
   cmake $CHAMELEON_ROOT -DCHAMELEON_ENABLE_DOCS=ON
   make docs && cp docs/texinfo/users_guide.pdf $CHAMELEON_ROOT && make package_source
   #+end_src

90 91 92
   A tarball chameleon-major.minor.patch.tar.gz should be generated
   and contains the users_guide documentation.

93 94
** Publish the release on internet

95 96 97 98 99 100 101 102 103
   A git tag must be first created, for example
   #+begin_src sh
   git tag -a v1.0.0 -m 'Version 1.0.0'
   git push --tags
   #+end_src

   Then in the Chameleon *Tags* tab,
   https://gitlab.inria.fr/solverstack/chameleon/tags, edit the
   release notes and attach the tarball previously generated.