1. Jason McKesson
  2. gltut


gltut / Documents / Building the Tutorials.xml

<?xml version="1.0" encoding="UTF-8"?>
<?oxygen RNGSchema="http://docbook.org/xml/5.0/rng/docbookxi.rng" type="xml"?>
<?oxygen SCHSchema="http://docbook.org/xml/5.0/rng/docbookxi.rng"?>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
    <?dbhtml filename="Building the Tutorials.html" ?>
    <title>Building the Tutorials</title>
    <para>These tutorials require a number of external libraries in order to function. The specific
        version of these libraries that the tutorials use are distributed with the tutorials. The
        tutorial <link xlink:href="http://bitbucket.org/alfonse/gltut/downloads">source
            distribution</link> can be found online. This section will describe each of the external
        libraries, how to build them, and how to build the tutorials themselves. Windows and Linux
        builds are supported.</para>
    <para>You will need minimal familiarity with using the command line in order to build these
        tutorials. Also, any mention of directories is always relative to where you unzipped this
        <title>File Structure</title>
        <para>The layout of the files in the tutorial directory is quite simple. The
                <filename>framework</filename> directory and all directories of the form
                <filename>Tut*</filename> contain all of the source code for the tutorials
            themselves. Each <filename>Tut*</filename> directory has the code for the various
            tutorials. The <filename>framework</filename> directory simply contains utility code
            that is commonly used by each tutorial.</para>
        <para>Each tutorial contains one or more projects; each project is referenced in the text
            for that tutorial.</para>
        <para>The <filename>Documents</filename> directory contains the source for the text
            documentation explaining how these tutorials work. This source is in xml files using the
            DocBook 5.0 format.</para>
        <para>Every other directory contains the code and build files for a library that the
            tutorials require.</para>
        <title>Necessary Utilities</title>
        <para>In order to build everything, you will need to download the <link
                xlink:href="http://industriousone.com/premake">Premake 4</link> utility for your
            platform of choice.</para>
        <para>Premake is a utility like <link xlink:href="http://www.cmake.org/">CMake</link>: it
            generates build files for a specific platform. Unlike CMake, Premake is strictly a
            command-line utility. Premake's build scripts are written in the <link
                xlink:href="http://www.lua.org/home.html">Lua language</link>, unlike CMake's build
            scripts that use their own language.</para>
        <para>Note that Premake only generates build files; once the build files are created, you
            can use them as normal. It can generate project files for Visual Studio, <link
                xlink:href="http://www.codeblocks.org/">Code::Blocks</link>, and XCode, as well as
            GNU Makefiles. And unless you want to modify one of the tutorials, you only need to run
            Premake once for each tutorial.</para>
        <para>The Premake download comes as a pre-built executable for all platforms of interest,
            including Linux.</para>
        <para><link xlink:href="http://freeglut.sourceforge.net/">FreeGLUT</link> is a
            cross-platform library that handles a lot of the boilerplate initialization code
            necessary for running a windowing application. It creates a window, attaches an OpenGL
            context to the window, and handles window messages. This makes it much easier to focus
            on OpenGL and less on how to initialize OpenGL properly.</para>
        <para>To build FreeGLUT for Win32 with Visual Studio, go to the
                <filename>freeglut-2.6.0/VisualStudio2008Static</filename> directory and open the
            solution file there. There will be several projects in the solution, but the only one of
            interest is the <quote>FreeGLUT</quote> project. Build this, for both debug and
        <para>To build FreeGLUT for Linux, or to build it on Windows without using Visual Studio,
            open a console window and go to the <filename>freeglut-2.6.0</filename> directory. Enter
            the following commands:</para>
        <para>Do <emphasis>not</emphasis> execute <userinput>make install</userinput>. This source
            distribution is intended to be self-contained. If you try to install FreeGLUT, it will
            make non-local changes to your system. The rest of the build process assumes that the
            results of the build are in the local directories after the make process.</para>
        <para><link xlink:href="http://sourceforge.net/projects/tinyxml/">TinyXML</link> is an XML
            parser. The framework uses an XML file format for loading complex 3D mesh data. This
            library simply makes the loading and parsing of this format easier.</para>
        <para>Unlike the previous libraries, this library uses Premake to generate its build files.
            So, with <command>premake4.exe</command> in your path, go to the
                <filename>tinyxml</filename> directory. Type <userinput>premake4
                    <replaceable>plat</replaceable></userinput>, where
                <replaceable>plat</replaceable> is the name of the platform of choice. For Visual
            Studio 2008, this would be <quote>vs2008</quote>; for VS2010, this would be
                <quote>vs2010.</quote> This will generate Visual Studio project and solution files
            for that particular version.</para>
        <para>For GNU and makefile-based builds, this is <quote>gmake</quote>. This will generate a
            makefile. To build for debug, use <userinput>make config=debug</userinput>; similarly,
            to build for release, use <userinput>make config=release</userinput>.</para>
        <para>Using the generated build files, compile for both debug and release.</para>
        <para>The GlLoader library is a home-brewed library for loading OpenGL function entrypoints
            from the .dll. For reasons that are too technical to repeat here, using OpenGL on most
            platforms requires manually loading function pointers from a .dll. This library makes
            this process painless.</para>
        <para>Like TinyXML, GlLoader uses Premake to generate its build files. To create the build
            files, go to the <filename>glloader</filename> directory. Type <userinput>premake4
                    <replaceable>plat</replaceable></userinput> as you did for TinyXML. This will
            create the build file you need to use to build the library for both debug and
        <title>Tutorial Building</title>
        <para>Each tutorial directory has a <filename>premake4.lua</filename> file; this file is
            used by Premake to generate the build files for that tutorial. Therefore, to build any
            tutorial, you need only go to that directory and type <userinput>premake4
                    <replaceable>plat</replaceable></userinput>, then use those build files to build
            the tutorial.</para>
        <para>Each tutorial will generally have more than one source file and generate multiple
            executables. Each executable represents a different section of the tutorial, as
            explained in that tutorial's documentation.</para>
        <para>If you want to build all of the tutorials at once, go to the root directory of the
            distribution and use Premake on the <filename>premake4.lua</filename> file in that
            directory. It will put all of the tutorials into one giant project that you can
        <para>If you look at any of the tutorial source files, you will not find the
                <function>main</function> function defined anywhere. This function is defined in
                <filename>framework/framework.cpp</filename>; it and all of the other source files
            in the <filename>framework</filename> directory is shared by every tutorial. It does the
            basic boilerplate work: creating a FreeGLUT window, etc. This allows the tutorial source
            files to focus on the useful OpenGL-specific code.</para>