Skip to content
GitLab
Commit 69f40748 authored by Pierre-Antoine Rouby's avatar Pierre-Antoine Rouby
Browse files

doc: dev: Update wine runner environement creation and minor change.

parent a1cdb1ad
master adists_release terraz_dev v1.2.0rc2 v1.0.2
No related merge requests found
Pipeline #59555 passed with stages
in 4 minutes and 20 seconds
Hide whitespace changes
Inline Side-by-side
Showing
with 149 additions and 82 deletions
+149 -82
doc/dev/documentation.org
+ 126
− 77
View file @ 69f40748
......@@ -28,20 +28,6 @@
#+OPTIONS: toc:t
#+LANGUAGE: UKenglish
#+NAME: attr_wrap
#+HEADER: :var width="\\textwidth"
#+HEADER: :var caption=""
#+HEADER: :var smallcaption=""
#+HEADER: :var name=""
#+HEADER: :var data=""
#+HEADER: :var float="nil"
#+BEGIN_SRC sh :results output :exports none
echo "#+CAPTION[$smallcaption]: $caption"
echo "#+NAME: $name"
echo "#+ATTR_LATEX: :width $width :float $float"
echo "$data"
#+END_SRC
#+BEGIN_abstract
This document is for the use of developers. It describes the project
architecture, the tools available to assist development and
......@@ -54,13 +40,13 @@ documentation, translations or code.
* Introduction
Pamhyr2 is free and open source software (FOSS) graphical user
{{{pamhyr2}}} is free and open source software (FOSS) graphical user
interface (GUI) for 1D hydro-sedimentary modelling of rivers developed
in Python (with version 3.8). It use PyQt at version 5 and matplotlib
in version 3.4.1 or later for the user insterface (see
{{{file(/requirements.txt)}}} for details). The architecture of
project code follow the Qt Model/View architecture [fn:qt-arch] (see
details in section [[Architecture]]). Pamhyr2 packages can be build
details in section [[Architecture]]). {{{pamhyr2}}} packages can be build
manually (see section [[Building packages]]), but there are automatically
build with the gitlab-ci (see the section [[Setup the CI
environment]]). Documentation files are written with org-mode[fn:org],
......@@ -75,7 +61,7 @@ https://doc.qt.io/qt-5/model-view-programming.html (last access
* Architecture
Pamhyr2's architecture is based on Qt Model/View, see Figure
{{{pamhyr2}}}'s architecture is based on Qt Model/View, see Figure
[[graph-architecture]]. It is made up of several different components: the
model (in blue), the graphical components (in red), the
actions/delegates (in green), the commands (in purple), the solvers
......@@ -178,7 +164,7 @@ https://doc.qt.io/qt-5/model-view-programming.html
** Model
The model is a set of Python classes. In Pamhyr2, this classes must
The model is a set of Python classes. In {{{pamhyr2}}}, this classes must
respect some constraint. Each model class must inherits
=Model.Tools.SQLSubModel= abstract class, except the =Model.Study=
class who inherits =Model.Tools.SQLModel= (see [[SQL]]).
......@@ -456,12 +442,12 @@ of Bar (Listing [[sql-bar]] and [[sql-foo]]).
bar._sql_save(execute, data=data)
#+end_src
Let see the results database scheme for Pamhyr2 at version v0.0.7 in
Let see the results database scheme for {{{pamhyr2}}} at version v0.0.7 in
Figure [[sql_schema]].
#+NAME: sql_schema
#+ATTR_LATEX: :width 16cm
#+CAPTION: SQLite database scheme at Pamhyr2 version v0.0.7 (generate with [[https://gitlab.com/Screwtapello/sqlite-schema-diagram]])
#+CAPTION: SQLite database scheme at {{{pamhyr2}}} version v0.0.7 (generate with [[https://gitlab.com/Screwtapello/sqlite-schema-diagram]])
[[./images/schema_v0.0.7.png]]
......@@ -486,7 +472,7 @@ PamhyrModelList but use a dictionary instead of list.
** View
Pamhyr2 use Qt as graphical user interface library with the
{{{pamhyr2}}} use Qt as graphical user interface library with the
application "Qt designer" for windows or widget creation (see [[UI file]])
and "Qt linguist" for interface translate (see [[Translate]]). In
addition, we use matplotlib as ploting library (see [[Plot]]).
......@@ -501,11 +487,11 @@ componant translate, and possible other files or sub-directories.
*** UI file
We define as possible all Pamhyr2 windows and custom widgets with "Qt
designer". This application generate UI file who describes interface
organisation with table, layout, button, etc. This method is faster
than hand made windows and widget creation, and saves us some purely
descriptive code. The UI files are saved into =src/View/ui= for
We define as possible all {{{pamhyr2}}} windows and custom widgets
with "Qt designer". This application generate UI file who describes
interface organisation with table, layout, button, etc. This method is
faster than hand made windows and widget creation, and saves us some
purely descriptive code. The UI files are saved into =src/View/ui= for
window, and =/src/View/ui/Widgets= for custom widget.
*** Translate
......@@ -533,10 +519,11 @@ window, and =/src/View/ui/Widgets= for custom widget.
*** Window
The abstract class PamhyrWindow and PamhyrDialog are used for most of
Pamhyr2 window. These class allow to create an window for Pamhyr2 GUI
and implemente some useful methods. The super class method difine some
generic value from optional parameters, for examples:
The abstract class =PamhyrWindow= and =PamhyrDialog= are used for most
of {{{pamhyr2}}} window. These class allow to create an window for
{{{pamhyr2}}} GUI and implemente some useful methods. The super class
method difine some generic value from optional parameters, for
examples:
- =self._study=: The study giving in constructor parameters =study=
(typically a =Model.Study= class object)
- =self._config=: The configuration giving in constructor parameters
......@@ -546,7 +533,7 @@ generic value from optional parameters, for examples:
object)
#+NAME: window
#+CAPTION: Example of Pamhyr2 window
#+CAPTION: Example of {{{pamhyr2}}} window
#+begin_src python :python python3 :results output :noweb yes
from View.Tools.PamhyrWindow import PamhyrWindow
from View.My.Translate import MyTranslate
......@@ -593,7 +580,7 @@ window componants or connections.
*** Table
An abstract class PamhyrTableModel is available to define a simple
An abstract class =PamhyrTableModel= is available to define a simple
QAbstractTableModel shortly. In simple cases, there are only =data=
and =setData= methode to implement, but the constructor needs more
information than a classic QAbstractTableModel class.
......@@ -654,7 +641,7 @@ class AddNodeCommand(QUndoCommand):
All undo command must be push into a =QUndoStack= (see Listing
[[undo-cmd-push]]) to perform the action and allow user undo and redo this
action. In PamhyrWindow (and PamhyrDialog) the undo stack is
action. In =PamhyrWindow= (and =PamhyrDialog=) the undo stack is
automatically create if the option ="undo"= is activate at window
creation, this stack is accessible at =self._undo_stack=.
......@@ -672,7 +659,7 @@ creation, this stack is accessible at =self._undo_stack=.
*** Plot
To define a new plot you can create a class who inherit to
PamhyrPlot. The creator need at leaste five argument:
=PamhyrPlot=. The creator need at leaste five argument:
- A =canvas= of type =MplCanvas=
- A (optional) =trad= of type =PamhyrTranslate=
- A =data= used in =draw= and =update= to create and update the plot
......@@ -719,8 +706,8 @@ data has changed.
** Solver
The Pamhyr2 architecture allow to define multiple solver. A solver is
define by a:
The {{{pamhyr2}}} architecture allow to define multiple solver. A
solver is define by a:
- type
- name
- description,
......@@ -736,11 +723,11 @@ different solver type, this solver type implement the code for export
study to solver input format, and read the solver output to study
results. There exists a generic solver with a generic input and output
format, the type could be use to use a solver not implemented in
Pamhyr2, but this solver must can read/write input and output generic
format or use external script. There is possible to define different
solver with the same type, for example two differents version of the
same solver. Finaly, with input and output formater is possible to
execute a code on distant computer, for example, over ssh.
{{{pamhyr2}}}, but this solver must can read/write input and output
generic format or use external script. There is possible to define
different solver with the same type, for example two differents
version of the same solver. Finaly, with input and output formater is
possible to execute a code on distant computer, for example, over ssh.
#+name: graph-multi-solver
#+header: :results drawer
......@@ -857,8 +844,8 @@ solver and get results:
- (2.1) The solver read the input file(s)
- (2.2) The solver compute results and write it to solver output
file(s)
- (3) Pamhyr2 create a =Results= object
- (3.1) The Pamhyr2 solver class read solver output file(s) and
- (3) {{{pamhyr2}}} create a =Results= object
- (3.1) The {{{pamhyr2}}} solver class read solver output file(s) and
complete Results with readed data
#+name: graph-pipeline
......@@ -976,7 +963,7 @@ the temporal order of action is prensented in Figure
}
#+end_src
To implement a Solver in Pamhyr2, there exists a abstract class
To implement a Solver in {{{pamhyr2}}}, there exists a abstract class
=Solver.AbstractSolver=. A class who herits this class, must implement
different methods:
- =export=: Export the study to solver input file(s)
......@@ -987,7 +974,7 @@ different methods:
** Unit tests
A very small part of Pamhyr2 has unit test. This part is limited to the Model.
A very small part of {{{pamhyr2}}} has unit test. This part is limited to the Model.
#+begin_src shell
python3 -m venv test
......@@ -1000,9 +987,9 @@ A very small part of Pamhyr2 has unit test. This part is limited to the Model.
** The debug mode
To activate an deactivate the Pamhyr2 debug mode you can open the
configuration window and type "Ctrl+G" or run Pamhyr2 with command
line:
To activate an deactivate the {{{pamhyr2}}} debug mode you can open
the configuration window and type "Ctrl+G" or run {{{pamhyr2}}} with
command line:
#+begin_src shell
./Pamhyr2 debug
#+end_src
......@@ -1015,7 +1002,7 @@ data base file.
#+NAME: debug-repl
#+ATTR_LATEX: :width 14cm
#+CAPTION: Pamhyr2 debug Python REPL
#+CAPTION: {{{pamhyr2}}} debug Python REPL
[[./images/python-debug-repl.png]]
* Build the project
......@@ -1028,7 +1015,7 @@ to build packages manually.
If you need an hand made package, you can script available in
{{{file(packages)}}} directory.
*** GNU/Linux
*** GNU/Linux {{{linux}}}
On GNU/Linux building GNU/Linux packages is easy, you just need python
in version 3.8 must be installed with venv and pyinstaller packages
......@@ -1050,7 +1037,7 @@ cd packages
./linux.sh
#+end_src
*** Windows
*** Windows {{{windows}}}
To make the Windows packages you have two choice: If you use Windows
you can use the script {{{file(packages/windows.bat)}}}, other else
......@@ -1065,10 +1052,10 @@ winetricks installed.
** Setup the CI environment
Pamhyr2 need a Linux ci-runner and a Windows ci-runner for building
{{{pamhyr2}}} need a Linux ci-runner and a Windows ci-runner for building
package. The windows ci-runner could run on a Wine environement.
*** Linux
*** Linux {{{linux}}}
The Linux ci-runner need some software and dependencies in addtion of
gitlab-ci.
......@@ -1078,10 +1065,11 @@ gitlab-ci.
emacs emacs-goodies-el \
texlive-full \
python3.8 python3.8-venv
sudo python3 -m pip install pyinstaller
#+end_src
*** Windows (Wine)
*** Windows (Wine) {{{windows}}}
The ci-runner environment for Wine need at least wine version 8, let
[[https://www.numetopia.fr/comment-installer-wine-sur-ubuntu-ou-linux-mint/][see who to add wine official depot to your linux distribution]].
......@@ -1090,18 +1078,77 @@ The ci-runner environment for Wine need at least wine version 8, let
sudo apt install wine-stable winetricks
#+end_src
In addition, the environment need windows version of:
- [[https://www.python.org/ftp/python/3.8.10/python-3.8.10-amd64.exe][Python 3.8.10]]
- Git
- PowerShell
- Gitlab-ci
**** Setup environment
Export Wine environment variable to set wine as 64 bits architecture
and set the correct path for wine environment.
#+begin_src shell
export WINARCH=win64
export WINEPREFIX=$PWD/my-wine-runner-prefix
#+end_src
Setup Wine environment to Windows 10 and install the minimal fonts
with =winetricks=.
#+begin_src shell
winetricks corefonts win10
#+end_src
**** Install dependencies
First install 7zip with help of =winetricks=.
#+begin_src shell
winetricks 7zip
#+end_src
In addition, install in the environment the Windows version of:
- [[https://www.python.org/ftp/python/3.8.10/python-3.8.10-amd64.exe][Python 3.8.10]] (ensure the python path is set and Pip is enable)
- [[https://git-scm.com/downloads][Git]]
- [[https://github.com/PowerShell/PowerShell/releases/download/v7.0.1/PowerShell-7.0.1-win-x64.msi][PowerShell]]
- [[https://freefr.dl.sourceforge.net/project/nsis/NSIS%203/3.08/nsis-3.08-setup.exe][Nsis]]
To run a Windows executable into wine environement, use =wine64= command:
#+begin_src shell
wine64 <the-exe-file>
#+end_src
Now, we can install =pyinstaller= on this windows environment:
#+begin_src shell
wine python -m pip install pyinstaller
#+end_src
Now, we can download [[https://docs.gitlab.com/runner/install/windows.html][Gitlab-ci]] runner for Windows an put it in the
current path.
**** Setup runner
You can configure the runner with command:
#+begin_src shell
wine64 gitlab-runner-windows-amd64.exe register
#+end_src
**** Run the runner
Create a new executable shell script =runner.sh= with following lines:
#+begin_src shell
#! /bin/sh
export WINARCH=win64
export WINEPREFIX=$PWD/my-wine-runner-prefix
wine64 gitlab-runner-windows-amd64.exe run
#+end_src
Now you can run the runner with command =./runner.sh=.
{{{bulb}}} You can run this command into a =screen= terminal, detach
the terminal and disconnect from runner machine to keep runner alive.
* Documentation files
This document and the user documentation are org files. This text file
......@@ -1284,23 +1331,23 @@ Some org-mode configuration used in documentations files are define in
* How to contribute?
Pamhyr2 is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License[fn:license], either
version 3 of the License, or any later version.
{{{pamhyr2}}} is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License[fn:license],
either version 3 of the License, or any later version.
[fn:license] The GPLv3 web page:
https://www.gnu.org/licenses/gpl-3.0.en.html
** Guidelines
To contribute to Pamhyr2, we expect a minimum of respect between
To contribute to {{{pamhyr2}}}, we expect a minimum of respect between
contributors. We therefore ask you to respect the following rules
regarding communication and contribution content:
+ No gender, racial, religious or social discrimination
+ No insults, personal attacks or potentially offensive remarks
+ Pamhyr2 is free software, and intended to remain so, so take care
with the licensing of libraries and external content you want to add
to the project
+ {{{pamhyr2}}} is free software, and intended to remain so, so take
care with the licensing of libraries and external content you want
to add to the project
+ Humour or hidden easter eggs are welcome if they respect the
previous rules
......@@ -1311,11 +1358,12 @@ an issue on the project's gitlab page[fn:p2-gitlab], or you can create
a merge request on the same page with the changes you have made to the
code, translation or documentation.
The Pamhyr2 copyright is owned by INRAE[fn:inrae], but we keep a
record of each contributors. If you made a modification to pamhyr2
software, please add your name at the end of {{{file(AUTHORS)}}} file
and respect the Listing [[auth-format]] format. You can update this file
information for following contribution.
The {{{pamhyr2}}} copyright is owned by INRAE[fn:inrae], but we keep a
record of each contributors. If you made a modification to
{{{pamhyr2}}} software, please add your name at the end of
{{{file(AUTHORS)}}} file and respect the Listing [[auth-format]]
format. You can update this file information for following
contribution.
#+NAME: auth-format
#+CAPTION: =AUTHORS= file format
......@@ -1326,16 +1374,17 @@ information for following contribution.
#+CAPTION: Current =AUTHORS= file
#+INCLUDE: "../../AUTHORS" src text
[fn:p2-gitlab] The Pamhyr2 Gitlab project page:
[fn:p2-gitlab] The {{{pamhyr2}}} Gitlab project page:
https://gitlab.irstea.fr/theophile.terraz/pamhyr
[fn:inrae] The INRAE web site: https://www.inrae.fr/
** Translate
You can improve or add translation for the project. To contribute to
Pamhyr2 translate, you need to use Qt Linguist[fn:qt-linguist]. Open
Qt-linguist and edit the translation ({{{file(.ts)}}}) file, finally,
commit the new version of file and make a merge request.
{{{pamhyr2}}} translate, you need to use Qt
Linguist[fn:qt-linguist]. Open Qt-linguist and edit the translation
({{{file(.ts)}}}) file, finally, commit the new version of file and
make a merge request.
If you want add a new language, edit the script
{{{file(src/lang/create_ts.sh)}}} like Listing [[ts-it]]. Run the script
......@@ -1344,7 +1393,7 @@ and open the new file with Qt-linguist, setup target language (Figure
file and make a merge request.
#+NAME: ts-it
#+CAPTION: Example of modified {{{file(src/lang/create_ts.sh)}}} to add italian (it) translate for Pamhyr2
#+CAPTION: Example of modified {{{file(src/lang/create_ts.sh)}}} to add italian (it) translate for {{{pamhyr2}}}
#+begin_src shell
...
LANG="fr it"
......@@ -1362,7 +1411,7 @@ https://doc.qt.io/qt-5/qtlinguist-index.html (last access 2023-09-18)
** Code contribution
If you are developper you can improve and/or add features to
Pamhyr2. Please, follow the architecture described in section
{{{pamhyr2}}}. Please, follow the architecture described in section
[[Architecture]] as closely as possible. Keep the code simple, clear and
efficient as possible. The master branch is reserved for the project
maintainer; you can create a new branch or fork the project before the
......
doc/tools/PamhyrDoc.cls
+ 4
− 0
View file @ 69f40748
......@@ -163,3 +163,7 @@
\SetWatermarkScale{3}
\SetWatermarkFontSize{1cm}
\SetWatermarkText{Work in progress}
%% Icons
\usepackage{fontawesome5}
doc/tools/macro.org
+ 19
− 5
View file @ 69f40748
......@@ -17,11 +17,15 @@
# -*- coding: utf-8 -*-
# Constant name
#+MACRO: oldPamhyr PAMHyR
#+MACRO: Pamhyr Pamhyr2
#+MACRO: Mage Mage
#+MACRO: Rubarbe RubarBE
#+MACRO: Inrae INRAE
#+MACRO: pamhyr \textsc{PAMHyR}
#+MACRO: pamhyr2 \textsc{Pamhyr2}
#+MACRO: mage \textsc{Mage}
#+MACRO: mage7 \textsc{Mage7}
#+MACRO: mage8 \textsc{Mage8}
#+MACRO: rubarbe \textsc{RubarBE}
#+MACRO: adists \textsc{AdisTS}
#+MACRO: mascaret \textsc{Mascaret}
#+MACRO: inrae INRAE
#+MACRO: latex \LaTeX
# Information
......@@ -35,6 +39,16 @@
#+MACRO: cite [cite:$1]
#+MACRO: biblio \bibliography{documentation}
# Icons
#+MACRO: bulb \faIcon{lightbulb}
#+MACRO: OK \faIcon{check}
#+MACRO: linux \faIcon{linux}
#+MACRO: windows \faIcon{windows}
#+MACRO: python \faIcon{python}
#+MACRO: java \faIcon{java}
# Wrapper
#+NAME: attr_wrap
#+HEADER: :var width="\\textwidth"
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment