README.md 5.08 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
10
11
12
### Requirements

 * [jalhyd](https://gitlab.irstea.fr/cassiopee/jalhyd)
 * nodejs
 
Building the documentation requires MkDocs and some extensions:
13
14

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

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

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

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

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

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

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

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

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


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

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


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

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


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

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


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

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


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

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

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

Find the .deb package in `/release`.

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

84

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

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

#### build .exe installer

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

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

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

#### build .exe installer

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

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

#### build package

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

Find the generated package in `/release`.

Note: the generated package will not be signed.


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

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

#### install Android Studio and SDKs

143
144
#### using GUI

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

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

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

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

#### build .apk package

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

Find the generated package in `/release`.

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

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

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


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

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

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

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

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

196

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

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

203

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

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

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

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

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

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

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

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

227

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

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
233
234
235
 - `CHANGELOG.md`
 - `package.json` (update "version")
 - `jalhyd_branch` (be sure that it contains "master" or is empty)
Mathias Chouet's avatar
Mathias Chouet committed
236
237
238
239
240
241
242
243

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
244
245
246
247
248
```sh
git tag -fa stable
git tag -fa 4.5.0
git push --tags --force
```