README.md 5.09 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
Mathias Chouet's avatar
Mathias Chouet committed
12
13
 
Building the documentation requires MkDocs and some extensions:
14
15

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

Mathias Chouet's avatar
Mathias Chouet committed
20
### Install dependencies
21

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

Mathias Chouet's avatar
Mathias Chouet committed
25
In `jalhyd` folder, run :
26

Mathias Chouet's avatar
Mathias Chouet committed
27
28
29
```sh
npm run package
```
30

Mathias Chouet's avatar
Mathias Chouet committed
31
32
#### other dependencies
Then in `nghyd` folder, run :
Grand Francois's avatar
Grand Francois committed
33

Mathias Chouet's avatar
Mathias Chouet committed
34
35
36
```sh
npm install
```
Grand Francois's avatar
Grand Francois committed
37

Mathias Chouet's avatar
Mathias Chouet committed
38
39
40
41
42
### Compile and get a deployable Web app

```sh
npm run build
```
Grand Francois's avatar
Grand Francois committed
43
44


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

Mathias Chouet's avatar
Mathias Chouet committed
47
48
49
```sh
npm start
```
Grand Francois's avatar
Grand Francois committed
50
51


Mathias Chouet's avatar
Mathias Chouet committed
52
### Run end-to-end unit tests
Grand Francois's avatar
Grand Francois committed
53

Mathias Chouet's avatar
Mathias Chouet committed
54
55
56
```sh
npm run e2e
```
Mathias Chouet's avatar
Mathias Chouet committed
57
58


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

Mathias Chouet's avatar
Mathias Chouet committed
61
62
63
```sh
npm run e2equick
```
Mathias Chouet's avatar
Mathias Chouet committed
64
65


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

Mathias Chouet's avatar
Mathias Chouet committed
68
69
70
```sh
npm run electron
```
Mathias Chouet's avatar
Mathias Chouet committed
71
72


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

Mathias Chouet's avatar
Mathias Chouet committed
75
#### build Debian package
Mathias Chouet's avatar
Mathias Chouet committed
76

Mathias Chouet's avatar
Mathias Chouet committed
77
78
79
```sh
npm run release-linux
```
Mathias Chouet's avatar
Mathias Chouet committed
80
81
82
83
84

Find the .deb package in `/release`.

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

85

Mathias Chouet's avatar
Mathias Chouet committed
86
### Build a desktop release for Windows (from Linux platform)
87
88
89
90
91
92

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

#### build .exe installer

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

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
102
### Build a desktop release for Windows (from Windows platform)
Mathias Chouet's avatar
Mathias Chouet committed
103
104
105

#### install dependencies
 * python for windows https://www.python.org/downloads/windows/
Mathias Chouet's avatar
Mathias Chouet committed
106
    * tick "add to path" option when installing
Mathias Chouet's avatar
Mathias Chouet committed
107
108
109
 * 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
110
 * pygments: `pip install pygments`
Mathias Chouet's avatar
Mathias Chouet committed
111
112
113

#### build .exe installer

Mathias Chouet's avatar
Mathias Chouet committed
114
115
116
```sh
npm run release-windows
```
Mathias Chouet's avatar
Mathias Chouet committed
117
118
119
120
121
122

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
123
### Build a desktop release for MacOS (from Linux platform)
124
125
126

#### build package

Mathias Chouet's avatar
Mathias Chouet committed
127
128
129
```sh
npm run release-mac
```
130
131
132
133
134
135

Find the generated package in `/release`.

Note: the generated package will not be signed.


Mathias Chouet's avatar
Mathias Chouet committed
136
### Build a mobile release for Android (from Linux platform)
Mathias Chouet's avatar
Mathias Chouet committed
137
138

#### install dependencies
Mathias Chouet's avatar
Mathias Chouet committed
139
140
 * java - `apt install openjdk-8-jdk` or `apt install oracle-java8-jdk`
 * gradle - `apt install gradle`
Mathias Chouet's avatar
Mathias Chouet committed
141
142
143

#### install Android Studio and SDKs

144
145
#### using GUI

Mathias Chouet's avatar
Mathias Chouet committed
146
Download Android Studio here and install it : https://developer.android.com/studio
147
148
149
150
151

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
152
153
154
155
156
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.
157
158

Install an SDK, for example android 28 (Android 9 "Pie") :
Mathias Chouet's avatar
Mathias Chouet committed
159
160
161
162

```sh
sdkmanager "platform-tools" "platforms;android-28" "build-tools;28.0.3"
```
Mathias Chouet's avatar
Mathias Chouet committed
163
164
165

#### build .apk package

Mathias Chouet's avatar
Mathias Chouet committed
166
167
168
```sh
npm run release-android
```
Mathias Chouet's avatar
Mathias Chouet committed
169
170
171

Find the generated package in `/release`.

172
173
Note: the generated package will not be signed.

Mathias Chouet's avatar
Mathias Chouet committed
174
### Generate HTML documentation
Mathias Chouet's avatar
Mathias Chouet committed
175

Mathias Chouet's avatar
Mathias Chouet committed
176
177
178
```sh
npm run mkdocs
```
179
180


Mathias Chouet's avatar
Mathias Chouet committed
181
### Create PDF documentation from HTML documentation
182

Mathias Chouet's avatar
Mathias Chouet committed
183
184
185
```sh
 sudo apt-get install texlive texlive-lang-french texlive-latex-extra pandoc
```
186

Mathias Chouet's avatar
Mathias Chouet committed
187
188
189
```sh
python3 mkdocs2pdf.py
```
190

Mathias Chouet's avatar
Mathias Chouet committed
191
### Generate compodoc
192

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

197

Mathias Chouet's avatar
Mathias Chouet committed
198
### Flag suspicious language usage
199

Mathias Chouet's avatar
Mathias Chouet committed
200
201
202
```sh
npm run lint
```
203

204

Mathias Chouet's avatar
Mathias Chouet committed
205
### Generate UML diagram
206

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

Mathias Chouet's avatar
Mathias Chouet committed
209
210
211
212
To install tsviz:
```sh
npm install -g tsviz
```
213

Mathias Chouet's avatar
Mathias Chouet committed
214
215
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` 
216

Mathias Chouet's avatar
Mathias Chouet committed
217
218
219
220
To draw the diagram:
```sh
npm run viz
```
221

Mathias Chouet's avatar
Mathias Chouet committed
222
## Caveats
Mathias Chouet's avatar
Mathias Chouet committed
223

Mathias Chouet's avatar
Mathias Chouet committed
224
### Deployment
225

Mathias Chouet's avatar
Mathias Chouet committed
226
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)
227

228

Mathias Chouet's avatar
Mathias Chouet committed
229
## Release policy
Mathias Chouet's avatar
Mathias Chouet committed
230
231
232
233

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

Before releasing a new stable version, one should complete the following files
Mathias Chouet's avatar
Mathias Chouet committed
234
235
236
 - `CHANGELOG.md`
 - `package.json` (update "version")
 - `jalhyd_branch` (be sure that it contains "master" or is empty)
Mathias Chouet's avatar
Mathias Chouet committed
237
238
239
240
241
242
243
244

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
Mathias Chouet's avatar
Mathias Chouet committed
245
246
247
248
249
```sh
git tag -fa stable
git tag -fa 4.5.0
git push --tags --force
```