Getting it going

Build system

OGLplus uses a CMake-based build/configuration system. The library itself is header only, which means that applications using it do not need to link to a compiled library, but need just to include the header files.

The build system handles several important tasks:

• Detects if the necessary things are installed and makes a site-configuration header file
• Builds several additional, automatically generated headers
• Installs all header files to a directory specified by the install prefix
• Builds the examples and textures used by the examples (optional)
• Builds and installs the documentation (optional)

Requirements

• C++11 compatible compiler.
• CMake.
• Doxygen is also required to build the documentation.
• Inkscape is required to convert textures used in examples from SVG to PNG. This is required only if the textures are not pre-built (typically when checked out from the repository, packaged releases are shipped with pre-built textures). Building of the textures is optional, they are not necessary when the building of examples is disabled.
• The GL/glcorearb.h header or GLEW. OGLplus does not define the OpenGL symbols (types, constants, functions, etc.) itself and therfore applications using it need to define them themselves (before including OGLplus). The examples currently need GLEW (at least version 1.9) or the GL/glcorearb.h header (available for download from http://www.opengl.org/registry/api/glcorearb.h) and a GL binary library exporting the OpenGL (3 or higher) functions. The build system detects the presence of GLEW or glcorearb.h and configures compilation and linking of the examples accordingly. If both are installed and the user does not specify otherwise GLEW is used.

libPNG. Some examples and some classes provided by OGLplus use libPNG to load PNG files. These are however not required for the general use of OGLplus, applications may use other means to load binary image files.

CMake-based build configuration

The CMake script defines and uses several variables to modify the build configuration, which can be specified on the command-line when invoking cmake (with the -D option. see cmake manual for details):

• HEADER_SEARCH_PATHS [empty]: (semicolon-separated) list of paths to additional directories to search when looking for 3rd-party headers like GL/glew.h, GL/glcorearb.h, GL3/gl3.h, etc.
• OGLPLUS_NO_EXAMPLES [Off]: Do not build the examples and the textures.
• OGLPLUS_NO_DOCS [Off]: Do not build and install the documentation.

User-friendly configuration script

The 'configure' script is a more user-friendly way to invoke cmake and specify additional parameters for the configuration process.

Some of the more important command-line options are described below:

• –prefix PATH: Specifies the installation prefix path for cmake (sets the value of the CMAKE_INSTALL_PREFIX variable). If this option is not specified, cmake's default prefix is used.
• –include-dir PATH: This options allows to specify additional directiories to search when looking for header files. It may be used multiple times to specify multiple directories.
• –library-dir PATH: This options allows to specify additional directiories to search when looking for binary libraries. It may be used multiple times to specify multiple directories.

See the –help option for the full description and detailed info on the usage of this script.

Building your own applications

The library itself is header-only, i.e. all an application using it has to do is to include the necessary header files. The library does not need to be built nor linked to. The cmake-based build system can be used to install the necessary files to a platform-default or a user-specified directory.

One important thing that an application using OGLplus needs to take care of is to make sure that the OpenGL® 3 (or higher) function prototypes, typedefs, preprocessor symbols, etc. are defined before including any OGLplus header.

There are several different ways how to do this; one of the most convenient is to download the GL/glcorearb.h header file from www.opengl.org/registry/api/glcorearb.h and place it to a directory implicitly searched by the compiler or to add the -I/path/to/include directive to your CXXFLAGS. If the OpengGL dynamic library or shared object is located in a nonstandard location also update the LDFLAGS.

On Linux and similar systems using Bash as shell you can for example put the following to your ~/.bashrc file:

# if GL/glcorearb.h is in $HOME/include
export CXXFLAGS="$CXXFLAGS -I$HOME/include"
# if libGL.so is in $HOME/lib
export LDFLAGS="$LDFLAGS -L$HOME/lib"

Some other alternatives include using GLEW or a similar library or framework which includes glcorearb.h or defines the necessary symbols itself. See the standalone examples for working applications using these alternative libraries.

Supported compilers

OGLplus is known to work with the following compilers:

• GCC (versions 4.5.1, 4.6.0, 4.6.1).
• MSVC 10 with some features (mostly related to variadic templates, initializer lists, and some others) disabled.
• MSVC 11 with some features (mostly related to variadic templates and initializer lists) disabled.
• MSVC 12 beta with some features disabled.

Note

Please refer to the README.rst file for more up-to-date version of this page.