 |
GeMA
The GeMA main application
|
|
GeMA
The GeMA main application
|
This tutorial presents a step by step guide on how to build the GeMA framework on the Windows platform.
The current development environment uses Visual Studio 2017.
It is also necessary to install the Qt library. Currently the development version is based on Qt 5.12 (the latest LTS - long term support - version).
Any minor revision 5.12.x should be compatible. The Open source version of Qt can be downloaded from http://www.qt.io/download/
It should be possible to compile the project with prior versions of Visual Studio / Qt but that is NOT recomended.
For compiling the iterative numerical solver plugin, based on the Lis library, you will need the header files for the Windows 7.1A SDK. If you have an old Visual studio installation (like VS2013) in your machine, those headers will already be in place. Otherwise, you can install them by enabling the "Windows XP support for C++" option in the Visual Studio 2017 installation.
You will also need to have the SVN command line tools installed in your environment. The 'svnversion' command is used in the build process. It can be installed by the Tortoise SVN installer if you select the command line tools option. Alternatively (if you don't have access to the GeMA SVN, for example), you can pass the -nosvn command line option when calling the vc_build.bat command on step 3.2 to bypass this requirement.
When installing Qt, make sure to select the Visual Studio 2017 64 bits version. You also need to select the QtCharts package if you want to build the "GeMA Monitor" application (you can pass the -nomonitor flag to step 3.2 if you don't want to build the monitor app).
Tip 1: After installing the Visual Studio environment, it can be updated by the "Check for updates" item in the "Help" menu.
Tip 2: Installing the "NPL Lua language Service" package helps editing Lua files in Visual studio. Go to the "Extensions and Updates" dialog from the "Tools" menu. In that dialog, select the "Online" item on the left tree. Next, go to the "search" box on the top right, type "npl" and press Enter. Select the "NPL_LuaLanguageService" package and click in the "Download" button. The installation will happen after closing the development environment.
Tip 3: Instaling the Qt Visual Studio Add-in greatly improves debugging experience. To install, just follow the instructions in Tip 2, searching for "Qt" instead. After installing, the path to the Qt distribution should be set through the "Qt options" item in the "Qt VS Tools" menu.
The Gema compilation should be started through a command prompt with an environment with variables set for using Qt and Visual Studio in 64 bits mode.
One way to do that is to create a bat file named qtenv_vs2017_64.bat containing the following code (please, check given paths and update them as needed):
An interesting place to put this file is in the Qt distribution, inside the C:\Qt\5.12.4\msvc2017_64 directory (update paths as needed).
After opening a command prompt, just run the bat to setup the environment. This can be easily automated by a shortcut having as target:
Setting the "Start in" option for the shortcut to your GeMA installation also helps.
The last step in configuring the environment is updating the contents of the setTestAndDocEnv.bat file, if your Qt path is not already listed in the tried options. Just follow the example for your environment. This file is needed for building the documentation and for running regression tests.
IMPORTANT: If you are compiling with a visual studio version other than 2017, you will need to set the environment variable GEMA_VS to the compiler version, like SET GEMA_VS=2019. This is used by commonLibOptions.pri to find the correct pre-built HDF5 libraries. See also item 3.6.
Inside Tecgraf, the code can be downloaded from the following SVN repository:
https://subversion.tecgraf.puc-rio.br/svn/gema/trunk
3.1) Open up a command prompt with the build environment set as explained previously.
3.2) On the root folder of your GeMA distribution, run the vc_build.bat command. This will prepare Visual Studio projects and build some external libraries that are changed very rarelly.
Files should be added to the project always by way of .pro files and never directlly to a visual studio project. So, it is important to run the vc_build.bat command after every code update from the source repository. Don't worry though. This is normally a quick step. The initial compilation, which takes a little time, only happens on the first time that vc_build.bat is executed (or in the rare ocassion of a change in external libraries).
3.3) From the command line, type gema.sln. This will open the GeMA solution in Visual Studio with the correct environment set.
3.4) Now just do a common Visual Studio release and debug builds and everything needed should be compiled and copied to the correct places.
3.5) To build the gemaMonitor GUI application, repeat steps 3.3 and 3.4 using the gemaMonitor.sln file.
3.6) To make the build process simpler, HDF5 library files are precompiled in the repository for Visual Studio 2017 x64. If for some reason you need to recompile those libraries or if you are using a different compiler (ex VS 2019), check the README file on ext\hdf5 for instructions on how to build. The needed steps are easy enough, but installing CMake is necessary.
If you want to enable some unit tests in your GeMA build, just run vc_build.bat -tests. Keep in mind that building with unit tests can only be done in debug mode.
If you are not going to develop code with GeMA and want to just compile the libraries and the console application, you can just run vc_build.bat -rebuild in step 3.2 and skip the other two steps.
After compiling the code (in release mode), at the command line, from the source root directory type:
This will run a simple temperature calculation simulation. Results will be printed to the screen and saved to the examples\temperature\out folder. The output can also be found in the file runlog.txt.
Before running the example, please make sure that you have write permission for creating the result file.
The GeMA documentation is built with the Doxygen tool.
The first step is to download and install the doxygen tool from www.doxygen.org. It is also necessary to install the Graphviz package from www.graphviz.org (the Dot tool from that package is needed by Doxygen to create class and collaboration diagrams).
Tip: Doxygen version 1.8.16 has trouble with some headers and is generating incorrect documentation. Version 1.8.15 seems to be working ok.
Next, follow the instructions on the README.txt file on the doxygenScripts folder. If you haven't already done so in step 1, update as needed the paths in the setTestAndDocEnv.bat file, located at the GeMA root path.
After this four steps, the documentation can be created by simply running the DoxygenBuild.bat file on the root directory.
When updating the docs, it is usefull to just run the DoxygenBuild.bat file from the changed docs folder, since the whole build process is lengthy. For example, if you changed the documentation for the HydroFemPhysics plugin in plugins\physics\hydroFemPhysics\doxygen, run the DoxygenBuild.bat file at plugins\physics\hydroFemPhysics.
This partial update procedure is essential while writting the docs, but this might break some connections between each project docs, so when building the whole documentation, remember to run the DoxygenClear and DoxygenBuild bats from the root directory.
To deploy the site, use the DoxygenCopy.bat to extract the whole documentation to a temporary folder (set the destination on the beginning of the batch file). Afterwards, the whole contents of the folder should be copied to the server.
1.8.15