-
Notifications
You must be signed in to change notification settings - Fork 26
Build Process in Windows using Visual Studio
Don Robinson, ESSA Technologies, October 2021
This wiki documents the process of setting things up on a Windows PC so you can build FVS executables from the source files in the open-fvs repository. Builds of 32-bit and 64-bit builds have been tested on Windows 7-10. For more information on the build process, including information for builds on other platforms please refer to building FVS in a Unix environment, building in Windows with Cmake or the FAQ.
- Getting the Necessary Tools
- Getting the Source Files
- Building the Visual Studio Solution (SLN) with Cmake
- Building the Executable for Development & Debugging
- Building the Executable in Batch
- Redistributables
- Switching Between CMake Build Systems
- Working with Databases
You will need Administrator privileges to install the necessary tools, so ensure you have that before proceeding.
Building with Visual Studio requires Microsoft Visual Studio 2010 and the Intel Fortran XE 2011 compiler. The instructions found on this page are known to work for these two releases. More recent versions of Visual Studio (including free or lower cost "Express" and free "Community" versions), and other compliant compilers may work, but have not been tested. Information about Visual Studio is found at www.visualstudio.microsoft.com. Information about the Intel compiler is found at http://software.intel.com. You must have these both installed before continuing.
You will also need to install the Cmake system, which can be found at http://cmake.org. The Cmake build steps described below have been tested with Version 2.8, which is now quite old. During the installation process for Windows, you will need to select the option "Add CMake to the system PATH..." for all users or current user. If you get an error during the installation saying that the PATH is too long and cannot be edited, you will need to edit it manually to include the folder where Cmake is installed.
Your development work will likely mean that you will eventually merge your work into the trunk code. Please see the Testing wiki to learn about the requirements for testing model behavior prior to integrating code. Note that creating and running FVS tests requires the following (Unix) utilities: make, echo, grep, diff and rm.
Please visit Downloading Source Code to find out about Git clients and the FVS code base.
Open a DOS Command Window and navigate to the directory which contains the FVS code base. If you aren't familiar with the command prompt, click Start > (All) Programs > Accessories > Command Prompt and the Command Window should open to your personal directory. Assuming you have the FVS code base installed as described in Downloading Source Code, use the cd command to navigate to the trunk\bin directory inside the directory into which you checked out the open-fvs files. If you had placed the files into a directory called MyFvsFiles you would type the command as shown below.
cd \MyFvsFiles\trunk\bin
Once you have navigated to the correct directory you are ready to use Cmake to create a VS2010 solution file. If VS2010/Intel is installed, Cmake should automatically detect it and build the tools for VS2010. (If this does not happen automatically, please post the problem so that it can be resolved.)
If you are building a VS2010 solution for a 32-bit version of FVS, type the following at the command line type (don't forget the '.' at the end!)
cmake -G"Visual Studio 10" .
If you are building a solution for a 64-bit version of FVS, type the following at the command line (including the '.'):
cmake -G"Visual Studio 10 Win64" .
It is not currently possible to have Cmake create a VS2010 solution that can toggle between building 32- and 64-bit versions of FVS within the same solution. For further specifics about 32- and 64-bit versions of FVS, see Redistributables.
Either of these Cmake commands will begin the creation of VS2010 solution files (suffix: SLN) for all FVS variants, depending on how the GLOB tobuild command is set up in CMakeLists.txt. In Visual Studio parlance, a "solution" creates one or more software systems based on projects that are the components of the solution. In this case of FVS, an executable file is the principal software system that is created, but 3 component DLLs are also created. Each variant's SLN will be placed in a sub-directory whose name is based on the variant name. The example below shows the q-flavor (SQLite version 3) for the FVS-BC variant:
\MyFvsFiles\trunk\bin\qFVSbc_CmakeDir
FVS variant subdirectories are named with the pattern FVS**_CmakeDir, where ** is a 2-letter abbreviation for the variant (e.g., 2-letters ie for Inland Empire or ls for Lake States).
Cmake utilizes two kinds of files to create to create each SLN file. First, it uses a master script file called CMakeLists.txt to control the creation of each variant SLN. (You are welcome to inspect this file, but editing it is not recommended for beginners.) This master script file utilizes a set of about 20 files in turn - one for each variant - with names like 'FVSbc_sourceList.txt'. These files need to exist in the trunk\bin directory in order to build the variants.
As Cmake creates each variant SLN you will see something like this:
-- Building for: Visual Studio 10
-- tobuild = <...>/trunk/bin/FVSbc_sourceList.txt
-- Building FVS variant with VS10/Intel
-- The C compiler identification is MSVC 16.0.40219.1
-- Check for working C compiler using: Visual Studio 10
-- Check for working C compiler using: Visual Studio 10 -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working Fortran compiler using: Visual Studio 10
-- Check for working Fortran compiler using: Visual Studio 10 -- works
-- Detecting Fortran compiler ABI info
-- Detecting Fortran compiler ABI info - done
-- Determine Intel Fortran Compiler Implicit Link Path
-- Determine Intel Fortran Compiler Implicit Link Path -- done
-- Checking whether ifort supports Fortran 90
-- Checking whether ifort supports Fortran 90 -- yes
-- slfn = FVSbc_sourceList.txt prgName= FVSbc
-- FVSvariant = FVSbc
-- Configuring done
-- Generating done
-- Build files have been written to: <...>/trunk/bin/FVSbc_CmakeDir
-- Configuring done
-- Generating done
-- Build files have been written to: <...>/trunk/bin
When that is complete, you can proceed to customize each variant SLN file to build FVS. You only need to repeat the step of creating an SLN file if the underlying set of FVS source files change. Afterward, you can just rebuild the variants you need, based on periodic updates to the source code.
Using Windows Explorer, navigate to the directory containing the variant SLN file you wish to work with. In the example that follows the BC variant (bc) is used throughout, and the SLN file will be located here:
\MyFvsFiles\trunk\bin\FVSbc_CmakeDir\FVS.sln
Double-click on FVS.sln to start Visual Studio. After it starts you will see that the Solution contains the sub-projects shown below:
| Project Name | Exclude After 1st Build | Language | Output |
|---|---|---|---|
| All_BUILD | Yes (optional) | - | - |
| FVS_bc | No | FORTRAN | FVS_bc.dll |
| FVSbc | No | FORTRAN | FVSbc.exe |
| FVSfofem | No | C/C++ | FVSfofem.dll |
| FVSsql | No | C | FVSsql.dll |
| ZERO_CHECK | Yes (optional) | - | - |
The Visual Studio Solution Explorer tree control will let you see each project component. You can navigate around this tree control to locate source code of various kinds. The bulk of the FVS code will be in the FVS_bc project.
Before trying to compile the FVSbc variant you should right-click the FVSbc project and select Set as StartUp Project. It will then appear in bold font (as shown above). Note that the FVSbc project is different from the FVS_bc project. The first of these builds the final executable; the second builds the DLL which contains most of the model code (and is linked to the executable, along with other DLL components).
This feature of Cmake could use some improvement The Cmake program does not automatically place the F77 include files in the proper sequence needed to compile correctly. To correct this, you will probably need to edit the order in which these files are accessed. To do this for the BC variant, right click on the FVS_bc component and select Properties > Fortran > General > Additional Include Directories. The select the Edit... option from the drop-down list and re-order the include files as shown below. The moved block of line is shown in bold face:
C:\open-fvs\trunk\bin\FVSbc_CmakeDir
C:\open-fvs\trunk\bin\FVSbc_CmakeDir\$(ConfigurationName)
C:\open-fvs\trunk\bin\FVSbc_CmakeDir\..\..\canada\bc
C:\open-fvs\trunk\bin\FVSbc_CmakeDir\..\..\canada\bc\$(ConfigurationName)
C:\open-fvs\trunk\bin\FVSbc_CmakeDir\..\..\common
C:\open-fvs\trunk\bin\FVSbc_CmakeDir\..\..\common\$(ConfigurationName)**
When you start Visual Studio, the first build of the variant should include all projects, but subsequent builds do not need to repeatedly perform the same internal checks. An example of a component that can be excluded after the first build is ZERO_CHECK. This component only needs to be created once. In Visual Studio such non-essential projects can be unloaded by right-clicking the project and selecting Unload Project after the first successful build. The image shown above shows these to run-once sub-projects as unloaded. After unloading, you can also remove the unloaded projects if you wish.
It is often helpful to further automate the coding and debugging process by providing a response file that reproduces the file names entered by typing at the command line, making it unnecessary to repeatedly type input and output file names. This is easy to do by creating a response file using any valid file name (e.g. 'qbc01.rsp'). Then right-click the FVSbc project in the Solution Explorer tree and select Properties. From the tree-control highlight Debugging and modify the Command Arguments to provide input redirection.
Assuming you have a command-prompt in this directory:
\MyFvsFiles\trunk\bin
you can run the command-line batch file shown below to compile Release versions of all variants in the \bin sub-directory. If you wish to modify this batch file for a subset of variants or Debug versions, please make a copy and use your copy.
BuildAll_VS10.bat
FVS executables created with VS2010/Intel - the EXE and 3 DLLs - can be freely distributed to others. If these are provided to users who do not have the Intel Fortran compiler installed (or whose components cannot be found by the PATH variable), the following files will need to be provided. When provided, they can be copied into the directory containing the FVS executable. Please note the restriction on distributing certain Debug DLLs.
| Component | Debug | Release | Redistributable |
|---|---|---|---|
| libifcoremd.dll | X | X | Yes |
| libifcoremdd.dll | X | No | |
| libifportmd.dll | X | X | Yes |
| libmmdd.dll | X | No | |
| libmmd.dll | X | X | Yes |
| svml_dispmd.dll | X | X | Yes |
On a default Intel installation building a 32-bit version of FVS, the release-mode redistributables can be found in one of these locations:
C:\Program Files\Common Files\Intel\Shared Libraries\redist\ia32\compiler
C:\Program Files\Common Files\Intel\ComposerXE-2011\redist\ia32\compiler
On a default Intel installation building a 64-bit version of FVS, the release-mode redistributables can be found here:
C:\Program Files (x86)\Intel\Composer XE\redist\intel64\compiler
The 32- or 64-bit DLL redistributables must match the 32- or 64-bit version of FVS.
Most of the time you will probably only want to build Visual Studio Solution (SLN) files. However, developers will sometimes need to test their code on a non-VS2010 system like MinGW or switch between 32- and 64-bit builds. If you need to do this, you should remove these files and directories before attempting to build with an alternative toolchain:
directory: CMakeFiles
file: cmake_install.cmake
file: CMakeCache.txt
These files and directories contain information that is stored by CMake the first time it is run, and will "lock" CMake into always creating VS2010 solutions. Removing them allows CMake to create other kinds of build systems.
FVS has recently been updated to adopt the SQLite open-source database format. SQLite is the standard database used by all the q-flavor variants (the name of the master file that contains all the variant's source code filenames begins with the letter 'q'). If you wish to interact with a SQLite database, no special drivers are needed; only the q-flavor compiled model. You may need to work with 3rd party tools to work with SQLite databases.
Earlier non-q versions can interact with many common database formats: SQL, MS Access, MS Excel and probably others using the ODBC protocols. These non-q flavors require special ODBC software drivers to enable input and output, and there are some limitations based on combinations of operating system, FVS tool chain and 32/64 bit versions of drivers. In all cases, there is a greater chance of first-time success if there is consistency in the use of 32- or 64-bit components, as these are the configurations that have been tested. That said, FVS support for legacy non-q database I/O is receiving less emphasis than the q-flavor variants using SQLite. If you wish to interact with a SQL database file using a 32- or 64-bit VS2010/Intel build of FVS, 32- and 64-bit versions of the SQLite3 database software for can be found here. Installation of this software creates a System DSN ODBC driver that can interact with SQLite3 databases having a default .db filename suffix. If 32- or 64-bit Microsoft Office software is installed on your computer, it is also possible to interact directly with Excel and Access files, as described in the FVS Database Extension documentation. This documentation also describes how to customize database connection parameters. It may be possible to mix 32- and 64-bit versions of FVS and Microsoft Office drivers, but this has not been tested. The Windows OS does not permit simultaneous installation of both 32- and 64-bit ODBC drivers for Excel or Access.