OpenTop Frequently Asked Questions

Holders of an OpenTop commercial licence with a current support agreement should create a small program or section of code that demonstrates the problem and mail it to support@elcel.com with the following additional information:-

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 ot\ subdirectory:

File	Description
`ot\opentop.dsw`	for static and dynamic OpenTop libraries
`ot\otxml.dsw`	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
Configure
Build
Install

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

Configuring

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 to configure unless you want OpenSSL support (see How do I enable OpenSSL support when building OpenTop?).

Building

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 API documentation.

See How do I specify which configuration to build? for further information about saving time by only creating the configurations that you need.

Installing

The OpenTop libraries are built into the opentop.n.n.n/lib directory. 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:

/usr/local/include/opentop/ot
/usr/local/include/opentop/ot/base
/usr/local/include/opentop/ot/net
... etc

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 www.gnu.org/software/make/make.html.

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

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:-

c:\unxutils\usr\local\wbin\make CXX=bcc32

By default this command builds the debug, multithreaded, narrow char, statically-linked version! 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 distribution.

Enabling OpenSSL under Linux/UNIX

To enable OpenSSL support, the OpenTop library must be configured with the --enable-openssl option specified. e.g:

./configure --enable-openssl

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:-

--with-openssl-inc=<INCLUDE-PATH>
--with-openssl-lib=<LIBRARY-PATH>

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 variables:-

Environment variable	Value
`OT_USE_OPENSSL`	Set to '`1`' to enable OpenSSL support; otherwise set to '`0`' or nothing. e.g. `set OT_USE_OPENSSL=1`
`OT_OPENSSL_DIR`	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 library names.

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: http://www.dinkumware.com/vc_fixes.html.

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:

make debug_multi_char_static

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 defined in buildtools/common_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 SSLPeerUnverifiedException.

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:-

misc/ca-bundle.pem

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
Library	Namespaces included
opentop	`ot` `ot::auxil` `ot::cvt` `ot::io` `ot::net` `ot::util`
otxml	`ot::xml` `ot::sax` `ot::xmlcat`

Suffixes

Each OpenTop configuration produces library files with a common base name (opentop and otxml) but with a unique suffix. The library suffixes work like this:-

<libname><mt><w|l><d><s>.<lib|so|a>

mt: indicates a multi-threaded build (OT_MT #defined). If this is absent it indicates a single-threaded build.
w: indicates a wchar_t build (OT_WCHAR #defined). If this is absent it indicates a char build. This sets the ot::CharType typedef and determines whether the OpenTop String typedef resolves to std::wstring or std::string.
l: indicates a char build using the ISO-8859-1 (Latin1) internal encoding (OT_LATIN1 #defined). This sets the ot::CharType typedef and sets the OpenTop String typedef resolves to std::string.
d: indicates a debug build (DEBUG #defined). Debug builds include assertions and debugging symbols. If this suffix is absent it indicates an optimized release build.
s: indicates a shared (DLL) library on Windows only - Linux differentiates between static and dynamic libraries by using different filename extensions.

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

OS	Build	Libraries required
Linux	Single-threaded	n/a
Linux	Multi-threaded	`libpthread`
Solaris	Single-threaded	`libpthread` `libsocket` `libnls` `libposix4`
Solaris	Multi-threaded	`libpthread` `libsocket` `libnls` `libposix4`
Windows	Any	automatically included

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.

Variable	Choice	`#define`	Library name suffix
Threading	single	n/a	-
Threading	multi	`OT_MT`	`mt`
Character type	`char` (UTF-8)	n/a	-
	`char` (ISO-8859-1)	`OT_LATIN1`	`l`
	`wchar_t`	`OT_WCHAR`	`w`
Mode	release	n/a	-
Mode	debug	`DEBUG`	`d`
Binding	static	n/a	-
Binding	shared	`OT_DLL`	`s`

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?

Yes, the 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.

If you wish to distribute your application in source code form, then your customers will need to purchase a licensed copy of OpenTop from ElCel Technology before they can compile the application. Such customers are required to purchase an OpenTop Commercial Licence for each developer who needs to compile the application and are bound by the same licence conditions.

We understand that this may cause some difficulty to customers who want to distribute source code, but it should not cause an insurmountable problem. It is not really any different to you requiring your customers to have a C++ compiler and standard library. We do guarantee that we will not unfairly discriminate against any customer, so you can rest assured that your customers will be able to purchase OpenTop on the same fair terms as yourselves.