README.md 8.04 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
### Requirements

9
10
11
12
Requirements for developping Cassiopee can be achieved by manually install the required dependencies on your computer or by using the dedicated docker container.

#### Required dependencies

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

Mathias Chouet's avatar
Mathias Chouet committed
19
Building the HTML documentation requires MkDocs and some extensions:
20
21

```sh
22
23
sudo apt install python3-pip python3-setuptools
python3 -m pip install mkdocs python-markdown-math mkdocs-material
24
```
25

Mathias Chouet's avatar
Mathias Chouet committed
26
27
28
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
29
sudo apt install pandoc texlive latexmk texlive-latex-extra texlive-bibtex-extra
Mathias Chouet's avatar
Mathias Chouet committed
30
```
31

32
33
34
35
36
37
#### Using docker container

Download and use the following docker image: https://hub.docker.com/repository/docker/geaucassiopee/ci-cd-cross-platform-webapp

More details on how to use it on vscode are available at https://gitlab.irstea.fr/cassiopee/cassiopee2-integration

Mathias Chouet's avatar
Mathias Chouet committed
38
### Install dependencies
39

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

Mathias Chouet's avatar
Mathias Chouet committed
43
In `jalhyd` folder, run :
44

Mathias Chouet's avatar
Mathias Chouet committed
45
46
47
```sh
npm run package
```
48

Mathias Chouet's avatar
Mathias Chouet committed
49
50
#### other dependencies
Then in `nghyd` folder, run :
Grand Francois's avatar
Grand Francois committed
51

Mathias Chouet's avatar
Mathias Chouet committed
52
```sh
53
npm ci --force --unsafe-perm
Mathias Chouet's avatar
Mathias Chouet committed
54
```
Grand Francois's avatar
Grand Francois committed
55

56
57
This installs the exact same version of dependencies as the ones specified in `package.lock.json`.
The parameter `--unsafe-perm` solves permissions issues for running e2e tests in a docker container.
Mathias Chouet's avatar
Mathias Chouet committed
58

Mathias Chouet's avatar
Mathias Chouet committed
59
60
61
62
63
### Compile and get a deployable Web app

```sh
npm run build
```
Grand Francois's avatar
Grand Francois committed
64
65


Mathias Chouet's avatar
Mathias Chouet committed
66
67
68
69
70
71
72
### 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
73
### Compile in dev (watch) mode
Grand Francois's avatar
Grand Francois committed
74

Mathias Chouet's avatar
Mathias Chouet committed
75
76
77
```sh
npm start
```
Grand Francois's avatar
Grand Francois committed
78
79


Mathias Chouet's avatar
Mathias Chouet committed
80
### Run end-to-end unit tests
Grand Francois's avatar
Grand Francois committed
81

Mathias Chouet's avatar
Mathias Chouet committed
82
83
84
```sh
npm run e2e
```
Mathias Chouet's avatar
Mathias Chouet committed
85
86


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

Mathias Chouet's avatar
Mathias Chouet committed
89
90
91
```sh
npm run e2equick
```
Mathias Chouet's avatar
Mathias Chouet committed
92
93


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

Mathias Chouet's avatar
Mathias Chouet committed
96
97
98
```sh
npm run electron
```
Mathias Chouet's avatar
Mathias Chouet committed
99
100


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

Mathias Chouet's avatar
Mathias Chouet committed
103
#### build Debian package
Mathias Chouet's avatar
Mathias Chouet committed
104

Mathias Chouet's avatar
Mathias Chouet committed
105
106
107
```sh
npm run release-linux
```
Mathias Chouet's avatar
Mathias Chouet committed
108
109
110
111
112

Find the .deb package in `/release`.

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

113

Mathias Chouet's avatar
Mathias Chouet committed
114
### Build a desktop release for Windows (from Linux platform)
115
116
117
118
119
120

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

#### build .exe installer

Mathias Chouet's avatar
Mathias Chouet committed
121
122
123
```sh
npm run release-windows
```
124
125
126
127
128
129

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
130
### Build a desktop release for Windows (from Windows platform)
Mathias Chouet's avatar
Mathias Chouet committed
131
132
133

#### install dependencies
 * python for windows https://www.python.org/downloads/windows/
Mathias Chouet's avatar
Mathias Chouet committed
134
    * tick "add to path" option when installing
Mathias Chouet's avatar
Mathias Chouet committed
135
136
137
 * 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
138
 * pygments: `pip install pygments`
Mathias Chouet's avatar
Mathias Chouet committed
139
140
141

#### build .exe installer

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

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
151
### Build a desktop release for MacOS (from Linux platform)
152
153
154

#### build package

Mathias Chouet's avatar
Mathias Chouet committed
155
156
157
```sh
npm run release-mac
```
158
159
160
161
162
163

Find the generated package in `/release`.

Note: the generated package will not be signed.


Mathias Chouet's avatar
Mathias Chouet committed
164
### Build a mobile release for Android (from Linux platform)
Mathias Chouet's avatar
Mathias Chouet committed
165
166

#### install dependencies
Mathias Chouet's avatar
Mathias Chouet committed
167
168
 * java - `apt install openjdk-8-jdk` or `apt install oracle-java8-jdk`
 * gradle - `apt install gradle`
Mathias Chouet's avatar
Mathias Chouet committed
169
170
171

#### install Android Studio and SDKs

172
173
#### using GUI

Mathias Chouet's avatar
Mathias Chouet committed
174
Download Android Studio here and install it : https://developer.android.com/studio
175
176
177
178
179

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
180
181
182
183
184
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.
185
186

Install an SDK, for example android 28 (Android 9 "Pie") :
Mathias Chouet's avatar
Mathias Chouet committed
187
188
189
190

```sh
sdkmanager "platform-tools" "platforms;android-28" "build-tools;28.0.3"
```
Mathias Chouet's avatar
Mathias Chouet committed
191
192
193

#### build .apk package

Mathias Chouet's avatar
Mathias Chouet committed
194
195
196
```sh
npm run release-android
```
Mathias Chouet's avatar
Mathias Chouet committed
197
198
199

Find the generated package in `/release`.

200
201
Note: the generated package will not be signed.

Mathias Chouet's avatar
Mathias Chouet committed
202
### Generate HTML documentation
Mathias Chouet's avatar
Mathias Chouet committed
203

Mathias Chouet's avatar
Mathias Chouet committed
204
205
206
```sh
npm run mkdocs
```
207
208


Mathias Chouet's avatar
Mathias Chouet committed
209
### Generate PDF documentation
210

Mathias Chouet's avatar
Mathias Chouet committed
211
```sh
Mathias Chouet's avatar
Mathias Chouet committed
212
npm run mkdocs2pdf
Mathias Chouet's avatar
Mathias Chouet committed
213
```
214

215

Mathias Chouet's avatar
Mathias Chouet committed
216
### Generate compodoc
217

Mathias Chouet's avatar
Mathias Chouet committed
218
219
220
```sh
npm run compodoc
```
221

222

Mathias Chouet's avatar
Mathias Chouet committed
223
### Flag suspicious language usage
224

Mathias Chouet's avatar
Mathias Chouet committed
225
226
227
```sh
npm run lint
```
228

229

Mathias Chouet's avatar
Mathias Chouet committed
230
### Generate UML diagram
231

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

Mathias Chouet's avatar
Mathias Chouet committed
234
235
236
237
To install tsviz:
```sh
npm install -g tsviz
```
238

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

Mathias Chouet's avatar
Mathias Chouet committed
242
243
244
245
To draw the diagram:
```sh
npm run viz
```
246

Mathias Chouet's avatar
Mathias Chouet committed
247
## Caveats
Mathias Chouet's avatar
Mathias Chouet committed
248

Mathias Chouet's avatar
Mathias Chouet committed
249
### Deployment
250

Mathias Chouet's avatar
Mathias Chouet committed
251
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)
252

253
254
255
256
257
258
259
260
### 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 ';'
```
261

