Installing_OWLNext

Installing OWLNext

This page gives full instructions on how to download and build OWLNext.

• Installing OWLNext
  • Prerequisites
    • OWL license
    • Supported compiler
  • Select a destination
  • Download the source code
    • Option 1: Download a static version (snapshot)
    • Option 2: Download a working copy using Subversion
      • Creating a working copy with write-access (for developers only)
    • Option 3: Download the Embarcadero installer and patch files
  • Perform build setup
    • Skipping automated build setup
  • Build the libraries
    • Prepare your build tools
    • Using OWLMaker
    • Using command line
    • Using IDE
  • Test the installation
  • Set up your IDE
  • Link the libraries
  • Get the OWLNext API documentation

---

Prerequisites

To use OWLNext you need an OWL license and a supported compiler.

OWL license

OWLNext is based on the Object Windows Library (OWL) which is copyrighted software owned by Embarcadero Technologies (acquired from Borland Software Corporation as part of its CodeGear division in 2008). To use OWLNext, you need a license to use OWL 5, e.g. from the purchase of a legacy product that includes OWL, such as Borland C++ 5.0-5.02 or C++Builder 4.0-XE2. Note that later Embarcadero products may not include OWL. If you cannot get hold of a product that includes OWL, you may try to contact Embarcadero directly about obtaining a license to use OWL.

Supported compiler

To build and use OWLNext you need a compiler on our list of Supported Compilers. The OWLNext installation procedure is similar for all the supported compilers, and is described in the following sections.

---

Select a destination

Create a directory for the OWLNext installation on your machine. It is important to install OWLNext in a directory for which you have full rights and which is not protected by Windows UAC. Otherwise the OWLNext build scripts may not be able to write and update files. For these reasons, you should not install OWLNext in the "Program Files" or "Program Files (x86)" folders. We recommend using "C:\OWLNext".

Note about naming: Old versions of OWLNext may not support spaces in the root path. Version 6.30.13, 6.36.4, 6.44, 7.0 and later versions should handle this fine, though. However, some legacy toolsets, such as Borland C++ and Embarcadero's BCC32, may require that the disk volume supports short filenames (8.3 format aliases). In modern Windows, short filename support is only enabled for the system drive (usually "C:") by default.

---

Download the source code

Note: We use the Subversion system for source code version control. If you are not familiar with this system and the associated terminology ("working copy", "trunk", "branches", "tags"), see the FAQ for help.

You have two options: Either download a static snapshot of the version of OWLNext you want, or use a Subversion client to create a working copy for one of the release branches. In the latter case, you can thereafter keep the working copy up-to-date using the Subversion commands.

A third option, now obsolete, is to use the Embarcadero installer for OWLNext 6.32, which can be further upgraded to version 6.34 via patch files. However, it is outdated, and we do not recommend its use. It is only documented here for completeness.

Make sure that the selected version supports the compiler you intend to use. The later versions of OWLNext have dropped support for the older compilers. See Supported Compilers. For more information about the OWLNext versions and the related changes, see OWLNext Releases.

Option 1: Download a static version (snapshot)

Available source code archives, including the latest version, can be downloaded using our automated build tool OWLMaker. See the OWLMaker user guide for more information on installing and using OWLMaker.

If you are not using OWLMaker, you can manually download the archive you want from our Files area:

• OWLNext Files/source

Only the most important releases are included here. If you want a different version, go to the Code section and select its tag directory in the repository:

• tags

Here you can select the command link "Download Snapshot" in the page banner. SourceForge will then generate a snapshot for you and start the download.

Extract the downloaded ZIP file. Then move the contents into the destination directory prepared earlier. Note that the downloaded ZIP file (in particular, if generated using the snapshot feature) may include an extraneous parent folder. If so, move the contents of this folder, not the parent folder itself. Your OWLNext destination folder should now contain something like this:

documentation
examples
include
source
OWLNext License.txt

Older versions may have slightly different contents, but the "include" and "source" directories should always be present.

Option 2: Download a working copy using Subversion

To use this option, you need to first install a Subversion client, e.g. the highly recommended TortoiseSVN. Then use the Subversion command "svn checkout" to create a working copy. The "svn:" path for the OWLNext repository is found in the Code section. Go to the project Code section and browse to the version that you want. Here are the currently supported versions:

• trunk (OWLNext 8, prerelease)
• branches/7.0 (OWLNext 7.0, latest stable release)
• branches/644 (OWLNext 6.44, Long-Term Support release)

Simply concatenate the repository path and the path to the selected branch or tag. For example, to check out the 7.0 branch into the folder "C:\OWLNext" the command will be:

svn checkout svn://svn.code.sf.net/p/owlnext/code/branches/7.0 C:\OWLNext

