How do I report a bug?
Holders of an OpenTop commercial licence with a current support
create a small program or section of code that
demonstrates the problem and mail it to firstname.lastname@example.org with the following
- operating system
- compiler (vendor and version)
- standard library (vendor and version)
- support agreement number
We will endevour to respond within 24 hours, often much sooner.
How do I make a Windows version using Visual C++?
The generic OpenTop make files are not currently able to
make a Windows version using Visual C++. However, OpenTop is supplied
with purpose-built Visual C++ project files which can be used to create all the
supported targets. The following VC project makefiles are located in the
| for static and dynamic OpenTop libraries
| for static and dynamic xml extension libraries
Please see Is the STL bundled with Visual C++ thread-safe? if you are planning to build a multi-threaded
version using the bundled Dinkumware STL.
How do I make a Linux version?
The OpenTop build process follows standard conventions
under Linux and UNIX:-
- Extract the source files
Extracting the source
- Copy the latest source tar file into a suitable directory
- Extract the source using
tar -zxf opentop-n-n-n.tar.gz
If you do not have GNU tar, you may have to use a utility
to uncompress the archive first such as
zcat opentop-n-n-n.tar.gz | tar -x
The configure script updates the OpenTop header and make files
with details of your operating system features.
To run this script
change the current directory to
opentop and execute
./configure. It is not usually necessary to pass any parameters
configure unless you want OpenSSL support (see How do I enable OpenSSL support when building OpenTop?).
In order to build OpenTop you can simply type make all from the
opentop directory. This will build all the configurations,
of which there are currently 24!
If you decide to make all configurations you should expect this to
take a little while, so this may be a good time to read the
See How do I specify which configuration to build? for further
information about saving time by only creating the configurations that you need.
The OpenTop libraries are built into the
Neither the build library files nor the header files are automatically
copied to an installation directory.
ElCel Technology suggests that you copy the header files into a common include
directory such as
/usr/local/include/opentop. Please make sure
you retain the original directory structure, such as the following:
How do I make a UNIX version?
Building a UNIX version of OpenTop is the same as building a
Linux version (see How do I make a Linux version?) but with two prerequisites: your system must have
GNU Make installed and include a relatively up-to-date C++ compiler.
The OpenTop UNIX-style makefiles use the GNU Make syntax and are
NOT compatible with many other flavours of Make. Before attempting to
build OpenTop on a UNIX platform, please check you have GNU make installed.
It may be obtained from
GNU Make is available in both source code and binary form for all the
platforms supported by OpenTop. When you have installed GNU make, replace the
'make' command with 'gmake',
or whatever name has been given to the GNU make program on your system.
By default, the OpenTop UNIX configuration script assumes that you will be using
g++ as your C++ compiler. If you wish to use a different compiler, then you need
to specify it using the CXX flag. See How do I override the compiler used by the UNIX-style makefiles? for further details.
How do I override the compiler used by the UNIX-style makefiles?
The OpenTop configure script attempts to automatically
detect the C++ compiler on your system. If you wish to compile using
a different compiler to the one chosen by configure you can
do so by overriding the CXX make flag.
Changing from one recognized compiler to another
This is the simplist case, where you wish to change the chosen compiler from,
say, g++ to Sun's Forte compiler known as CC. To achieve this, first ensure the
PATH environment variable contains the location of the desired compiler,
then alter the make command to specify the chosen compiler like so:
make all CXX=compiler-name
(Please note that if you choose to make the 'all' target it will take some time
so you may wish to choose a more restrictive target).
Invoking a custom compiler
The UNIX-style OpenTop makefiles use the CXX environment variable
to specify the name of the C++ compiler to use. Generally this is set
by the configure script and can be left untouched. However,
if you wish to use a different compiler, or your compiler is located in
a non-standard location, then you may need to create a custom compiler
configuration file within the buildtools directory.
To create a new compiler configuration file, the easiest thing is to copy
one of the existing XXX_compiler_options files and rename
it to compiler-name_compiler_options, where XXX is replaced
by the symbolic name you will set CXX equal to when you invoke make.
Edit your new compiler_options file using the comments at the top of the
buildtools/compiler_options file to guide you to which macros
to set. Among other things, this allows you to specify the compiler file
to execute, which need not reside in your PATH.
When you are done, alter the make command to specify the chosen custom compiler like so:
make all CXX=compiler-name (where compiler-name
is the XXX prefix in the XXX_compiler_options filename.)
Note: in OpenTop versions prior to 1.3, it was necessary to amend
buildtools/compiler_options to associate your chosen
symbolic name with the new configuration file.
How do I make a Borland C++ Builder version?
Unlike for Microsoft Visual C++, we do not provide Borland C++ Builder project files,
but the generic (UNIX-style) makefiles can be used instead. However, before
using these generic makefile under Windows, a few things need to be
- There is no need to run the configure script under Windows as
Windows configuration options are picked up automatically.
- The generic makefiles use the
GNU Make syntax (which differs slightly to the
syntax supported by Borland's make), so it is necessary
to use a WIN32 port of GNUMake. We have found that the version of GNUMake
that comes with Cygwin does not work correctly.
It seems that the OpenTop recursive build under Windows requires a native WIN32 GNU Make.
We suggest downloading the version from
http://unxutils.sourceforge.net/UnxUtils.zip which does the job.
After downloading and unzipping the UnxUtils make, ensure the Borland
compiler binaries are available in your path and execute the following command
to make the OpenTop libraries, sample apps and test harnesses:-
By default this command builds the debug, multithreaded, narrow char,
See How do I specify which configuration to build? for further information about building different targets.
How do I enable OpenSSL support when building OpenTop?
OpenTop versions 1.4 and above include support for OpenSSL
to be used as a security provider. With OpenSSL enabled, OpenTop's SSL facilities
such as HTTPS URLs and SSLSockets become available for use within your applications.
Please note that OpenSSL is provided under licence and that its
use is subject to a few minor restrictions. Further information
may be found in the LICENCE file supplied with the OpenSSL
Enabling OpenSSL under Linux/UNIX
To enable OpenSSL support, the OpenTop library must be configured
with the --enable-openssl option specified. e.g:
The configure script will search for the OpenSSL library and include
files in the standard locations. If you have installed OpenSSL in a non-standard location
then you will need to specify the OpenSSL include and library locations using the following options:-
Enabling OpenSSL under Windows
Firstly you will need to download and build OpenSSL on your platform. See How do I build OpenSSL to be compatible with OpenTop?.
There is no configure script for Windows, so optional features such as
OpenSSL support are communicated to the Visual C++ compiler via the following environment
||Set to '1' to enable OpenSSL support; otherwise set to '0' or nothing. e.g.
||Set to the directory when OpenSSL has been installed. The project makefiles
will expect to find a inc32\openssl sub-directory containing
the OpenSSL header files and a out32 sub-directory containing the
binary LIB and DLL files.
Note: the above environment variables must be set prior to starting Visual C++ so
that their value is visible to the Visual C++ compiler.
How do I build OpenSSL to be compatible with OpenTop?
If you wish OpenSSL support under Linux and UNIX variants, you can configure,
make and install OpenSSL in the usual way.
Unfortunately the same is not true on the Windows platform because the OpenSSL library
must be specifically built to use variants of the C/C++ runtime libraries which are
compatible with those used by OpenTop.
Steps to build OpenSSL on Windows
- Download the most recent version of OpenSSL from www.openssl.org.
We recommend using version 0.9.7d or above as all earlier versions are compromised
in one way or another.
- Extract the OpenSSL source from the downloaded zip/tar file into a local directory.
- Read and follow the instructions in the INSTALL.W32 file from the OpenSSL distribution.
This will show you how to create the necessary makefiles and build a default version of the OpenSSL
libraries. Note that you will need to have a version of perl installed to
create the necessary makefiles.
- Edit the two files called ms\libeay32.def and ms\ssleay32.def. These text
files have LIBRARY directives followed by hard-coded library names. The library name
is an optional parameter for the LIBRARY directive, but it MUST be removed prior to
building OpenSSL for compatibility with OpenTop. This is necessary because the specified name conflicts
with the modified name used for the OpenTop-compatible DLLs.
- The OpenTop source distribution contains a file called misc\w32_openssl.bat.
This batch file uses the custom makefiles created by step (3) to build custom version
of the OpenSSL libraries for static/dynamic linking, debug/release mode and single/multi-threading.
You can now execute this file (from the OpenSSL base directory.
The resulting libraries are given specific names following a similar convention to the OpenTop
Once OpenSSL is built in all its various configurations, you're ready to build OpenTop with SSL support.
Is the STL bundled with Visual C++ thread-safe?
The standard library shipped with Visual C++ 5.0 and 6.0 is not
thread-safe, therefore you should not attempt to build multi-threaded
versions of OpenTop using this library. However, the modifications
required to fix the library are simple and Dinkumware have supplied
patches which can be obtained from their web site:
Alternatively, you can use other third-party standard libraries which
are thread-safe. One good example is STLPort.
How do I specify which configuration to build?
There are 4 variables which are used to control the build process:-
- Threading: single- or multi-threaded
- Character type: wide (
wchar_t) or narrow (
char). Narrow may be configured to use UTF-8 or Latin-1 encoding.
- Mode: release or debug
- Binding: static or dynamic linking
Each variable has 2 possible values (except Character which has 3), hence we have 2*2*2*3 (24)
possible configurations! Pseudo make targets exist for all the possible
configurations. These targets follow the following naming convention:-
So, for example, to build a multi-threaded, narrow-character (UTF-8), debug,
static library you would simply enter the following command:
The same pseudo target names are available in the MSVC project files.
In addition to the individual pseudo targets, the OpenTop make files
also contain some convenient group targets. Take a look at the targets
How do I provide trusted root CA certificates for SSL?
When a client application initiates a secure connection
with a SSL/TLS server (for example when using the HTTPS protocol),
the server normally sends a X.509 certificate chain as part of the initial handshake.
The client verifies the identity of the server by checking the chain's
root certificate against its database of trusted Certificate Authority (CA)
certificates. If it finds a match then the identity of the server is confirmed, otherwise
the handshake will fail with a
During initialization, an application that uses SSL/TLS
should provide OpenTop with the location of its trusted CA certificates.
When OpenSSL is used as the security provider, these CA certificates
can be located in a single PEM-encoded file (sometimes known as a ca bundle),
or they can be located in individual files located within a named directory.
Both of these options are supported by the SSLContext class,
which provides the initialization mechanism. The
API documentation for SSLContext
provides all the detail you need.
Root CA certificates should be obtained from a trusted source
and stored in a tamper-proof location, otherwise the security
of the application is compromised. Root certificates can usually
be obtained from the CA's web site, but each CA will provide
only their own certificate and there are a growing number
of CA's in general use. Another good source of root CA
certificates is your web browser application, assuming that
you trust the provider of the browser and you are willing to accept
their choice of trusted CAs.
The OpenTop source distribution contains the sample CA bundle file:-
which contains certificates
exported from Microsoft's Internet Explorer. This file may be
suitable if you are creating a general-purpose application and you can't predict
which root CAs will be used by the servers your application will connect to.
If you know the specific root CA, then it will be more secure to specify
just that one certificate in your CA bundle file.
What OpenTop library files should I link with?
The current OpenTop distribution is split into two libraries:-
opentop which contains all the I/O, Networking, Threading
and infrastructure code and
otxml which contains the
XML parsers and associated tools.
Namespaces supplied by library
Each OpenTop configuration produces library files with a
common base name (
with a unique suffix. The library suffixes work like this:-
- indicates a multi-threaded build (
OT_MT #defined). If this is
absent it indicates a single-threaded build.
- indicates a
wchar_t build (
OT_WCHAR #defined). If this is absent it
This sets the
ot::CharType typedef and determines whether the OpenTop String typedef resolves to
- indicates a
char build using the ISO-8859-1 (Latin1) internal encoding (
This sets the
ot::CharType typedef and sets the OpenTop String typedef resolves to
- indicates a debug build (
DEBUG #defined). Debug builds include assertions and debugging symbols.
If this suffix is absent it indicates an optimized release build.
- indicates a shared (DLL) library on Windows only - Linux differentiates
between static and dynamic libraries by using different filename
It is imperative that you link your program against a version of the
library that has been built with the same configuration options. This
is achieved automatically with MSVC by use of a
directive, but this is not the case with other compilers.
What system library files should I link with?
The following table shows the libraries on which OpenTop is dependent.
The C++ compiler will automatically link with its associated standard library.
However, if you use the STLPort IO streams
in your project, you will also need to include the STLPort library.
What macros do I need to #define?
The OpenTop library can be built in a number of different ways. As described in
How do I specify which configuration to build?, there are 4 variables which are used to determine which
configuration should be built.
User programs must ensure that the appropriate
macros are defined before the OpenTop header files are included. It is also vital
that all compilation units specify the macros consistently.
|Library name suffix
Can I build a wchar_t version using libstdc++ Version 2?
Yes you can, but first let us explain the problem.
libstdc++ version 2 is an old c++ library that came bundled with GCC 2.9x.
It pre-dates the C++ standard and is therefore not conforming. It is no longer
actively maintained as it has been superseded by
libstdc++ version 3 which
comes bundled with GCC 3.
libstdc++ does not have a typedef for std::wstring. It seems
the reason for this is a bug in basic_string<class T>::c_str() which
attempts to return the constant value "" for an empty string.
This will not compile when T is anything other than char.
OpenTop avoids using the c_str() method, but there is one place where
we just have to use it. However, to enable OpenTop to compile with
libstdc++ v2, we have some conditional code to by-pass the problem
area. The conditional code is invoked when the OT_BROKEN_C_STR
macro is #defined.
So, to build a wide char version using GCC 2.x with the bundled
libstdc++ V2, issue the following command:
make CXXFLAGS=-DOT_BROKEN_C_STR target
How do you produce that great JavaDoc-style API documentation?
Thanks for the complement. The documentation is produced
by first generating an XML representation of the source code using
Doxygen. If you haven't
yet taken a look at this great tool then we recommend that you do so now.
The bare XML is then transformed in a multi-stage XSLT pipeline, resulting
in pages which reproduce the familiar JavaDoc look-and-feel.
Can I sell and distribute applications built with OpenTop?
OpenTop Commercial Licence
allows you to sell and distribute compiled applications that are either statically
or dynamically linked with OpenTop. If your application uses dynamic linking,
you may also include the appropriate OpenTop dynamic library
in your software distribution. There are no runtime fees or additional costs
involved in distributing your application in binary executable form.
You may not distribute the OpenTop source code, header files,
export libraries, build scripts or documentation. Such a distribution would be in
competition with ElCel Technology and would be in violation of the terms of the
OpenTop Commercial Licence.