From 478070fd6c6d036ff91311dce16e89b6b19bbb16 Mon Sep 17 00:00:00 2001
From: Benoit Lavenier <benoit.lavenier@e-is.pro>
Date: Fri, 20 Mar 2020 15:27:24 +0100
Subject: [PATCH] [enh] Add documentation for build web-ext and web artifacts
---
doc/build_android.md | 4 +-
doc/build_desktop.md | 7 ++
doc/build_docker.md | 2 +
doc/build_ios.md | 2 +-
doc/build_web.md | 26 ++++++++
doc/build_web_extension.md | 51 ++++++++++++++
doc/development_guide.md | 133 ++++++++++++++++++++++---------------
7 files changed, 169 insertions(+), 56 deletions(-)
create mode 100644 doc/build_desktop.md
create mode 100644 doc/build_web.md
create mode 100644 doc/build_web_extension.md
diff --git a/doc/build_android.md b/doc/build_android.md
index a091842f1..da93f2383 100644
--- a/doc/build_android.md
+++ b/doc/build_android.md
@@ -1,6 +1,6 @@
-# Android Builds
+# Build Cesium for Android
-Cesium can be build as Android App.
+Cesium can be build as an Android App.
Cesium use [Ionic Framework v1.7.16](http://ionicframework.com/docs/v1/) with some Apache Cordova plugins.
diff --git a/doc/build_desktop.md b/doc/build_desktop.md
new file mode 100644
index 000000000..19397982e
--- /dev/null
+++ b/doc/build_desktop.md
@@ -0,0 +1,7 @@
+# Build Cesium as a Desktop application
+
+Cesium can be build as a standalone desktop application, for Linux (`.deb`), Windows (`.exe`) or MacOSx;
+
+- Clone the [cesium-desktop](https://git.duniter.org/clients/cesium-grp/cesium-desktop) project locally;
+- Follow this project documentation.
+
diff --git a/doc/build_docker.md b/doc/build_docker.md
index 96d1359d4..3b2733a2f 100644
--- a/doc/build_docker.md
+++ b/doc/build_docker.md
@@ -1,5 +1,7 @@
# Cesium docker image
+> WARNING: This documentation need a review! (not up to date)
+
## Build
```bash
diff --git a/doc/build_ios.md b/doc/build_ios.md
index 1c8c56cc4..ddcaf2f84 100644
--- a/doc/build_ios.md
+++ b/doc/build_ios.md
@@ -1,4 +1,4 @@
-# iOS Builds
+# Build Cesium for iOS
Cesium can be build as desktop application for iOS. .
diff --git a/doc/build_web.md b/doc/build_web.md
new file mode 100644
index 000000000..a3b636018
--- /dev/null
+++ b/doc/build_web.md
@@ -0,0 +1,26 @@
+# Build Cesium as an unhosted web application
+
+Cesium can be build as a simple web application, portable and runnable anywhere.
+
+## 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`or `yarn run start`, and to test it.
+
+## Build the unhosted web application
+
+
+- To create a compressed ZIP artifact, run:
+ ```bash
+ cd cesium
+ gulp webBuild --release
+ ```
+
+ A ZIP archive will be visible `dist/web/build/cesium-vx.y.z.zip`
+
+## Publishing to a web site
+
+Uncompress the web archive, then open the `ìndex.html` file in your web browser.
\ No newline at end of file
diff --git a/doc/build_web_extension.md b/doc/build_web_extension.md
new file mode 100644
index 000000000..79b931698
--- /dev/null
+++ b/doc/build_web_extension.md
@@ -0,0 +1,51 @@
+# Build Cesium as a Web extension
+
+Cesium can be build as Web extension, for Mozilla Firefox extension (`.xpi`) and Chrome/Chromium (`.crx`).
+
+## 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`or `yarn run start`, and to test it.
+
+## Build the web extension
+
+
+- To create a uncompressed extension, use :
+ ```bash
+ cd cesium
+ gulp webExtensionCopyFiles --release
+ ```
+
+ The uncompressed web extension will be visible `dist/web/ext`
+
+- To create a portable and compressed ZIP extension :
+ ```bash
+ cd cesium
+ gulp webExtBuild --release
+ ```
+
+ The web extension is visible at `dist/web/build/cesium-vx.y.z-extension.zip`
+
+> Remove the option `--release` to skip creation of minified CSS and JS files (and source maps)
+
+## Publishing to Mozilla Addons
+
+- Make sure you have `web-ext` installed. If not, run:
+ ```bash
+ npm install -g web-ext
+ ```
+
+- Sign your extension :
+ ```bash
+
+ # Define your credentials on addons.mozilla.org (your developer account)
+ export AMO_JWT_ISSUER = // username
+ export AMO_JWT_SECRET = // password
+
+ # Will archive and upload your extension
+ cd cesium
+ web-ext sign "--api-key=${AMO_JWT_ISSUER}" "--api-secret=${AMO_JWT_SECRET}" "--source-dir=dist/web/ext" "--artifacts-dir=${PROJECT_DIR}/dist/web/build" --id=${WEB_EXT_ID} --channel=listed
+ ```
\ No newline at end of file
diff --git a/doc/development_guide.md b/doc/development_guide.md
index 2eb309058..a82e3c62d 100644
--- a/doc/development_guide.md
+++ b/doc/development_guide.md
@@ -4,76 +4,103 @@
To build Cesium, you will have to:
- - Installing build tools:
-```
- sudo apt-get install git wget curl unzip build-essential software-properties-common ruby ruby-dev ruby-ffi gcc make
-```
+1. Installing build tools:
+ ```bash
+ sudo apt-get install git wget curl unzip build-essential software-properties-common ruby ruby-dev ruby-ffi gcc make
+ ```
- - Installing [nvm](https://github.com/nvm-sh/nvm)
-```
- wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.1/install.sh | bash
-```
+2. Installing node.js v10 :
-If you are using fish shell, there is a [dedicated plugin](https://github.com/jorgebucaran/fish-nvm).
+ * First, install [nvm](https://github.com/nvm-sh/nvm) (Node Version Manager) :
+ ```bash
+ wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.1/install.sh | bash
+ ```
-> Then reload your terminal, for instance by executing the commande `bash`
+ > Alternatively, if you are using `fish shell`, there is a [dedicated plugin](https://github.com/jorgebucaran/fish-nvm).
- - Configure NodeJS to use a version 10: (**WARNING**: upper version will NOT work !)
-```
- nvm install 10
-```
+ * Then, reload your terminal (for instance by executing the command `bash`);
+
+ * Configure nvm to use the expected version: (**WARNING**: upper version will NOT work !)
+ ```bash
+ nvm install 10
+ ```
- - Installing node.js build tools, as global dependencies:
-```
- npm install -g yarn gulp cordova ionic
-```
+3. Installing node build tools, as global dependencies:
+ ```bash
+ npm install -g yarn gulp cordova ionic
+ ```
## 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
- yarn
-```
-
- - Installing Cordova plugins (need for platforms specific builds)
-```
- ionic cordova preapre
-```
+1. Getting the source code:
+ ```bash
+ git clone git@git.duniter.org:clients/cesium-grp/cesium.git
+ ```
+
+2. Install project dependencies:
+ ```bash
+ cd cesium
+ yarn install
+ ```
-- This should create a new directory `platforms/android`
+3. Installing Cordova plugins (required to build Android and iOS artifacts):
+ ```bash
+ ionic cordova preapre
+ ```
-> 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 v6: `nvm use 6` (please check using the command `node --version`)
+ This should create new directories `platforms/android` and `platforms/ios`.
+ > 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 v10: `nvm use 10` (please check using the command `node --version`)
+
-## Prepare environment, then compile and launch
+## Prepare Cesium default config
- - To configure your build environment :
+Configure Cesium default settings :
- * Add your environment config into `app/config.json`
+1. Add your environment config into `app/config.json`
- * Update default configuration, using the command:
-
-```
- gulp config --env <your_env_name>
-```
+2. Update default configuration, using the command:
+ ```bash
+ gulp config --env <your_env_name>
+ ```
-> This will update the configuration file used by cesium, at `www/js/config.json`.
+ This will update a configuration file `www/js/config.json`.
- - Compiling and running Cesium:
-```
- npm start
+## Compile and launch
+
+To compile and launch Cesium, run :
+```bash
+ yarn run start
```
-
-> or alternative: `yarn run start` or `ionic serve`
- - Open a web browser at address: [localhost:8100](http://localhost:8100). The application should be running.
-
-## Best practices for development
+or alternative: `npm start` or `ionic serve`
+
+The application should be running at [localhost:8100](http://localhost:8100)!
+
+
+## Build artifacts
+
+Cesium can be build:
+- [as an unhosted web applicationa](build_web.md);
+- [for Android](build_android.md);
+- [for iOS](build_ios.md);
+- [as a Web extension](build_web_extension.md) for Mozilla Firefox or Chrome/Chomium;
+- [as a Desktop application](build_desktop.md) for Linux (`.deb`), Windows and MacOSx;
+
+You may also [use Docker image](./build_docker.md) to simplify this task;
+
+
+## Time to code !
+
+### Pull request
+
+For each pull request, please create a issue first.
+
+### 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.
- 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).
+Read also [Angular performance for large applicatoins](https://www.airpair.com/angularjs/posts/angularjs-performance-large-applications).
--
GitLab