Mathias Chouet's avatar
Mathias Chouet committed
262
## Release policy
Mathias Chouet's avatar
Mathias Chouet committed
263
264
265

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

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

Mathias Chouet's avatar
Mathias Chouet committed
268
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)
269

270
Then, one should complete the following files:
Mathias Chouet's avatar
Mathias Chouet committed
271
 - `CHANGELOG.md`
272
 - `package.json` (update "version", or use `npm version`)
Mathias Chouet's avatar
Mathias Chouet committed
273
 - `jalhyd_branch` (be sure that it contains "master" or is empty)
Mathias Chouet's avatar
Mathias Chouet committed
274
275
276
277
278

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

279
280
281
282
283
284
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.

285
286
287
288
Before running the script:
 * update `CHANGELOG.md` in both JaLHyd and NgHyd
 * set the content of `jalhyd_branch` to "master"

289
290
This script:
 * checks out "master" branch of JaLHyd, pulls the latest changes, installs dependencies, runs unit tests, commits changes if any
291
 * updates JaLHyd version in `package.json`, commits changes
292
293
 * 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
294
 * updates NgHyd version in `package.json`, commits changes
295
296
297
298
299
300
301
 * 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
302

Mathias Chouet's avatar
Mathias Chouet committed
303
```sh
304
305
./scripts/deploy-new-stable-version.sh 4.10.4
```