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 LMS) 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 2.8 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 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 recommend the git version control system). 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.

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.

• 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 
  

• If you add new .cpp files, be sure to add them to the CMakeLists.txt file.

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

On Windows with Visual Studio

• Install Visual Studio
  Note: Visual Studio 2008 users will probably need to install Visual C++ 2008 Feature Pack Release to get Standard Library TR1, which includes unordered_map (and change provided code to from std::unordered_map to std::tr1::unordered map)

• 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 the source code directory. E.g.,

  If you are using the 64-bit graphics libraries:

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

  If you are using the 32-bit graphics libraries:

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

  It should say something like: "Building for: Visual Studio 20XX".
  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