open-dnp3
      Copyright (c) 2010, 2011 Green Energy Corp.
      
      This project is licensed under the terms of the Apache Public License
      v2.0.  For additional details on licensing terms and conditions, see
      COPYING.
      
      For more information about the OpenDNP3 library, visit the project
      website at http://code.google.com/p/dnp3.


Overview
========

The OpenDNP3 library and testset is a portable, scalable, and
rigorously tested implementation of the DNP3 (www.dnp.org) protocol
stack written in C++ and provided by Green Energy Corp to the community
under the Apache 2.0 license.  The library is optimized for massively
parallel front end  processor implementations and slave device
simulations, although it has been verified to perform very well on
embedded linux ARM architectures. It includes a command line
master/slave test set.


Building and Installing
=======================

The OpenDNP3 library can be built in Linux using GNU autotools or in Windows
using the provided Visual Studio projects.

## GNU autotools ##

The GNU autotools are comprised of two packages, GNU autoconf and GNU
automake.  Libtool support is required.  Lcov and swig support may be
required if you choose to build those options.

Requirements:

  - astyle v2.01 or later           (required if 'make astyle')
  - boost v1.42 or later            (required)
    * boost::date_time              (required)
    * boost::program_options        (required)
    * boost::system                 (required)
    * boost::thread                 (required)
    * Boost Unit Test Framework     (required)
  - docbook v0.6.14 or later        (required if 'make docs')
  - lcov                            (required if 'make lcov')
  - libtool                         (required)
  - swig v1.3.17 or later           (required if 'configure --with-java')
  - Java JDK with JNI support       (required if 'configure --with-java')
  - Python 2.6 or later             (required if 'configure --with-python')

To start, first reinitialize autotools to be compatible with the version
running on your system:

      autoreconf -f -i

Next, create a build directory and run the 'configure' script:

     mkdir build
     cd build
     ../configure

A full list of options can be found using 'configure --help'.

You can now build the OpenDNP3 libraries and programs:

      make

When ready, you can install the libraries, headers, and programs onto
your system:

      make install

If you want to generate the book "OpenDNP3 Library: The Definitive
Guide," use one or more of the following make target after configuring
the system:

      make docs
      make docs-html
      make docs-pdf

The resulting book will be placed in a subfolder inside of the 'docs'
folder.

If you want to build the doxygen code documentation, use the following
make target after configuring the system:

      make doxygen-doc

The resulting HTML documentation will be placed in a folder named
'doxygen-doc'.

If you want to build the libraries with lcov support (analysis tool for
code coverage of the unit/integration test infrastructure), the process
changes slightly:

      autoreconf -f -i
      ./configure --enable-lcov
      make
      ./test-dnp3
      make lcov

The lcov HTML report is written to './lcov/html/index.html' and can be
opened with any standard web browser.

If you will be making changes to the unit/integration test
infrastructure while analyzing the lcov results, use an alternate
sequence to reduce the amount of rebuilding required:

      autoreconf -f -i
      ./configure --enable-lcov
      make
      ./test-dnp3
      make lcov

Iterate on the following sequence after changing the tests:

      make lcov-reset        ; # Reset lcov data between each run
      make                   ; # Rebuild with the new changes
      ./test-dnp3            ; # Profile the new changes
      make lcov-report       ; # Regenerate the lcov report

If you are a developer and are making changes to the OpenDNP3 library
code, you can run the 'astyle' utility to ensure that your code
conforms to the style guidelines used for the project:

      make astyle

Please run this utility before submitting any patches to the project.

If you want to build the Java bindings for the OpenDNP3 library, make
sure that your system has both swig and a valid JDK installed.  Enable
the build tree to create the Java library:

      autoreconf -f -i
      ./configure --with-java=/path/to/jdk/include
      make

The Java source files are created in the 'maven' build directory, which allows 
for compiling, testing, and publishing the Java sub-project with Maven.

If you want to build the Python bindings for the OpenDNP3 library, make
sure that your system has both swig and a valid Python interpreter
installed.  Enable the build tree to create the Python library:

      autoreconf -f -i
      ./configure --with-python
      make

The Python library is called pyopendnp3.  The Python class and shared
library are installed to the 'opendnp3' package directory.


## Windows / Visual Studio ##


A solution and project files for Visual Studio 2010 can be found in the `vstudio10` directory.

The Visual Studio solution is organized as a set of projects of libraries and
executables.

The main libraries are:

  - *APL*            - Portable functionality for things like parsing, physical layers, logging
  - *APLTestTools*   - Library of tools/mocks uses for testing
  - *DNP3*           - Protocol library for dnp3
  - *Terminal*       - Extensible library for creating command line driven UI
  - *DNP3Java*       - Library generated by swig that wraps the stack with JNI

The main executable targets are:

  - *TestAPL*        - A test suite for the protocol framework library
  - *DNP3Test*       - A test suite for the DNP3 library
  - *TerminalTest*   - A test suite for the Terminal library
  - *TestSet*        - A dnp3 command line master/slave test set.


External Dependencies/Miscellaneous
===================================


### Install Boost ###

If possible, install the boost libraries packaged for your OS distribution. 
Otheriwse, you can build and install the boost libraries and headers by 
running the following helper script:

   cd tools/install_scripts/boost/{VERSION}
   ./install-boost.sh

This step will take some time as it retrieves the boost package and
builds from source.


### TOOLS_HOME ###

The Visual Studio build expects the Boost libraries to be installed to 
a path specified by the TOOLS_HOME environment variable. Set it to an 
appropriate directory for installing tools and libraries. The Boost 
install scripts also copy the Boost distributables to this location.

- On Windows this variable is set via:
   Start Menu > ControlPanel > System > Advanced > EnvironmentVariables


### Installing ARM Cross-Compiler ###

If you want to build for the Technologic Systems ARM platform, install
the cross-compiler:

      cd tools/install_scripts/crosstool
      ./install-crosstool.sh

It is important that this step be completely successfully prior to the
boost installation, as the Boost libraries will be built for ARM as well
as your platform.