Merge pull request #1 from OpenFAST/dev

Dev

.github/ISSUE_TEMPLATE/bug_report.md

@@ -6,28 +6,24 @@ labels: "Type: Bug"
 ---
 
 **Bug description**
-
-A clear and concise description of the bug.
+<A clear and concise description of the bug.>
 
 **To Reproduce**
-
+<Update the following list with your specific information.>
 Steps to reproduce the behavior:
 1. Compile with '...'
 2. Run '...' case with '...' settings
 3. Open '...' output
 4. See the error
 
 **Expected behavior**
+<A clear and concise description of what you expected to happen.>
 
-A clear and concise description of what you expected to happen.
-
-**Screenshots**
-
-If applicable, add screenshots to help explain your problem.
+**Screenshots, if applicable**
+<Add screenshots to help explain your problem.>
 
 **OpenFAST Version**
-
-Please provide as much detail as possible including git commit. The best information is a screenshot of the OpenFAST system description that prints when running OpenFAST:
+<Please provide as much detail as possible including git commit. The best information is a screenshot of the OpenFAST system description that prints when running OpenFAST:>
 
 ```
 **************************************************************************************************
@@ -52,11 +48,9 @@ Please provide as much detail as possible including git commit. The best informa
 ```
 
 **System Information (please complete the following information):**
-
- - OS: [e.g. Ubuntu 14.04 or macOS 10.12]
- - Compiler: [e.g. GFortran 4.4]
- - Compiler settings: [e.g. CMake flags or other settings]
+ - OS: <e.g. Ubuntu 14.04 or macOS 10.12>
+ - Compiler: <e.g. GFortran 4.4>
+ - Compiler settings: <e.g. CMake flags or other settings>
 
 **Additional context**
-
-Add any other context about the problem here.
+<Add any other context about the problem here.>

.github/ISSUE_TEMPLATE/feature_request.md

@@ -6,17 +6,13 @@ labels: 'Type: Enhancement'
 ---
 
 **Is your feature request related to a problem? Please describe.**
-
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+<A clear and concise description of the problem.>
 
 **Describe the solution you'd like**
-
-A clear and concise description of what you want to happen.
+<A clear and concise description of what you want to happen.>
 
 **Describe alternatives you've considered**
-
-A clear and concise description of any alternative solutions or features you've considered.
+<A clear and concise description of any alternative solutions or features youve considered.>
 
 **Additional context**
-
-Add any other context or screenshots about the feature request here.
+<Add any other context or screenshots about the feature request here.>

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,24 +1,18 @@
 
-Complete this sentence
-**THIS PULL REQUEST __ [IS/IS NOT] __ READY TO MERGE**
+**Complete this sentence**
+THIS PULL REQUEST __ [IS/IS NOT] __ READY TO MERGE
 
 **Feature or improvement description**
-
-A clear and concise description of the new code.
+<A clear and concise description of the new code.>
 
 **Related issue, if one exists**
-
-Link to a related GitHub Issue.
+<Link to a related GitHub Issue.>
 
 **Impacted areas of the software**
-
-List any modules or other areas which should be impacted by this pull request. This helps to determine the verification tests.
+<List any modules or other areas which should be impacted by this pull request. This helps to determine the verification tests.>
 
 **Additional supporting information**
+<Add any other context about the problem here.>
 
-Add any other context about the problem here.
-
-**Automated test results**
-
-Add the automated test results (unit tests and regression tests) here, if they've been run.
-For any failing tests, please provide justification.
+**Test results, if applicable**
+<Add the results from unit tests and regression tests here along with justification for any failing test cases.>

.travis.yml

@@ -25,6 +25,7 @@ before_install:
     - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then brew install gcc@7; fi
 
     # linux configuration
+    - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then sudo apt-get update; fi
     - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then sudo apt-get install gfortran; fi
     - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then sudo apt-get install libblas-dev liblapack-dev; fi
     - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then pyenv shell 3.6.3; fi

CMakeLists.txt

