Building mCtrl

Note:

This page provides information how to build MCTRL.DLL from sources. If you want to just use MCTRL.DLL, you can likely just use prebuilt packages available for download on project homepage.

This information is usefull for you if you want to hack MCTRL.DLL internals or contribute to the project.

Building with Mingw

Originally mingw was the primary development platform. However building 64bit binaries was never supported within mingw and therefore, the project is now developped under mingw-w64.

Building with mingw may or may not work. Either way it is now considered obsolete and not supported by mCtrl project.

Building with Mingw-w64

Mingw-w64 is currently the main development platform of the mCtrl project.

The mingw-w64 provides both native toolchain for Windows and also crosscompiling for Linux and other systems. The instructions below assume your are building on Windows:

1. Download the following packages (or their more recent versions if available) from https://sourceforge.net/projects/mingw-w64/files:
   1. Toolchains targetting Win32 / Automated Builds / mingw-w32-1.0-bin_i686-mingw_20101129.zip
   2. Toolchains targetting Win64 / Automated Builds / mingw-w64-1.0-bin_i686-mingw_20101129.zip
   3. External binary packages (Win64 hosted) / MSYS (32-bit) / MSYS-20101010.zip
2. Install MSYS:
   1. Unzip MSYS-20101010.zip. Further we assume you placed the unzipped files into C:\msys. Note there must not be any space in the path.
   2. Add C:\msys\bin into your environment variable PATH.
3. Install mingw-w64 toolchain for building 32-bit binaries:
   1. Unzip mingw-w32-1.0-bin_i686-mingw_20101129.zip. Further we assume you placed the unzipped files into C:\mingw32.
   2. Add C:\mingw32\bin into your environment variable PATH.
4. Install mingw-w64 toolchain for building 64-bit binaries:
   1. Unzip mingw-w64-1.0-bin_i686-mingw_20101129.zip. Further we assume you placed the unzipped files into C:\mingw64.
   2. Add C:\mingw64\bin into your environment variable PATH.
5. Download and unzip mCtrl source code package. Further we assume you placed the unzipped files into C:\prj\mCtrl.
6. Build mCtrl in MSYS environment:
   1. Launch C:\msys\msys.bat
   2. Type the following command in the MSYS prompt cd /c/prj/mctrl/
7. Now type one of the two following commands to build mCtrl. The first command performs 32-bit build, second one 64-bit build. Please note that both builds drop the files into same subdirectories.
   1. make PREFIX=i686-w64-mingw32- all examples
   2. make PREFIX=x86_64-w64-mingw32- all examples

Building with MS Visual Studio

mCtrl provides also project files for MS Visual Studio 2005 and 2010.

As the MSVC is not main development platform for the project, the project files can be slightly outdated but it should not be hard to fix any problems.

The project files reside in mCtrl\contrib\VS2005 and mCtrl\contrib\VS2010 respectively. Follow information in mCtrl\contrib\VS2005\README.txt or mCtrl\contrib\VS2010\README.txt.

Attention:

Please note that using MCTRL.DLL built with MS Visual Studio has one unfortunate drawback: The MCTRL.DLL then depends on the C runtime library of the particular MSVC version (e.g. MSVCRT100.DLL) which then has to be distributed along with your application.

Debug Level

mCtrl provides a debugging facility which can be turned on with preprocessor macro DEBUG, when building MCTRL.DLL from sources.

When build with mingw-w64 it can be for examaple done like this:

• make DEBUG=1 PREFIX=i686-w64-mingw32- all examples

Value 0 means the debugging is disabled ("Release" version). This is the default. It is expected this release build will be used within the final release of your applications. This is also how the default prebuilt packages are made.

Value 1 enables the "Debug" build. This implies several points:

• MCTRL.DLL disables compiler optizations and keeps debugging information in resulted MCTRL.DLL binary (at least when built with mingw using the MAKEFILE included in mCtrl source package.)
• Traces are enabled when something interesting happens or if any failure is detected. The traces are outputted with OutputDebugString so you can catch them with any reasonable debugger for Windows (debugger in MS Visual Studio or gdb are fine) or with application DebugView (http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx).

The traces can give you a valuable information what's going wrong and that can often directly point to a bug in your application or in mCtrl.

Value 2 enables everyting what value 1 does and additionally enables tracking memory allocation and releases performed inside of MCTRL.DLL. It can help the classical memory management bugs like memory leaks, multiple freeing of the same memory block, buffer overruns or underruns etc.

This is especially useful when debugging MCTRL.DLL, but it can also be used to check that there are no leaks in your application caused by calling some function from MCTRL.DLL allocating some resource which is not paired with corresponding releasing function. Typical example is that your application can call some initialization function (e.g. mcMditab_Initialize()) but not corresponding function (e.g. mcMditab_Terminate()).

However it is not intended for general use: it has higher memory and CPU consumtion, and tracing is much more verbous about the memory management, making the resulted log much longer.

When refering to "debug build" of MCTRL.DLL without specifying the debug level, DEBUG=1 is usually assumed.

Some extra debugging traces can also be turned on for some mCtrl modules by defining additional preprocessor macros, but these are intended only for mCtrl own development and bug hunting, so these are not covered here.

Generating Reference Manual

You can also generate this documentation from the mCtrl source package. All you should need to achieve this is to download the Doxygen tool and run it from the main directory of the mCtrl project (i.e. where the file Doxyfile resides).