forked from greenenergycorp/dnp3
/
README
217 lines (149 loc) · 7.01 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
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.