Skip to content

Commit 8ae8e1b

Browse files
TlazypandaTlazypanda
authored
Merge pull request #20 from moja-global/add_flint.example_setup
add flint.example setup and format
2 parents 5d9b95f + 139d2f6 commit 8ae8e1b

6 files changed

Lines changed: 278 additions & 44 deletions

‎docs/DevelopmentSetup/FLINT.example_installation.rst‎

Lines changed: 24 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,39 @@
11
.. _DevelopmentSetup:
22

3-
FLINT.example: Docker Installation (for Linux Variants)
4-
#######################################################
3+
FLINT.example
4+
#############
55

6-
Docker file can be found in the Dockerfile
6+
The FLINT.example gives an example of how to build and run libraries using the FLINT framework. It is recommended to set up FLINT.example repository before setting up FLINT in order to get a better idea of how FLINT works.
77

8-
Builds fom the image mojaglobal/flint:bionic which can be found in docker hub
8+
The Docker file used here can be found in the ``Dockerfile`` file at the root of the repository.
9+
This Docker file builds from the image ``mojaglobal/flint:bionic`` which can be found in docker hub.
910

10-
Building the docker:
11-
--------------------
11+
There are 3 different environemnts listed in this document to build and run the examples:
1212

13-
::
13+
* **Windows - Visual Studio 2019**: develop, run and debug
14+
* **Visual Studio Code**: develop, run and debug
15+
* **Docker**: run only
1416

15-
# from repository root folder
16-
cd Docker
17-
docker build --build-arg NUM_CPU=8 -t moja/flint.example:bionic .
17+
We currently have four different sample runs:
1818

