ngHyd - Angular application for Hydraulics using JaLHyd library
See also developers documentation (in french)
Build and deploy
Requirements
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
- jalhyd
- npm
- python3
- pandoc ^2 (optional, for PDF documentation only)
- texlive, texlive-bibtex-extra, texlive-latex-extra, latexmk (optional, for PDF documentation only)
Building the HTML documentation requires MkDocs and some extensions:
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:
sudo apt install pandoc texlive latexmk texlive-latex-extra texlive-bibtex-extra
Using docker container
Use the DockerFile provided at the root of this repository. This repository also
provide a .devcontainer
configuration for developing nghyd in vscode
(See https://code.visualstudio.com/docs/devcontainers/containers).
Install dependencies
JaLHyd
Clone JalHyd into to ngHyd, for ex. respectively in /home/foo/nghyd
and /home/foo/nghyd/jalhyd
.
In jalhyd
folder, run :
npm run package
other dependencies
Then in nghyd
folder, run :
npm ci --force --unsafe-perm
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.
Compile and get a deployable Web app
npm run build
Compile and get a deployable Web app (without PDF doc)
Use this if you don't want to install LaTeX dependencies.
npm run build-no-pdf
Compile in dev (watch) mode
npm start
Run end-to-end unit tests
npm run e2e
Quickly run end-to-end unit tests while watch mode is running
npm run e2equick
Quickly try electron wrapping when code is already compiled
npm run electron
Build a desktop release for Linux (from Linux platform)
build Debian package
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
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
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
npm run release-mac
Find the generated package in /release
.
Note: the generated package will not be signed.
Generate HTML documentation
npm run mkdocs
Generate PDF documentation
npm run mkdocs2pdf
Generate compodoc
npm run compodoc
Flag suspicious language usage
npm run lint
Generate UML diagram
The tsviz package can be used for drawing class diagram of the current code.
To install tsviz:
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:
npm run viz
CI/CD docker image
Gitlab CI/CD uses a docker image created with the DockerFile
located at the root
of this repository. This image needs to be pushed on the Gitlab registry in order to
be used by the CI/CD.
Requirements
You need to have Docker installed on your computer (See: https://docs.docker.com/get-docker/). On Windows, you first need to install a Linux distro under WSL2 (See https://learn.microsoft.com/en-us/windows/wsl/install).
Build and push container images to the Container Registry
This notice is inspired from https://docs.gitlab.com/ee/user/packages/container_registry/build_and_push_images.html.
You first need to create an access token (personal or project token):
Go to https://gitlab.irstea.fr/-/profile/personal_access_tokens
and create a token with a minimum scope write_registry
and read_registry
.
Open a terminal in the root folder of this repository on your local machine,
and type (with <token name>
and <token value>
the credentials
of the access token):
docker login registry.forgemia.inra.fr -u <token name> -p <token value>
docker build -t registry.forgemia.inra.fr/cassiopee/nghyd .
docker push registry.forgemia.inra.fr/cassiopee/nghyd
Deployment
Custom Material SVG Icons will only show up when the application is deployed on the domain root (no subfolders), see this feature request
chromedriver version in e2e tests
The chromedriver version used in e2e tests is determined by the Docker image dedicated to these tests. For further information, see Dockerfile of cassiopee2-integration project.
Release policy
Use semantic versioning.
It's discouraged to execute release steps manually, skip this section and see Release Script below
Before releasing a new stable version, a new version of JaLHyd should be tagged, see "Release Policy" in JaLHyd's README.md
Then, one should complete the following files:
CHANGELOG.md
-
package.json
(update "version", or usenpm 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). 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 under the nghyd
directory.
Before running the script:
- update
CHANGELOG.md
in both JaLHyd and NgHyd - set the content of
jalhyd_branch
to "master"
This script:
- checks out "master" branch of JaLHyd, pulls the latest changes, installs dependencies, runs unit tests, commits changes if any
- updates JaLHyd version in
package.json
, commits changes - 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
- updates NgHyd version in
package.json
, commits changes - 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 :
./scripts/deploy-new-stable-version.sh 4.10.4