development_tutorial-01.md 12.3 KB
Newer Older
Benoit Lavenier's avatar
Benoit Lavenier committed
1 2 3 4 5 6 7 8 9 10 11 12
## Introduction

Cet article est un tutoriel d'initiation au code source du logiciel Cesium. Celui-ci vous permettra, à travers une succession d'étapes, d'accéder à la maîtrise des outils et méthodes utilisés quotidiennement par les développeurs de Cesium pour créer et modifier le logiciel.

A la fin de ce tutoriel, vous serez donc *capable de modifier le logiciel*. Et si le cœur vous en dit, vous pourrez même réaliser une modification et partager celle-ci avec le dépôt de code principal, afin que celle-ci soit officiellement intégrée et disponible aux utilisateurs !

A vos claviers !

## Niveau I : récupérer le code source

Ce premier niveau consiste à créer *votre propre version* des sources du logiciel et de récupérer cette copie sur votre ordinateur. Vous y produirez : 

13
* votre propre compte sur le [GitLab de Duniter](https://git.duniter.org)
Benoit Lavenier's avatar
Benoit Lavenier committed
14 15 16
* votre propre version du logiciel, votre *fork*
* une copie locale des fichiers de code source provenant de votre *fork*

17
### Créez un compte GitLab Duniter
Benoit Lavenier's avatar
Benoit Lavenier committed
18

19
> Si vous disposez déjà d'un compte GitLab, vous pouvez passer cette étape.
Benoit Lavenier's avatar
Benoit Lavenier committed
20

21
Rendez-vous sur [https://git.duniter.org](https://git.duniter.org/users/sign_in?redirect_to_referer=yes) (site en anglais).
Benoit Lavenier's avatar
Benoit Lavenier committed
22

23 24 25
Dans `Register` Renseigner les 3 champs proposés :

* Nom complet
Benoit Lavenier's avatar
Benoit Lavenier committed
26 27 28 29
* Nom d'utilisateur
* E-mail
* Mot de passe

30
Vous recevrez probablement un e-mail de confirmation qu'il vous faudra valider. Une fois cette étape passée, vous devriez disposer d'un compte sur le GitLab Duniter.
Benoit Lavenier's avatar
Benoit Lavenier committed
31 32 33

### Forkez le dépôt principal

34
Rendez-vous à l'adresse https://git.duniter.org/clients/cesium-grp/cesium.
Benoit Lavenier's avatar
Benoit Lavenier committed
35

36
Cliquez sur le bouton « Fourcher » (ou « Fork ») en haut de la page (sous le logo).
Benoit Lavenier's avatar
Benoit Lavenier committed
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52

### Installer Git

L'installation de Git dépend de votre système d'exploitation. Suivez simplement les indications présentes sur : https://git-scm.com/

### Cloner votre fork

A ce stade, vous êtes en mesure de récupérer votre version du code source (votre *fork*), afin de pouvoir travailler dessus.

#### Ouvrez Git en ligne de commande

Pour récupérer le code source, lancez Git en mode console.

* Sous Linux et MacOS, ouvrez tout simplement le Terminal
* Sous Windows lancez le programme *Git Bash* :

53
<img src="./img/6fc638dc0a22d88da7e84dbf0371e69747767f78.png" width="432" height="80">
Benoit Lavenier's avatar
Benoit Lavenier committed
54 55 56 57 58 59 60 61 62 63

#### Clonez votre fork, en ligne de commande

Retournez sur la page web GitHub, puis trouvez le bouton « Clone or download » : 
Cliquez dessus, vous pourrez alors copier l'URL de clonage en cliquant sur l'icône de valise.

Vous n'avez plus qu'à retourner dans votre console Git et saisir : 

    git clone <coller l'URL copiée>

64
ce qui donne **dans mon cas** : 
Benoit Lavenier's avatar
Benoit Lavenier committed
65 66

```
67
git clone git@git.duniter.org:blavenie/cesium.git
Benoit Lavenier's avatar
Benoit Lavenier committed
68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92
Cloning into 'cesium'...
 (...)
Checking connectivity... done.
```

Si vous êtes arrivés à un comportement similaire, **bravo**, vous posséder désormais le code source Cesium !
 
## Niveau II : Compilation et lancement dans un navigateur

Ce second niveau vise à obtenir les outils de base pour exécuter le code source, et vérifier son bon fonctionnement. Vous y réaliserez : 

* l'installation du moteur d'exécution JavaScript *Node.js*
* la vérification du bon fonctionnement du code source *via* le lancement de l'application, en mode web.

Si l'application se lance, vous aurez dores et déjà un environnement entièrement **fonctionnel** !

### Installer Node.js

#### Sous Linux / MacOS

Installer Node.js est devenu extrêmement simple pour ces OS : un outil vous permet d'installer la version de Node.js que vous souhaitez, en changer quand vous voulez et sans conflit avec une version précédente : il s'agit de [nvm](https://github.com/creationix/nvm).

Vous pouvez installer nvm avec la commande suivante :

```bash
93
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.6/install.sh | bash
Benoit Lavenier's avatar
Benoit Lavenier committed
94 95
```

96
Fermez puis rouvrez votre terminal, comme indiqué. Puis, installez Node.js (choisissez la version 6) : 
Benoit Lavenier's avatar
Benoit Lavenier committed
97 98

```bash
99
nvm install 6
Benoit Lavenier's avatar
Benoit Lavenier committed
100 101 102 103 104 105 106 107 108 109 110 111 112
```

Vous aurez alors la dernière version de la branche 5.x de Node.js prête à l'emploi.

##### Outils de compilation

Installer les outils nécessaires pour la compilation.
```bash
sudo apt-get install build-essential
```

#### Sous Windows

113
Pour Windows, téléchargez la version 6 disponible sur le site officiel de Node.js : https://nodejs.org
Benoit Lavenier's avatar
Benoit Lavenier committed
114 115 116 117 118

Puis lancez l'installeur ainsi téléchargé.

### Installer les modules Node.js de Cesium

119
Cesium repose sur des librairies tierce pour fonctionner appelées *dépendances*, comme par exemple des librairies de compilation (gulp, ionic, angularJS).
Benoit Lavenier's avatar
Benoit Lavenier committed
120 121 122 123 124 125 126 127 128 129

Le fait d'avoir cloné les sources n'est en réalité pas suffisant pour lancer l'application. Nous devons obtenir le code des dépendances pour obtenir ainsi l'ensemble du code exécutable du programme. Pour ce faire, retournez dans la console Git et déplacez-vous dans le répertoire cloné : 

```bash
cd cesium
```

Puis, lancez le téléchargement et l'installation des modules Cesium à l'aide de la commande : 

```bash
130
npm install -g yarn gulp cordova@10.0.0 @ionic/cli web-ext
Benoit Lavenier's avatar
Benoit Lavenier committed
131
```
Benoit Lavenier's avatar
Benoit Lavenier committed
132

Benoit Lavenier's avatar
Benoit Lavenier committed
133
Puis pour les dépendances non globales :
Benoit Lavenier's avatar
Benoit Lavenier committed
134

Benoit Lavenier's avatar
Benoit Lavenier committed
135
```bash
136
yarn
Benoit Lavenier's avatar
Benoit Lavenier committed
137 138 139 140 141 142 143
```

> Le processus d'installation peut prendre plusieurs minutes. En effet, il faut télécharger toutes les dépendances de Cesium et même en compiler certaines.

Si tout s'est bien passé, vous devriez obtenir une fin d'arborescence dans la console, et l'invité de commande devrait vous avoir rendu la main : 

```bash
144 145 146 147 148
yarn install v1.15.2
[1/4] Resolving packages...
  (...)
$ node -e "try { require('fs').symlinkSync(require('path').resolve('node_modules/@bower_components'), 'www/lib', 'junction') } catch (e) { }"
Done in 0.82s.
Benoit Lavenier's avatar
Benoit Lavenier committed
149 150 151 152
```

> Il se peut que vous obteniez des messages `npm WARN [...]`. Rien de grave : comme le nom du message l'indique, il s'agit simplement d'un avertissement non bloquant pour la suite des événements.

153
Puis installer les dépendences restantes (via bower) :
Benoit Lavenier's avatar
Benoit Lavenier committed
154

Benoit Lavenier's avatar
Benoit Lavenier committed
155
```bash
156
npm run postintall
Benoit Lavenier's avatar
Benoit Lavenier committed
157 158 159 160 161 162 163
```

### Installer un IDE

Pour développer sous NodeJS, vous pouvez utiliser l'IDE de votre choix :

 * Par exemple Sublime Text (non libre) : https://www.sublimetext.com/
164 165 166
 * Autres possibilités : 
    * VS Code (libre).
    * WebStorm (non libre mais fonctionnement très avancé).
Benoit Lavenier's avatar
Benoit Lavenier committed
167 168 169

### Installer Chrome et/ou Firefox

Benoit Lavenier's avatar
Benoit Lavenier committed
170
Pour débugger plus facilement le javascript Cesium, il est plus facile d'utiliser le navigateur Chrome
Benoit Lavenier's avatar
Benoit Lavenier committed
171 172 173 174 175 176 177 178 179 180

## Niveau III : maîtriser les commandes usuelles

Ce troisième niveau permet de découvrir les quelques (cinq) commandes que vous utiliserez tout le temps si vous développez Cesium. Vous y apprendrez : 

* à configurer Cesium, notamment le noeud Duniter qu'il utilisera (par défaut);
* à le lancer Cesium dans votre navigateur;

### Configurer Cesium

Benoit Lavenier's avatar
Benoit Lavenier committed
181
La configuration par défaut de notre environnement est visible dans le fichier `app/config.json`. Plusieurs profils y sont présents : `default`, `dev`, etc.
Benoit Lavenier's avatar
Benoit Lavenier committed
182

Benoit Lavenier's avatar
Benoit Lavenier committed
183
```json
Benoit Lavenier's avatar
Benoit Lavenier committed
184
{
Benoit Lavenier's avatar
Benoit Lavenier committed
185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202
   "default": {
       "cacheTimeMs": 60000,
       "fallbackLanguage": "en",
       "rememberMe": false,
       "showUDHistory": false,
       "timeout": 10000,
       "timeWarningExpireMembership": 5184000,
       "timeWarningExpire": 7776000,
       "useLocalStorage": true,
       "useRelative": true,
       "initPhase": false,
       "expertMode": false,
       "decimalCount": 4,
       "helptip": {
         "enable": true,
         "installDocUrl": "https://github.com/duniter/duniter/blob/master/doc/install-a-node.md"
       },
       "node": {
ArnaudCerisier's avatar
ArnaudCerisier committed
203 204
         "host": "g1.duniter.org",
         "port": "443"
Benoit Lavenier's avatar
Benoit Lavenier committed
205 206 207 208 209
       },
       "plugins":{
         "es": {
           "enable": true,
           "askEnable": false,
ArnaudCerisier's avatar
ArnaudCerisier committed
210 211
           "host": "g1.data.duniter.fr",
           "port": "443"
Benoit Lavenier's avatar
Benoit Lavenier committed
212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243
         }
       }
     },
     
     (...)
     "dev": {
         "cacheTimeMs": 60000,
         "fallbackLanguage": "fr-FR",
         "defaultLanguage": "fr-FR",
         "rememberMe": true,
         "showUDHistory": false,
         "timeout": 6000,
         "timeWarningExpireMembership": 5184000,
         "timeWarningExpire": 7776000,
         "useLocalStorage": true,
         "useRelative": true,
         "initPhase": false,
         "expertMode": false,
         "decimalCount": 2,
         "helptip": {
           "enable": true,
         },
         "node": {
           "host": "localhost",
           "port": "9600"
         },
         "plugins":{
           "es": {
             "enable": false
           }
         }
       },
Benoit Lavenier's avatar
Benoit Lavenier committed
244 245 246 247
}
```

Nous utiliserons la configuration "dev", pour utiliser votre noeud Duniter.
Benoit Lavenier's avatar
Benoit Lavenier committed
248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274

Modifiez les valeurs `host` et `port` du profil de configuration `dev`, afin qu'elles correspondent à votre noeud Duniter :

```json
  "dev: {
  ...
         "node": {
           "host": "localhost",
           "port": "9600"
         },
  ...
```

Désactivez le plugin "es" (utilisé pour Cesium+) :

```json
  "dev: {
  ...
         "plugins":{
           "es": {
             "enable": false
           }
         }
  ...
```

Pour activer cette configuration, lancez maintenant la commande :
Benoit Lavenier's avatar
Benoit Lavenier committed
275 276

```bash
Benoit Lavenier's avatar
Benoit Lavenier committed
277
 gulp config --env dev
Benoit Lavenier's avatar
Benoit Lavenier committed
278 279 280
```

```bash
281
[17:32:34] Using gulpfile (...)/cesium/gulpfile.js
Benoit Lavenier's avatar
Benoit Lavenier committed
282 283
[17:32:34] Starting 'config'...
[17:32:34] Building `www/js/config.js` for `dev` environment...
Benoit Lavenier's avatar
Benoit Lavenier committed
284
[17:32:36] Finished 'config' after 10 μs
Benoit Lavenier's avatar
Benoit Lavenier committed
285 286
```

Benoit Lavenier's avatar
Benoit Lavenier committed
287 288
> Cette commande sera à relancer à cachune de vos modifications du fichier `app/config`.

Benoit Lavenier's avatar
Benoit Lavenier committed
289 290 291 292
Cesium est maintenant configuré pour utiliser votre noeud Duniter local.

### Lancer Cesium (mode web)

Benoit Lavenier's avatar
Benoit Lavenier committed
293 294
Il ne vous reste plus qu'à lancer l'application (en mode web) pour savoir si tout s'est bien passé et que vous êtes prêts pour la suite.

Benoit Lavenier's avatar
Benoit Lavenier committed
295 296 297
Lancez la commande suivante : 

```bash
298
npm start
Benoit Lavenier's avatar
Benoit Lavenier committed
299 300
```

301 302
 > Alternative : `ionic serve`

Benoit Lavenier's avatar
Benoit Lavenier committed
303 304 305 306 307 308 309 310 311 312 313 314 315 316 317
Une fois terminée, la commande affiche : 

```bash
Running live reload server: http://localhost:35729
Watching: 0=www/**/*, 1=!www/lib/**/*
Running dev server:  http://localhost:8100
Ionic server commands, enter:
  restart or r to restart the client app from the root
  goto or g and a url to have the app navigate to the given url
  consolelogs or c to enable/disable console log output
  serverlogs or s to enable/disable server log output
  quit or q to shutdown the server and exit

ionic $ 
```
Benoit Lavenier's avatar
Benoit Lavenier committed
318 319 320 321 322

Vous pouvez ouvrir un navigateur web à l'adresse suivante : http://localhost:8100
Vous devriez y voir la page d'accueil de Cesium. 
 
Bravo, vous avez une installation de Cesium opérationnelle !
Benoit Lavenier's avatar
Benoit Lavenier committed
323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341

### Documentation

Cesium utilise le framework Ionic, qui a une bonne documentation : http://ionicframework.com.

Consulter ce site pour en savoir plus.

## Niveau IV : Se repérer dans le code 

### Répérer les couches logicielles

Ouvrir votre IDE, et ouvrir le projet Cesium.

Chercher et répérer dans le code : 

* les templates HTML qui porte les IHM : www/templates
* les controllers (JS)  : www/js/controllers
* les services (JS)  : www/js/services

342
<img src="./img/a5078db3abdf71c87f245e948ce94a181b0e0f37.png" width="690" height="369">
Benoit Lavenier's avatar
Benoit Lavenier committed
343 344


Benoit Lavenier's avatar
Benoit Lavenier committed
345 346 347 348
### Aller plus loin dans le code

Cesium s'appuie sur AngularJS. D'excellentes documentations sont présentes sur le web.

349
__Note :__ La version d'AngularJS utilisée est une 1.x. Les 2.x et supérieure changent complètement et impose une refonte complète... Cette refonte est prévue d'ici 2019, dans une version 2 de Cesium.
Benoit Lavenier's avatar
Benoit Lavenier committed
350 351 352 353 354

## Niveau V : Debuggage

### Sous Chrome

Benoit Lavenier's avatar
Benoit Lavenier committed
355
#### Ouvrir l'explorateur de sources
Benoit Lavenier's avatar
Benoit Lavenier committed
356

Benoit Lavenier's avatar
Benoit Lavenier committed
357
Ouvrez l'application dans Chrome à l'adresse http://localhost:8100
Benoit Lavenier's avatar
Benoit Lavenier committed
358

Benoit Lavenier's avatar
Benoit Lavenier committed
359 360 361 362 363 364 365
Ouvrez les outils de développement :
 * Menu `Option > Plus d'outils > Outils de développement`
 * ou par le raccourcis clavier : `Ctrl + Maj + i`

#### Débugger la certification d'un utilisateur

Ouvrez l'explorateur de source, puis cherchez le fichier `dist/dist_js/app/controllers/wot-controllers.js`.
Benoit Lavenier's avatar
Benoit Lavenier committed
366

Benoit Lavenier's avatar
Benoit Lavenier committed
367
Recherchez la méthode `$scope.certify()`, et placez y un point d'arrêt.
Benoit Lavenier's avatar
Benoit Lavenier committed
368

Benoit Lavenier's avatar
Benoit Lavenier committed
369 370
Naviguez dans l'application Cesium de la manière suivante : 

371
 * Cliquez dans le menu (à gauche) `Annuaire`;
Benoit Lavenier's avatar
Benoit Lavenier committed
372 373
 * Recherche un utilisateur, puis visualiser son identité;
 * Dans `Certification reçues`, cliquez sur le bouton `Certifier`;
Benoit Lavenier's avatar
Benoit Lavenier committed
374 375
 * Vérifier que la console s'arrête sur le point d'arrêt.

376
<img src="./img/eca671a6d24b8e11566cfcca11b65e6c9c9c370c.png" width="690" height="223">
Benoit Lavenier's avatar
Benoit Lavenier committed
377 378

Découvrez le code en déroulant l'action pas à pas.
Benoit Lavenier's avatar
Benoit Lavenier committed
379

Benoit Lavenier's avatar
Benoit Lavenier committed
380
> Utiliser les touches de `F9` à `F11`, pour rentrer dans une méthode (F11), avancer pas à pas (F10) ou jusqu'au prochain point d'arrêt (F9), etc.
Benoit Lavenier's avatar
Benoit Lavenier committed
381

382 383 384 385

## La Suite ?!

Vous pouvez maintenant poursuivre avec les niveaux qui suivent. Nous y verrons comment modifier un écran de Cesium.
Benoit Lavenier's avatar
Benoit Lavenier committed
386

387
[Voir la suite ici >>](./development_tutorial-02.md)