19-
Commands to run using docker - stock result written to screen and results files create (./Run_Env/*.csv):
20-
::
19+
* **Test Module sample** - Point level
20+
* **RothC sample** - Point level
21+
* **Chapman richards** - Point sample
22+
* **Chapman richards** - Spatial sample
2123

22-
# from repository root folder
23-
docker run --rm -v $(pwd)/Run_Env:/usr/local/run_env -ti moja/flint.example:bionic bash -c "cd /usr/local/run_env/; moja.cli --config config/point_example.json --config config/libs.base.simple.json --logging_config logging.debug_on.conf"
24-
docker run --rm -v $(pwd)/Run_Env:/usr/local/run_env -ti moja/flint.example:bionic bash -c "cd /usr/local/run_env/; moja.cli --config config/point_rothc_example.json --config config/libs.base_rothc.simple.json --logging_config logging.debug_on.conf"
24+
The FLINT.example repository is available `here <https://github.com/moja-global/FLINT.Example>`_ under the moja global organisation on GitHub. Before proceeding to the instuctions for installing FLINT.example, please follow the following steps to clone this repository on your fork:
2525

26-
Commands to run moja from within the docker - stock result written to screen and results files create (./Run_Env/*.csv):
2726
::
28-
docker run --rm -v $(pwd)/Run_Env:/usr/local/run_env -ti moja/flint.example:bionic bash
2927

30-
Then inside the running container:
31-
::
32-
cd /usr/local/run_env/
33-
moja.cli --config config/point_example.json --config config/libs.base.simple.json --logging_config logging.debug_on.conf
34-
moja.cli --config config/point_rothc_example.json --config config/libs.base_rothc.simple.json --logging_config logging.debug_on.conf
28+
git clone https://github.com/<your-username>/FLINT.example.git
3529

36-
Outputs
37-
-------
30+
For more instructions on our GitHub fork, clone and pull request practices, refer our `Git and GitHub Guide <git_and_github_guide.html>`_.
3831

39-
The runs above will create output files. While Stock values are output to the screen, there will also be some simplace CVS files created with both Stock and Flux values for the simulation.
40-
::
32+
Contents:
33+
34+
.. toctree::
35+
:maxdepth: 1
4136

42-
Example_Point_Flux.csv
43-
Example_Point_Stock.csv
44-
Example_Rothc_Point_Flux.csv
45-
Example_Rothc_Point_Stock.csv
37+
visual_studio_win_example
38+
visual_studio_example
39+
docker_installation_example

‎docs/DevelopmentSetup/docker_installation.rst‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,20 +5,20 @@ Docker Installation (for Linux Variants)
55

66
This section guides first-time contributors through installing FLINT development environment.
77

8-
Before proceeding further, make sure you have setup the project using Git by following our guide `here `.
8+
Before proceeding further, make sure you have setup the project using Git by following our `Git and GitHub Guide <git_and_github_guide.html>`_.
99
Also make sure you have the following prerequisites setup -
1010

11-
.. toctree::
12-
:maxdepth: 1
11+
Prerequisites
12+
-------------
1313

14-
../prerequisites/docker
14+
* `Docker <../prerequisites/docker.html>`_
1515

1616
Now that you have all the necessary prerequisites, you can proceed with the Installation.
1717

1818
Setup Docker Container
1919
----------------------
2020

21-
Containers are a simple way to build FLINT and all required dependencies. Before setting up please check out the FLINT.example repository first.
21+
Containers are a simple way to build FLINT and all required dependencies. Before setting up, it is recommended to install the `FLINT.example <FLINT.example_installation.html>`_ repository first.
2222

2323
Building the containers
2424
-----------------------
@@ -50,8 +50,8 @@ Once in, you should be able to run the CLI program moja.cli
5050

5151
That should respond with the following options:
5252

53-
Allowed options:
54-
----------------
53+
Allowed options
54+
---------------
5555

5656
::
5757

‎docs/DevelopmentSetup/docker_installation_example.rst‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
.. _DevelopmentSetup:
2+
3+
Environment: Docker
4+
###################
5+
6+
In the Docker environment option for setting up FLINT.example, only the run option is available.
7+
In case you want to develop or debug the repository code, please switch to the Visual Studio environments.
8+
9+
Prerequisites
10+
=============
11+
* `Docker <../prerequisites/docker.html>`_
12+
13+
Building the docker
14+
===================
15+
16+
::
17+
18+
# from repository root folder
19+
cd Docker
20+
docker build --build-arg NUM_CPU=8 -t moja/flint.example:bionic .
21+
22+
Commands to run using docker - stock result written to screen and results files create (./Run_Env/*.csv):
23+
::
24+
25+
# from repository root folder
26+
docker run --rm -v $(pwd)/Run_Env:/usr/local/run_env -ti moja/flint.example:bionic bash -c "cd /usr/local/run_env/; moja.cli --config config/point_example.json --config config/libs.base.simple.json --logging_config logging.debug_on.conf"
27+
docker run --rm -v $(pwd)/Run_Env:/usr/local/run_env -ti moja/flint.example:bionic bash -c "cd /usr/local/run_env/; moja.cli --config config/point_rothc_example.json --config config/libs.base_rothc.simple.json --logging_config logging.debug_on.conf"
28+
29+
Commands to run moja from within the docker - stock result written to screen and results files create (./Run_Env/*.csv):
30+
::
31+
32+
docker run --rm -v $(pwd)/Run_Env:/usr/local/run_env -ti moja/flint.example:bionic bash
33+
34+
Then inside the running container:
35+
::
36+
37+
cd /usr/local/run_env/
38+
moja.cli --config config/point_example.json --config config/libs.base.simple.json --logging_config logging.debug_on.conf
39+
moja.cli --config config/point_rothc_example.json --config config/libs.base_rothc.simple.json --logging_config logging.debug_on.conf
40+
41+
Outputs
42+
=======
43+
44+
The runs above will create output files. While Stock values are output to the screen, there will also be some simplace CVS files created with both Stock and Flux values for the simulation.
45+
::
46+
47+
Example_Point_Flux.csv
48+
Example_Point_Stock.csv
49+
Example_Rothc_Point_Flux.csv
50+
Example_Rothc_Point_Stock.csv

‎docs/DevelopmentSetup/visual_studio_example.rst‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
.. _DevelopmentSetup:
2+
3+
Environment: Visual Studio (Remote Containers)
4+
##############################################
5+
6+
In the Visual Studio environment using Remote Containers option for setting up FLINT.example, the options to run, develop and debug the repository code is available.
7+
Here remote containers are available in Visual Studio as an extension and can be installed with the help of the link mentioned in the prerequisites section.
8+
9+
Prerequisites
10+
-------------
11+
* `Visual Studio <../prerequisites/visual_studio.html>`_
12+
* `Remote - Container (VS Extension) <https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers>`_
13+
14+
Others extensions may be required, please follow instructions during VS Code startup. Extensions required during development will be installed in the container (listed below).
15+
16+
Building the Project
17+
--------------------
18+
19+
With these extensions installed, on startup, VS Code should ask if you want to open the project in a Container - OR you can press ``F1`` and select ``Remote-Containers: Open folder in Container...``
20+
21+
The VS Code project has some ``launch.json`` settings in place (in the ``.vscode`` folder), these can run both the base and rothc samples. It is possible to debug into the moja.flint libraries by loading on of the ``.cpp/.h`` files and setting a breakpoint - OR stepping into a method using the debugger
22+
23+
To build the project the cmake and C++ extensions will be required. These have been specified in the ``devcontainer.json`` file. To build the library use Cmake Configure, Build and Install.
24+
25+
::
26+
27+
28+
"extensions": [
29+
"ms-vscode.cpptools",
30+
"austin.code-gnu-global",
31+
"twxs.cmake",
32+
"ms-vscode.cmake-tools"
33+
]
34+
35+
Once the project opens the folder in the dev container, use the cmake commands to configure and build the project. Once this is done you should be ready to run/debug one of the samples.
36+
37+
**NOTE** : The libraries require a slightly different paths to work inside the dev-container, so there is a new version of the library configs for VS Code. These commands will work from the terminal in the running container after cmake has been successful.
38+
39+
::
40+
41+
42+
# start in the correct folder
43+
cd /workspaces/FLINT.example/Run_Env
44+
45+
# sample
46+
moja.cli --config config/point_example.json --config config/libs.base.vscode.json --logging_config logging.debug_on.conf
47+
48+
# rothc
49+
moja.cli --config config/point_rothc_example.json --config config/libs.base_rothc.vscode.json --logging_config logging.debug_on.conf
50+
51+
# Chapman Richards - forest point
52+
moja.cli --config config/point_forest_config.json --config config/libs.gdal.chaprich.vscode.json
53+
54+
# Chapman Richards - forest spatial
55+
moja.cli --config config/forest_config.json --config config/libs.gdal.chaprich.vscode.json --config_provider config/forest_provider.json

‎docs/DevelopmentSetup/visual_studio_win_example.rst‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
.. _DevelopmentSetup:
2+
3+
Environment: Visual Studio
4+
##########################
5+
6+
In the Visual Studio environment option for setting up FLINT.example, the options to run, develop and debug the repository code is available.
7+
Also make sure you have the following prerequisites setup -
8+
9+
Prerequisites
10+
-------------
11+
* `Cmake <../prerequisites/cmake.html>`_
12+
* `Visual Studio <../prerequisites/visual_studio.html>`_
13+
* `Docker <../prerequisites/docker.html>`_
14+
15+
Now that you have all the necessary prerequisites, you can proceed with the Installation.
16+
17+
Using vcpkg to install required libraries
18+
-----------------------------------------
19+
20+
Start a command shell in the Vcpkg repository folder (that you had cloned earlier) and use the following commands:
21+
22+
::
23+
24+
# bootstrap
25+
bootstrap-vcpkg.bat
26+
27+
# install packages
28+
vcpkg.exe install boost-test:x64-windows boost-program-options:x64-windows boost-log:x64-windows turtle:x64-windows zipper:x64-windows poco:x64-windows libpq:x64-windows gdal:x64-windows sqlite3:x64-windows boost-ublas:x64-windows
29+
30+
Building the project
31+
--------------------
32+
33+
Launch the Windows Powershell and run the following commands:
34+
35+
::
36+
37+
# Create a build folder under the Source folder
38+
mkdir -p Source\build
39+
cd Source\build
40+
41+
Now depending on which type of simulation you want to execute, you may run one of the following generate commands:
42+
43+
Commands to run cmake for the point simulations:
44+
45+
::
46+
47+
# Point simulations
48+
# Generate the project files
49+
cmake -G "Visual Studio 16 2019" -DCMAKE_INSTALL_PREFIX=C:\Development\Software\moja -DVCPKG_TARGET_TRIPLET=x64-windows -DOPENSSL_ROOT_DIR=c:\Development\moja-global\vcpkg\installed\x64-windows -DENABLE_TESTS=OFF -DCMAKE_TOOLCHAIN_FILE=c:\Development\moja-global\vcpkg\scripts\buildsystems\vcpkg.cmake ..
50+
51+
Commands to run cmake for the spatial simulations:
52+
53+
::
54+
55+
# Spatial simulations
56+
# if your planning to run spatial chapman richards example you also need to enable the gdal module
57+
# Generate the project files
58+
cmake -G "Visual Studio 16 2019" -DCMAKE_INSTALL_PREFIX=C:\Development\Software\moja -DVCPKG_TARGET_TRIPLET=x64-windows -DOPENSSL_ROOT_DIR=c:\Development\moja-global\vcpkg\installed\x64-windows -DENABLE_TESTS=OFF -DENABLE_MOJA.MODULES.GDAL=ON -DCMAKE_TOOLCHAIN_FILE=c:\Development\moja-global\vcpkg\scripts\buildsystems\vcpkg.cmake ..
59+
60+
61+
Running the project
62+
-------------------
63+
64+
Running in the IDE and debugging is a little tricky. This could more than likely be resolved with better cmake setups. But for now there is some setup that can make running and debugging work.
65+
66+
The issue is we want to run with the ``moja.cli.exe`` from the moja.FLINT project, but debug in our current IDE (FLINT.example).
67+
68+
The solution is to use properties to setup a Debug run in the IDE, making the command run ``moja.cli.exe``.
69+
70+
**NOTE** : All paths used below with ``C:\Development\moja-global`` will need to be modified to match your system build location of the moja project.
71+
72+
Test Module Example
73+
===================
74+
The settings required in VS2019 are:
75+
76+
::
77+
78+
# Command
79+
C:\Development\moja-global\FLINT\Source\build\bin\$(Configuration)\moja.cli.exe
80+
81+
# Command Args
82+
--config config\point_example.json --config config\$(Configuration)\libs.base.win.json --logging_config logging.debug_on.conf
83+
84+
# Working Directory
85+
$(SolutionDir)\..\..\Run_Env
86+
87+
# Environment Debug
88+
PATH=C:\Development\moja-global\vcpkg\installed\x64-windows\debug\bin;C:\Development\moja-global\FLINT\Source\build\bin\$(Configuration);%PATH%
89+
LOCAL_LIBS=$(OutDir)
90+
MOJA_LIBS=C:\Development\moja-global\FLINT\Source\build\bin\$(Configuration)
91+
92+
# Environment Release
93+
PATH=C:\Development\moja-global\vcpkg\installed\x64-windows\bin;C:\Development\moja-global\FLINT\Source\build\bin\$(Configuration);%PATH%
94+
LOCAL_LIBS=$(OutDir)
95+
MOJA_LIBS=C:\Development\moja-global\FLINT\Source\build\bin\$(Configuration)
96+
97+
**With Envs**: ``PATH`` for various libraries built in the Moja stage and ``LOCAL_LIBS`` so we can modify the explicit path for our example config to load libraries from this vs build (the default is the same location as the EXE).
98+
99+
To match this, the example point config uses an environment variable in the library path:
100+
101+
::
102+
103+
{
104+
"Libraries": {
105+
"moja.flint.example.base": {
106+
"library": "moja.flint.example.based.dll",
107+
"path": "%LOCAL_LIBS%",
108+
"type": "external"
109+
}
110+
}
111+
}
112+
113+
RothC example
114+
=============
115+
We also have a RothC example for point level simulations. Inorder to run this example, you may modify the following arguments in the above test settings command arguments.
116+
These arguments will point at the right configuration files for RothC.
117+
118+
::
119+
120+
# Command Args
121+
--config config/point_rothc_example.json --config config/$(Configuration)/libs.base_rothc.win.json --logging_config logging.debug_on.conf
122+
123+
Chapman Richards example
124+
========================
125+
Based on the moja global repository `Chapman Richards <https://github.com/moja-global/FLINT.chapman_richards>`_ , this sample can be run on both point and spatial versions (over Dominica).
126+
Inorder to run this example, you may modify the following arguments in the above test settings command arguments.
127+
These arguments will point at the right configuration files for Chapman Richards.
128+
129+
::
130+
131+
132+
# Command Args
133+
# Point
134+
--config config/point_forest_config.json --config config/$(Configuration)/libs.gdal.chaprich.win.json
135+
# Spatial
136+
--config config/forest_config.json --config config/$(Configuration)/libs.gdal.chaprich.win.json --config_provider config/forest_provider.json

‎docs/DevelopmentSetup/windows_installation.rst‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,14 @@ Windows Installation
55

66
This section guides first-time contributors through installing FLINT development environment.
77

8-
Before proceeding further, make sure you have setup the project using Git by following our guide `here`.
8+
Before proceeding further, make sure you have setup the project using Git by following our guide `Git and GitHub Guide <git_and_github_guide.html>`_.
99
Also make sure you have the following prerequisites setup -
1010

11-
.. toctree::
12-
:maxdepth: 1
13-
14-
../prerequisites/cmake
15-
../prerequisites/vcpkg
16-
../prerequisites/visual_studio
11+
Prerequisites
12+
-------------
13+
* `Cmake <../prerequisites/cmake.html>`_
14+
* `Visual Studio <../prerequisites/visual_studio.html>`_
15+
* `Vcpkg <../prerequisites/vcpkg.html>`_
1716

1817
Now that you have all the necessary prerequisites, you can proceed with the Installation.
1918

0 commit comments

Comments
 (0)