Skip to content

New Developer Setup / Overview

Read this documentation if a new developer or an existing developer with a new computer.

This documentation is for software developers that are members of the core StateMod team and others who have an interest in contributing to the StateMod software project. It is recommended that the StateMod development environment should follow these setup instructions, which are consistent with the Development Environment and Initial Project Setup documentation. The standard development folder structure should be followed to minimize potential for issues, especially given the number of components and setup steps.

This documentation is consistent with the recommended StateMod development environment. This documentation and the StateMod development environment are also consistent with the StateCU software. Configuring the development environment for StateMod will support compiling StateCU.

The intent of this documentation is to completely document setup steps and allow new developers (and existing developers with new computers) to effectively set up a development environment and allow commenting on the documentation so that it can be improved for other developers.

The following steps need to occur to set up a new developer's environment. Links to other documentation are included to provide more information and "see details below" is used to indicate that specific instructions are included below. After reading instructions for a step, use "back" to return to this outline so that setup instructions can be followed in the proper sequence. Bold comments indicate which steps are required and which are optional.

The following sections are available below in this page:

Minimal Development Environment Setup (for command line compiling)

A minimal development environment can be configured to develop and compile StateMod using a text editor and command line compiler.

  1. Create folder for development files - where development will occur - required - see details below
  2. Development Environment software install part 1 (version control)
  3. Clone Git Repositories - clone the repositories to get access to all files - required - see details below
  4. Development Environment software install part 2 (documentation tools) - optional, install if will view and edit documentation within development environment
  5. Development Environment software install part 3 (Fortran development tools)
  6. Next Steps - Development Tasks - compile software

Full Eclipse Development Environment Setup (for interactive development environment)

Optionally, a full development environment can be configured to develop and compile StateMod using the Eclipse integrated development environment.

  1. Create folder for development files - where development will occur - required - see details below
  2. Development Environment software install part 1 (version control)
  3. Clone Git Repositories - clone the repositories to get access to all files - required - see details below
  4. Development Environment software install part 2 (documentation tools) - optional, install if will view and edit documentation within development environment
  5. Development Environment software install part 3 (Fortran development tools)
  6. Eclipse Workspace Setup (interactive development environment), optional, not needed for command-line compile, install if Eclipse/Photran IDE is used
  7. Next Steps - Development Tasks - compile software

Create Folder for Development Files

This step is used with minimal and full Eclipse development environments.

Create a development home folder consistent with the initial project setup - this is an umbrella folder for all StateMod development files, including software tools that are installed locally. The recommended overall organization that is used for CDSS software development is shown below, which allows a user to manage development for CDSS and other clients/systems/projects, multiple products within CDSS, and multiple repositories for a product.

C:\Users\UserName\                    User's files on Windows (can use a different drive letter if appropriate).
/home/UserName/                       User's files on Linux, including MinGW.
   cdss-dev/                          Software development work for CDSS.
     StateMod/                        StateMod software product within CDSS.
       git-repos/                     One or more Git repositories for the product (software, documentation, tests, etc.).
         cdss-app-statemod-fortran/   The Git repository files for StateMod software.

It is assumed that development will occur within a developer's home folder on the computer in order to provide separation from the work of other developers on the computer. A different Windows drive can be used other than the C drive.

Additional instructions describe how to install development files into the folders described below.

Linux Linux

Do the following using a terminal window. Note that the syntax ~ indicates the home folder and is equivalent to the $HOME environment variable location (/home plus / plus $USERNAME). Use the printenv command to show all environment variables. The $ shown below indicates the prompt.

$ cd
$ mkdir cdss-dev
$ cd ~/cdss-dev/
$ mkdir StateMod

See the Development Environment / Tips and Tricks documentation for an example of defining an alias for changing directories.

Press back in the browser to return to the outline.

Windows Windows

Do the following in a Windows command shell, or perform the equivalent actions in File Explorer, Git Bash, or another command environment. Use the set command in a Windows cmd command shell to show environment variables. The > shown below indicates the prompt.

