Troubleshooting

Installation

• The doc directory is not included in the archive Imagine++-...tar.gz even though I built the doc explicitly. This happens on Windows. In the build directory, remove the folder _CPack_Packages and the file CPackConfig.cmake. Go back to cmake to regenerate the project (in the same build directory). In Visual, rebuild the doc (right-clicking on the doc project in the 'Solution Explorer' window). Rebuild the package (project 'PACKAGE'). The doc directory and its content should now be in the archive.
• When building from source Imagine++, make doc-qt results in an error. This the case with Ubuntu 14.04 and Qt5. The bug is caused by the Qt5 package not providing qhelpgenerator. A correction:

  sudo apt-get install qt4-dev-tools
  cd /usr/lib/x86_64-linux-gnu/
  sudo ln -s /usr/lib/x86_64-linux-gnu/qt4/bin/qhelpgenerator qt5/bin/

• Under MacOS, CMake complains it does not find the compiler, even though XCode is installed. The gcc compiler is not in the standard path. To remedy this, enter the following in a terminal:

  sudo /usr/bin/xcode-select -switch /Applications/Xcode.app/Contents/Developer

Compilation

• Many problems in QtCreator get fixed by the following procedure:
  1. Close QtCreator.
  2. Remove the file CMakeLists.txt.user in your source directory.
  3. (optional) Remove the directory of build of your project (it it exists).
  4. Launch QtCreator and open your project. Normally, it should propose to "configure" the project proposing different kits. Do not use any "imported" kit (if present), and select the correct one if there are several. A good configuration for a kit is presented: Windows Mac.
• Problems with newer Mac (M1). The architecture of M1 is ARM64, though x86_64 (Intel 64-bit) is supported through Rosetta (included in MacOS). The build of Imagine++ was done for x86_64 and should be used. In the CMakeLists.txt, insert the line just after cmake_minimum_required(...)

  set(CMAKE_OSX_ARCHITECTURES "x86_64" CACHE STRING "")

• On Windows, Qt Creator signals an error "The C compiler is not able to compile a simple test program". It you get something like:
  
  You are hit by a bug where Qt Creator in French chooses a build directory containing an accent (Défaut) and then has some encoding problem, as seen in the image above. The solution is to change the build directory to a name containing no special character, like simply build (configurable in mode Projets).
• Cmake signals an error 'Could not find module FindImagine.cmake or a configuration file for package Imagine'. It is due to a missing or erroneous Imagine_DIR environment variable. This should be set to the installation path of Imagine++ (it is not the source directory of Imagine++, if you have it). For example, here is a good configuration under Windows:
  

  A correct configuration of Imagine_DIR under Windows
• Cmake complains with the following message

  CMake Warning at ThirdParty/Qt5/CMakeLists.txt:6 (FIND_PACKAGE):
    By not providing "FindQt5Core.cmake" in CMAKE_MODULE_PATH this project has
    asked CMake to find a package configuration file provided by "Qt5Core", but
    CMake did not find one.

  CMake does not find Qt. To fix it, you can set the environment variable CMAKE_PREFIX_PATH to a correct path, like (under Mac):

  env CMAKE_PREFIX_PATH=/Users/pascal/Qt/5.3/clang_64/lib/cmake cmake .

  and reboot.

Usage

• Running my program in Debug mode under MacOS fails with a message complaining about an ambiguity between QtCore and QtCore_debug. This happens with recent versions of Qt and is specific to Debug mode. To fix it, you can download and launch from a terminal the script fixQtDebug.sh:

  source fixQtDebug.sh

• Running the debugger from QtCreator hangs with the message "Launching debugger" and nothing happens. According to this source, a bug in XCode command line tools can be fixed from the terminal:

  defaults write com.apple.dt.lldb DefaultPythonVersion 2

• The build of my program went well but when I execute it, it complains about something related to Qt. This happens on Windows in Release mode. First, the location of Qt's dynamic libraries (where the dll files are stored) must be in the 'path' environment variable.
  

  Error related to Qt at execution time.
  However, the final 'path' environment variable is a concatenation of the system variable and the user variable (unlike regular environment variables, for which the user variable overrides the system variable). In the image above, the path to Qt is in the user variable. However, some Qt libraries are used by MiKTeX (Latex program) and the path to MiKTeX is in the system variable. As witnessed by Visual's output, this is the problem:
  

  Conflicting Qt dynamic libraries
  When it looks for QtOpenGL4.dll, it is present only in the correct location, so it finds it there as it should. However, the required QtGui4.dll is also present in MiKTeX's directory, and built from another minor version of Qt. The solution is to prevent it from looking in the MiKTeX directory:
  • A permanent solution is to add the Qt path in the system 'path' variable, before MiKTeX. However, you need administrator rights to do that.
  • Alternatively, you can copy the correct Qt dll files in the Release directory of your build (where your exe file is located). You have to do that for every Imagine++ program that you want to run in Release mode.
  • The least convenient solution is to launch the program from a terminal window where you have modified the 'path' environment variable. This only affects the current terminal.
• My program using the Graphics module complains with my main function 'int main(int argc, char** argv)'. This definition of the main function is correct in C++, though perhaps less frequent than the also correct 'int main()'. The idea is to get arguments of the program at execution, if any. You are using an outdated version of Imagine++, you need to upgrade to a more recent version to fix this problem.