Initial Project Setup / Overview

The Initial Project Setup documentation is a record of how the project was set up the first time. It is assumed that all software listed in the Development Environment has been installed, although the project initialization steps will list each setup step.

This documentation is a useful reference in case the project needs to be reinitialized or other similar projects need to be configured. Sections of this documentation are also referenced by the New Developer documentation, such as configuring the Eclipse workspace.

This documentation includes the following sections:

Background on Code Versions

The StateCU code has been under development for over 20 years as part of CDSS. However, few changes have occurred since 2012 and the following discussion focuses on recent history.

TODO smalers 2016-12-31 need to decide if need to explain earlier history

The StateCU 13.00 code was loaded into Jim Brannon's private statecu-project GitHub repository on January 20, 2011. This repository only contains source code, with no documentation or tests, and all source code files are located in the main repository folder. The repository does not contain any Eclipse files, although Eclipse/Photran was used for recent development. Several code changes occurred on a limited number of files since that time, mainly to support compiling on Linux with gfortran.

The Open Water Foundation (OWF) compared the repository code with the latest code provided by Erin Wilson of Wilson Water Group (WWG), as of Nov 18, 2016, and found only minor differences due to end-of-line characters. Consequently, Jim Brannon's GitHub repository contains the latest version of the code, marked as version 13.10. The latest StateCU version on the CDSS website as of Dec 31, 2016, is 13.03.

The OpenCDSS project, led by OWF, is establishing a more comprehensive StateCU repository and development environment, in particular to establish a development environment that can support multiple developers. Consequently, the code from Jim Brannon's repository was migrated to the OWF private repository named cdss-app-statecu-fortran, retaining the code history. The repository was cloned to the OWF repository and the remote reference was deleted so that no link to the Jim Brannon repository remains. This is appropriate because the OpenCDSS repository will be the main repository going forward.

The code organization was restructured as per the folder structure discussed in the following section and additional content was added, including this developer documentation. The goal is to allow a new developer to clone the repository and get up and running as quickly as possible, while also avoiding user-specific files in the repository, which would cause ongoing conflicts in file content.

Development Folder Structure

This documentation assumes that files are configured according to the following folder structure. It is recommended that StateCU developers follow this folder structure closely because if they do not, the documentation will be less helpful and troubleshooting will require additional resources. Feedback on the structure can be discussed with the development team leads. There does not seem to be a clear folder structure standard for Fortran projects and consequently the following builds upon Maven Java Standard Directory Layout.

TODO smalers 2016-12-31 need to flesh out how automated testing could work using Python pytest and Fortran unit tests - will perhaps result in "fortran" and "python" folders under "test".

Linux

The Linux development environment relies on compilers being installed on the operating system (whereas Windows development environment relies on additional layer of MinGW or Cygwin). The following folder structure is similar to the Windows version other than different conventions for Linux file locations.

/usr/... etc.                                      (TODO smalers 2016-12-31 need to document where compilers install)

/home/user/                                        (Software developer's home folder)
    cdss-dev/                                      (CDSS software projects)
        StateCU/                                   (CDSS StateCU software project)
            eclipse-workspace/                     (Eclipse workspace to organize Eclipse projects)
            git-repos/                             (Git repositories that comprise StateCU)
                cdss-app-statecu-fortran/          (StateCU Git main program repository)
                    .git/                          (Git local repository - DO NOT TOUCH DIRECTLY)
                    .gitattributes                 (Git repository properties)
                    .gitignore                     (Git repository global ignore list)
                    doc/                           (Legacy documentation, such as Word user manual)
                    doc-dev-mkdocs-project/        (MkDocs project for the developer documentation)
                    doc-user-mkdocs-project/       (MkDocs project for the user documentation)
                    src/                           (StateCU source code, main and tests)
                        main/                      (StateCU program code)
                            fortran/               (StateCU Fortran code)
                                *.for
                                *.inc
                                makefile 
                            resources/             (Envisioned as non-Fortan code that may be needed - supporting files)
                        test/                      (StateCU tests)
                            fortran/               (Envisioned for Fortran unit tests)
                                *.for
                            python/                (Envisioned for pytest functional tests)
                                *.py

Windows

The following assumes that MinGW is used to provide the compilers.

TODO smalers 2017-01-01 need to add description for Cygwin.

C:\MinGW\                                          (Install home for MinGW, which includes gfortran)

C:\Users\user\                                     (Software developer's home folder)
    cdss-dev\                                      (CDSS software projects)
        StateCU\                                   (CDSS StateCU software project)
            eclipse-workspace\                     (Eclipse workspace to organize Eclipse projects)
            git-repos\                             (Git repositories that comprise StateCU)
                cdss-app-statecu-fortran\          (StateCU Git main program repository)
                    .git\                          (Git local repository - DO NOT TOUCH DIRECTLY)
                    .gitattributes                 (Git repository properties)
                    .gitignore                     (Git repository global ignore list)
                    doc\                           (Legacy documentation, such as Word user manual)
                    doc-dev-mkdocs-project\        (MkDocs project for the developer documentation)
                    doc-user-mkdocs-project\       (MkDocs project for the user documentation)
                    src\                           (StateCU source code, main and tests)
                        main\                      (StateCU program code)
                            fortran\               (StateCU Fortran code)
                                *.for
                                *.inc
                                makefile 
                            resources\             (Envisioned as non-Fortan code that may be needed - supporting files)
                        test\                      (StateCU tests)
                            fortran\               (Envisioned for Fortran unit tests)
                                *.for
                            python\                (Envisioned for pytest functional tests)
                                *.py

Eclipse File Location Overview

TODO smalers 2016-12-31 Need to fill this in to explain how various levels of Eclipse files are used.

Project Initialization Steps

The following are the project initialization steps in the recommended order, although some steps were actually implemented in slightly different order for practical reasons.