README.md

# ngHyd - Angular application for Hydraulics using JaLHyd library

See also [developers documentation](DEVELOPERS.md) (in french)

## Build and deploy

### Requirements

 * [jalhyd](https://gitlab.irstea.fr/cassiopee/jalhyd)
 * npm
 * python3
 * pandoc ^2 (optional, for PDF documentation only)
 * texlive (optional, for PDF documentation only)
 
Building the HTML documentation requires MkDocs and some extensions:

```sh
sudo apt install python3-pip python3-setuptools
python3 -m pip install mkdocs python-markdown-math mkdocs-material
```
 
Building the PDF documentation requires pandoc and a LaTeX distribution (for ex. texlive) with a few packages:

```sh
sudo apt install pandoc texlive latexmk texlive-latex-extra texlive-bibtex-extra
```

### Install dependencies

#### JaLHyd
Clone JalHyd next to ngHyd, for ex. respectively in `/home/foo/jalhyd` and `/home/foo/nghyd`.

In `jalhyd` folder, run :

```sh
npm run package
```

#### other dependencies
Then in `nghyd` folder, run :

```sh
npm install
```


### Compile and get a deployable Web app

```sh
npm run build
```


### Compile and get a deployable Web app (without PDF doc)
Use this if you don't want to install LaTeX dependencies.
```sh
npm run build-no-pdf
```


### Compile in dev (watch) mode

```sh
npm start
```


### Run end-to-end unit tests

```sh
npm run e2e
```


### Quickly run end-to-end unit tests while watch mode is running

```sh
npm run e2equick
```


### Quickly try electron wrapping when code is already compiled

```sh
npm run electron
```


### Build a desktop release for Linux (from Linux platform)

#### build Debian package

```sh
npm run release-linux
```

Find the .deb package in `/release`.

Running `dpkg -i cassiopee_*.deb` will install Cassiopée in `/opt/Cassiopee`


### Build a desktop release for Windows (from Linux platform)

#### install dependencies
 * wine >= 2.0 - see https://wiki.winehq.org/Download#binary

#### build .exe installer

```sh
npm run release-windows
```

Find the generated installer in `/release`.

Running the generated installer will install Cassiopée in `C:\Users\YourUser\AppData\local\Programs\cassiopee`


### Build a desktop release for Windows (from Windows platform)

#### install dependencies
 * python for windows https://www.python.org/downloads/windows/
    * tick "add to path" option when installing
 * mkdocs: `pip install mkdocs`
 * mkdocs-material: `pip install mkdocs-material`
 * python-markdown-math: `pip install https://github.com/mitya57/python-markdown-math/archive/master.zip`
 * pygments: `pip install pygments`

#### build .exe installer

```sh
npm run release-windows
```

Find the generated installer in `/release`.

Running the generated installer will install Cassiopée in `C:\Users\YourUser\AppData\local\Programs\cassiopee`


### Build a desktop release for MacOS (from Linux platform)

#### build package

```sh
npm run release-mac
```

Find the generated package in `/release`.

Note: the generated package will not be signed.


### Build a mobile release for Android (from Linux platform)

#### install dependencies
 * java - `apt install openjdk-8-jdk` or `apt install oracle-java8-jdk`
 * gradle - `apt install gradle`

#### install Android Studio and SDKs

#### using GUI

Download Android Studio here and install it : https://developer.android.com/studio

Run Android Studio, click "configure > SDK manager". Install at least one SDK, for ex. 7.0 Nougat.

#### using CLI

Download Android SDK Tools from https://developer.android.com/studio : click "DOWNLOAD OPTIONS" then scroll down to "Command line tools only" and choose `sdk-tools-linux-*.zip`.

Download and unzip to, for example, `/opt/android/`.

Add `/opt/android/tools/bin` to your PATH.

Install an SDK, for example android 28 (Android 9 "Pie") :

```sh
sdkmanager "platform-tools" "platforms;android-28" "build-tools;28.0.3"
```

#### build .apk package

```sh
npm run release-android
```

Find the generated package in `/release`.

Note: the generated package will not be signed.

### Generate HTML documentation

```sh
npm run mkdocs
```


### Generate PDF documentation

```sh
npm run mkdocs2pdf
```


### Generate compodoc

```sh
npm run compodoc
```


### Flag suspicious language usage

```sh
npm run lint
```


### Generate UML diagram

The tsviz package can be used for drawing class diagram of the current code.

To install tsviz:
```sh
npm install -g tsviz
```

There's currently a bug on debian like distribution due to a wrong declaration of graphviz path in the code: https://github.com/joaompneves/tsviz/issues/5
As a workaround, you can create a link to the right path: `sudo ln -s /usr/bin/dot /usr/local/bin/dot` 

To draw the diagram:
```sh
npm run viz
```

## Caveats

### Deployment

Custom Material SVG Icons will only show up when the application is deployed on the domain root (no subfolders), see [this feature request](https://github.com/angular/material2/issues/4263)

### chromedriver version in e2e tests

It is possible that Chrome / Chromium version installed on your system evolves faster than the Chrome Selenium driver (`chromedriver`) installed by "protractor" dependency of Angular, which makes e2e tests fail with an error message about versions compatibility. In this case, it's possible to install an updated system-wide version of the pilot:
```bash
sudo npm install -g protractor
sudo webdriver-manager update
sudo find /usr/lib/node_modules/protractor -regextype sed -regex "^.*/chromedriver.*[0-9]$" -exec ln -s '{}' /usr/bin/chromedriver ';'
```

## Release policy

Use [semantic versioning](https://semver.org/).

Before releasing a new stable version, one should complete the following files
 - `CHANGELOG.md`
 - `package.json` (update "version")
 - `jalhyd_branch` (be sure that it contains "master" or is empty)

Every stable version should be tagged with both
 - the `stable` tag
 - a version tag of the form `X.Y.Z` (semver)

The `stable` tag should be set **before** the version tag, so that `git describe` returns `X.Y.Z` (latest tag).

Here are the steps to follow for an example **4.5.0** version
```sh
git tag -fa stable
git tag -fa 4.5.0
git push --tags --force
```