If you use TortoiseSVN, just right-click the folder you prepared earlier and select "SVN Checkout". Specify the "svn:" address to the selected branch or tag, and press OK. TortoiseSVN will then download the files into your folder.

To later update the source code, e.g. after a new update has been released on the branch, then use the Subversion command "svn update". Using TortoiseSVN, just right-click the folder and select "SVN Update".

Creating a working copy with write-access (for developers only)

If you are a registered developer on the OWLNext project, and you want a working copy with write-access, which allows you to submit changes to the central code repository, then you must use a repository address using a secure protocol, such as SVN+SSH or HTTPS. Buttons "SSH" and "HTTPS" in the Code section will show the correct address.

For example, to check out the trunk of the code repository into the folder "C:\OWLNext-trunk", using HTTPS for authentication and write-access, the command will be:

svn checkout https://svn.code.sf.net/p/owlnext/code/trunk C:\OWLNext-trunk

In general, developers should submit changes to the trunk of the repository. Only release managers should submit changes to a release branch. Never submit changes to a tag. For these reasons, tags and branches should normally be checked out read-only using the plain SVN protocol ("svn:").

If you want to register as a developer, contact us in the discussion forum.

Option 3: Download the Embarcadero installer and patch files

Note: This option is obsolete. It is only included here to document how the old patch system worked. Prefer the previously described ways to obtain the source code for the version you want.

This installation procedure relies on a base version of OWLNext 6.32 made available by Embarcadero. The base version can then be patched to later versions. Start by downloading the full installer for OWLNext 6.32 from Embarcadero. Note that access to the download requires registration for a free membership of the Embarcadero Developer Network (EDN).

• Item ID: 28415, OWLNext (Object Windows Library)
  Version: 6.32.1.1123
  Size: 60,131,785 bytes
  MD5 Hash: 215F816542DB274930372F835D5A7D3F

Unpack the downloaded file and run the installer. When prompted for a folder, select the destination folder prepared earlier. The setup file will create a full installation of OWLNext including examples, documentation and tools. This serves as the base installation for applying OWLNext updates. After the installation, the OWLNext root should contain the following sub-folders:

bin
examples
help
include
lib
obj (may first appear after build)
source
tools

The full version number for the base version should be 6.32.1.1123. See the file "include/owl/version.h" for the full version number. Updates to the base version are provided as executable patch files. When run, a patch file will automatically update your OWLNext installation. The available patch files are found in our Files download section:

• OWLNext Files/obsolete

After you have downloaded a patch, extract the executable and open it. When prompted, select the root folder of your OWLNext installation and click Next. The patch installer will verify the sources, then if everything is OK, it will apply the patch. If you get an error message saying that the patch cannot be applied, it is usually because some file in your OWLNext installation has been modified. Restore the file in question, or do a full reinstallation of the OWLNext base version. Then try again.

---

Perform build setup

OWLNext 6.32 and later versions require build setup. This involves generating the file "include/owl/version.h" based on information about the version of the source code. OWLNext 6.30 and earlier versions do not require such setup. These older versions have the version header file as part of the source code.

For OWLNext 6.32 and later, the build scripts can use the SubWCRev tool included with TortoiseSVN to automatically generate the version header "include/owl/version.h" based on the template file "source/owlcore/version.h". The generated version header will have accurate information about the code, such as revision number and revision date. So if you have TortoiseSVN installed, and you have checked out a working copy of the code, you can skip to the next section.

Otherwise, if SubWCRev is not installed, or the OWLNext root directory is not a Subversion working copy, the build scripts will create a crude version header with revision number 0 instead. You may want to correct the header manually to reflect the accurate revision number and revision date of the code (see Code logs). However, this is not strictly necessary.

Older source code from tags and earlier branches may have outdated build scripts that may require manual build setup. In this case, you will have to generate the version header by hand:

1. Copy "source/owlcore/version.h" to "include/owl/version.h".
2. Open "include/owl/version.h" in an editor.
3. Replace "$WCREV$" by the revision number of the code (see the code repository log).
4. Replace "$WCDATEUTC$" by the revision date.
5. Replace "$WCMIXED?1:0$" and "$WCMODS?1:0$" by 0.
6. Save.

The source code is now ready to be built.

Skipping automated build setup

If you have not installed TortoiseSVN, and you instead perform manual build setup as described earlier, you may get a warning that the automated build setup failed. To skip the automated build setup, pass the argument "SETUP=0" to the makefile, or if you use OWLMaker, simply turn off the option "Perform build setup".

---

Build the libraries

There are multiple ways to build the OWLNext libraries: Use OWLMaker, the command line, or an IDE. We recommend using OWLMaker, as this is the easiest way to configure the build parameters.

Prepare your build tools

