README.md 7.37 KB
Newer Older
Mathias Chouet's avatar
Mathias Chouet committed
1
# ngHyd - Angular application for Hydraulics using JaLHyd library
Grand Francois's avatar
Grand Francois committed
2

Mathias Chouet's avatar
Mathias Chouet committed
3
See also [developers documentation](DEVELOPERS.md) (in french)
Grand Francois's avatar
Grand Francois committed
4

Mathias Chouet's avatar
Mathias Chouet committed
5
## Build and deploy
Grand Francois's avatar
Grand Francois committed
6

Mathias Chouet's avatar
Mathias Chouet committed
7
8
9
### Requirements

 * [jalhyd](https://gitlab.irstea.fr/cassiopee/jalhyd)
Mathias Chouet's avatar
Mathias Chouet committed
10
11
 * npm
 * python3
12
 * pandoc ^2 (optional, for PDF documentation only)
Mathias Chouet's avatar
Mathias Chouet committed
13
 * texlive (optional, for PDF documentation only)
14

Mathias Chouet's avatar
Mathias Chouet committed
15
Building the HTML documentation requires MkDocs and some extensions:
16
17

```sh
18
19
sudo apt install python3-pip python3-setuptools
python3 -m pip install mkdocs python-markdown-math mkdocs-material
20
```
21

Mathias Chouet's avatar
Mathias Chouet committed
22
23
24
Building the PDF documentation requires pandoc and a LaTeX distribution (for ex. texlive) with a few packages:

```sh
Mathias Chouet's avatar
Mathias Chouet committed
25
sudo apt install pandoc texlive latexmk texlive-latex-extra texlive-bibtex-extra
Mathias Chouet's avatar
Mathias Chouet committed
26
```
27

Mathias Chouet's avatar
Mathias Chouet committed
28
### Install dependencies
29

Mathias Chouet's avatar
Mathias Chouet committed
30
31
#### JaLHyd
Clone JalHyd next to ngHyd, for ex. respectively in `/home/foo/jalhyd` and `/home/foo/nghyd`.
32

Mathias Chouet's avatar
Mathias Chouet committed
33
In `jalhyd` folder, run :
34

Mathias Chouet's avatar
Mathias Chouet committed
35
36
37
```sh
npm run package
```
38

Mathias Chouet's avatar
Mathias Chouet committed
39
40
#### other dependencies
Then in `nghyd` folder, run :
Grand Francois's avatar
Grand Francois committed
41

Mathias Chouet's avatar
Mathias Chouet committed
42
43
44
```sh
npm install
```
Grand Francois's avatar
Grand Francois committed
45

Mathias Chouet's avatar
Mathias Chouet committed
46

Mathias Chouet's avatar
Mathias Chouet committed
47
48
49
50
51
### Compile and get a deployable Web app

```sh
npm run build
```
Grand Francois's avatar
Grand Francois committed
52
53


Mathias Chouet's avatar
Mathias Chouet committed
54
55
56
57
58
59
60
### 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
```


Mathias Chouet's avatar
Mathias Chouet committed
61
### Compile in dev (watch) mode
Grand Francois's avatar
Grand Francois committed
62

Mathias Chouet's avatar
Mathias Chouet committed
63
64
65
```sh
npm start
```
Grand Francois's avatar
Grand Francois committed
66
67


Mathias Chouet's avatar
Mathias Chouet committed
68
### Run end-to-end unit tests
Grand Francois's avatar
Grand Francois committed
69

Mathias Chouet's avatar
Mathias Chouet committed
70
71
72
```sh
npm run e2e
```
Mathias Chouet's avatar
Mathias Chouet committed
73
74


Mathias Chouet's avatar
Mathias Chouet committed
75
### Quickly run end-to-end unit tests while watch mode is running
Mathias Chouet's avatar
Mathias Chouet committed
76

Mathias Chouet's avatar
Mathias Chouet committed
77
78
79
```sh
npm run e2equick
```
Mathias Chouet's avatar
Mathias Chouet committed
80
81


Mathias Chouet's avatar
Mathias Chouet committed
82
### Quickly try electron wrapping when code is already compiled
Mathias Chouet's avatar
Mathias Chouet committed
83

Mathias Chouet's avatar
Mathias Chouet committed
84
85
86
```sh
npm run electron
```
Mathias Chouet's avatar
Mathias Chouet committed
87
88


Mathias Chouet's avatar
Mathias Chouet committed
89
### Build a desktop release for Linux (from Linux platform)
Mathias Chouet's avatar
Mathias Chouet committed
90

Mathias Chouet's avatar
Mathias Chouet committed
91
#### build Debian package
Mathias Chouet's avatar
Mathias Chouet committed
92

Mathias Chouet's avatar
Mathias Chouet committed
93
94
95
```sh
npm run release-linux
```
Mathias Chouet's avatar
Mathias Chouet committed
96
97
98
99
100

Find the .deb package in `/release`.

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

101

Mathias Chouet's avatar
Mathias Chouet committed
102
### Build a desktop release for Windows (from Linux platform)
103
104
105
106
107
108

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

#### build .exe installer

Mathias Chouet's avatar
Mathias Chouet committed
109
110
111
```sh
npm run release-windows
```
112
113
114
115
116
117

Find the generated installer in `/release`.

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


Mathias Chouet's avatar
Mathias Chouet committed
118
### Build a desktop release for Windows (from Windows platform)
Mathias Chouet's avatar
Mathias Chouet committed
119
120
121

#### install dependencies
 * python for windows https://www.python.org/downloads/windows/
Mathias Chouet's avatar
Mathias Chouet committed
122
    * tick "add to path" option when installing
Mathias Chouet's avatar
Mathias Chouet committed
123
124
125
 * 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`
Mathias Chouet's avatar
Mathias Chouet committed
126
 * pygments: `pip install pygments`
Mathias Chouet's avatar
Mathias Chouet committed
127
128
129

#### build .exe installer

Mathias Chouet's avatar
Mathias Chouet committed
130
131
132
```sh
npm run release-windows
```
Mathias Chouet's avatar
Mathias Chouet committed
133
134
135
136
137
138

Find the generated installer in `/release`.

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


Mathias Chouet's avatar
Mathias Chouet committed
139
### Build a desktop release for MacOS (from Linux platform)
140
141
142

#### build package

Mathias Chouet's avatar
Mathias Chouet committed
143
144
145
```sh
npm run release-mac
```
146
147
148
149
150
151

Find the generated package in `/release`.

Note: the generated package will not be signed.


Mathias Chouet's avatar
Mathias Chouet committed
152
### Build a mobile release for Android (from Linux platform)
Mathias Chouet's avatar
Mathias Chouet committed
153
154

#### install dependencies
Mathias Chouet's avatar
Mathias Chouet committed
155
156
 * java - `apt install openjdk-8-jdk` or `apt install oracle-java8-jdk`
 * gradle - `apt install gradle`
Mathias Chouet's avatar
Mathias Chouet committed
157
158
159

#### install Android Studio and SDKs

160
161
#### using GUI

Mathias Chouet's avatar
Mathias Chouet committed
162
Download Android Studio here and install it : https://developer.android.com/studio
163
164
165
166
167

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

#### using CLI

Mathias Chouet's avatar
Mathias Chouet committed
168
169
170
171
172
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.
173
174

Install an SDK, for example android 28 (Android 9 "Pie") :
Mathias Chouet's avatar
Mathias Chouet committed
175
176
177
178

```sh
sdkmanager "platform-tools" "platforms;android-28" "build-tools;28.0.3"
```
Mathias Chouet's avatar
Mathias Chouet committed
179
180
181

#### build .apk package

Mathias Chouet's avatar
Mathias Chouet committed
182
183
184
```sh
npm run release-android
```
Mathias Chouet's avatar
Mathias Chouet committed
185
186
187

Find the generated package in `/release`.

188
189
Note: the generated package will not be signed.

Mathias Chouet's avatar
Mathias Chouet committed
190
### Generate HTML documentation
Mathias Chouet's avatar
Mathias Chouet committed
191

Mathias Chouet's avatar
Mathias Chouet committed
192
193
194
```sh
npm run mkdocs
```
195
196


Mathias Chouet's avatar
Mathias Chouet committed
197
### Generate PDF documentation
198

Mathias Chouet's avatar
Mathias Chouet committed
199
```sh
Mathias Chouet's avatar
Mathias Chouet committed
200
npm run mkdocs2pdf
Mathias Chouet's avatar
Mathias Chouet committed
201
```
202

203

Mathias Chouet's avatar
Mathias Chouet committed
204
### Generate compodoc
205

Mathias Chouet's avatar
Mathias Chouet committed
206
207
208
```sh
npm run compodoc
```
209

210

Mathias Chouet's avatar
Mathias Chouet committed
211
### Flag suspicious language usage
212

Mathias Chouet's avatar
Mathias Chouet committed
213
214
215
```sh
npm run lint
```
216

217

Mathias Chouet's avatar
Mathias Chouet committed
218
### Generate UML diagram
219

Mathias Chouet's avatar
Mathias Chouet committed
220
The tsviz package can be used for drawing class diagram of the current code.
221

Mathias Chouet's avatar
Mathias Chouet committed
222
223
224
225
To install tsviz:
```sh
npm install -g tsviz
```
226

Mathias Chouet's avatar
Mathias Chouet committed
227
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
228
As a workaround, you can create a link to the right path: `sudo ln -s /usr/bin/dot /usr/local/bin/dot`
229

Mathias Chouet's avatar
Mathias Chouet committed
230
231
232
233
To draw the diagram:
```sh
npm run viz
```
234

Mathias Chouet's avatar
Mathias Chouet committed
235
## Caveats
Mathias Chouet's avatar
Mathias Chouet committed
236

Mathias Chouet's avatar
Mathias Chouet committed
237
### Deployment
238

Mathias Chouet's avatar
Mathias Chouet committed
239
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)
240