> C:                           Use a different drive letter if appropriate.
> cd \Users\UserName
> mkdir cdss-dev
> cd cdss-dev
> mkdir StateMod

See the Development Environment / Tips and Tricks documentation for an example of defining a command file for changing directories.

Press back in the browser to return to the outline.

Git Bash on Windows

If Git Bash is used on a Windows computer, create the folder as follows.

$ cd /C/Users/UserName           Use a different drive letter if appropriate.
$ mkdir cdss-dev
$ cd cdss-dev/
$ mkdir StateMod

See the Development Environment / Tips and Tricks documentation for an example of defining an alias for changing directories.

Press back in the browser to return to the outline.

Clone Git Repositories

This step is used with minimal and full Eclipse development environments.

If an existing StateMod developer is setting up a new computer, copy files from the old computer using folders as described above and below, or follow the instructions below to clone the current Git repository onto the new computer.

The cdss-app-statemod-fortran Git repository hosted on GitHub contains the StateMod code and Git repository configuration files. This is referred to to as the main StateMod repository.

If using Eclipse/Photran, the repository will be imported into the Eclipse/Photran workspace as a Fortran project in a later step, which allows the files to be managed in Git but also be accessed from Eclipse. Eclipse/Photran is not used if doing a minimal setup.

If prompted, specify the GitHub account credentials. The repository will include the Fortran StateMod project.

The files resulting from the following steps should match the Development Folder Structure.

Linux Clone the repository files (Linux)

$ cd ~/cdss-dev/StateMod
$ mkdir git-repos
$ cd git-repos
$ git clone https://github.com/OpenCDSS/cdss-app-statemod-fortran.git

# Output...

Cloning into 'cdss-app-statemod-fortran'...
remote: Enumerating objects: 282, done.
remote: Counting objects: 100% (282/282), done.
remote: Compressing objects: 100% (264/264), done.
remote: Total 1237 (delta 48), reused 27 (delta 14), pack-reused 955
Receiving objects: 100% (1237/1237), 5.75 MiB | 6.29 MiB/s, done.
Resolving deltas: 100% (482/482), done.

Once the main repository has been cloned, the git-clone-all-statemod.sh helper script will clone remaining repositories including documentation and tests.

$ cd ~/cdss-dev/StateMod/git-repos/cdss-app-statecu-fortran/build-util
$ ./git-clone-all-statemod

# Output...

operatingSystem=mingw (used to check for Cygwin and filemode compatibility)

Clone all repositories for the product to set up a new developer environment.
The following is from /c/Users/sam/cdss-dev/StateMod/git-repos/cdss-app-statemod-fortran/build-util/product-repo-list.txt

--------------------------------------------------------------------------------
# Repositories that comprise StateMod
# - assumes that local folder name will match the repository name
cdss-app-statemod-fortran
cdss-app-statemod-fortran-doc-dev
cdss-app-statemod-fortran-doc-user
cdss-app-statemod-fortran-test
--------------------------------------------------------------------------------

