Installing_OWLNext_from_the_Code_Repository

Installing OWLNext

This page gives full instructions on how to install OWLNext directly from the project Code Repository at SourceForge using a Subversion client for source code revision control, or simply by downloading a snapshot of a particular release.

• Installing OWLNext
  • Prerequisites
    • OWL license
    • Supported compiler
  • Select a destination
  • Download the source code
    • Download a snapshot
    • Create a Subversion working copy
      • Creating a working copy with write-access (for developers only)
  • 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
  • Get the OWLNext 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). Therefore, you need a license to one of Embarcadero's C++Builder products, or an earlier legacy product, such as Borland C++, that gives you rights to use OWL 5.

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. Do not use a directory name or path that contains spaces. This is important, since the OWLNext build scripts may fail for directory names with spaces. It is also necessary 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 update the files. For these reasons, you should not install OWLNext in the "Program Files" or "Program Files (x86)" folders. We recommend using "C:\OWLNext".

---

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.

In any case, go to the project Code section and browse to the version that you want. Here are the currently supported versions:

• trunk (OWLNext 7 Alpha Prerelease)
• branches/6.44 (OWLNext 6.44)

If you want a specific release, not to be updated, select its tag directory in the repository:

• tags

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.

Download a snapshot

If you just want a static snapshot of the selected version, then select the command link "Download Snapshot" in the page banner of the Code section. SourceForge will then generate a snapshot for you and start the download. Extract the downloaded ZIP file. Then move the contents of the resulting folder into the destination directory prepared earlier.

Create a Subversion working copy

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. Simply concatenate the repository path and the path to the selected branch or tag. For example, to check out the 6.44 branch into the folder "C:\OWLNext" the command will be:

svn checkout svn://svn.code.sf.net/p/owlnext/code/branches/6.44 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 "RW" and "HTTP" 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 forums.

---

Perform build setup

The OWLNext 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 the build scripts for version 6.32 and later 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).

Older source code from tags and earlier branches will 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.

Note for users of C++Builder/RAD Studio 10.3 Rio: When buiding OWLNext with the classic compiler BCC32, we rely on the Boost C++ library for the definition of "exception_ptr" (in standard C++ since C++11). As of the time of writing (2018-12-13), a GetIt package for Boost is not yet available for 10.3 Rio. A workaround is to copy the folder "include\boost_1_39" from 10.2 Tokyo.

Note for users of C++Builder Starter Edition: OWLNext may fail to build with the C++Builder Starter Edition when using the Clang-based toolset, due to a bug in this product. See [bugs:#405]. OWLMaker Build 4298 has explicit support for the Starter Edition and includes a workaround for this issue. See [feature-requests:#131].

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 various supported compilers.

Driver	Makefile	Compiler
vcmake.bat	vc.mak	Microsoft Visual C++
bcmake.bat	bc.mak	Borland C++/Embarcadero C++Builder (32-bit only)
gcmake.bat	gc.mak	GNU Compiler Collection (GCC)

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

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

:::bat    
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).

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-2017
• 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.

---

Get the OWLNext documentation

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