Compile OpenCV software for Windows with the MinGW-W64 GCC (C++) toolchain

A page dedicated to the compilation of the OpenCV library in Windows using the  MinGW-W64 GCC workchain.

Preliminary points to consider

Portability within the same Operating System and also across different ones is among the reasons why bytecode-compiled languages like Java, C#, Python (and more recently Ruby) have attracted the interest of developers not just for prototyping but also for commercial-grade software production. The fact that there is basically one Virtual Machine per bytecode-compiled language and that such VM is available in different OSs guarantees both intra-OS and inter-OS portability. However, both levels of portability are lost with binary-compiled languages such as C++. The fact that C++ code compiled for UNIX does not work under Windows (and vice versa), thus preventing inter-OS portability, is well known and clearly understood. However, it is often neither too obvious nor widely realised that intra-OS portability too is likely to be prevented if C++ code is compiled under the same operating system but using different compilation toolchains. Even worse, intra-OS lack of portability often extends to C++ code compiled using different versions of the very same toolchain.

Unfortunately, this is the case under MS Windows, where the two most widely used toolchain are based on MS Visual Studio C++ and the MingW-W64 porting of the GCC (MinGW GCC for short) rispectively. More specifically, if two binary chunks of C++ code compiled using two different toolchains are linked together using one of these toolchains, the linkage process will likely terminate with an error because of the different ways of compiling C++ code in its binary form. The bottom line of all this is that whenever a C++ application under development compiled with a specific toolchain uses third party libraries, the latter would have to be recompiled from source code using the same toolchain (and possibly the same toolchain version too).

Most C++ applications (and libraries) for MS Windows are compiled using the MS Visual Studio C++ toolchain rather than the MinGW GCC one. Hence,  C++ developers that use the MinGW GCC toolchain and who need third party libraries to be included in their application are forced to recompile such libraries from source code using the MinGW GCC toolchain to begin with. For instance, this is the case with connectors to DBMSs like MySQL and PostgreSQL. Its is also the case with OpenCV, whose Windows distribution has been compiled using Visual Studio C++. Hence, this instructable, explains how to compile OpenCV source code using the MinGW-W64 GCC toolchain..

 Preliminary steps to perform

  1. Download the OpenCV for Windows executable from the OpenCV website and extract it in a suitable directory. We suggest you create a general root directory C:\Program_Files\OpenCV and extract everything there. OpenCV files will thus be extracted to directory C:\Program_Files\OpenCV\opencv .
  2. Rename the above to C:\Program_Files\OpenCV\ , e.g., C:\Program_Files\OpenCV\opencv-3.1.0. The reason for such a choice is twofold. Firstly, avoid blank spaces in directory paths and file names if at all possible when dealing with MinGW-related stuff. Secondly, in this way it is possible to install several different OpenCV releases. Afterwards, it will be easy to  change the Windows path to point to the specific version you want to use.
  3. The  C:\Program_Files\OpenCV\  directory in which you have extracted all OpenCV files ( for short)  contains two subdirectories, namely  build  and sources , whose content is self-explanatory. However, the binaries in the released  build  directory have been compiled using the Visual Studio C++ toolchain, so they will not work with the MinGW-W64 GCC toolchain. Hence, remove subdirectories bin and x64 inside build  leaving at least subdirectory include  in place, together with all its content. You can also leave subdirectories  java and python if you are interested in calling OpenCV functionalities from programs written in these languages using the corresponding wrappers provided by the distributions in those directories. Having done the avove, you are left with the C++ OpenCV sources only and you would need to prepare and compile these for the MinGW-W64 GCC toolchain.

Creating a makefile

Before compilation using the MinGW-W64 GCC toolchain, the source code must be prepared. This implies creating a script file (called a makefile) that lists all files to be compiled, together with specific compilation directives and switches that depend on the toolchain to be used and on the target operating system for which the binaries are intended. Once this script file (i.e., the makefile) has been created, it can be passed to a special utility called make. This will invoke the compilation toolchain for each of the source code files listed in the makefile which have not been already compiled (or which have been modified since the last time they were compiled).

Compiling a large software written in C++ (or in other compiled languages)  is thus a two-step process that involves the creation of a makefile first and then the compilation of the whole source codebase managed by the make utility following the directives specified in such makefile. The latter can be created either manually or using a specific utility called CMake, which uses simple configuration files (called CMakeLists.txt files) placed in each source directory. CMake reads all such files and generates a corresponding single makefile, which can be interpreted using make to guide the overall, articulated compilation process.

It is worth noting that not all (C++) source code is suitable for treatment with CMake out of the box. Unless source code specifically includes CMakeLists.txt files in each source directory, CMake cannot be used. However, in all such cases, a makefile is generally provided. The benefit of using CMake as a pre-processing step to generate a makefile rather than using the one provided with the source code is that makefiles are platform- and toolchain- dependent while CMakeLists.txt files are not. Hence, a makefile created for a specific toolchain and a specific OS may not work in a different setup. In other words, C++ source code with an acccompanying makefile created for compilation under UNIX using the CGG toolchain will likely not work to compile the same source code under Windows using the Visual C++ toolchain. Similarly, this could still be the case if the MinGW Wndows porting of the GCC toolchain were used in place of the Visual C++ one to compile source code with a makefile originally intended to be compiled using the GCC under UNIX.. Luckily, the OpenCV developers have decided to use CMake so that makefile generation and compilation under different OSs and with different toolchains can be performed without any hassle.