241
242
243
244
245
246
247
248
### 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 ';'
```
249

Mathias Chouet's avatar
Mathias Chouet committed
250
## Release policy
Mathias Chouet's avatar
Mathias Chouet committed
251
252
253

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

254
**It's discouraged to execute release steps manually, skip this section and see Release Script below**
255

Mathias Chouet's avatar
Mathias Chouet committed
256
Before releasing a new stable version, a new version of JaLHyd should be tagged, see "Release Policy" in [JaLHyd's README.md](https://gitlab.irstea.fr/cassiopee/jalhyd/blob/master/README.md)
257

258
Then, one should complete the following files:
Mathias Chouet's avatar
Mathias Chouet committed
259
 - `CHANGELOG.md`
260
 - `package.json` (update "version", or use `npm version`)
Mathias Chouet's avatar
Mathias Chouet committed
261
 - `jalhyd_branch` (be sure that it contains "master" or is empty)
Mathias Chouet's avatar
Mathias Chouet committed
262
263
264
265
266

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

267
268
269
270
271
272
The `stable` tag should be set **before** the version tag, so that `git describe` returns `X.Y.Z` (latest tag). There should be **at least 1s** between the two tag commands, so that date sorting is not confused.

### Release script

**Important:** the release script assumes that you run it from the current nghyd source directory `nghyd`, and that JaLHyd source directory `jalhyd` is present at the same level.

273
274
275
276
Before running the script:
 * update `CHANGELOG.md` in both JaLHyd and NgHyd
 * set the content of `jalhyd_branch` to "master"

277
278
This script:
 * checks out "master" branch of JaLHyd, pulls the latest changes, installs dependencies, runs unit tests, commits changes if any
279
 * updates JaLHyd version in `package.json`, commits changes
280
281
 * creates the right tags for JaLHyd and pushes them
 * checks out "master" branch of NgHyd, pulls the latest changes, installs dependencies, commits changes if any
282
 * updates NgHyd version in `package.json`, commits changes
283
284
285
286
287
288
289
 * creates the right tags for NgHyd and pushes them

It **does not** check that `jalhyd_branch` is OK nor that `jalhyd/CHANGELOG.md` and `nghyd/CHANGELOG.md` are up to date, but reminds you to do it.

Once tags are pushed, Gitlab CI/CD takes care of building and deploying the new packages.

Example for a **4.10.4** version :
Mathias Chouet's avatar
Mathias Chouet committed
290

Mathias Chouet's avatar
Mathias Chouet committed
291
```sh
292
293
./scripts/deploy-new-stable-version.sh 4.10.4
```