README

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.


Organization
============

The repository 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 PSI 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.


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

The OpenDNP3 library has been verified under linux, cygwin, and windows.
Three build systems are included:

  1. GNU g++ and the rake (ruby make) build system provided
  2. GNU autotools (experimental)
  3. Visual Studio SLN and PROJ files

## GNU rake (ruby make) ##

## Common Dependencies for all platforms ##

Set the TOOLS_HOME environment variable to an appropraite path for
installing tools and libraries. Reasonable choices are C:\Tools or
~/tools.

- On cygwin/windows this variable is set via:
   Start Menu > ControlPanel > System > Advanced > EnvironmentVariables

- On Linux systems its common to add the following line to ~/.bashrc
   export TOOLS_HOME=~/tools

## Configuring CYGWIN ##

Get a copy of setup.exe from www.cygwin.com. Hold onto setup.exe as you
may need it to install additional packages.

You will need the following additional packages to build the C++
libraries and tests. Please be careful to get the correct version if
noted below:

- Web -> wget         // used in install scripts to retrieve packages
- Devel -> gcc-g++    // C++ compiler (version 3.4.4, not tested on gcc4x)
- Devel -> cache      // C compiler cache for improving recompilation
- Devel -> make       // GNU version of make utility
- Devel -> ruby       // Scripting language we use it for build scripts
- Devel -> libtool    // Shared library generation tool

Optional packages:

- Devel -> swig       // C/C++ wrapper generator used for Java bindings
- Devel -> doxygen    // documentation system for C++

Doxygen needs GraphViz. Download and install GraphViz:
http://www.graphviz.org/Download_windows.php

The msi installer will put a program called dot onto your path that
doxygen needs to generate images.

## 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.

## Install Boost ##

Install the boost libraries and headers by running the 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 for both your platform and for ARM.

When the boost version we are using is updated we will update the
references in rakefile.rb and config/boost_*.vsprops to use the new
version name and include updated installers to compile the new version,
if after and update the build suddenly fails with missing boost include
errors errors check that the boost version hasn't been upgraded
recently.


## Install Ruby Gems and Rake ##

RubyGems is a package delivery system for ruby libraries. Follow the
instructions from the RubyGems website to install:

http://rubygems.org/

Rake is a ruby gem. To install rake:

   gem install rake

## Creating Native -> Java (JNI) Bindings ##

We have created native bindings for java using SWIG. Prior to version
0.9.3, the native libraries where embedded into the jar file and
extracted before use on the target. This caused us problems with OSGi
and made integrating the jar difficult with some build tools.

The shared library must now be installed in a directory found on the
java.library.path. Typical locations are /usr/lib or
C:\<windir>\System32.

We keep some precompiled versions of the library on the project site for
various platforms.

1) Use rake to generate the bindings and build the shared library. This
   step also outputs the java code.
2) cd to the DNP3Java dir and use Maven to build/deploy the jar.


## Building the libraries and tests ##

Use rake to build. To see a list of targets and their descriptions,
type:

   rake -T

rake understands dependencies similarly to the GNU make utility. To
build and run the dnp3test executable, type:

   rake dnp3test:run

Flags not documented by Rake -T:

- debug=true       // debug mode, compiler generate debug information to
                   // use with gdb, etc

- arm=true         // crosscompile for arm, requires the arm cross
                   //compiler to be installed w/ arm Boost libs

- coverage=true    // compile with coverage information

- SH_VERBOSE=true  // print every command that rake issues to the shell

### Examples ###

   rake                                       // build everything

   rake arm=true                              // build everything in
                                              // release mode for arm

   rake dnp3test:run debug=true               // build and run the
                                              // dnp3test w/ debug info

   rake dnp3test:run["--show_progress=true"]  // run the test in release
					      // mode, w/ arg for
					      // Boost.Test

## Generating Code Coverage ##

To generate documentation for the code coverage of the unit tests
relative to the rest of the stack, you will need to have lcov installed
before invoking:

   rake dnp3test:run coverage=true

Be patient, this generates several megabytes of data.

The HTML output will be generated in at
./coverage-DNP3Test/html/index.html.

## Generating Documentation ##

To generate documentation for the stack you need to have doxygen and
graphviz (dot) installed before invoking:

   rake document

Be patient, this generates hundreds of megs worth of images.

The HTML output will be generated in ./docs.

### Building the Java bindings ###

The Java Developers Kit (JDK) and Swig are required to build Java
bindings. Install Open JDK 1.6 or greater.

Set the JAVA_HOME directory to the install path of your JDK version.

### Deploying the jar ###

The deployment tasks require Apache Buildr to be installed:

   gem install buildr

There are 2 tasks for deploying the jar:

- dnp3java:install : copies the file to your local maven repository
		     (doesn't overwrite an existing build so delete that
		     library first)

- dnp3java:upload  : uploads the file to the remote maven repository
		     (this should generally only be done by the build
		     server)

## 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, run the 'configure' script:

  ./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
  ./dnp3test
  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
  ./dnp3test
  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
     ./dnp3test             ; # 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 'src' directory structure.

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.