From d71a3214ca7c97b6767edec632df1e0a2bff7bcb Mon Sep 17 00:00:00 2001
From: Erwan Jahier <erwan.jahier@univ-grenoble-alpes.fr>
Date: Mon, 27 Jan 2020 22:14:46 +0100
Subject: [PATCH] Doc: some precisions on the install process
---
Makefile | 3 -
guides/users/README.md | 124 +++++++++++++++++++++-------------------
guides/users/README.org | 26 ++++++---
3 files changed, 83 insertions(+), 70 deletions(-)
diff --git a/Makefile b/Makefile
index 2b517a37..575b86f9 100644
--- a/Makefile
+++ b/Makefile
@@ -16,9 +16,6 @@ test:
make
cd test; make
-test-doc:
- cd guides/users; make
-
odoc:
dune build @doc
diff --git a/guides/users/README.md b/guides/users/README.md
index f61a7067..2bc7c3ed 100644
--- a/guides/users/README.md
+++ b/guides/users/README.md
@@ -1,34 +1,34 @@
-- [TL;DR](#orgd851639)
-- [Topology](#org297be1b)
-- [Algorithms](#org06dc33c)
-- [Examples](#orgd0c4a0f)
-- [Batch mode](#org2483f76)
- - [Running batch simulations with Built-in daemons](#org26c2c5b)
- - [Running batch simulations with manual daemons](#org90f958f)
- - [Running batch simulations with `lurette`](#orgc332df1)
- - [Viewing Results](#org76d3f38)
- - [The `sasa` CLI](#orge649a65)
-- [Interactive mode](#org8e72f9f)
- - [Example: use `rdbg` from the `test/alea-coloring/` directory](#org31927a0)
- - [The exemples of test directory](#org94d1131)
- - [Running interactive sessions with `rdbg`](#orge89a030)
- - [Getting `rdbg` on-line help](#org2c11b7f)
- - [Useful Modules](#org743efca)
-- [Install](#org3b08da5)
- - [Via opam 2 (prefered method)](#org3c0ec86)
- - [Via docker](#org6f38193)
- - [From source](#orgdc4be6f)
-- [More](#org666d974)
-- [FAQ](#orgc12b460)
- - [Is there a FAQ?](#org3ef8a2c)
-
-
-
-<a id="orgd851639"></a>
+- [TL;DR](#orgc2cabd3)
+- [Topology](#org4b585e5)
+- [Algorithms](#org64c16fc)
+- [Examples](#orgd093f23)
+- [Batch mode](#org341c3c0)
+ - [Running batch simulations with Built-in daemons](#orgd196033)
+ - [Running batch simulations with manual daemons](#orgad24fb9)
+ - [Running batch simulations with `lurette`](#org063119a)
+ - [Viewing Results](#org17ee087)
+ - [The `sasa` CLI](#orgd22c6eb)
+- [Interactive mode](#org7e42662)
+ - [Example: use `rdbg` from the `test/alea-coloring/` directory](#org77d4010)
+ - [The exemples of test directory](#org2c0dc88)
+ - [Running interactive sessions with `rdbg`](#org88109e3)
+ - [Getting `rdbg` on-line help](#orgc9897b0)
+ - [Useful Modules](#orgcfdcf07)
+- [Install](#orgdc4beab)
+ - [Via opam 2 (prefered method for linux users)](#orge971f77)
+ - [Via docker (prefered method for mac users)](#orgcc52ef1)
+ - [From source](#org5fed492)
+- [More](#orgd027067)
+- [FAQ](#orgff3477e)
+ - [Is there a FAQ?](#org7d94f98)
+
+
+
+<a id="orgc2cabd3"></a>
# TL;DR
-<a id="orgab95120"></a> SASA is a **Self-stabilizing Algorithms SimulAtor**, based on the so-called **Atomic State model** (ASM) introduced by <span class="underline">Dijkstra</span> in its seminal article on [Self-stabilizing distributed algorithms](http://www.cs.utexas.edu/~EWD/ewd04xx/EWD426.PDF).
+<a id="org357fa28"></a> SASA is a **Self-stabilizing Algorithms SimulAtor**, based on the so-called **Atomic State model** (ASM) introduced by <span class="underline">Dijkstra</span> in its seminal article on [Self-stabilizing distributed algorithms](http://www.cs.utexas.edu/~EWD/ewd04xx/EWD426.PDF).
Basically, one needs to provide:
@@ -50,7 +50,7 @@ The source code is available at <https://gricad-gitlab.univ-grenoble-alpes.fr/ve
[](http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/sasa/poster.pdf)
-<a id="org297be1b"></a>
+<a id="org4b585e5"></a>
# Topology
@@ -113,11 +113,11 @@ Such parameters can be retreived in Algorithms using the `Algo.get_graph_attribu
nb: a `Algo.diameter: unit -> int` function is provided, but it can be expensive to use.
-<a id="org06dc33c"></a>
+<a id="org64c16fc"></a>
# Algorithms
-<a id="org16f664a"></a>
+<a id="org6d64c78"></a>
The following has been generated from [algo.mli](https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/blob/master/lib/algo/algo.mli)
@@ -127,7 +127,7 @@ The following has been generated from [algo.mli](https://gricad-gitlab.univ-gren
</div>
-<a id="orgd0c4a0f"></a>
+<a id="orgd093f23"></a>
# Examples
@@ -155,14 +155,14 @@ The `test` directory also contains sub-directories which gathers programs shared
- `test/*/my-rdbg-tuning.ml`: includes `test/my-rdbg-tuning.ml` and defines commands specific to the example of the directory. Indeed, `rdbg`, once launched, first tries to read the content of the file name `my-rdbg-tuning.ml` (it it exists).
-<a id="org2483f76"></a>
+<a id="org341c3c0"></a>
# Batch mode
-<a id="org26c2c5b"></a>
+<a id="orgd196033"></a>
## Running batch simulations with Built-in daemons
@@ -187,7 +187,7 @@ sasa -h | grep "\-daemon"
--custom-daemon, -custd
-<a id="org90f958f"></a>
+<a id="orgad24fb9"></a>
## Running batch simulations with manual daemons
@@ -214,7 +214,7 @@ It can also by simulated by [`lutin`](http://www-verimag.imag.fr/DIST-TOOLS/SYNC
Built-in daemons can of course be programmed in Lutin. One can generate such daemons using the `--gen-lutin-daemon` option: `sasa --gen-lutin-daemon a_graph.dot`. It can be handy at least to get the daemons variables names in the good order if one to write its own daemon.
-<a id="orgc332df1"></a>
+<a id="org063119a"></a>
## Running batch simulations with `lurette`
@@ -237,14 +237,14 @@ lurette \
```
-<a id="org76d3f38"></a>
+<a id="org17ee087"></a>
## Viewing Results
-`sasa -rif` and `lurette` generates `.rif` files that can be viewed with `gnuplot-rif` or `sim2chro`; cf <http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/lustre-v6/>
+`sasa -rif` and `lurette` generates `.rif` files that can be viewed with `gnuplot-rif` or `sim2chro`; cf <http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/reactive-toolbox/>
-<a id="orge649a65"></a>
+<a id="orgd22c6eb"></a>
## The `sasa` CLI
@@ -307,14 +307,14 @@ sasa --more
Display the version ocaml version sasa was compiled with and exit.
-<a id="org8e72f9f"></a>
+<a id="org7e42662"></a>
# Interactive mode
-<a id="orge81af28"></a> If you want to perform interactive session, you can launch `sasa` under the control of [rdbg](http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/rdbg/). Before reading this section, please read at least the [Basic usage Section if the rdbg documentation](http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/rdbg/README.html#Level0).
+<a id="org707dffe"></a> If you want to perform interactive session, you can launch `sasa` under the control of [rdbg](http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/rdbg/). Before reading this section, please read at least the [Basic usage Section if the rdbg documentation](http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/rdbg/README.html#Level0).
-<a id="org31927a0"></a>
+<a id="org77d4010"></a>
## Example: use `rdbg` from the `test/alea-coloring/` directory
@@ -367,7 +367,7 @@ $ rdbg
Typing `[Enter]` will therefore also load the `rdbg_session.ml` file we have just been using.
-<a id="org94d1131"></a>
+<a id="org2c0dc88"></a>
## The exemples of test directory
@@ -378,7 +378,7 @@ The [test](https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/t
- `test/*/my-rdbg-tuning.ml`: includes `test/my-rdbg-tuning.ml` and defines commands specific to the example of the directory. Indeed, `rdbg`, once launched, first tries to read the content of the file name `my-rdbg-tuning.ml` (it it exists).
-<a id="orge89a030"></a>
+<a id="org88109e3"></a>
## Running interactive sessions with `rdbg`
@@ -395,7 +395,7 @@ The [test](https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/t
All those commands are defined in (the common) [test/my-rdbg-tuning.ml](https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/tree/master/test/my-rdbg-tuning.ml) that is included in (locals) `test/*/my-rdbg-tuning.ml` that are included in (generated) `test/*/rdbg-session.ml` files. `my-rdbg-tuning.ml` contains straigthforward `ocaml` code that defines various `rdbg` shortcuts to ease the simulation of `sasa` systems. Feel free to tailor those command to yours needs by modyfying the local `my-rdbg-tuning.ml`!
-<a id="org2c11b7f"></a>
+<a id="orgc9897b0"></a>
## Getting `rdbg` on-line help
@@ -408,10 +408,10 @@ Here are 2 useful entry-points to rdbg on-line help:
(rdbg) l
```
- f01b12af88000136e82fb79fe9e8bd74
+ 9bf78f64b677001b1010261a371e4e6f
-<a id="org743efca"></a>
+<a id="orgcfdcf07"></a>
## Useful Modules
@@ -438,14 +438,18 @@ Some modules, used by the sasa core engine, can be useful from `rdbg`.
</div>
-<a id="org3b08da5"></a>
+<a id="orgdc4beab"></a>
# Install
-<a id="org3c0ec86"></a>
+<a id="orge971f77"></a>
-## Via opam 2 (prefered method)
+## Via opam 2 (prefered method for linux users)
+
+One way to install `sasa` is via [opam](http://opam.ocaml.org/doc/Install.html), a package manager for ocaml programs. opam works out of the box with most Linux distributions and OSX (mac). opam ougth to work on windows too [(follow this link for instructions)](http://protz.github.io/ocaml-installer/).
+
+Once opam is installed and configured:
```sh
opam repo add verimag-sync-repo "http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/opam-repository"
@@ -460,22 +464,24 @@ opam update
opam upgrade
```
-In order to install the tools mentionned in this documentation that can be used with `sasa` (namely, `gnuplot-rif`, `sim2chro`, `luciole-rif`, `lutin`, `lurette`, `rdbg`):
+In order to install the tools mentionned in this documentation that can be used with `sasa` (namely, `gnuplot-rif`, `lutin`, `lurette`, `rdbg`, `lv6`)):
```sh
-opam depext -y rdbg lutin
-opam install -y rdbg lutin
+opam depext -y rdbg lutin lustre-v6
+opam install -y rdbg lutin lustre-v6
```
+In order to be able to use `luciole` and `sim2chro`, you need to install the Lustre V4 distribution: <http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/lustre-v4/distrib/index.html>
+
-<a id="org6f38193"></a>
+<a id="orgcc52ef1"></a>
-## Via docker
+## Via docker (prefered method for mac users)
cf the Docker Install section of the [Synchrone Reactive Tool Box](http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/lustre-v6/#docker).
-<a id="orgdc4be6f"></a>
+<a id="org5fed492"></a>
## From source
@@ -495,7 +501,7 @@ opam install dune ocamlgraph rdbg lutin
One can mimick the content of the `test` job in the project [.gitlab-ci.yml Gitlab CI script](https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/tree/master/.gitlab-ci.yml).
-<a id="org666d974"></a>
+<a id="orgd027067"></a>
# More
@@ -504,12 +510,12 @@ One can mimick the content of the `test` job in the project [.gitlab-ci.yml Gitl
- Tutorials: <https://verimag.gricad-pages.univ-grenoble-alpes.fr/vtt//categories/sasa/>
-<a id="orgc12b460"></a>
+<a id="orgff3477e"></a>
# FAQ
-<a id="org3ef8a2c"></a>
+<a id="org7d94f98"></a>
## Is there a FAQ?
diff --git a/guides/users/README.org b/guides/users/README.org
index 1ef0f2ff..56c9a36c 100644
--- a/guides/users/README.org
+++ b/guides/users/README.org
@@ -3,7 +3,7 @@
#+LANGUAGE: en
#+OPTIONS: H:3 \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:nil skip:nil tags:not-in-toc
#+LINK_UP:https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa
-#+LINK_HOME:http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/lustre-v6
+#+LINK_HOME:http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/reactive-toolbox
#+HTML_HEAD:https://gricad-gitlab.univ-grenoble-alpes.fr/verimag/synchrone/sasa/tree/master/
#+HTML_HEAD: <base target="_parent">
@@ -236,7 +236,7 @@ in Lustre, one can use =lurette= as follows:
** Viewing Results
=sasa -rif= and =lurette= generates =.rif= files that can be viewed
-with =gnuplot-rif= or =sim2chro=; cf http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/lustre-v6/
+with =gnuplot-rif= or =sim2chro=; cf http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/reactive-toolbox/
** The =sasa= CLI
#+BEGIN_SRC sh :results output :exports both
@@ -463,9 +463,14 @@ Some modules, used by the sasa core engine, can be useful from =rdbg=.
* Install
-** Via opam 2 (prefered method)
+** Via opam 2 (prefered method for linux users)
+One way to install =sasa= is via [[http://opam.ocaml.org/doc/Install.html][opam]], a package manager
+for ocaml programs. opam works out of the box with most Linux
+distributions and OSX (mac). opam ougth to work on windows too [[http://protz.github.io/ocaml-installer/][(follow
+this link for instructions)]].
+Once opam is installed and configured:
#+BEGIN_SRC sh :tangle sh/install-opam.sh :noweb yes :tangle-mode (identity #o444)
opam repo add verimag-sync-repo "http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/opam-repository"
@@ -482,14 +487,19 @@ opam upgrade
#+END_SRC
In order to install the tools mentionned in this documentation that
-can be used with =sasa= (namely, =gnuplot-rif=, =sim2chro=,
-=luciole-rif=, =lutin=, =lurette=, =rdbg=):
+can be used with =sasa= (namely, =gnuplot-rif=, =lutin=, =lurette=,
+=rdbg=, =lv6=)):
#+BEGIN_SRC sh :tangle sh/install-opam.sh :noweb yes :tangle-mode (identity #o444)
-opam depext -y rdbg lutin
-opam install -y rdbg lutin
+opam depext -y rdbg lutin lustre-v6
+opam install -y rdbg lutin lustre-v6
#+END_SRC
-** Via docker
+In order to be able to use =luciole= and =sim2chro=, you need to
+install the Lustre V4 distribution:
+http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/lustre-v4/distrib/index.html
+
+
+** Via docker (prefered method for mac users)
cf the Docker Install section of the [[http://www-verimag.imag.fr/DIST-TOOLS/SYNCHRONE/lustre-v6/#docker][Synchrone Reactive Tool Box]].
--
GitLab