Make sure that your compiler installation have all the libraries necessary, such as the Windows SDK, set up and ready. In particular, some versions of OWLNext require the Boost library to compile with Embarcadero C++Builder/RAD Studio, and Boost may not be installed by default. If it is not, go to the GetIt Plugin Manager within the IDE and install it. Make sure that the installation path agrees with CG_BOOST_ROOT in the make-files, otherwise you will get compilation errors (see [bugs:#549]).

Note about legacy toolsets: Some legacy toolsets, such as Borland C++ and Embarcadero's legacy toolset (BCC32), may require that support for short filenames (8.3 format aliases) is enabled for the disk volume on which the toolset is installed. Otherwise, the OWLNext build may fail. In modern Windows, short filename support is only enabled for the system drive (usually "C:") by default. Hence, we recommend installing your build tools on the system drive in the default location (usually within "C:\Program Files" or "C:\Program Files (x86)").

Using OWLMaker

OWLMaker lets you specify the build options interactively and then invokes the makefiles automatically. See OWLMaker User Guide for more information on installing and using OWLMaker.

Using command line

If you prefer working on the command line, you can use the provided scripts (makefiles and drivers) for the supported compilers.

Driver	Makefile	Compiler
vcmake.bat	vc.mak	Microsoft Visual C++
bcmake.bat	bc.mak	Borland C++/Embarcadero RAD Studio/C++Builder (classic toolset)
(none)	owl.cbproj	Embarcadero RAD Studio/C++Builder (Clang toolsets)

For example, to build the core OWLNext libraries for Visual C++, open the "Visual Studio Command Prompt", and type the following commands:

cd "%OWLROOT%\source\owlcore"
vcmake

The 'vcmake' script will build core libraries for the 8 combinations of link, debug, and character set build modes.

Here is an example of using the makefile for Visual C++ directly to build the static debug version and passing on the "/MP" option to the compiler (which instructs it to use multiple threads to build on multi-core and multi-processor systems):

cd "%OWLROOT%\source\owlcore"
nmake -f vc.mak DEBUG=1 OPT=/MP

See the makefile for other build modes and options (such as "COMPAT=5" for OWL5_COMPAT mode).

Here is an example of calling MSBuild on the command line to build OWLNext 7.0 in 64-bit debug build mode using the Embarcadero C++Builder 11 Clang-based toolset, including automatic build setup:

cd "%OWLROOT%\source\owlcore"
msbuild CB\owl.cbproj /t:Clean;Build /p:Config=Debug;Platform=Win64;OWLNextVersion=7.0;OWLNextCompilerVersion=760;OWLNextSetup=true

Using IDE

IDE project files for Visual Studio and C++Builder can be found in the source directories. These will let you build the libraries, but note that you may have to configure the project properties to set up the build with the desired options. You may also have to perform manual build setup before the build, and you may have to rename the target files, so that they correctly match our library file naming convention.

---

Test the installation

To test that everything is set up correctly, you may want to build and run the example projects provided in the examples folder created by the installation. See Examples for an overview of some of the available examples.

---

Set up your IDE

To set up an OWLNext project (e.g. in Visual Studio) you just need to point the compiler at the OWLNext "include" and "lib" directories (Configuration Properties | VC++ Directories), set the character set mode (Configuration Properties | General | Character Set) and the RTL link mode (Configuration Properties | C/C++ | Code Generation | Runtime Library). For dynamic linking you also need to define _OWLDLL (Configuration Properties | C/C++ | Preprocessor | Preprocessor Definitions), although static linking is recommended (see "Should I use static or dynamic linking (DLL)?").

Take a look at the example projects located in the "examples" folder. Most of the examples have ready-made project files for C++Builder and Visual Studio. Also, our download area contains project templates for various versions of Visual Studio and C++Builder.

Here are more specific instructions on how to set up some of the popular Integrated Development Environments:

• Borland C++
• C++Builder 2007/2009
• C++Builder 2010
• C++Builder XE2
• Visual C++ 2008
• Visual Studio 2010-2022
• Installing the OWLNext Application template for Visual Studio

If your IDE is not listed and you need help setting it up, post a request for help in the Open Discussion forum.

---

Link the libraries

To link OWLNext in your own projects, you do not need to explicitly specify the OWLNext library file to the linker, since OWLNext uses auto-linking controlled by pragma statements in the library headers. See "include/owl/private/owllink.h".

If you are using the old Borland C++ IDE, see FAQ for advise on how to turn off linking with the old OWL.

For details on the naming of the library files, see our library file naming convention.

---

Get the OWLNext API documentation

You can access the online OWLNext API Documentation from the wiki Main Page. Alternatively, you can look for an offline help file in our Files download area. If you cannot find the version that you want, you may build the documentation yourself from the source using Doxygen. See the Doxygen documentation for details.