From bdd5b561cbf8283532fbc7422da4867632fa8963 Mon Sep 17 00:00:00 2001
From: Erwan Jahier <erwan.jahier@univ-grenoble-alpes.fr>
Date: Fri, 22 Mar 2019 15:59:54 +0100
Subject: [PATCH] Doc: Initiate a contributors guide
---
guides/contributors/README.md | 139 +++++++++++++++++++++++++++++++
guides/contributors/README.org | 103 +++++++++++++++++++++++
{doc => guides/users}/README.md | 36 +++++---
{doc => guides/users}/README.org | 5 ++
4 files changed, 272 insertions(+), 11 deletions(-)
create mode 100644 guides/contributors/README.md
create mode 100644 guides/contributors/README.org
rename {doc => guides/users}/README.md (83%)
rename {doc => guides/users}/README.org (96%)
diff --git a/guides/contributors/README.md b/guides/contributors/README.md
new file mode 100644
index 00000000..9d254ef7
--- /dev/null
+++ b/guides/contributors/README.md
@@ -0,0 +1,139 @@
+- [Compiling sasa sources](#org30c5984)
+- [Graph editor](#org350e6d3)
+- [The Algo API](#orgf0dab07)
+- [Demons](#org009ddc4)
+- [Dealing with Algorithm values](#org02f3ab5)
+- [Representing Processes](#org889a969)
+- [CLI arguments (sasa options)](#org83b3139)
+- [The Main Simulation](#orge4efe80)
+- [Generating Version Numbers](#orgd3a1891)
+- [Pluging `sasa` on Synchronous tools](#org20e7801)
+ - [RIF](#org286d056)
+ - [The rdbg plugin](#org769e7a6)
+
+Self-stabilizing Algorithms SimulAtor (Simulation d'Algorithmes autoStAbilisants)
+
+Contributors Guide
+
+
+<a id="org30c5984"></a>
+
+# Compiling sasa sources
+
+You will need:
+
+- make
+- a set of tools installable via opam
+ - dune
+ - ocamlgraph
+ - lutin (not for compiling actually, but for using sasa with custom demons)
+
+cf the test job in the Gitlab CI script: <../../.gitlab-ci.yml> for a working installation process.
+
+
+<a id="org350e6d3"></a>
+
+# Graph editor
+
+Based on dot + custom fields (algo, init) <../../lib/sasacore/topology.mli> <../../lib/sasacore/topology.ml>
+
+This module is also used from `rdbg` (<../../test/rdbg-utils/dot.ml>)
+
+
+<a id="orgf0dab07"></a>
+
+# The Algo API
+
+<../../lib/algo/algo.mli> <../../lib/algo/algo.ml>
+
+Functions registration is based on Dynlink + (Hash)tables
+
+Users only need to see the [mli](../../lib/algo/algo.mli) file.
+
+
+<a id="org009ddc4"></a>
+
+# Demons
+
+built-in + custom
+
+<../../lib/sasacore/demon.mli> <../../lib/sasacore/demon.ml>
+
+custom in Lutin that can generated by:
+
+<../../lib/sasacore/genLutin.mli> <../../lib/sasacore/genLutin.ml>
+
+
+<a id="org02f3ab5"></a>
+
+# Dealing with Algorithm values
+
+<../../lib/sasacore/env.mli> <../../lib/sasacore/env.ml>
+
+
+<a id="org889a969"></a>
+
+# Representing Processes
+
+<../../lib/sasacore/process.mli>
+
+
+<a id="org83b3139"></a>
+
+# CLI arguments (sasa options)
+
+<../../lib/sasacore/sasArg.mli> <../../lib/sasacore/sasArg.ml>
+
+
+<a id="orge4efe80"></a>
+
+# The Main Simulation
+
+Splitted into 2 modules, so that the sasa rdbg plugin can reuse the step functions <../../lib/sasacore/sasa.ml>
+
+<../../src/sasaMain.ml>
+
+
+<a id="orgd3a1891"></a>
+
+# Generating Version Numbers
+
+The <../../lib/sasacore/sasaVersion.ml> is automatically generated
+
+- by <../../Makefile.version>
+- using git tags that are automatically generated using the `release` job of the CI script, which is based on [semantic-release-gitlab](https://www.npmjs.com/package/semantic-release-gitlab)
+
+In order to generate sensible version numbers, please follow in your commit messages the conventions described here: <https://www.npmjs.com/package/conventional-changelog-eslint>
+
+This also permits to generate some Releases Notes: <https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/releases>
+
+
+<a id="org20e7801"></a>
+
+# Pluging `sasa` on Synchronous tools
+
+
+<a id="org286d056"></a>
+
+## RIF
+
+<http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/lustre-v6/#outline-container-sec-5>
+
+```ocaml
+(* Time-stamp: <modified the 13/03/2019 (at 17:45) by Erwan Jahier> *)
+
+(** Reads on stdin a bool *)
+
+val bool: bool -> Process.t -> string -> bool
+```
+
+<../../lib/sasacore/rifRead.mli> <../../lib/sasacore/rifRead.ml>
+
+
+<a id="org769e7a6"></a>
+
+## The rdbg plugin
+
+<https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/rdbg/blob/master/src/rdbgPlugin.mli> <https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/lutils/blob/master/src/data.mli>
+
+<../../test/rdbg-utils/dot.ml>
diff --git a/guides/contributors/README.org b/guides/contributors/README.org
new file mode 100644
index 00000000..fd4210e0
--- /dev/null
+++ b/guides/contributors/README.org
@@ -0,0 +1,103 @@
+
+Self-stabilizing Algorithms SimulAtor
+(Simulation d'Algorithmes autoStAbilisants)
+
+Contributors Guide
+
+
+* Compiling sasa sources
+
+You will need:
+- make
+- a set of tools installable via opam
+ - dune
+ - ocamlgraph
+ - lutin (not for compiling actually, but for using sasa with custom demons)
+
+cf the test job in the Gitlab CI script: file:../../.gitlab-ci.yml
+for a working installation process.
+
+* Graph editor
+
+Based on dot + custom fields (algo, init)
+file:../../lib/sasacore/topology.mli
+file:../../lib/sasacore/topology.ml
+
+This module is also used from =rdbg= (file:../../test/rdbg-utils/dot.ml)
+
+* The Algo API
+file:../../lib/algo/algo.mli
+file:../../lib/algo/algo.ml
+
+Functions registration is based on Dynlink + (Hash)tables
+
+Users only need to see the [[file:../../lib/algo/algo.mli][mli]] file.
+
+* Demons
+
+built-in + custom
+
+file:../../lib/sasacore/demon.mli
+file:../../lib/sasacore/demon.ml
+
+custom in Lutin that can generated by:
+
+file:../../lib/sasacore/genLutin.mli
+file:../../lib/sasacore/genLutin.ml
+
+* Dealing with Algorithm values
+
+file:../../lib/sasacore/env.mli
+file:../../lib/sasacore/env.ml
+
+* Representing Processes
+
+file:../../lib/sasacore/process.mli
+
+* CLI arguments (sasa options)
+
+
+file:../../lib/sasacore/sasArg.mli
+file:../../lib/sasacore/sasArg.ml
+
+* The Main Simulation
+
+Splitted into 2 modules, so that the sasa rdbg plugin
+can reuse the step functions
+file:../../lib/sasacore/sasa.ml
+
+
+file:../../src/sasaMain.ml
+
+* Generating Version Numbers
+
+The file:../../lib/sasacore/sasaVersion.ml is automatically generated
+- by file:../../Makefile.version
+- using git tags that are automatically generated using the =release=
+ job of the CI script, which is based on [[https://www.npmjs.com/package/semantic-release-gitlab][semantic-release-gitlab]]
+
+In order to generate sensible version numbers, please follow in your
+commit messages the conventions described here:
+https://www.npmjs.com/package/conventional-changelog-eslint
+
+This also permits to generate some Releases Notes:
+https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/releases
+
+* Pluging =sasa= on Synchronous tools
+
+** RIF
+http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/lustre-v6/#outline-container-sec-5
+
+
+#+INCLUDE: "../../lib/sasacore/rifRead.mli" src ocaml
+
+file:../../lib/sasacore/rifRead.mli
+file:../../lib/sasacore/rifRead.ml
+
+
+** The rdbg plugin
+
+https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/rdbg/blob/master/src/rdbgPlugin.mli
+https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/lutils/blob/master/src/data.mli
+
+file:../../test/rdbg-utils/dot.ml
diff --git a/doc/README.md b/guides/users/README.md
similarity index 83%
rename from doc/README.md
rename to guides/users/README.md
index c944be7b..3c3d4151 100644
--- a/doc/README.md
+++ b/guides/users/README.md
@@ -1,8 +1,10 @@
-- [Dot files](#org0cd41b9)
-- [Algorithms](#org33281bc)
-- [Simulation](#org629cdd4)
-- [Custom mode](#org44c3285)
-- [Installation (not yet working)](#orgdce8a56)
+- [Dot files](#org8fd8577)
+- [Algorithms](#orgcbbf32f)
+- [Simulation](#org996e21a)
+- [Custom mode](#orgd85b8c1)
+- [rdbg](#orgc83f02b)
+- [Releases Notes](#org56e1efd)
+- [Installation (not yet working)](#orgf1a43f7)
Basically, one needs to provide
@@ -10,7 +12,7 @@ Basically, one needs to provide
2. the algorithms mentionned in the dot file
-<a id="org0cd41b9"></a>
+<a id="org8fd8577"></a>
# Dot files
@@ -34,7 +36,7 @@ graph ring {
```
-<a id="org33281bc"></a>
+<a id="orgcbbf32f"></a>
# Algorithms
@@ -77,7 +79,7 @@ ocamlopt -shared -I +sasa some_algo.ml -o some_algo.cmxs
Some examples can be found in the [test](https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/tree/master/test) directory.
-<a id="org629cdd4"></a>
+<a id="org996e21a"></a>
# Simulation
@@ -87,14 +89,26 @@ sasa --help
```
-<a id="org44c3285"></a>
+<a id="orgd85b8c1"></a>
# Custom mode
For using the custom mode, it is mandatory to register actions
-<a id="orgdce8a56"></a>
+<a id="orgc83f02b"></a>
+
+# rdbg
+
+
+<a id="org56e1efd"></a>
+
+# Releases Notes
+
+<https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/releases>
+
+
+<a id="orgf1a43f7"></a>
# Installation (not yet working)
@@ -111,4 +125,4 @@ Once is is done, upgrading to the last version of the tools is as simple as:
```yaml
opam update
opam upgrade
-```
\ No newline at end of file
+```
diff --git a/doc/README.org b/guides/users/README.org
similarity index 96%
rename from doc/README.org
rename to guides/users/README.org
index 1c380830..644ec0c3 100644
--- a/doc/README.org
+++ b/guides/users/README.org
@@ -81,6 +81,11 @@ Some examples can be found in the [[https://gricad-gitlab.univ-grenoble-alpes.fr
For using the custom mode, it is mandatory to register actions
+* rdbg
+* Releases Notes
+
+https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/releases
+
* Installation (not yet working)
#+BEGIN_SRC sh :tangle sh/install-opam.sh :noweb yes :tangle-mode (identity #o444)
--
GitLab