Building GridPACK Applications
==============================

GridPACK comes with several applications that are included in the main
distribution. These currently include power flow, contingency analysis,
dynamic simulation, state estimation and Kalman filter applications as
well as some non-power grid examples that illustrate features of the
framework. These applications are automatically built whenever the full
GridPACK distribution is built.

For applications developed outside the GridPACK distribution, the build
process is fairly simple, provided you are using CMake (you will need to
have CMake installed on your system to build GridPACK so using CMake for
your application build should be a straightforward extension). For a
CMake build, you need to create a CMakeLists.txt file in the same
directory that includes your application files. A template for the
CMakeLists.txt file is

::

    1 cmake_minimum_required(VERSION 3.5.0)
    2
    3 if (NOT GRIDPACK_DIR)
    4   set(GRIDPACK_DIR /HOME/gridpack-install
    5       CACHE PATH "GridPACK installation directory")
    6 endif()
    7
    8 include("${GRIDPACK_DIR}/lib/GridPACK.cmake")
    9
   10 project(MyProject)
   11
   12 enable_language(CXX)
   13
   14 gridpack_setup()
   15
   16 add_definitions(${GRIDPACK_DEFINITIONS})
   17 include_directories(BEFORE ${CMAKE_CURRENT_SOURCE_DIR})
   18 include_directories(BEFORE ${GRIDPACK_INCLUDE_DIRS})
   19
   20 add_executable(myapp.x
   21   myapp_main.cpp
   22   mayapp_driver.cpp
   23   myapp_file1.cpp
   24   myapp_file2.cpp
   25 )
   26 target_link_libraries(myapp.x ${GRIDPACK_LIBS})
   27 
   28 add_custom_target(myapp.input
   29 
   30   COMMAND ${CMAKE_COMMAND} -E copy 
   31   ${CMAKE_CURRENT_SOURCE_DIR}/input.xml
   32   ${CMAKE_CURRENT_BINARY_DIR}
   33 
   34   COMMAND ${CMAKE_COMMAND} -E copy 
   35   ${CMAKE_CURRENT_SOURCE_DIR}/myapp_test.raw
   36   ${CMAKE_CURRENT_BINARY_DIR}
   37 
   38   DEPENDS 
   39   ${CMAKE_CURRENT_SOURCE_DIR}/input.xml
   40   ${CMAKE_CURRENT_SOURCE_DIR}/myapp_test.raw
   41 )
   42 add_dependencies(myapp.x myapp.input)

Lines 1-6 check to see if the CMake installation is recent enough and
also make sure that the ``GRIDPACK_DIR`` variable has been defined
in the configuration step. If it hasn’t, then the CMake will try and use
a default value and look for a build
in ``$HOME/gridpack-install``. However, this is unlikely to
be successful, so it is better to define ``GRIDPACK_DIR`` when
configuring your application. Line 8 picks up a file that is used by the
application build to link to libraries and header files in the GridPACK
build and line 10 can be used to assign a name to your application.
Lines 12-18 can be included as is, if all application files are in the
same directory as the CMakeLists.txt file. If other directories contain
source and header files, then they can be included using the directives
in lines 17 and 18.

Lines 20-25 define the name of the executable and all the source code
files that are used in the application. The ``add_executable``
command on line 26 adds the executable ``myapp.x`` to the build. The
arguments to this command consist of the name of the executable followed
by the executable source files. There can be an arbitrary number of
source files associated with any one executable. Note that the source
files just consist of the user application source files, the framework
files are handled automatically. If some of the files are located in
subdirectories, then the path relative to the directory where the
CMakeLists.txt file is located should be included.

The remaining lines 28-42 are optional and can be used to automatically
copy files from the application source file directory to the build
directory. These could include example input files or external
configuration files that are called by the code to set internal
parameters. The ``add_custom_target`` command on line 28 defines a
list of files and what should be done with them. In this example, the
two files ``input.xml`` and ``myapp_test.raw`` are the files to
be copied. The ``COMMAND`` line specifies the action (copy) and the
next two lines specify the location of the file to be copied and its
destination. The ``DEPENDS`` keyword (line 38) indicates that any
time the ``input.xml`` or ``myapp_test.raw`` files are modified,
they should be recopied to the build directory if make is invoked and
the ``add_dependencies`` command (line 42) binds the custom target
to the build of the executable.

A template file for ``CMakeLists.txt`` can be found in the
``src`` directory under ``CMakeLists.template.txt``. Users
should copy this file to their application directory, modify the name to
``CMakeLists.txt`` and add their own source files and test input.