@@ -22,12 +22,6 @@ include(${CMAKE_SOURCE_DIR}/cmake/OpenfastFortranOptions.cmake)
 
 set(CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
 
-# Get the git info into the executable
-list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake/")
-include(GetGitRevisionDescription)
-git_describe(GIT_DESCRIBE)
-add_definitions(-DGIT_VERSION_INFO="${GIT_DESCRIBE}")
-
 # CMake Configuration variables
 if (NOT CMAKE_BUILD_TYPE)
   set(CMAKE_BUILD_TYPE "Release" CACHE STRING
@@ -98,6 +92,7 @@ set(OPENFAST_MODULES_LOCAL
   supercontroller
   turbsim
   openfast-library
+  version
   )
 
 ########################################################################

docs/source/dev/build_doc.rst

@@ -1,36 +1,59 @@
 .. _build_doc:
 
+Developing Documentation
+========================
+OpenFAST documentation is hosted on
+`readthedocs <http://openfast.readthedocs.io/>`_. It is automatically generated
+through the readthedocs build system from both the ``master`` and ``dev``
+branches whenever new commits are added. This documentation uses the
+`restructured text <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_
+markup language.
+
 Building this documentation locally
-===================================
+-----------------------------------
+The documentation is compiled with Sphinx, which is a Python based tool.
+Install it and the other required Python packages listed in
+``docs/requirements.txt`` with pip or another python package manager.
+
+These packages are optional:
+- `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`__
+- `Doxylink <https://pythonhosted.org/sphinxcontrib-doxylink/>`__
+- `Graphviz <http://www.graphviz.org>`__
+
+Doxygen and Graphviz can be installed directly from their website or with a
+package manager like ``brew``, ``yum``, or ``apt``.
 
-This document describes how to build the OpenFAST documentation on your local machine. The official documentation is automatically built
-and updated on `readthedocs <http://openfast.readthedocs.io/en/latest/>`__ when new material is pushed to the github repo.
-However, while developing documentation, it is helpful to build locally in order to see changes quickly and without needing
-to publish your changes to the public facing site.
+Pure python build
+-----------------
+If CMake and Make are not available on your system, the documentation can
+be generated directly with `sphinx`.
+**Note: This method does not generate the API documentation through Doxygen.**
 
-Dependencies
-------------
-The documentation is built in `Sphinx <http://www.sphinx-doc.org/en/master/>`__ with optional support for 
-`Doxygen <http://www.stack.nl/~dimitri/doxygen/>`__, `Doxylink <https://pythonhosted.org/sphinxcontrib-doxylink/>`__, and
-`Graphviz <http://www.graphviz.org>`__. Therefore users will need to install these tools as well as several extensions of Sphinx that are utilized.
+First, align your build structure to the standard OpenFAST build by creating
+a directory  at ``openfast/build``.
 
-Doxygen and Graphviz can be installed directly from their website or with a package manager like ``brew``, ``yum``, or ``apt``.
+If all tools are available, move into ``openfast/build`` and run the `sphinx`
+command:
 
-The remaining tools are Python based and should be installed with `pip` using the requirements file at
-``docs/requirements.txt``.
+::
 
-With CMake and Make
--------------------
-In the OpenFAST repository checkout, if it has not been created yet,
-create a ``build`` directory.  Change
-to the build directory and run CMake with ``BUILD_DOCUMENTATION`` on.  If all
+    # sphinx-build -b <builder-name> <source-directory> <output-directory>
+    sphinx-build -b html ../docs ./docs/html
+
+If this completes successfully, a html file will be created at
+``build/docs/html/index.html`` which can be opened with any web browser.
+
+Building with CMake and Make
+----------------------------
+In the OpenFAST directory, create a ``build`` directory and move into it.
+Then, run CMake with this flag: ``-DBUILD_DOCUMENTATION=ON``.  If all
 of the required tools are found successfully, CMake will configure with the
 ability to build the documentation.
 
-Issue the command ``make docs`` which will first build the Doxygen
+Next, run the command ``make docs`` which will first build the Doxygen
 documentation and then the Sphinx documentation. If this completes
-successfully, the entry point to the documentation will be in
-``build/docs/html/index.html``.
+successfully, a html file will be created at ``build/docs/html/index.html``
+which can be opened with any web browser.
 
 For example, from the OpenFAST directory:
 
@@ -41,42 +64,20 @@ For example, from the OpenFAST directory:
     cmake .. -DBUILD_DOCUMENTATION=ON
     make docs
 
-If you modify document source files in ``OpenFAST/docs/source``, you can simply update the html files through another ``make docs`` in ``OpenFAST/build``:
+If you modify document source files in ``openfast/docs/source``, you can simply
+update the html files through another ``make docs`` in ``openfast/build``:
 
 ::
 
     make docs
 
-Pure python
------------
-If CMake and Make are not available on your system, the documentation can be generated directly
-with `sphinx`. **Note: This method does not generate the API documentation through Doxygen.**
-
-First, align your build structure to the standard OpenFAST build by creating a directory 
-at ``openfast/build``.
-
-If all tools are available, move into ``openfast/build`` and run the `sphinx` command:
-
-::
-
-    # sphinx-build -b <builder-name> <source-directory> <output-directory>
-    sphinx-build -b html ../docs ./docs/html
-
-
-
-Documentation Output
---------------------
-
-After building the documentation, it can be accessed by opening the output in a browser.
-Open the high level html file generated at ``openfast/build/docs/html/index.html``
-and begin using the page as any other web page.
-
-
-Additional Build Targets
-------------------------
-
-The html portion of the documentation can be built with ``make sphinx-html``, and
-the output is available at ``openfast/build/docs/html/index.html``.
+Building only the html
+~~~~~~~~~~~~~~~~~~~~~~
+Generating the only html is much faster than compiling all components of the
+documentation. This can be done with ``make sphinx-html``.
 
+Building the PDF
+~~~~~~~~~~~~~~~~
 If LaTeX is installed, a pdf version of the documentation can be built with
-``make sphinx-pdf``, and the output is available at ``openfast/build/docs/latex/Openfast.pdf``.
+``make sphinx-pdf``, and the output is available at
+``OpenFAT/build/docs/latex/Openfast.pdf``.

docs/source/dev/debugging.rst

@@ -0,0 +1,93 @@
+.. _debugging:
+
+Debugging OpenFAST
+==================
+
+Being a Fortran project, OpenFAST can be challenging to debug and the process
+is unique for each system and environment. However, a common requirement for
+all systems is to compile OpenFAST in debug mode.
+
+Keep in mind that some OpenFAST cases can be quite large in their memory
+footprint and may take a long time to reach the point you're targetting in
+the code. Choosing a minimal test case could save significant time.
+
+It may by helpful to write a small fortran program to verify that your
+debugging tools are set up properly before diving in to OpenFAST. Be sure to
+simulate a bug by doing something like accessing an array element that is not
+allocated and verify that you can catch the bug with your tools.
+
+Debugging on Windows
+--------------------
+Windows developers using Intel tools can use Visual Studio for debugging. This
+is a straightforward process with lots of support from Intel.
+
+Otherwise, Windows developers compiling with CygWin or MinGW should proceed to
+the section for debugging with linux.
+
+Debugging on Linux and macOS
+----------------------------
+First, compile OpenFAST in debug mode by setting CMAKE_BUILD_TYPE to Debug.
+You can do this on the command line with
+
+.. code-block:: bash
+
+    cmake .. -D CMAKE_BUILD_TYPE=Debug
+
+or by using ccmake to open the command line cmake gui to change it.
+
+The GNU debugger, GDB, works well for debugging compiled code. It has a
+comprehensive command line interface which enables developers to add
+breakpoints and inspect variables.
+
+Driving the debugger through an IDE can make inspecting the code much more
+efficient. One IDE known to work well is Visual Studio Code with the Native
+Debug extension. You can set up a launch configuration in VS Code so that
+you can debug a particular OpenFAST case through the IDE. To do this, open
+the launch configuration and add a block similar to this:
+
+.. code-block:: json
+
+        {
+            "name": "AOC_WSt",
+            "type": "gdb",
+            "request": "launch",
+            "printCalls": false,
+            "showDevDebugOutput": false,
+            "valuesFormatting": "prettyPrinters",
+            "gdbpath": "gdb",
+            "target": "${workspaceRoot}/build/glue-codes/openfast/openfast",
+            "cwd": "${workspaceRoot}/build/reg_tests/glue-codes/openfast/AOC_WSt/",
+            "arguments": "${workspaceRoot}/build/reg_tests/glue-codes/openfast/AOC_WSt/AOC_WSt.fst",
+        },
+
+macOS configuration
+~~~~~~~~~~~~~~~~~~~
+GDB on macOS needs some configuration before the system allows it to take
+over a process. It is recommended that gdb be installed with homebrew
+
+.. code-block:: bash
+
+    brew info gdb
+    brew install gdb
+
+After that completes, be sure to follow the caveats to finish the installation.
+For gdb 8.2.1, it looks like this:
+
+.. code-block:: bash
+
+    ==> Caveats
+    gdb requires special privileges to access Mach ports.
+    You will need to codesign the binary. For instructions, see:
+
+    https://sourceware.org/gdb/wiki/BuildingOnDarwin
+
+    On 10.12 (Sierra) or later with SIP, you need to run this:
+
+    echo "set startup-with-shell off" >> ~/.gdbinit
+
+For Native Debug on macOS, you have to sort of hack the extension to allow
+breakpoints in fortran files by adding this line to your settings.json:
+
+.. code-block:: json
+
+    "debug.allowBreakpointsEverywhere": true,