Skip to main content

Using CMake

We will use CMake, a cross-platform, open-source make system. The provided homework code will be developed on MaxOSX using CMake/clang, but has been tested and should also work on Linux using CMake/g++, and Windows using CMake/VisualStudio. Note that fighting through the installation & compilation of the various graphics libraries on a specific OS/hardware can be frustrating. Use the Google and please ask for help if you are stuck.

When you start a new assignment/project, you should first run cmake on the provided code following the directions below. These steps allow you to setup the build environment, verify installation of all libraries, ensure the project correctly compiles and links, and allows you to test the initial executable. These steps create the Makefile or Visual Studio project file for your system. Once completed you can launch your favorite source code editor or Integrated Development Environment (IDE) and start working on the assignment.

Please let the instructor know (by email or through the Discussion Forum) if there are errors/updates to any of the information below. Also, please share any additional installation/compilation instructions you have for your specific environment. And if you catch any portability bugs in the code while working on the homework let us know so we can update the provided files.

Common Instructions for all Operating Systems

  • Install CMake. You'll need version 3.1.1 or later.
    Note for the Windows OS: Windows CMake should be on the path ahead of Cygwin CMake. This is a common mistake!

  • Install GLFW, GLEW, and GLM (for Linux/Windows) or Metal (for Mac) following the Graphics library installation notes.

  • Download the provided files and put them in a new directory, e.g., AdvancedGraphics/hw0/src. The CMakeLists.txt file, all the .cpp and .h files, the shaders, the data files, as well as your README.txt file and your self-assessment gradesheet will go in this directory.

  • Make a separate directory for building this project (e.g., AdvancedGraphics/hw0/build).

    Note: Separating the source code from the compilation/build directory is a good software development strategy and works well with version control (we'll be using git version control with Submitty!). You should "check in" all files in the src directory. It also makes it simple to submit the source code w/o submitting any platform-specific compilation files. To do a clean build from scratch, you can simply delete and recreate the build subdirectory.

  • It may not be necessary, but we will include these files in your src/ directory to help CMake find the libraries you've just installed:

Now on to the OS specific CMake instructions...

On Linux or MacOSX

  • Open up a terminal/shell and cd into the build directory. Then run CMake giving it the relative path to the source code directory. For example: 

      cmake ../src

  • Now build the program: 

      make

    Your executable will be in the current directory (or on a Mac, in a subdirectory).

  • On Linux, to run the program, and refer to a data file that is in the src directory, you'll type something like this: 

      ./ifs -input ../src/fern.txt

    On Mac (with Metal), it will be something like: 

      ./ifs.app/Contents/MacOS/ifs -input ../src/fern.txt

  • If you add new .cpp files (or .m Objective-C files), be sure to add them to the CMakeLists.txt file.

  • To rebuild the program after changing the source files, just type make.

On Windows with Visual Studio

Note: Cygwin does not support the more recent versions of OpenGL (yet?). So on Windows, you will use the Visual Studio compiler.

Note: Windows Subsystem for Linux (WSL) is great for Data Structures... but does it work for graphics/GPU program? Unlikely. Why try to do things the really hard way? Use native Windows or dual boot Linux.

  • Install Visual Studio

  • Launch the Visual Studio command shell (not just the cmd shell and not a Cygwin shell). From the Start menu, under All Programs, find your Visual Studio version and expand it. Then expand Visual Studio Tools. Select the "Visual Studio 20XX Command Prompt". Or, on Windows 8.... hold down the windows key and hit 'q', then search for "Visual Studio Tools" or "VS2012" or "Command Prompt", and double click on the "Developer Command Prompt for VS20XX". Make sure to use the command prompt without "x64" in the name if you're using 32-bit libraries, and use a command prompt with "x64" in the name for 64-bit libraries. You don't need "Cross Tools".

  • Within the Visual Studio command shell, navigate (using cd) into the build directory. Then run CMake giving it a generator and the source code directory.

    To list the available generators, run: 

      cmake --help

    For Visual Studio 2015, using the 64-bit graphics libraries: 

      cmake -G"Visual Studio 14 Win64" ../src

    For Visual Studio 2015 using the 32-bit graphics libraries: 

      cmake -G"Visual Studio 14" ../src

    It should say something like: "Building for: Visual Studio 2015".
    Hopefully it finds all the necessary libraries and completes successfully!

    If it complains about one of the graphics libraries not being found, make sure you have installed them correctly. (NOTE: You need to re-launch the Visual Studio command shell after installing new libraries).

  • Now actually run the compiler: 

      cmake --build .

    And hopefully the build is successful and you have an executable will be in Debug\your_program.exe or debug\your_program.exe

  • To run your executable with a data file in the source directory, type something like this: 

      debug\ifs.exe -input ../src/fern.txt

  • Once your build environment is setup, you can launch the Visual Studio IDE by opening the solution file (named XXX.sln). E.g., 

      start hw0.sln