Skip to content
GitLab
Commit a1ede45e authored by PRUVOST Florent's avatar PRUVOST Florent
Browse files

Merge branch 'add_readme_for_dev' into 'master' 

initiate a README-dev.md where we could define rules for developers

See merge request !15
parents bad63cc6 4403ce03
Hide whitespace changes
Inline Side-by-side
CMakeLists.txt
View file @ a1ede45e
......@@ -1131,7 +1131,7 @@ generate_pkgconfig_file()
##################
set(CPACK_SOURCE_GENERATOR "TGZ")
set(CPACK_PACKAGE_NAME "chameleon")
set(CPACK_PACKAGE_DESCRIPTION_FILE ${CMAKE_CURRENT_SOURCE_DIR}/README.md)
set(CPACK_PACKAGE_DESCRIPTION_FILE ${CMAKE_CURRENT_SOURCE_DIR}/README.org)
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "Chameleon is a C library providing parallel algorithms to perform BLAS/LAPACK "
" operations exploiting fully modern architectures.")
set(CHAMELEON_VERSION_PATCH ${CHAMELEON_VERSION_MICRO})
......@@ -1140,7 +1140,7 @@ set(CPACK_PACKAGE_FILE_NAME "${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}")
set(CPACK_SOURCE_PACKAGE_FILE_NAME "${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}")
set(CPACK_PACKAGE_VENDOR "Inria")
set(CPACK_PACKAGE_CONTACT "morse-devel@lists.gforge.inria.fr")
set(CPACK_RESOURCE_FILE_README ${CMAKE_CURRENT_SOURCE_DIR}/README.md)
set(CPACK_RESOURCE_FILE_README ${CMAKE_CURRENT_SOURCE_DIR}/README.org)
set(CPACK_RESOURCE_FILE_LICENSE ${CMAKE_CURRENT_SOURCE_DIR}/LICENCE.txt)
set(CPACK_SOURCE_IGNORE_FILES "plasma-conversion;build;.cproject;.settings;.dir-locals.el;.project;.pydevproject;.svn;.git;.gitmodules;.gitlab-ci.yml")
include(CPack)
......
CONTRIBUTING.md deleted 100644 → 0
View file @ bad63cc6
# To contribute to the project, you need to do it through pull/merge request
First you need to fork the repository into your own account. You can do that simply by clicking the fork button on the gitlab interface.
https://gitlab.inria.fr/solverstack/chameleon/forks/new
Then, clone the repository on your laptop:
```
#!shell
git clone git@gitlab.inria.fr:username/forkname.git
```
Once this is done, you can setup the chameleon repository as the upstream of your clone to simplify the update of your fork repository.
```
#!shell
git remote add upstream git@gitlab.inria.fr:solverstack/chameleon.git
```
To update your fork with the upstream chameleon's state:
```
#!shell
git pull upstream master
git push -u origin master
```
Now, you have your repository configured, and you want to create a new pull request. The first step is to create a branch from the HEAD of the your fork repository.
```
#!shell
git branch your_branch_name
git checkout your_branch_name
```
Apply your modifications in your branch. Then, you need to push this branch on your online repository
```
#!shell
git push -f origin your_branch_name
```
or without -f, if the branch already exists online, and you just want to update it.
Once your branch is online, on the gitlab interface, go to the branches webpage, select the branch you want to push as a merge request, and push the button !!!
***Be careful to check the 'close after merge' check box, and to push to the solverstack/chameleon repository*** By default the checkbox is not checked, and the default repository is your fork.
# To review locally a private pull request submitted by someone else
Get the patch from the pull request (Need to update that !!!! Coming from bitbucket)
```
#!shell
curl https://bitbucket.org/api/2.0/repositories/icldistcomp/parsec/pullrequests/#PR/patch > pr#PR.patch
```
Than apply the patch on your local copy
```
#!shell
git apply pr#PR.patch
```
CONTRIBUTING.org 0 → 100644
View file @ a1ede45e
* To contribute to the project, you need to do it through merge request
First you need to fork the repository into your own account. You can
do that simply by clicking the fork button on the gitlab interface.
https://gitlab.inria.fr/solverstack/chameleon/forks/new
Then, clone the repository on your laptop:
#+begin_src sh
git clone git@gitlab.inria.fr:username/forkname.git
#+end_src
Once this is done, you can setup the chameleon repository as the
upstream of your clone to simplify the update of your fork
repository.
#+begin_src sh
git remote add upstream git@gitlab.inria.fr:solverstack/chameleon.git
#+end_src
To update your fork with the upstream chameleon's state:
#+begin_src sh
git pull upstream master
git push -u origin master
#+end_src
Now, you have your repository configured, and you want to create a
new pull request. The first step is to create a branch from the HEAD
of the your fork repository.
#+begin_src sh
git branch your_branch_name
git checkout your_branch_name
#+end_src
Apply your modifications in your branch. Then, you need to push this
branch on your online repository
#+begin_src sh
git push -f origin your_branch_name
#+end_src
or without -f, if the branch already exists online, and you just
want to update it.
Once your branch is online, on the gitlab interface, go to the
branches webpage, select the branch you want to push as a merge
request, and push the button !!!
*Be careful to check the 'close after merge' check box, and to push
to the solverstack/chameleon repository*. By default the checkbox
may not be checked, and the default repository is your fork.
If the pull request is made to fix an issue, please name the branch
"issueXX" so it is automatically linked to the issue. In addition,
please add "fix issue #xx" in the comment of the pull request to
automatically close the issue when the PR is merged.
** Rebase on top of 'master'
In some cases your "feature" branch you want to merge into "master"
has a long life span so that your branch and the master branch
could make some conflicts. To avoid having to handle the possible
conflicts at *merge request* time, please rebase your "feature" on
top of "master" before pushing the button *merge request*.
To do that, just go at the HEAD of your "feature" branch and rebase
#+begin_src sh
git checkout feature
git rebase master
#+end_src
Then force to push on your origin
#+begin_src sh
git push --force origin feature
#+end_src
Then push the button *merge request*.
* To review locally a private pull request submitted by someone else
Get the patch from the pull request (Need to update that !!!!
Coming from bitbucket)
#+begin_src sh
curl https://bitbucket.org/api/2.0/repositories/icldistcomp/parsec/pullrequests/#PR/patch > pr#PR.patch
#+end_src
Then apply the patch on your local copy
#+begin_src sh
git apply pr#PR.patch
#+end_src
README.md deleted 100644 → 0
View file @ bad63cc6
Chameleon: A dense linear algebra software for heterogeneous architectures
====================
Chameleon is a C library providing parallel algorithms to perform
BLAS/LAPACK operations exploiting fully modern architectures.
Chameleon dense linear algebra software relies on sequential
task-based algorithms where sub-tasks of the overall algorithms are
submitted to a Runtime system. Such a system is a layer between the
application and the hardware which handles the scheduling and the
effective execution of tasks on the processing units. A Runtime system
such as [StarPU](http://starpu.gforge.inria.fr/) is able to manage
automatically data transfers between not shared memory area
(CPUs-GPUs, distributed nodes).
This kind of implementation paradigm allows to design high performing
linear algebra algorithms on very different type of architecture:
laptop, many-core nodes, CPUs-GPUs, multiple nodes. For example,
Chameleon is able to perform a Cholesky factorization
(double-precision) at 80 TFlop/s on a dense matrix of order 400 000
(i.e. 4 min). Chameleon is a sub-project of
[MORSE](http://icl.cs.utk.edu/morse/) specifically dedicated to dense
linear algebra.
Get Chameleon
---------------------
To use last development states of Chameleon, please clone the master
branch. Note that Chameleon contains a `git submodule` **morse_cmake**.
To get sources please use these commands:
# if git version >= 1.9
git clone --recursive git@gitlab.inria.fr:solverstack/chameleon.git
cd chameleon
# else
git clone git@gitlab.inria.fr:solverstack/chameleon.git
cd chameleon
git submodule init
git submodule update
Last releases of Chameleon are hosted on the
[gforge.inria.fr](https://gforge.inria.fr/frs/?group_id=2884) for now.
Future releases will be available on this gitlab project.
Documentation
---------------------
There is no up-to-date documentation of Chameleon. We would like to
provide a doxygen documentation hosted on
[gitlab](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/) in
the future.
The documentation of Chameleon's last release is available here:
[chameleon-0.9.1
documentation](http://morse.gforge.inria.fr/chameleon/0.9.1/chameleon_users_guide-0.9.1.html)
Installation
---------------------
### Build and install with CMake
Chameleon can be built using [CMake](https://cmake.org/). This
installation requires to have some library dependencies already
installed on the system.
Please refer to the
[chameleon-0.9.1](http://morse.gforge.inria.fr/chameleon/0.9.1/chameleon_users_guide-0.9.1.html#Installing-CHAMELEON)
to get configuration information.
### Distribution of Chameleon
To get support to install a full distribution (Chameleon +
dependencies) we encourage users to use the morse branch of
**Spack**.
Please read these documentations:
* [Spack Morse](http://morse.gforge.inria.fr/spack/spack.html).
* [Section Chameleon](http://morse.gforge.inria.fr/spack/spack.html#sec-2-1).
Get involved!
---------------------
### Mailing list
TODO
### Contributions
https://gitlab.inria.fr/solverstack/chameleon/blob/master/CONTRIBUTING.md
### Authors
First, since the Chameleon library started as an extension of the PLASMA library
to support multiple runtime systems, all developpers of the PLASMA library are
developpers of the Chameleon library.
The following people contributed to the development of Chameleon:
* Emmanuel Agullo, PI
* Olivier Aumage
* Cedric castagnede
* Terry Cojean
* Mathieu Faverge, PI
* Nathalie Furmento
* Reazul Hoque, PaRSEC support
* Gregoire Pichon, Two-sided algorithms
* Florent Pruvost, PI, CMake and Spack
* Marc Sergent
* Guillaume Sylvand
* Samuel Thibault, StarPU support
* Omar Zenati
If we forgot your name, please let us know that we can fix that mistake.
### Citing Chameleon
TODO
### Licence
https://gitlab.inria.fr/solverstack/chameleon/blob/master/LICENCE.txt
README.org 0 → 100644
View file @ a1ede45e
#+TITLE: Chameleon: A dense linear algebra software for heterogeneous architectures
#+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
Chameleon is a C library providing parallel algorithms to perform
BLAS/LAPACK operations exploiting fully modern architectures.
Chameleon dense linear algebra software relies on sequential
task-based algorithms where sub-tasks of the overall algorithms are
submitted to a Runtime system. Such a system is a layer between the
application and the hardware which handles the scheduling and the
effective execution of tasks on the processing units. A Runtime system
such as [[http://starpu.gforge.inria.fr/][StarPU]] is able to manage automatically data transfers between
not shared memory area (CPUs-GPUs, distributed nodes).
This kind of implementation paradigm allows to design high performing
linear algebra algorithms on very different type of architecture:
laptop, many-core nodes, CPUs-GPUs, multiple nodes. For example,
Chameleon is able to perform a Cholesky factorization
(double-precision) at 80 TFlop/s on a dense matrix of order 400 000
(i.e. 4 min). Chameleon is a sub-project of [[http://icl.cs.utk.edu/morse/][MORSE]] specifically
dedicated to dense linear algebra.
* Get Chameleon
To use last development states of Chameleon, please clone the master
branch. Note that Chameleon contains a ~git submodule~ *morse_cmake*.
To get sources please use these commands:
#+begin_src sh
# if git version >= 1.9
git clone --recursive git@gitlab.inria.fr:solverstack/chameleon.git
cd chameleon
# else
git clone git@gitlab.inria.fr:solverstack/chameleon.git
cd chameleon
git submodule init
git submodule update
#+end_src
Last releases of Chameleon are hosted on the [[https://gforge.inria.fr/frs/?group_id=2884][gforge.inria.fr]] for
now. Future releases will be available on this gitlab project.
* Documentation
There is no up-to-date documentation of Chameleon. We would like to
provide a doxygen documentation hosted on [[https://about.gitlab.com/2016/04/07/gitlab-pages-setup/][gitlab]] in the
future. Please refer to the section 2.1 of [[file:READMEDEV.org][READMEDEV]] to get
information about the documentation generation.
The documentation of Chameleon's last release is available here:
[[http://morse.gforge.inria.fr/chameleon/0.9.1/chameleon_users_guide-0.9.1.html][chameleon-0.9.1 documentation]].
** For developers
[[file:READMEDEV.org][READMEDEV]]
* Installation
** Distribution of Chameleon
To get support to install a full distribution (Chameleon +
dependencies) we encourage users to use the morse branch of *Spack*.
Please read these documentations:
* [[http://morse.gforge.inria.fr/spack/spack.html][Spack Morse]]
* [[http://morse.gforge.inria.fr/spack/spack.html#sec-2-1][Section Chameleon]]
*** Usage example for a simple distribution of Chameleon
#+begin_src sh
git clone https://github.com/solverstack/spack.git
. ./spack/share/spack/setup-env.sh
spack install -v chameleon
# chameleon is installed here:
`spack location -i chameleon`
#+end_src
** Build and install with CMake
Chameleon can be built using [[https://cmake.org/][CMake]]. This installation requires to
have some library dependencies already installed on the system.
Please refer to [[http://morse.gforge.inria.fr/chameleon/0.9.1/chameleon_users_guide-0.9.1.html#Installing-CHAMELEON][chameleon-0.9.1]] to get configuration information.
* Get involved!
** Mailing list
To contact the developers send an email to
[[mailto:morse-devel@lists.gforge.inria.fr][morse-devel@lists.gforge.inria.fr]]
** Contributions
[[file:CONTRIBUTING.org][CONTRIBUTING]]
* Authors
First, since the Chameleon library started as an extension of the
PLASMA library to support multiple runtime systems, all developpers
of the PLASMA library are developpers of the Chameleon library.
The following people contributed to the development of Chameleon:
* Emmanuel Agullo, PI
* Olivier Aumage
* Cedric castagnede
* Terry Cojean
* Mathieu Faverge, PI
* Nathalie Furmento
* Reazul Hoque, PaRSEC support
* Gregoire Pichon, Two-sided algorithms
* Florent Pruvost, PI, CMake and Spack
* Marc Sergent
* Guillaume Sylvand
* Samuel Thibault, StarPU support
* Omar Zenati
If we forgot your name, please let us know that we can fix that mistake.
* Citing Chameleon
Feel free to use the following publications to reference Chameleon:
* Original paper that initiated Chameleon and the principles:
- Agullo, Emmanuel and Augonnet, Cédric and Dongarra, Jack and
Ltaief, Hatem and Namyst, Raymond and Thibault, Samuel and Tomov,
Stanimire, *Faster, Cheaper, Better -- a Hybridization Methodology
to Develop Linear Algebra Software for GPUs*, /GPU Computing Gems/,
[[https://hal.inria.fr/inria-00547847][First Online: 17 December 2010]].
* Design of the QR algorithms:
- Agullo, Emmanuel and Augonnet, Cédric and Dongarra, Jack and
Faverge, Mathieu and Ltaief, Hatem and Thibault, Samuel an
Tomov, Stanimire, *QR Factorization on a Multicore Node Enhanced
with Multiple GPU Accelerators*, /25th IEEE International Parallel
& Distributed Processing Symposium/, [[https://hal.inria.fr/inria-00547614][First Online: 16 December
2010]].
* Design of the LU algorithms:
- Agullo, Emmanuel and Augonnet, Cédric and Dongarra, Jack and
Faverge, Mathieu and Langou, Julien and Ltaief, Hatem and Tomov,
Stanimire, *LU Factorization for Accelerator-based Systems*,
/9th ACS/IEEE International Conference on Computer Systems and
Applications (AICCSA 11)/, [[https://hal.inria.fr/hal-00654193][First Online: 21 December 2011]].
* Regarding distributed memory:
- Agullo, Emmanuel and Aumage, Olivier and Faverge, Mathieu and
Furmento, Nathalie and Pruvost, Florent and Sergent, Marc and
Thibault, Samuel, *Achieving High Performance on Supercomputers
with a Sequential Task-based Programming Model*, /Research Report/,
[[https://hal.inria.fr/hal-01332774][First Online: 16 June 2016]].
* Licence
[[file:LICENCE.txt][LICENCE]]
READMEDEV.org 0 → 100644
View file @ a1ede45e
#+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
Please read and follow guidelines given in the [[file:CONTRIBUTING.org][CONTRIBUTING file]].
** 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
<<sec:doc>>
** Generate the documentation
*** Prerequisites
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
Please refer to this file for the documentation guidelines [[file:docs/doxygen/README.org][README]].
* Naming and writting conventions
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.
* 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,
3) has an up-to-date ChangeLog file,
4) is published on internet.
** 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
This step requires to generate the [[sec:doc][documentation]].
#+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
A tarball chameleon-major.minor.patch.tar.gz should be generated
and contains the users_guide documentation.
** Publish the release on internet
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.
docs/doxygen/README.org 0 → 100644
View file @ a1ede45e
#+TITLE: Doxygen Documentation
Document all functions prototypes, modules, macros, structures and
variables. Doxygen is not very flexible: read this documentation and
follow the guidelines. Remember to generate the documentation, and
check that it appears as expected.
The file ~xxxx.c~ has examples of all features used in the
documentation.
* Functions Prototype Documentation
To document a function, use the following format:
#+begin_src c
/**
*******************************************************************************
*
* @ingroup name_of_parent_module
*
* @brief Single line explanation of the function
*
* Multiple lines explaining the detailed function behavior
* exceptions, preconditions, algorithm, etc.
*
*******************************************************************************
*
* @param[inout] name_of_parameter
* Explanation of the parameter
*
* @param[in] name_of_parameter
* Explanation of the parameter
*
*******************************************************************************
*
* @return Explain what is returned by the function
*
* or
*
* @retval value1 explanation of the returned value and in which case it is returned
* @retval value2 ...
*
*******************************************************************************/
int
function(int param1, int *param2)
{
}
#+end_src
~[in]~ *must* be attached to ~@param~, and *it must* be /lower
case/. Otherwise, Doxygen thinks the name of the parameter is ~[IN]~.
Blank lines are /important/: there must be a blank line between ~@brief~
and the ~details~ section.
* Structures documentation
Use the following format:
#+begin_src c
/**
* @ingroup name_of_parent_module
* @brief Single line explanation of the structure
*
* General description of the structure
*/
struct name_s {
type1 field1; /**< What is stored in this field */
type2 field2; /**< What is stored in this field */
};
#+end_src
It is important to use the ~/**<~ marker, or the description of the
field is not imported in an array representation of the data
structure.
* Macros Documentation
Use the following format:
#+begin_src c
/**
* @ingroup name_of_parent_module
*
* @brief Single line explanation of the macro
*
* General description of the macro if needed
*/
#define macro
#+end_src
Without the ~@brief~, the documentation does not appear just under the
macro definition. All macro definitions are output directly in the
generated documentation.
* Variable Documentation
Use the following format:
#+begin_src c
/**
* @ingroup name_of_parent_module
*
* @brief Single line explanation of the variable
*
* General description of the variable if needed
*/
int var;
#+end_src
Without the ~@brief~, the documentation does not appear just under the