READMEDEV.org 3.28 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
** Generate the documentation
31
*** Prerequisites
32 33

     To generate the documentation you need to have [[http://www.stack.nl/~dimitri/doxygen/][Doxygen]] and
34
     [[https://orgmode.org/][org-mode]] installed on your system.
35 36 37

     For example, on Debian systems:
     #+begin_src sh
38
     sudo apt install doxygen org-mode texlive texlive-latex-extra emacs
39 40 41 42 43
     #+end_src

*** configure + make documentation

    Enter into the Chameleon's source root directory and configure
44 45
    with *CHAMELEON_ENABLE_DOC=ON*, then generate the documentation
    with ~make doc~
46 47 48 49

    #+begin_src sh
    cd chameleon
    mkdir build && cd build
50 51
    cmake .. -DCHAMELEON_ENABLE_DOC=ON
    make doc
52 53 54 55
    #+end_src

** Rules about source code documentation

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

* Naming and writting conventions

60 61
  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.
62 63 64 65 66 67 68

* 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,
69 70
   3) has an up-to-date ChangeLog file,
   4) is published on internet.
71 72 73 74 75 76 77 78 79 80

** 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

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

83 84
   #+begin_src sh
   export CHAMELEON_ROOT=/path/to/chameleon/sources/to/be/released
85 86 87 88
   cmake $CHAMELEON_ROOT -DCHAMELEON_ENABLE_DOC=ON
   make doc
   cp doc/orgmode/users_guide.pdf $CHAMELEON_ROOT
   make package_source
89 90
   #+end_src

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

94 95
** Publish the release on internet

96 97 98 99 100 101 102 103 104
   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.