From 498c518f4579ee1a45737eea1ccff03ed0a8cc5c Mon Sep 17 00:00:00 2001
From: blavenie <benoit.lavenier@e-is.pro>
Date: Wed, 30 May 2018 09:37:28 +0200
Subject: [PATCH] Update documentation (move development guide from the
README.md to doc/development_guide.md)
---
.gitmodules | 3 +
README.md | 100 ++++--------------
doc/build_android.md | 47 +-------
doc/build_ubuntu.md | 8 ++
doc/deploy.md | 2 +-
doc/development_guide.md | 78 ++++++++++++++
doc/fr/development_tutorial-01.md | 39 ++++---
hooks/after_prepare/061_copy_build_extras.js | 44 +++++++-
package.json | 21 ++--
.../android/build/build-extras.gradle | 0
10 files changed, 186 insertions(+), 156 deletions(-)
create mode 100644 doc/development_guide.md
rename build-extras.gradle => resources/android/build/build-extras.gradle (100%)
diff --git a/.gitmodules b/.gitmodules
index d23f3b6f3..3eee4bcbd 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -1,3 +1,6 @@
[submodule "platforms/desktop"]
path = platforms/desktop
url = git@git.duniter.org:clients/cesium/cesium-desktop.git
+[submodule "platforms/android"]
+ path = platforms/android
+ url = git@git.duniter.org:clients/cesium-grp/cesium-android.git
diff --git a/README.md b/README.md
index b60aed748..94b3d59da 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@ Manage your wallet, certify your friends, and more !
## Installation
-### On desktop computer
+### On a desktop computer
To use Cesium from your desktop computer :
@@ -27,8 +27,14 @@ Manage your wallet, certify your friends, and more !
* Choose the web packaging (`cesium-vX.Y.Z-web.zip`);
* Unpack the archive into a empty folder;
* Open the file `index.html` in your web browser;
-
-### On web server
+
+### On a Yunohost installation
+
+There is a [package](https://github.com/duniter/cesium_ynh) for [YunoHost self-hosting distribution](https://yunohost.org).
+
+### On a web server
+
+#### Installation
Cesium can be easily installed on most web server :
@@ -36,30 +42,23 @@ Cesium can be easily installed on most web server :
- Unpack in a empty directory;
- Configure a virtual host, to use previous directory as root. Check the file `index.html` exist in the root directory.
-
For Linux distribution, a installation script could also be used to:
- Download the [latest release](https://github.com/duniter/cesium/releases/latest)
- Unpack archive into the directory `./cesium`. Existing files will be override.
```
-curl -kL https://raw.githubusercontent.com/duniter/cesium/master/install.sh | bash
+curl -kL https://git.duniter.org/clients/cesium-grp/cesium/raw/master/install.sh | bash
```
or:
```
-wget -qO- https://raw.githubusercontent.com/duniter/cesium/master/install.sh | bash
+wget -qO- https://git.duniter.org/clients/cesium-grp/cesium/raw/master/install.sh | bash
```
**Note**: You may need root permission to write files. If so just replace `| bash` with `| sudo bash`.
-
-#### Yunohost package
-
-There is a [package](https://github.com/duniter/cesium_ynh) for [YunoHost self-hosting distribution](https://yunohost.org).
-
-
#### Configuration
To change default configuration, on a web server installation:
@@ -108,77 +107,16 @@ angular.module("cesium.config", [])
To learn more about configuration options, see the [detailed documentation](doc/configuration.md).
-## License
-
-This software is distributed under [GNU GPLv3](https://raw.github.com/duniter/cesium/master/LICENSE).
-
-## Development Guide
-
-### Prerequisite
-
-To build Cesium, you will have to:
-
- - Installing build tools:
-```
- sudo apt-get install build-essential
-```
-
- - Installing [nvm](https://github.com/creationix/nvm)
-```
- wget -qO- https://raw.githubusercontent.com/creationix/nvm/v0.31.0/install.sh | bash
-```
+## Developement
-> Then reload your terminal, for instance by executing the commande `bash`
+Wants to compile Cesium ? or contribute ?
- - Configure NodeJS to use a version 8:
-```
- nvm install 5
-```
-
- - Installing node.js build tools:
-```
- npm install -g gulp bower@1.8.0 cordova@6.5.0 ionic@1.7.16
-```
-
-### Get the source code
-
- - Getting source and installing project dependencies:
-```
- git clone https://github.com/duniter/cesium.git
- cd cesium
- npm install
-```
-
- - Installing Cordova plugins (need for platforms specific builds)
-```
- ionic state restore
- ionic browser add crosswalk@12.41.296.5
-```
-
-
-### Prepare environment, then compile and launch
-
- - To configure your build environment :
-
- * Add your environment config into `app/config.json`
-
- * Update default configuration, using the command:
-
-```
- gulp config --env <your_env_name>
-```
-
-> This will update the configuration file used by cesium, at `www/js/config.json`.
-
- - Compiling and running Cesium:
-```
- npm start
-```
+A [Development Guide](doc/development_guide.md) is available to learn :
+ - How to install your development environment.
+ - Development best practices.
-> or alternative: `ionic serve`
+A [development tutorial](doc/fr/development_tutorial-01.md) (in French) is also available.
-### Best practices for development
+## License
- Cesium could be run on phone devices. Please read [performance tips on AgularJS + Ionic ](http://julienrenaux.fr/2015/08/24/ultimate-angularjs-and-ionic-performance-cheat-sheet/)
- before starting to contribute.
- Read also [Angular performance for large applicatoins](https://www.airpair.com/angularjs/posts/angularjs-performance-large-applications).
+This software is distributed under [GNU GPLv3](https://raw.github.com/duniter/cesium/master/LICENSE).
diff --git a/doc/build_android.md b/doc/build_android.md
index 681509ea7..6e6d5793d 100644
--- a/doc/build_android.md
+++ b/doc/build_android.md
@@ -6,27 +6,11 @@ Cesium use [Ionic Framework v1.7.16](http://ionicframework.com/docs/v1/) with so
## Prerequisites
-### Install build tools
+### Install the development environment
-```
-sudo apt-get install build-essential
-```
-
-### Install NodeJS 5
-
-Cesium need NodeJS v5. You can install it the [this download page](https://nodejs.org/download/release/v5.12.0/), but we recommand the use of MVN (Node Version Manager).
-MV? help you to manage many versions of NodeJS.
-
- - Install [MVN](https://github.com/creationix/nvm):
-```bash
-curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.31.1/install.sh | bash
-```
-
- - Open a new terminal (to reload environment), then install NodeJS 5 :
-```bash
-nvm install 5
-```
+Follow all the steps defined in the [Development guide](./development_guide.md).
+After that you should be able to start the application using `npm start`, and to test it.
### Install JDK (Java Development Kit)
@@ -89,31 +73,6 @@ Install the version that it proposes to you.
- Fill in the installation path of the NDK.
-## Get source and dependencies
-
-- Get Cesium sources:
-```bash
-git clone https://github.com/duniter/cesium.git
-cd cesium
-```
-
-- Install dependencies (global then project's dependencies):
-```bash
-npm install -g gulp bower@1.8.0 cordova@6.5.0 ionic@1.7.16
-npm install
-```
-
-- Install Cordova plugins:
-```
-ionic state restore
-```
-
-- This should create a new directory `platforms/android`
-
-> To remind: check that your command line is configured:
-> - You must place yourself in the directory of the application: `cd cesium`
-> - and be configured for NodeJs v5: `nvm use 5` (please chek using the command `node --version`)
-
## Android configuration
Android need some configuration, to be able to build Cesium.
diff --git a/doc/build_ubuntu.md b/doc/build_ubuntu.md
index 43a19d4ae..a2ee72468 100644
--- a/doc/build_ubuntu.md
+++ b/doc/build_ubuntu.md
@@ -2,6 +2,14 @@
Cesium can be build as desktop application for Ubuntu, or as App on Ubuntu phone. Such builds use cross-architecture [click targets](https://developer.ubuntu.com/en/phone/apps/sdk/tutorials/click-targets-and-device-kits/) and the specific Apache Cordova platform `ubuntu`.
+## Prerequisites
+
+### Install the development environment
+
+Follow all the steps defined in the [Development guide](./development_guide.md).
+
+After that you should be able to start the application using `npm start`, and to test it.
+
## Install Ubuntu SDK
Source documentation [here](https://developer.ubuntu.com/en/phone/platform/sdk/installing-the-sdk/) and [here](https://cordova.apache.org/docs/en/latest/guide/platforms/ubuntu/index.html)
diff --git a/doc/deploy.md b/doc/deploy.md
index c04c9e98c..e2827c334 100644
--- a/doc/deploy.md
+++ b/doc/deploy.md
@@ -34,7 +34,7 @@ cd $BASEDIR
echo "Installing cesium into '$BASEDIR/cesium'..."
-wget -qO- https://raw.githubusercontent.com/duniter/cesium/master/install.sh | bash
+wget -qO- https://git.duniter.org/clients/cesium-grp/cesium/raw/master/install.sh | bash
export VERSION=`sed -rn "s/\s*\"version\": \"([^\"]*)\",\s*/\1/p" cesium/config.js`
export BUILD=`sed -rn "s/\s*\"build\": \"([^\"]*)\",\s*/\1/p" cesium/config.js`
diff --git a/doc/development_guide.md b/doc/development_guide.md
new file mode 100644
index 000000000..097ecdb83
--- /dev/null
+++ b/doc/development_guide.md
@@ -0,0 +1,78 @@
+# Development Guide
+
+## Prerequisite
+
+To build Cesium, you will have to:
+
+ - Installing build tools:
+```
+ sudo apt-get install build-essential
+```
+
+ - Installing [nvm](https://github.com/creationix/nvm)
+```
+ wget -qO- https://raw.githubusercontent.com/creationix/nvm/v0.31.0/install.sh | bash
+```
+
+> Then reload your terminal, for instance by executing the commande `bash`
+
+ - Configure NodeJS to use a version 5: (**WARNING**: upper version will NOT work !)
+```
+ nvm install 5
+```
+
+ - Installing node.js build tools:
+```
+ npm install -g gulp bower@1.8.0 cordova@6.5.0 ionic@1.7.16
+```
+
+## Get the source code and dependencies
+
+ - Getting source and installing project dependencies:
+```
+ git clone git@git.duniter.org:clients/cesium-grp/cesium.git
+ cd cesium
+ npm install
+```
+
+ - Installing Cordova plugins (need for platforms specific builds)
+```
+ ionic state restore
+ ionic browser add crosswalk@12.41.296.5
+```
+
+- This should create a new directory `platforms/android`
+
+> To remind: check that your command line is configured:
+> - You must place yourself in the directory of the application: `cd cesium`
+> - and be configured for NodeJs v5: `nvm use 5` (please check using the command `node --version`)
+
+
+## Prepare environment, then compile and launch
+
+ - To configure your build environment :
+
+ * Add your environment config into `app/config.json`
+
+ * Update default configuration, using the command:
+
+```
+ gulp config --env <your_env_name>
+```
+
+> This will update the configuration file used by cesium, at `www/js/config.json`.
+
+ - Compiling and running Cesium:
+```
+ npm start
+```
+
+> or alternative: `ionic serve`
+
+ - Open a web browser at address: [localhost:8100](http://localhost:8100). The application should be running.
+
+## Best practices for development
+
+ Cesium could be run on phone devices. Please read [performance tips on AgularJS + Ionic ](http://julienrenaux.fr/2015/08/24/ultimate-angularjs-and-ionic-performance-cheat-sheet/)
+ before starting to contribute.
+ Read also [Angular performance for large applicatoins](https://www.airpair.com/angularjs/posts/angularjs-performance-large-applications).
diff --git a/doc/fr/development_tutorial-01.md b/doc/fr/development_tutorial-01.md
index 70aff26e1..cef797671 100644
--- a/doc/fr/development_tutorial-01.md
+++ b/doc/fr/development_tutorial-01.md
@@ -10,29 +10,30 @@ A vos claviers !
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 :
-* votre propre compte *GitHub*
+* votre propre compte sur le [GitLab de Duniter](https://git.duniter.org)
* votre propre version du logiciel, votre *fork*
* une copie locale des fichiers de code source provenant de votre *fork*
-### Créez un compte GitHub
+### Créez un compte GitLab Duniter
-> Si vous disposez déjà d'un compte GitHub, vous pouvez passer cette étape.
+> Si vous disposez déjà d'un compte GitLab, vous pouvez passer cette étape.
-Rendez-vous sur https://github.com (site en anglais). Renseigner les 3 champs proposés :
+Rendez-vous sur [https://git.duniter.org](https://git.duniter.org/users/sign_in?redirect_to_referer=yes) (site en anglais).
+Dans `Register` Renseigner les 3 champs proposés :
+
+* Nom complet
* Nom d'utilisateur
* E-mail
* Mot de passe
-<img src="./img/13ade346327b73bbf1acc97027af147eeb4e9089.png" width="346" height="325">
-
-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 GitHub .
+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.
### Forkez le dépôt principal
-Rendez-vous à l'adresse https://github.com/duniter/cesium. Cliquez sur le bouton « Fork » en dans le coin supérieur droit de la page :
+Rendez-vous à l'adresse https://git.duniter.org/clients/cesium-grp/cesium.
-<img src="./img/3b9228c664520496d6a7e86e3f9c4c438f111914.png" width="388" height="98">
+Cliquez sur le bouton « Fourcher » (ou « Fork ») en haut de la page (sous le logo).
### Installer Git
@@ -60,10 +61,10 @@ Vous n'avez plus qu'Ã retourner dans votre console Git et saisir :
git clone <coller l'URL copiée>
-ce qui donne dans mon cas :
+ce qui donne **dans mon cas** :
```
-git clone https://github.com/blavenie/cesium.git
+git clone git@git.duniter.org:blavenie/cesium.git
Cloning into 'cesium'...
(...)
Checking connectivity... done.
@@ -161,10 +162,10 @@ user1@~$
> 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.
-Puis installer les dépendences via bower :
+Puis installer les dépendences restantes (via bower) :
```bash
-bower install
+npm run postintall
```
### Installer un IDE
@@ -172,7 +173,9 @@ bower install
Pour développer sous NodeJS, vous pouvez utiliser l'IDE de votre choix :
* Par exemple Sublime Text (non libre) : https://www.sublimetext.com/
- * Autre possibilité : WebStorm (non libre mais fonctionnement très avancé).
+ * Autres possibilités :
+ * VS Code (libre).
+ * WebStorm (non libre mais fonctionnement très avancé).
### Installer Chrome et/ou Firefox
@@ -287,7 +290,7 @@ Pour activer cette configuration, lancez maintenant la commande :
```
```bash
-[17:32:34] Using gulpfile ~/git/duniter/cesium/gulpfile.js
+[17:32:34] Using gulpfile (...)/cesium/gulpfile.js
[17:32:34] Starting 'config'...
[17:32:34] Building `www/js/config.js` for `dev` environment...
[17:32:36] Finished 'config' after 10 μs
@@ -304,9 +307,11 @@ Il ne vous reste plus qu'Ã lancer l'application (en mode web) pour savoir si to
Lancez la commande suivante :
```bash
-ionic serve
+npm start
```
+ > Alternative : `ionic serve`
+
Une fois terminée, la commande affiche :
```bash
@@ -353,7 +358,7 @@ Chercher et répérer dans le code :
Cesium s'appuie sur AngularJS. D'excellentes documentations sont présentes sur le web.
-__Note :__ La version d'AngularJS utilisée est une 1.x : la 2.x change complètement l'approche du code... La suite nous dira si Cesium passera à la version 2.
+__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.
## Niveau V : Debuggage
diff --git a/hooks/after_prepare/061_copy_build_extras.js b/hooks/after_prepare/061_copy_build_extras.js
index 66be5f3de..c47b71c36 100755
--- a/hooks/after_prepare/061_copy_build_extras.js
+++ b/hooks/after_prepare/061_copy_build_extras.js
@@ -1,6 +1,8 @@
#!/usr/bin/env node
"use strict";
var fs = require('fs');
+var glob = require('glob');
+var path = require('path')
// See: https://stackoverflow.com/questions/49162538/running-cordova-build-android-unable-to-find-attribute-androidfontvariation
@@ -15,8 +17,11 @@ if (rootdir) {
var platform = platforms[x].trim().toLowerCase();
if (platform == 'android') {
+ var build_dir = rootdir + '/resources/android/build';
var android_dir = rootdir + '/platforms/android';
- var gradle_file = rootdir + '/build-extras.gradle';
+
+ /*
+ var gradle_file = build_dir + '/build-extras.gradle';
var dest_gradle_file = android_dir + '/build-extras.gradle';
if (fs.existsSync(android_dir) && fs.existsSync(gradle_file)) {
@@ -29,7 +34,42 @@ if (rootdir) {
console.log( ' File ' + gradle_file + ' not found. Skipping copy to /platforms/android');
console.log('-----------------------------------------');
}
- }
+
+ var signing_file = build_dir + '/release-signing.properties';
+ var dest_signing_file = android_dir + '/release-signing.properties';
+
+ if (fs.existsSync(android_dir) && fs.existsSync(signing_file)) {
+ console.log('-----------------------------------------');
+ console.log(' Copy ' + signing_file + ' to ' + android_dir);
+ console.log('-----------------------------------------');
+ fs.createReadStream(signing_file).pipe(fs.createWriteStream(dest_signing_file));
+ } else {
+ console.log('-----------------------------------------');
+ console.log( ' File ' + signing_file + ' not found. Skipping copy to /platforms/android');
+ console.warn( ' WARNING: release APK files will not be signed ! ');
+ console.log('-----------------------------------------');
+ }*/
+
+ var build_files = build_dir + '/*.*';
+
+ if (fs.existsSync(android_dir) && fs.existsSync(build_dir)) {
+ glob(build_files, null, function(er, files) {
+ console.log('-----------------------------------------');
+
+ files.forEach(function(file) {
+ console.log(' Copy ' + file + ' to ' + android_dir);
+ var dest_file = android_dir + '/' + path.basename(file);
+ fs.createReadStream(file).pipe(fs.createWriteStream(dest_file));
+ });
+ console.log('-----------------------------------------');
+ });
+
+ } else {
+ console.log('-----------------------------------------');
+ console.log( ' Directory ' + build_dir + ' not found. Skipping copy to /platforms/android');
+ console.log('-----------------------------------------');
+ }
+ }
} catch (e) {
process.stdout.write(e);
}
diff --git a/package.json b/package.json
index cdd262f68..6d0f8faaa 100644
--- a/package.json
+++ b/package.json
@@ -27,7 +27,6 @@
"new": "https://git.duniter.org/clients/cesium/cesium/issues/new"
},
"dependencies": {
- "bower": "^1.8.0",
"cordova": "^6.5.0",
"cordova-android": "^6.2.3",
"cordova-plugin-camera": "^2.4.1",
@@ -45,6 +44,13 @@
"cordova-plugin-websocket": "^0.12.2",
"cordova-plugin-whitelist": "^1.3.2",
"cordova-plugin-x-toast": "^2.6.0",
+ "ionic-plugin-keyboard": "^2.2.1",
+ "phonegap-plugin-barcodescanner": "git+https://github.com/phonegap/phonegap-plugin-barcodescanner.git",
+ "moment": "~2.19.3",
+ "numeral": "1.5.3"
+ },
+ "devDependencies": {
+ "bower": "^1.8.0",
"delete-empty": "^0.1.3",
"gulp": "^3.9.1",
"gulp-bump": "^2.1.0",
@@ -52,17 +58,11 @@
"gulp-rename": "^1.2.0",
"gulp-sass": "^2.2.0",
"ionic": "^1.7.16",
- "ionic-plugin-keyboard": "^2.2.1",
"node-sass": "^3.3.3",
- "phonegap-plugin-barcodescanner": "git+https://github.com/phonegap/phonegap-plugin-barcodescanner.git",
- "moment": "~2.19.3",
- "numeral": "1.5.3"
- },
- "devDependencies": {
"cordova-uglify": "^0.2.3",
"del": "^2.2.0",
- "fs": "0.0.2",
- "gulp": "^3.9.1",
+ "fs": "^0.0.2",
+ "glob": "^5.0.15",
"gulp-angular-templatecache": "^1.8.0",
"gulp-angular-translate": "^0.1.4",
"gulp-base64": "^0.1.3",
@@ -117,8 +117,7 @@
"cordova-clipboard"
],
"cordovaPlatforms": [
- "android",
- "firefoxos"
+ "android"
],
"cordova": {
"plugins": {
diff --git a/build-extras.gradle b/resources/android/build/build-extras.gradle
similarity index 100%
rename from build-extras.gradle
rename to resources/android/build/build-extras.gradle
--
GitLab