Usage

Using CMake

CMake philosophy is the following:

• your sources are in a directory containing a platform independent CMakeLists.txt configuration file describing your programs, the files from which they are built and the libraries they rely on (the source directory).
• from this file, CMake creates, in some build directory you specify, all the files needed by your own system and your own development environment to compile your programs.
• you can generate projects for Visual Studio on Windows, XCode on MacOS, Code::Blocks on all platforms... Some development environments, such as Kdevelop (Linux) and QtCreator (all platforms) know natively CMake, and you do not need to launch the cmake progam before.
• it is a good idea to have separate source and build directories: you do not pollute your source directory with numerous temporary files needed for build.
• this process is done once and for all. Even further modifications of CMakeLists.txt are handled automatically by the build process.

The 'test' sub-directory of the Imagine++ installation directory contains useful examples of such files. As an example, let's compile the Graphics tests.

The CMakeLists.txt (<Imagine_DIR>/test/Graphics/CMakeLists.txt) file of the Graphics test is simple, and your own should follow this model:

project(ImagineGraphicsTests)

Two executables are defined, ImagineGraphicsExample and ImagineGraphicsTest, built respectively from example.cpp and tesp.cpp, each of them using the Graphics module. The first few lines are mandatory for any Imagine++ project: they check the Imagine_DIR environment variable, which is mandatory to use Imagine++ (see Introduction).

Finally, if an executable depends on more than one C++ source, just add them as arguments to add_executable separated by whitespace. See other tests and refer to CMake own manual for further information.

QtCreator (all platforms)

QtCreator works on all platforms

• launch QtCreator. Under Windows, it may complain about some problem related to OpenGL. It is happens, launch from a terminal:

  c:\Qt\Tools\QtCreator\bin\qtcreator.exe -noload Welcome

• launch menu File/Open file or project.... Choose the file <Imagine_DIR>/test/Graphics/CMakeLists.txt
  

  Choose your build directory, click Next
  

  Set arguments as above to be able to debug the programs. Click button 'Run CMake', then Finish.
  

  Build (hammer button), select program to launch (button all) and launch (green arrow)
  

  The text output of the program is displayed in QtCreator
  

  To launch from a terminal instead, go to Projects, select Run and click 'Run in terminal'. You must do that if your program expects user text input.
  

  The green button with a ladybug launches the debugger. Set breakpoints , run line by line, observe variables...

Visual Studio (Windows)

To use under Windows:

• launch cmake-gui from the menus
• choose 'C:/Program Files/Imagine++/test/Graphics' (or equivalent) as the source code directory
• choose 'C:/Users/login/Desktop/test' or any temporary directory as the build directory
• generate. When asked, choose 'Visual Studio 2013' as build system.
  

  When the indicated build directory does not exist, the 'Configure' button proposes to create it.
  

  Choose the correct generator for your project, here Visual 2013 in 32 bits.
  

  A correct configuration after clicking 'Generate'
• you may now run Visual on the ImagineGraphicsTests.sln solution freshly created in your build directory
  

  The solution file is created in the build directory. After that, Cmake can be closed.
• note that several entries are defined under your Visual solution (ALL_BUILD, INSTALL, ...). These are for advanced usage. Don't forget to right-click on your own executable and 'Set as StartUp Project'
  

  Define your execution project through a right-click on the project
  

  Running the project 'ImagineGraphicsTest' (key F5)

From a terminal (all platforms)

• run CMake GUI, and select a generator, 'Unix makefiles' for Linux and MacOS, 'MinGW Makefiles' for Windows. To install cmake-gui under Debian or derivative:

  sudo apt-get install cmake-qt-gui

  Notice it is in the Universe part of Ubuntu, which may not be activated by default.
• you may now run make (Linux/Mac) or mingw32-make (Windows) in your build directory to compile your project.
• under Mac, it may complain about not finding Qt. This is fixed by the command

  PATH=$HOME/Qt/5.3/clang_64/bin:$PATH

• important notes:
  • while being under cmake-gui, you may change build type to Debug (for use with a debugger) or Release to generate optmized programs (default is neither Release nor Debug). For some applications, the Release executable can be much faster.
  • you can use cmake instead of cmake-gui as a command line version. Try also ccmake (non graphic version under Linux/Mac) to change build type:

    cmake /path/to/source
    ccmake .
    [change CMAKE_BUILD_TYPE to Release, press [g], quit [q]]
    make