Step-by-step makefile generation procedure with CMake

  1. Make sure that the MSYS environment variable (or the corresponding value pointing to /bin in the Windows path environment variable)  is temporarily disabled until the end of the CMake makefile generation process Ii.e., until the completion of point 6 below). This must be done to prevent MSYS binaries (notably, make)  interfering with CMake. If MSYS binaries are visible during the CMAking process, the CMake configuration step (see point 3 below) will fail (and it will point to MSYS being the likely culprit).
  2. Launch CMake (version 3.6.2 for x64 is used in this example, but any recent version would do). Set the rootsource code directory as /sources  and the root binary code directory as /release as in figure below.
    opencv-cmakesetup1

    Source code and binary directory roots

    Note that the root for binary files (release) is empty but will have to be created before it is actually selected as the location where to deposit binaries. A new directory release has been chosen for binaries in place of the existing (but previously almost emptied) directory  build not to generate any confusion on the specific MinGW-W64 GCC nature of these new binaries.

  3. Click the Configure button. The CMake configuration windows open.
    opencv-cmakeconfigoptions

    CMake configuration options

    Make sure to select “MinGW makefiles” as the generator for the project and the “Use default native compilers” option.

  4. Click the Finish button to close the configuration window. CMake will then open the following main window
    OpenCV-CMAkeConfigOptRes1.JPG

    CMake configuration window after selecting setup options

    Note that this main CMake window requests you to press the Configure button to update and display new compilation values that are currently shown in red. It is recommended that you leave the list as it is suggested by CMake, i.e., without selecting any further options or deselecting any active ones unless you know very well what you are doing and you have a very specific reason for doing so.

  5. Click the Configure button. The configuration will be processed and as a result, all the red highlighting of compilation variables will disappear.
    opencv-cmakeconfigoptres2

    Processed configuration ready for makefile generation

    All configuring has been done and CMake is now ready to generate a suitable makefile for the MinGW-W64 GCC toolchain.

  6. Click the Generate button. A further message “generating done” will appear at the bottom of the CMake main windows immediately below the previously issued “Configuring done” message.
    opencv-cmakeconfigoptres3

    Makefile generation completed

    This completes the makefile generation process. You can now close CMake

  7. Make sure that the MSYS environment variable (or the corresponding value pointing to /bin in the Windows path environment variable)  is correctly set again. MSYS binaries (and more specifically, MSYS make) are not involved in the MYNGW GCC toolchain compilation process. However, but not making MSYS binaries globally visible again through the Windows path can have serious consequences for toolchain operations later on. It is worth noting that the main practical difference between the MSYS version and the native version of makeis that the former uses the MSYS shell to execute its commands, while the later uses cmd. This means that the MSYS version of make allows users to write makefiles much the same as they would on Unix or Linux system, while with the native Windows version users might have to do things differently. For simple command execution they work the same, but for more complicated actions the scripts will have to differ because cmd has a much different syntax than Unix shells.

Compiling the OpenCV source code

Once a specific makefile for the MinGW-W64 GCC toolchain has been generated by CMake, the compilation process can be performed straightforwardly.

  1. Open a Windows command prompt (there is a customised executable file mingw-w64.batfile inside the root of the specific MinGW-w64 release you have installed).
  2. Change the working directory to the OpenCV release directory where you want your binaries to be placed after compilation. You will note that this directory is no longer empty, as it has been popolated with files by CMake. In particular, makefile has created a file called Makefile (no extension).
  3. Type the command mingw32-make If the MINGW_HOME environment variable has been correctly set, this will launch the OpenCV compilation process. Please note that due to the size of the OpenCV source code , the compilation process will take considerable time. On a machine with an i7 CPU, 8GB RAM, and an SSD, the compilation process takes around 25 minutes; it takes slightly more on a machine with an i3 CPU, 2GB RAM, and a standard HD.

Finally…

The compilation process performed using the MinGW GCC toolchain produces three kinds of binaries in two specific subdirectories, namely:

  1. Dynamic libraries (DLLs) in /release/bin 
  2. Standalone executables (ancillary applications) in /release/bin
  3. Static libraries (libopencv_XYZ.dll.a)  in /release/lib

The compilation, linkage, and execution using the MinGW GCC toolchain of any C++ program that uses any of the OpenCV library functionalities will need to include:

  • At compilation time, the absolute paths
    /build/include  ,
    /build/include/opencv , and
    /build/include/opencv2
    to the subdirectories where library function headers are stored;
  • At linkage time,
    • the absolute path to all static libraries, namely /release/lib, and
    • the specific static libraries (libopencv_XYZ.dll.a) that provide the required functionalities
  • At run time, the absolute path to directory  OpenCVroot>/release/bin , so that DLLs and ancillary executables can be found and invoked. This Windows-specific setting is described below.

Setting the OPENCV_HOME environment variable

The best approach to make sure that any executable that calls an OpenCV functionality which, in turn, requires an OpenCV library DLL or a standalone executable to perform a specific task, is to define a specific system environment variable.

Such a variable can be defined in Windows as
OPENCV_HOME = release
so that the OPENCV_HOME\bin subdirectory is added to the Windows path variable, i.e.,
PATH = …;%OPENCV_HOME%\bin;


Page last updated by ECOMPAT on 17/10/2016