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>
        <title>Unofficial OpenGL SDK</title>
        <para>The <link xlink:href="http://glsdk.sourceforge.net/docs/html/index.html">Unofficial
                OpenGL SDK</link> is an aggregation of libraries, unifying a number of tools for
            developing OpenGL applications, all bound together with a unified build system. A
            modified SDK distribution is bundled with these tutorials; this distro does not contain
            the documentation or GLFW that comes with the regular SDK.</para>
        <para>The SDK his library uses Premake to generate its build files. So, with
                <command>premake4.exe</command> in your path, go to the <filename>glsdk</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 projects 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. You should build
            the entire solution; the tutorials use all of the libraries provided.</para>
        <para>Note that there is no execution of <userinput>make install</userinput> or similar
            constructs. The SDK is designed to be used where it is; it does not install itself to
            any system directories on your machine. Incidentally, neither do these tutorials.</para>
        <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>