Commit 026712d1 authored by BorisPAING's avatar BorisPAING

STY: code markup looked bad for some reason

parent 71f6199d
......@@ -34,7 +34,9 @@ Vous pouvez pour cela utiliser Sakia ou [Cesium pour Ğ1-Test](https://g1-test.d
Pour lancer Sakia sur Ğ1-Test, utilisez la commande :
sakia --currency=g1-test
```bash
sakia --currency=g1-test
```
Notez également que le réseau Ğ1-Test pourra être redémarré de zéro si cela s'avère nécessaire.
......@@ -84,6 +86,8 @@ Puis, synchronisez-vous sur le réseau :
### Avec Duniter Server :
duniter sync g1-test.duniter.org 443
```bash
duniter sync g1-test.duniter.org 443
```
A bientôt sur Ğ1-Test !
\ No newline at end of file
......@@ -32,7 +32,9 @@ Une documentation sur les modules [est mise à disposition ici]({filename}/pages
Le client Cesium était historiquement livré avec Duniter. Avec l'arrivée des modules, ce choix d'installer Cesium est laissé à chacun. L'adresse du module Cesium est :
https://github.com/duniter/duniter-ui-cesium/archive/1.0.0.tar.gz
```
https://github.com/duniter/duniter-ui-cesium/archive/1.0.0.tar.gz
```
## Synchronisation
......
......@@ -26,17 +26,23 @@ Suivez ce tutoriel : [Installer son environnement Rust]({filename}../blockchain-
Installez nvm :
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/install.sh | bash
```bash
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/install.sh | bash
```
Puis installez la version de NodeJs que vous souhaitez utiliser :
nvm install VERSION
```bash
nvm install VERSION
```
## 3. Installez Neon
Installez l'utilitaire neon-cli, c'est indispensable :
npm install -g neon-cli
```bash
npm install -g neon-cli
```
## Votre Hello Word en Rust appelé par Node
......
......@@ -16,11 +16,15 @@ Aussi, la version *Duniter Server* dispose d'un mécanisme permettant d'analyser
Pour produire ce dump, déterminer l'identifiant de processus de Duniter :
ps aux | grep duniter
```bash
ps aux | grep duniter
```
Puis notez cet identifiant. Imaginons qu'il s'agisse du PID `12345`. Alors pour produire le heapdump, lancer la commande :
kill -USR2 12345
```bash
kill -USR2 12345
```
Un fichier nommé `heapdump-<id>.heapsnapshot` sera alors créé sur la machine, soit dans votre répertoire HOME, soit dans le répertoire depuis lequel Duniter a été lancé, soit encore à la racine `/` du système.
......
......@@ -27,14 +27,18 @@ Ce module permet :
Tout d'abord, procéder à la copie des sources et à la compilation :
git clone https://github.com/duniter/wotb.git && cd wotb
npm install --build-from-source
```bash
git clone https://github.com/duniter/wotb.git && cd wotb
npm install --build-from-source
```
#### En JavaScript
C'est le plus haut niveau, le plus complet. Ce niveau englobe tous les appels que fera finalement Duniter à ce module.
npm test
```bash
npm test
```
#### En C++
......@@ -66,7 +70,9 @@ Pour publier une nouvelle version, quelques étapes sont à respecter.
La commande qu'il devra lancer sur le code à jour est :
npm publish
```bash
npm publish
```
#### Publier le binaire pré-compilé pour Windows ou ARM
......@@ -76,23 +82,33 @@ Cette étape est nécessaire pour le build Windows ou ARM de Duniter.
Sélectionner la version de NodeJS pour laquelle publier, par exemple avec NVM :
nvm use 10
```bash
nvm use 10
```
Compiler les sources :
npm i --build-from-source
```bash
npm i --build-from-source
```
Vérifier que le résultat est conforme en lançant les tests :
npm test
```bash
npm test
```
Packager le binaire :
npm run package
```bash
npm run package
```
Publier le binaire :
npm run publish
```bash
npm run publish
```
## [naclb](https://github.com/duniter/naclb)
......@@ -108,14 +124,18 @@ Ce module diminue le contenu initial de la librairie NaCl, certaines parties n'a
Tout d'abord, procéder à la copie des sources et à la compilation :
git clone https://github.com/duniter/naclb.git && cd naclb
npm install --build-from-source
```bash
git clone https://github.com/duniter/naclb.git && cd naclb
npm install --build-from-source
```
#### En JavaScript
Le module ne se teste qu'en JavaScript, bien qu'il pût être aussi testé en C++.
npm test
```bash
npm test
```
### Publier
......
......@@ -45,15 +45,19 @@ Pour obtenir un tel jeton, rendez-vous à l'adresse [https://github.com/settings
Copiez alors le jeton généré, par exemple `b23ab3cbe624a8552545900d781a1779b928aa90`, puis enregistrez ce jeton :
echo -n 'b23ab3cbe624a8552545900d781a1779b928aa90' > ~/.config/duniter/.github
```bash
echo -n 'b23ab3cbe624a8552545900d781a1779b928aa90' > ~/.config/duniter/.github
```
## Procédure
### 1. Cloner Duniter et installer ses modules
git clone git@github.com:duniter/duniter.git
cd duniter
yarn
```bash
git clone git@github.com:duniter/duniter.git
cd duniter
yarn
```
### 2. Créer une nouvelle version
......@@ -64,15 +68,21 @@ Cette opération se réalise sur n'importe quel branche, selon le besoin :
Sélectionnez la branche :
git checkout master
```bash
git checkout master
```
Une fois positionné sur la bonne branche, lancez le script de changement de version. Par exemple pour passer en version `1.2.3` :
./release/new_version.sh 1.2.3
```bash
./release/new_version.sh 1.2.3
```
Poussez les modifications sur le dépôt :
git push origin master --tags
```bash
git push origin master --tags
```
A ce stade, le code source de Duniter est monté en version, et un nouveau tag a été ajouté au dépôt. GitHub est au courant, et reflète une entrée dans les releases à cette occasion. Toutefois la release n'existe pas encore.
......@@ -84,7 +94,9 @@ Cette fois, nous allons créer la release avec le status *pre-release*. Ce statu
Pour produire la pre-release et l'ensemble des livrables (hors ARM), toujours pour notre version d'exemple `1.2.3` :
./release/new_prerelease.sh 1.2.3
```bash
./release/new_prerelease.sh 1.2.3
```
Cette procédure **est longue** et se résume en 3 étapes :
......@@ -98,7 +110,9 @@ La 1ère étape est quasi-instantannée, mais la production et le téléversemen
Vous pouvez alors consulter les livrables [sur la page releases du dépôt GitHub](https://github.com/duniter/duniter/releases). Après avoir contrôlé que l'ensemble des fichiers sont bien présents, il est possible de valider la release via :
./release/set_release.sh 1.2.3 rel
```bash
./release/set_release.sh 1.2.3 rel
```
La *pre-release* passera alors en *release*, et les utilisateurs seront alertés du changement via Duniter UI (dont disposent Duniter Desktop ou Duniter Server démarré en `webstart`). La page d'accueil https://duniter.org/fr affichera également cette nouvelle version.
......
......@@ -24,13 +24,17 @@ La réalisation de ces livrables ainsi que leur mise à disposition est :
Produire les livrables de Duniter Desktop et Duniter Server pour Linux (hors ARM) s'effectue depuis le code source de Duniter à l'aide du script :
./release/new_version.sh 1.6.24
```bash
./release/new_version.sh 1.6.24
```
Remplacer `1.6.24` par la version à produire.
Puis pousser le tag sur le dépôt GitLab :
git push origin --tags
```bash
git push origin --tags
```
Dans les pipelines GitLab, une action manuelle de packaging sera disponible une fois les tests passés.
......@@ -59,14 +63,18 @@ Produire ce livrable requiert les conditions suivantes :
Après avoir installé `vagrant` (version 1.9.8), il sera nécessaire d'installer le plugin `winrm` :
vagrant plugin install winrm
vagrant plugin install winrm-fs
```bash
vagrant plugin install winrm
vagrant plugin install winrm-fs
```
#### Lancer le build
Le script pour réaliser le build Windows est :
./release/scripts/build.sh make win 1.6.24
```bash
./release/scripts/build.sh make win 1.6.24
```
Remplacer `1.6.24` par la version à produire.
......@@ -87,7 +87,9 @@ La difficulté personnalisée d'un membre résulte de l'assemblage de deux contr
Soient `powMin` la difficulté commune, `exFact` le facteur d'exclusion d'un membre et `handicap` son handicap. La difficulté personnalité `diff` de ce membre est :
diff = powMin*exFact + handicap
```
diff = powMin*exFact + handicap
```
#### Le facteur d'exclusion `exFact` d'un membre
......@@ -115,7 +117,9 @@ Nous avons dit que le facteur d'exclusion `exFact` augmente brutalement dès que
Soient `nbPreviousIssuers` la valeur du champ `issuersCount` du dernier bloc trouvé par le membre et `nbBlocksSince` le nombre de blocs trouvés par le reste du réseau depuis que le membre considéré a trouvé son dernier bloc.
exFact = MAX [ 1 ; FLOOR (0.67 * nbPreviousIssuers / (1 + nbBlocksSince)) ]
```
exFact = MAX [ 1 ; FLOOR (0.67 * nbPreviousIssuers / (1 + nbBlocksSince)) ]
```
La fonction FLOOR est une simple troncature, ainsi pour que `exFact` soit excluant il faut que le rapport `(0.67 * nbPreviousIssuers / (1 + nbBlocksSince))` soit supérieur ou égal à 2. On voit bien que si `nbBlocksSince` est supérieur au tiers des calculateurs = `0.33*nbPreviousIssuers` alors le rapport sera inférieur à 2 et donc le membre ne sera pas exclu du calcul du prochain bloc.
À l'inverse, si le membre considéré est l'auteur du dernier bloc alors `nbBlocksSince=0` et le facteur d'exclusion vaut donc `0.67 * nbPreviousIssuers`, c'est d'autant plus grand que le nombre de calculateurs est élevé. Je vous laisse imaginer la difficulté vertigineuse que vous atteindrez en trouvant un bloc s'il y a des centaines de membres calculant !
......@@ -133,7 +137,9 @@ Soient `nbPersonalBlocksInFrame` le nombre de blocs écrits par le membre consid
Voici la formule :
handicap = FLOOR(LN(MAX(1;(nbPersonalBlocksInFrame + 1) / medianOfBlocksInFrame)) / LN(1.189))
```
handicap = FLOOR(LN(MAX(1;(nbPersonalBlocksInFrame + 1) / medianOfBlocksInFrame)) / LN(1.189))
```
Démystifions cette formule, `(nbPersonalBlocksInFrame + 1) / medianOfBlocksInFrame)` est simplement le rapport entre le nombre de blocs calculés par le membre et la médiane. Par exemple si le membre a calculé `9` blocs dans la fenêtre courante alors que la médiane vaut `5`, ce rapport vaudra `(9+1)/5 = 2`.
On s'assure via la fonction MAX que ce rapport vaut au moins `1`.
......
......@@ -28,11 +28,15 @@ Il reste toutefois à installer quelques outils de compilation propres à votre
Sous Ubuntu :
sudo apt-get install build-essential
```bash
sudo apt-get install build-essential
```
Sous Debian :
sudo apt-get install build-essentials
```bash
sudo apt-get install build-essentials
```
Autre distribution : installer `gcc`, `g++`, `make` et `python2`.
......@@ -46,7 +50,9 @@ Rendez-vous à l'adresse : [https://www.microsoft.com/fr-fr/download/details.asp
Lancez un invité de commande **avec les droits administrateur** puis lancez la commande :
npm install --global --production windows-build-tools
```bash
npm install --global --production windows-build-tools
```
Cette commande peut durer 1h ou plus en fonction des composants déjà installés sur votre système.
......
......@@ -17,7 +17,9 @@ L'objectif de ce chapitre est de récupérer ce code afin de pouvoir l'exécuter
À l'aide d'un terminal (celui de votre système ou celui présent dans VSCode > Afficher > Terminal intégré), récupérez le code source de Duniter présent sur la branche de développement :
git clone https://github.com/duniter/duniter.git -b dev
```bash
git clone https://github.com/duniter/duniter.git -b dev
```
Comme vous pouvez le remarquer, nous utilisons ici la branche `dev`. En effet la branche `master` constitue plutôt la branche stable sur laquelle sont basées les versions de production du logiciel, tandis que la branche `dev` est utilisée pour les développements en cours.
......@@ -27,7 +29,9 @@ Comme vous pouvez le remarquer, nous utilisons ici la branche `dev`. En effet la
Duniter repose sur plusieurs bibliothèques de code tierces, ou *dépendances*. Pour que le code fonctionne il faut donc les installer :
yarn
```bash
yarn
```
> <span class="icon">![Attention !]({static}/images/icons/warning.png)</span> Attention pour les habitués de NodeJS : **ne remplacez pas `yarn` par `npm`**, car ce dernier ne permet pas d'avoir rigoureusement les mêmes versions des dépendances d'un poste à l'autre, or sans cette assurance nous ne pouvons pas garantir que le code fonctionnera comme attendu sur votre poste.
......@@ -35,13 +39,16 @@ Duniter repose sur plusieurs bibliothèques de code tierces, ou *dépendances*.
À ce stade, les tests automatisés devraient passer avec succès :
yarn test
```bash
yarn test
```
Patientez, les tests peuvent prendre jusqu'à 2-3 minutes. Finalement, vous obtenez :
687 passing (2m)
Done in 119.39s.
```bash
687 passing (2m)
Done in 119.39s.
```
Il se peut que quelques tests échouent en fonction des performances de votre machine, certains tests y étant sensibles. S'il n'y en a qu'une dizaine ou moins qui échouent, vous pouvez considérer que Duniter fonctionne sur votre machine et que le code source est correctement récupéré.
......
......@@ -22,7 +22,9 @@ Ensuite, nous expérimenterons le démarrage du nœud dans l'éditeur VSCode en
Pour initialiser votre nœud, il vous suffit de télécharger et d'appliquer la blockchain Ğ1 :
node bin/duniter sync g1.duniter.org 443
```bash
node bin/duniter sync g1.duniter.org 443
```
Nous initions ici le téléchargement de la blockchain depuis le nœud `g1.duniter.org`, mais en réalité le téléchargement se fera en P2P depuis l'ensemble du réseau Ğ1 afin d'optimiser la procédure. Indiquer le nœud `g1.duniter.org` permet juste de donner un point d'entrée sur le réseau, mais aussi d'indiquer que l'on souhaite la blockchain dont le bloc courant est celui de `g1.duniter.org`, ce qui permet d'identifier l'intégralité du reste de la blockchain.
......@@ -32,7 +34,9 @@ Nous initions ici le téléchargement de la blockchain depuis le nœud `g1.dunit
À ce stade, votre nœud devrait pouvoir se lancer et se connecter au réseau Ğ1 et agir en tant que miroir (nœud passif du réseau) :
node bin/duniter direct_start
```bash
node bin/duniter direct_start
```
Pour arrêter Duniter, terminez le processus (Ctrl+C).
......@@ -42,7 +46,9 @@ Vous avez désormais un nœud prêt à fonctionner, et que vous pouvez même mod
Le débogage nécessite une configuration de VSCode pour le projet. Afin de faciliter la prise en main initiale, un dossier « de base » a été initié, que vous pouvez copier pour votre utilisation :
cp -r doc/.vscode .vscode
```bash
cp -r doc/.vscode .vscode
```
À partir de là, à l'aide de la combinaison de touches Ctrl+Shift+D, vous pouvez sélectionne la configuration de débogage souhaitée :
......@@ -76,16 +82,20 @@ Une subtilité à retenir est que le code source est écrit en TypeScript, mais
La façon manuelle de le faire dans Duniter est avec yarn :
yarn tsc
yarn tsc v1.0.1
$ tsc
Done in 6.59s.
```bash
yarn tsc
yarn tsc v1.0.1
$ tsc
Done in 6.59s.
```
`tsc` est la commande « TypeScript Compiler », c'est notre transpilation. Quand la commande est terminée, `tsc` nous indique si l'opération s'est bien passée ou si des erreurs de transpilation sont apparues.
Toutefois cette opération est fastidieuse à la longue. Nous disposons d'une commande de « surveillance » des fichiers TypeScript et qui lance automatiquement la transpilation pour tout fichier `.ts` modifié :
yarn tscw
```bash
yarn tscw
```
Ce qui signifie « TypeScript Compiler Watch ». Dès lors, nous pouvons modifier n'importe quel fichier et la modification sera impactée à l'exécution.
......
......@@ -25,13 +25,15 @@ Nous ferons également le lien avec les fichiers concernés.
Commençons par l'exécution de Duniter, par exemple la commande :
node bin/duniter reset data
```bash
node bin/duniter reset data
```
Ici, nous exécutons Duniter en faisant appel à NodeJS (`node`) et demandons d'interpréter le fichier `bin/duniter` (un fichier JavaScript, sans extension) et passons les arguments `reset data` qui sont des chaînes de caractères.
Le fichier `bin/duniter` est le point de départ de toute commande Duniter. C'est l'unique fichier d'entrée pour tout appel au logiciel. Voyons ce qu'il se passe alors :
::uml:: format="svg" alt="Cycle d'execution de Duniter"
::uml:: format="svg" alt="Diagramme Cycle d'execution de Duniter"
@startuml
......@@ -91,13 +93,17 @@ Nous pouvons voir ici que tout appel à Duniter déclenche 3 procédures dans le
Dans notre exemple :
node bin/duniter reset data
```bash
node bin/duniter reset data
```
Le code finalement exécuté est celui de la commande `reset data` présent dans le fichier `app/modules/reset.ts`. Ce code est en charge de supprimer toutes les données du nœud, afin de le remettre à neuf par exemple.
Si l'on avait appelé une autre commande, comme :
node bin/duniter sync g1.duniter.org 443
```bash
node bin/duniter sync g1.duniter.org 443
```
Alors le code appelé aurait été celui de la commande de synchronisation présent dans le fichier `app/modules/crawler/index.ts`. On aurait pu penser qu'il s'agirait du fichier sync.ts, mais ici le module crawler gère plusieurs commandes dont celle qui permet la synchronisation au réseau : or il est possible de regrouper plusieurs commandes dans un même fichier, pourquoi pas nommé de façon générique `index.ts`.
......@@ -216,12 +222,14 @@ module.exports = {
Exécution de la commande :
bin/duniter nb-membres
Nombre de membres : 402
```bash
bin/duniter nb-membres
Nombre de membres : 402
```
Notez ici l'utilisation de `onDatabaseExecute:` : il s'agit d'une des deux phases possibles pour l'exécution d'une commande. L'autre est `onConfiguredExecute` :
::uml::
::uml:: format="svg" alt="Diagramme Moment d'execution d'un module"
@startuml
......@@ -284,8 +292,10 @@ module.exports = {
Exécution de la commande :
bin/duniter nb-membres --tres-certifies
Nombre de membres : 402
```bash
bin/duniter nb-membres --tres-certifies
Nombre de membres : 402
```
### Service
......@@ -352,16 +362,15 @@ class MyService extends stream.Readable {
Et l'on pourra alors constater si l'on lance `node bin/duniter direct_start` des messages de log toutes les 5 secondes (5000 millisecondes) :
Le service tourne ! (message#1)
Le service tourne ! (message#2)
Le service tourne ! (message#3)
...
<samp>Le service tourne ! (message#1)
Le service tourne ! (message#2)
Le service tourne ! (message#3)</samp>
## Fonctionnement général
Pour un nœud démarré par la commande `direct_start`, alors **tous les services de modules** fonctionnent de concert. Voici un petit aperçu :
::uml::
::uml:: format="svg" alt="Diagramme fonctionnement général"
@startuml
......@@ -392,7 +401,7 @@ Exemple de flux observables dans Duniter :
*Réception, traitement puis retransmission d'un document via BMA* :
::uml::
::uml:: format="svg" alt="Diagramme BMA"
@startuml
......@@ -405,7 +414,7 @@ serveur -> [BMA router] : retransmet
*Réception, traitement puis retransmission d'un document via WS2P* :
::uml::
::uml:: format="svg" alt="Diagramme réception, traitement puis retransmission d'un document via WS2P"
@startuml
......@@ -418,7 +427,7 @@ serveur -> [WS2P] : retransmet le bloc#2299
*Partage d'un signal de bloc empilé sur la blockchain* :
::uml::
::uml:: format="svg" alt="Diagramme Partage d'un signal de bloc"
@startuml
......@@ -432,7 +441,7 @@ Ce signal permet de notifier au module `prover` qu'un nouveau bloc a été ajout
*Partage d'un signal de déconnexion* :
::uml::
::uml:: format="svg" alt="Diagramme Partage d'un signal de déconnexion"
@startuml
......@@ -451,7 +460,9 @@ Il est à noter que seul `server` réalise de l'écho, ainsi le signal ne rebond
Et donc, quand on « démarre » Duniter, que se passe-t-il ?
node bin/duniter direct_start
```bash
node bin/duniter direct_start
```
Alors, Duniter passe par les phases décrites plus tôt :
......
......@@ -20,12 +20,16 @@ Tout d'abord installez docker, pour cela suivez la documentation officielle :
Ensuite cloner le dépot Dunitrust puis placez vous a sa racine :
git clone https://git.duniter.org/nodes/rust/duniter-rs.git
cd duniter-rs
```bash
git clone https://git.duniter.org/nodes/rust/duniter-rs.git
cd duniter-rs
```
Enfin lancez l'image docker qui se chargera de compiler Dunistrust pour armv6 :
sudo docker run -it --rm -v $(pwd):/source dlecan/rust-crosscompiler-arm:stable
```bash
sudo docker run -it --rm -v $(pwd):/source dlecan/rust-crosscompiler-arm:stable
```
A noter que cette image docker permet de compiler n'importe quel programme rust, elle n'est pas spécifique a Duniter.
Vous pouvez retrouver les sources de cette image et le manuel expliquant les différentes options sur le dépot github : https://github.com/dlecan/rust-crosscompiler-arm
......@@ -38,29 +42,41 @@ C'est un "binaire tout en un" vous pouvez le copier n'importe ou sur votre raspb
Fonctionne sur ubuntu 16.04.
Vous devez avoir rust d'installé sur votre machine, si tel n'est pas le cas installez Rust en une seule ligne de commande :
curl https://sh.rustup.rs -sSf | sh
```bash
curl https://sh.rustup.rs -sSf | sh
```
Une fois que vous avez Rust, ajoutez la toolchain arm :
rustup target add armv7-unknown-linux-gnueabihf
```bash
rustup target add armv7-unknown-linux-gnueabihf
```
Installez les paquets debian suivants :
sudo apt-get install gcc-4.7-multilib-arm-linux-gnueabihf crossbuild-essential-armhf
```bash
sudo apt-get install gcc-4.7-multilib-arm-linux-gnueabihf crossbuild-essential-armhf
```
Indiquez a cargo quel compilateur il doit utiliser lorsqu'il compilera avec la toolchain arm, pour cela créez le fichier `~/.cargo/config` et collez y le contenu suivant :
[target.armv7-unknown-linux-gnueabihf]
linker = "arm-linux-gnueabihf-gcc-4.7"
```bash
[target.armv7-unknown-linux-gnueabihf]
linker = "arm-linux-gnueabihf-gcc-4.7"
```
Rendez vous a la racine du dépot de Dunistrust puis compilez avec la toolchain arm :
cd duniter-rs
cargo build --target=armv7-unknown-linux-gnueabihf --no-default-features --release
```bash
cd duniter-rs
cargo build --target=armv7-unknown-linux-gnueabihf --no-default-features --release
```
Si votre terminal vous dit que la commande `cargo` n'existe pas, c'est que vous devez ajouter le chemin `~/.cargo/bin` à votre variable d'environnement `PATH` :