Building OpenGL/GLFW Apps

on:

• Linux Ubuntu with Eclipse,
• Mac OS X with Xcode, and
• Windows 8.1 with Visual Studio 2013 or Cygwin.

• First install GLFW's dependencies, including OpenGL/Mesa:

  sudo apt-get install cmake xorg-dev libglu1-mesa-dev


  You must have sudo privileges. (On Red Hat, you'll need to install cmake28 instead.)

  You should now have:

  /usr/include/GL
/usr/lib/x86_64-linux-gnu/libGL.so


• At the time of writing, the GLFW package one gets with apt-get is version 2.7 whereas we're using version 3.0.4. So we need to install GLFW from source. Unzip the source file and change your working directory to the glfw-3.0.4 directory. Install GLFW:

  cd glfw-3.0.4
rehash
cmake -G "Unix Makefiles"
make
sudo make install


  You should now have:

  /usr/local/include/GLFW
/usr/local/lib/libglfw3.a


• In your OpenGL source files, include the following line:
  #include <GLFW/glfw3.h>

  You don't need to include gl.h as it is already included in glfw3.h.
  For an example, see the provided sample source code.
  If you want to include glu.h automatically, set the -DGLFW_INCLUDE_GLU compiler flag.

• To make a GLFW application on the command line, use the following linker options:
  -lglfw3 -lGL -lm -lXrandr -lXi -lX11 -lXxf86vm -lpthread

  The last three libraries are needed on Ubuntu 14.04.1.

• Eclipse 3.7.2 project (graphical step-by-step):
  • To install Eclipse:

    sudo apt-get install eclipse eclipse-cdt

  • Start up Eclipse and choose your workspace, click "OK" (Fig. 1)

  • Open the C/C++ perspective: on the main menu select "Window→Open Perspective→C/C++" (Fig. 2). If the C/C++ perspective is not available, choose "Other..." and it should show up in the window that pops up.

  • Create a new project:
    • Select "File→New→C++ Project" (Fig. 3)
    • Give the project a name, e.g., "sampleapp". In the panels below, specify project type, "Executable→Empty Project", and select the appropriate toolchain (make, gcc, ld, etc.). Since we're not cross compiling, I choose the "Linux GCC" toolchain. Click "Finish" (Fig. 4)

  • Add source files:
    • Right click on "sampleapp" on the first line of the "Project Explorer" tab on the left and select "Import" (Fig. 5)
    • On the "Select" page, choose "General→File System" and click "Next >" (Fig. 6)
    • On the "File system" page, either type in the directory where your source file resides, or click the "Browse" button next to "From directory:" to choose the directory (Fig. 7). In browsing for the directory, remember that you're telling eclipse the directory where your source files are, not the source files themselves.
    • Once the directory is identified, click on all the source files on the right pane you want imported, for example, the provided server.c (or click the directory name on the left pane to import all files in the directory), and click "Finish" (Fig. 8)

  • Add libraries:
    • Right click on "sampleapp" on the first line of the "C/C++" pane on the left and
      select "Properties" to tell the linker which libraries need to be added (Fig. 9)
    • On the "Properties for sampleapp" page, click "C/C++ Build→Settings". Under the "Tool Settings" tab, click "GCC C++ Linker→Libraries" (Fig. 10)
    • On the "Libraries (-l)" pane click the add file () button (Fig. 10)
    • On the popup dialog box type "GL" and click "OK"
    • Repeat the above two steps to add "glfw3", "m", "Xrandr", "Xi", "X11", "Xxf86vm", and "pthread" libraries.
    • Next click "Apply" and "OK". Be sure to click "Apply" before clicking "OK" (Fig. 11)

  • Build and run the program:
    • On the main menu, select "Project→Build All" (Fig. 13)
    • Under the play button on the second menu bar (   ), click on the drop-down menu and select "Run Configurations..."" (Fig. 14)
    • On the "Create, manage, and run configurations" page, double click on "C/C++ Application" (Fig. 15). It will create a "sampleapp Debug" application.
    • On the "sampleapp Debug" configuration page, check "Enable auto build" and click "Run" (Fig. 16)
    • Click on the "Console" tab on the lower part of the central pane to view the console output of the program, if any. Click on the red square to stop the program. (Fig. 17).

• OpenGL installation verification:
  OpenGL comes with the OS. To verify, check for:
  /System/Library/Frameworks/OpenGL.framework

• Be sure that you've run xcode-setup --install
• To install GLFW, normally you could install it as a MacPorts port. For this course, we need to install a modified GLFW library. GLFW by default differentiates window and framebuffer sizes. If your viewport is set to the window size (as it normally would be, prior to hiDPI, e.g., Retina, displays), the viewport will appear in the lower left corner of your hiDPI window. We can tell GLFW to use the same framebuffer size as the window size. Unfortunately this can only be done at compile time, which is why we have to build our own GLFW library, as follows:
  • download and unzip the GLFW Source package
  • cd to the top level glfw folder created in the previous step
  • mkdir build; cd build
  • cmake .. -DGLFW_USE_RETINA=0 -DBUILD_SHARED_LIBS=1 -DCMAKE_C_FLAGS="-Wno-deprecated"
  • make; sudo make install
  • cd /usr/local/
  • sudo chmod -R a+rX *

• In your OpenGL source files, include the following line:
  #include <GLFW/glfw3.h>
  You don't need to include gl.h as it is already included in glfw3.h. For an example, see the provided sample source code.
  If you want to include glu.h automatically, set the -Wno-deprecated -DGLFW_INCLUDE_GLU compiler flags when building your app.

• To make a GLFW application on the command line,
  • when linking your code, use the following linker options:
    -lglfw -framework OpenGL
    To link with the static GLFW library, use instead:
    -lglfw3 -framework Cocoa -framework OpenGL -framework IOKit -framework CoreVideo

• Xcode 5.1.1 project (graphical step-by-step):
  • Create a new project:
    • Select "File→New→New Project" (Fig. 18).
    • Choose a template for your new project under "OS X" (not iOS):
      "Application→Command Line Tool" and click "Next" (Fig. 19).
    • For the sample code, specify "Product Name" as "sampleapp", "Company Identifier" as "sample", select "Type" "C++", and click "Next" (Fig. 20).
    • A window pops up to prompt you where you want to put the new project folder. In this example I've decided to put the project folder on my Desktop. Uncheck "Create git repository on [My Mac]" if you don't want it. Then click "Create" (Fig. 21).
    • In the leftmost pane, under "sampleapp" select "main.cpp" and "sampleapp.1" and right click to Delete them (Fig. 22). Click "Move to Trash" on the confirmation dialog box.

  • Add source files:
    Right click on "sampleapp" at the top of the left most pane and select "Add Files to 'sampleapp'" (Fig. 23), select your file, for example, the provided sample.cpp. You can choose whether to copy added items into the project folder. I've chosen to do so in this example. Click "Add" (Fig. 24).

  • Add libraries:
    • In the middle pane, click the "Build Phases" tab, open the "Link Binary With Libraries" list, and click the '+' sign at the bottom left corner of the list (Fig. 25).
    • A list of frameworks should pop up. Scroll down to "OpenGL.framework" and click "Add" (Fig. 26).
    • Click the '+' sign as per above again to bring up the list of libraries and frameworks (Fig. 27). But this time click the "Add Other . . ." button (Fig. 28).
    • In the file selection window that pops up, navigate to /opt/local/lib and search for libglfw.3.1.dylib, select it, and click "Open" (Fig. 29).

  • Add header search path:
    • In the middle pane, click the "Build Settings" tab, on the second menu of the panel, click on "All". Scroll down (or search for) "Header Search Paths". Double click to the right of "Header Search Paths" and append " /opt/local/include" (without the quotes but WITH a space to separate this path from the existing ones) (Fig. 30).

  • Click on the play button at the top left corner of the Xcode window to build and run the program.

• OpenGL installation verification:
  OpenGL comes with the OS and Visual Studio 2013 installations, to verify:
  • header file:
    C:\Program Files (x86)\Windows Kits\8.1\Include\um\gl\GL.h

    Your installation may have something other than um on the path.

  • static library (32- and 64-bit respectively):
    C:\Program Files (x86)\Windows Kits\8.1\Lib\winv6.3\um\x86\OpenGL32.Lib
C:\Program Files (x86)\Windows Kits\8.1\Lib\winv6.3\um\x64\OpenGL32.Lib


  • runtime shared library (32- and 64-bit respectively):
    C:\Windows\System32\opengl32.dll
C:\Windows\SysWOW64\opengl32.dll


• To install GLFW, download either its 32- or 64-bit Windows binaries zip file and install the files inside the lib-msvc120 folder in the zip file as follows:
  • header files:
    C:\Program Files\Microsoft Visual Studio 12.0\VC\include\GLFW\glfw3.h
C:\Program Files\Microsoft Visual Studio 12.0\VC\include\GLFW\glfw3native.h


  • If you've chosen 32-bit:
    • static libraries:
      C:\Program Files\Microsoft Visual Studio 12.0\VC\lib\glfw3.lib
C:\Program Files\Microsoft Visual Studio 12.0\VC\lib\glfw3dll.lib


    • runtime shared library/dll:
      C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin\glfw3.dll


  • Or if you've chosen 64-bit:
    • static libraries:
      C:\Program Files\Microsoft Visual Studio 12.0\VC\lib\amd64\glfw3.lib
C:\Program Files\Microsoft Visual Studio 12.0\VC\lib\amd64\glfw3dll.lib


    • runtime shared library/dll:
      C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin\amd64\glfw3.dll


• In your OpenGL source files, include the following line:
  #include <GLFW/glfw3.h>
  You don't need to include gl.h as it is already included in glfw3.h. For an example, see the provided sample source code.
  [If you want to include glu.h automatically, add
  #define GLFW_INCLUDE_GLU
  before the above #include statement. Similarly if you want to build apps using GLFW's DLL instead of the static library, add
  #define GLFW_DLL
  before the #include.]

• Command line make: see the instructions for Cygwin below.

• Visual Studio 2013 project (graphical step-by-step):
  • Create a new project:
    • Select "File→New→Project" (Fig. 31)
    • Choose a template for your new project:
      "Visual C++→Win32→Win32 Console Application" (even if you're building 64-bit app), give the project a name, e.g., "sampleapp", specify the location of the project, and click "OK" (Fig. 32)
    • On the "Welcome to the Win32 Application Wizard" page, click "Next >" (Fig. 33)
    • On the "Application Setting" dialog box, under "Additional options" tick "Empty project", untick "Security Development Lifecycle (SDL) checks", then click "Finish" (Fig. 34)
    • To build a 64-bit app, click on the drop down menu next to the third textbox on the second menu bar at the top of the window ("Solution Platform" should show up when you mouse over it) and choose "x64" instead of "Win32" (Fig. 35). If you don't have "x64" as an option, select "Configuration Manager" and create a new platform definition by simply copying the Win32 configuration when prompted.

  • Add source files:
    Right click on your project, for example, "sampleapp", on the second line of the "Solution Explorer" pane on the left to "Add→Existing Item" (Fig. 36),
    select your source and header file(s), for example, the provided sample.cpp, and click "Add" (Fig. 37).

  • Add libraries:
    • Right click on "sampleapp" again and select "Properties" (Fig. 38).
    • On the "Property Pages", under "Configuration:" tell VS to add the additional libraries to "All Configurations" (Fig. 39)
    • Select "Configuration Properties→Linker→Input" on the left pane. Next to "Additional Dependencies" at the top of the right pane enter:
      opengl32.lib;glfw3.lib;
      Be careful not to add a space before or after the semicolon. Hit RETURN and then click "Apply" (Fig. 40). [If you're using the GLFW's DLL, replace glfw3.lib with glfw3dll.lib.]

  • Optional:
    To prevent your program from opening a console window, while still on the "Property Pages", select "Configuration Properties→Linker→Command Line" on the left pane. Under "Additional options" at the bottom of the right pane enter:
    /SUBSYSTEM:WINDOWS /ENTRY:mainCRTStartup
    then click "Apply" (Fig. 41). You may not want to disable the console window if you print out messages to the console (see next step).

  • Close the "Property Pages" pane by clicking "Ok", then click on the play button on the second menu bar to build and run the program. If you print out messages to the console, run the program using Ctl-F5 instead, to keep the cmd window from exiting after the program exits.

  • If you've built with DLLs, to distribute your app, you may need to distribute the DLLs along with it.

• Installation verification:
  To use WGL instead of GLX under Cygwin, you need to link your program against native Win32 graphics libraries. Verify that you have the Win32 version of OpenGL and the Microsoft GDI libraries on your system:
  • header files:
    /usr/include/w32api/GL

  • static libraries:
    /lib/w32api/lib{opengl,gdi}32.a

• To install GLFW, download either the 32- or 64-bit Windows binaries zip file of GLFW and install the files inside the lib-mingw folder of the zip file as follows:
  • header file:

    /usr/YOUR_TOOLCHAIN/include/GLFW

    You'd have to create the include and GLdirectory. Here YOUR_TOOLCHAIN is x86_64-pc-cygwin, so replace every occurrences of YOUR_TOOLCHAIN with x86_64-pc-cygwin, we'll see the use of other toolchains below.

  • library:

    /usr/YOUR_TOOLCHAIN/lib/libglfw3.a
/usr/YOUR_TOOLCHAIN/lib/glfw3dll.a

    When linking against a library, unlike Visual Studio, the MinGW/Cygwin linker looks for either lib<pkg>.a or <pkg>.lib, not lib<pkg>.lib.

  • runtime dynamically-linked, shared library:

    /usr/YOUR_TOOLCHAIN/bin/glfw3.dll

    You must add /usr/YOUR_TOOLCHAIN/bin to your environment PATH variable prior to launching your app.

  If you use other libraries, e.g., GLEW, PNG, JPEG, etc. you'll need to link against the Win32 version of those libraries instead of the ones installed through Cygwin's setup program. See the course note on how to add libraries.

• Prepare your source files as you would for Visual Studio above.

• To compile, use the following linker options:

  -lglfw3 -lopengl32 -lgdi32

  [Some antivirus software such as Avast! may automatically move the binary you build into its virus quarantine folder. You may want to exclude your working folder from automatic virus quarantine.]

Devel→cygwin32-gcc-g++
Devel→mingw64-x86_64-gcc-g++
Devel→mingw64-i686-gcc-g++
Devel→mingw-gcc-g++


References not cited:

• Jamin, S., Building OpenGL/GLUT Programs, 2013.
• GLFW, Getting started.
• GLFW, Building programs that use GLFW.
• Bird, E. How to build & install GLFW 3 and use it in a Linux project, July 21, 2013.