All repositories that don't already exist will be cloned to /c/Users/sam/cdss-dev/StateMod/git-repos.
Repositories will be cloned using root URL https://github.com/OpenCDSS
You may be prompted to enter credentials.
Continue [y/n]?: y
================================================================================
Cloning repository:  cdss-app-statemod-fortran
Repository folder:  /c/Users/sam/cdss-dev/StateMod/git-repos/cdss-app-statemod-fortran
Repository Url:  https://github.com/OpenCDSS/cdss-app-statemod-fortran
Repo folder already exists so skipping:  /c/Users/sam/cdss-dev/StateMod/git-repos/cdss-app-statemod-fortran
================================================================================
Cloning repository:  cdss-app-statemod-fortran-doc-dev
Repository folder:  /c/Users/sam/cdss-dev/StateMod/git-repos/cdss-app-statemod-fortran-doc-dev
Repository Url:  https://github.com/OpenCDSS/cdss-app-statemod-fortran-doc-dev
Cloning into 'cdss-app-statemod-fortran-doc-dev'...
remote: Enumerating objects: 214, done.
remote: Total 214 (delta 0), reused 0 (delta 0), pack-reused 214
Receiving objects: 100% (214/214), 4.70 MiB | 5.25 MiB/s, done.
Resolving deltas: 100% (32/32), done.
================================================================================
Cloning repository:  cdss-app-statemod-fortran-doc-user
Repository folder:  /c/Users/sam/cdss-dev/StateMod/git-repos/cdss-app-statemod-fortran-doc-user
Repository Url:  https://github.com/OpenCDSS/cdss-app-statemod-fortran-doc-user
Cloning into 'cdss-app-statemod-fortran-doc-user'...
remote: Enumerating objects: 199, done.
remote: Total 199 (delta 0), reused 0 (delta 0), pack-reused 199
Receiving objects: 100% (199/199), 17.45 MiB | 5.09 MiB/s, done.
Resolving deltas: 100% (50/50), done.
================================================================================
Cloning repository:  cdss-app-statemod-fortran-test
Repository folder:  /c/Users/sam/cdss-dev/StateMod/git-repos/cdss-app-statemod-fortran-test
Repository Url:  https://github.com/OpenCDSS/cdss-app-statemod-fortran-test
Cloning into 'cdss-app-statemod-fortran-test'...
remote: Enumerating objects: 3, done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 3
Unpacking objects: 100% (3/3), done.
================================================================================

After cloning, /c/Users/sam/cdss-dev/StateMod/git-repos contains:
cdss-app-statemod-fortran
cdss-app-statemod-fortran-doc-dev
cdss-app-statemod-fortran-doc-user
cdss-app-statemod-fortran-test

Windows Clone the repository files (Windows)

Use the Linux instructions if using Git Bash. The following will work if using Git Cmd.

> C:
> cd \Users\user\cdss-dev\StateMod
> mkdir git-repos
> cd git-repos
> git clone https://github.com/OpenCDSS/cdss-app-statemod-fortran.git

Press back in the browser to return to the outline.

Create Eclipse Workspace Folder

This step is the same as the Initial Project Setup so follow those instructions with the following input:

  • Linux Linux: the workspace folder is ~/cdss-dev/StateMod/eclipse-workspace
  • Windows Windows: the workspace folder is C:\Users\user\cdss-dev\StateMod\eclipse-workspace

Start Eclipse by running the Eclipse run script as shown below. This script can be used any time to run Eclipse for this project. If it is necessary to modify this script, see recommendations for a developer-specific run script.

Open the workspace in Eclipse in preparation of adding the code project from the Git repository in the next step.

Linux Linux

$ cd ~/cdss-dev/StateMod/git-repos/cdss-app-statemod-fortran/build-util/eclipse
$ ./run-eclipse-statemod.sh

Windows Windows

> C:
> cd \Users\user\cdss-dev\StateMod\git-repos\cdss-app-statemod-fortran\build-util\eclipse
> .\run-eclipse-statemod-mingw.bat

Press back in the browser to return to the outline.

Import the Existing Eclipse StateMod Project from the Git Repository Folder

The Initial Project Setup process performed by the software team leads did extensive work to set up the Eclipse project and these files were saved to the Git repository as an Eclipse/Photran Fortran project.

New developers need to import the project into the empty workspace as follows.

Use File / Import and then follow the sequence below.

Import project

The first step allows browsing to an existing project (the user name will be different).

Import project

Press Finish in the initial import dialog.

The resulting Eclipse workspace is shown as below. Note that Eclipse recognizes the associated Git repository indicated by the repository name/branch next to the Eclipse project.

Import project

Next Steps - Development Tasks

At this point it should be possible to compile and run StateMod in Eclipse or on the command line. See also: