-
Notifications
You must be signed in to change notification settings - Fork 3
Open source Distributed Network Protocol
License
cverges/dnp3
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
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. ## Generate Debian Package ## *Dependencies -- once per compile machine* sudo apt-get install -y \ dh-make devscripts dh-autoreconf \ libboost-all-dev \ oracle-java7-installer \ swig *Common variables used below* export PN="opendnp3" export PV="1.1.2" export P="${PN}-${PV}" export ORIG_TARBALL="${PN}_${PV}.orig.tar.gz" # Step 1 - create the .orig.tar.gz file git clone github:sentient-energy/dnp3.git ${P} rm -rf ${P}/debian/ ${P}/.git tar cfz ${ORIG_TARBALL} ${P} rm -rf ${P} # Step 2 - create the DEB(s) git clone github:sentient-energy/dnp3.git ${P} rm -rf ${P}/.git cd ${P} debuild -uc -us # Step 3 - get the DEB(s) cd .. ls -la *.deb
About
Open source Distributed Network Protocol
Resources
License
Stars
Watchers
Forks
Packages 0
No packages published
Languages
- C++ 69.5%
- XSLT 20.3%
- HTML 6.0%
- C# 3.1%
- Ruby 0.5%
- Scala 0.4%
- Other 0.2%