Zuerst benötigt man bjam, das Build-Tool. Man kann es herunterladen, oder man erzeugt es sich eben mal aus dem Sourcecode. Im Verzeichnis tools\jam\src (vom Boost-Hauptverzeichnis aus) ruft man die Datei build.bat auf. Voraussetzung ist, man hat die Compiler-Umgebungsvariablen setzen lassen (z.B. über “vcvarsall.bat x86″ o.ä.). Es wird die Datei bjam.exe im Unterverzeichnis “bin.ntx86″ erstellt, die man getrost ins Boost-Hauptverzeichnis schieben kann.

bjam-Kommandozeile

Zurück in diesem Verzeichnis kann man bjam nun aufrufen. Folgendes Format sollte der Aufruf haben:

bjam toolset=msvc –with-{library-name} {weitere-optionen} stage

das Toolset kann für alle Visual C++-Versionen auf msvc belassen werden, das Build-System findet selbst die passende Version heraus. Die –with-{library-name} -Option kann öfters vorkommen. Folgende library-names sind gültig (die Liste kann sich auch jederzeit mit dem Aufruf “bjam –show-libraries” angezeigt werden):

• date_time
• filesystem
• function_types
• graph
• iostreams
• mpi
• program_options
• python
• regex
• serialization
• signals
• system
• test
• thread
• wave

Die Angabe stage gibt an, daß die Dateien ins Verzeichnis “lib/stage” kopiert werden. Nach dem Kompilieren kann man das Verzeichnis “bin.v2″ entfernen, es enthält die intermediate-Dateien für die einzelnen Libraries.

Build-Optionen

Für die {weitere-optionen} -Option können folgende Optionen angegeben werden:

• –build-type=(single|complete)
  Gibt an, wie viele der verschiedenen Targets kompiliert werden. single kompiliert nur die release-Versionen mit shared linking (also DLLs)
• debug, release bzw variant=(debug|release)
  Bestimmt, welche Variante kompiliert wird. Wie im Visual Studio.
• stdlib={standard-library}
  Gibt die Art der Standard-C++-Library an. Möglicher Wert, z.B.: stlport (siehe weiter unten)
• link=(shared|static)
  Gibt an, ob eine DLL oder eine statische Library erzeugt wird. Standardmäßig will boost durch den autolink-Mechanismus die statischen .lib-Dateien dazulinken.
• define=THIS_DEFINE=1
  Praktisch, um Defines an der Kommandozeile festzulegen, z.B. _SECURE_SCL=1
• threading=(multi|single)
  Gibt an, ob die Bibliotheken multithreaded kompiliert werden. Bei single fallen u.U. mutexe und locking weg und entspricht dem Compiler-Schalter /ML
• runtime-link=(shared|static)
  Gibt an, welche C und C++-Runtime-Bibliothek zu den erzeugten Bibliotheken dazugelinkt wird. shared linkt die msvcrXY.dll und msvcpXY.dll, static linkt je nach threading-Option die libc.lib/libcp.lib oder die libcmt.lib/libcpmt.lib dazu. XY steht für die interne Visual Studio-Version, fürs 2005er für 80, fürs 2008er für 90.
• optimization=(off|speed|…?)
  Schaltet Optimierungen an bzw. aus.
• architecture=(x86|ia64|sparc|power|mips(1|2|3|4|32|32r2|64)|…?)
  Prozessorarchitektur
• address-model=(32|64)
  Gibt das Address-Modell an; die 64 wird benötigt, wenn man unter Visual Studio >= 2005 für AMD64-Plattformen kompiliert.
• cxxflags={…}
  Flags, die direkt dem C++-Compiler mit übergeben werden.
• linkflags={…}
  Flags, die direkt dem Linker übergeben werden.
• inlining=(on|off)
  Steuert das Inlining von Funktionen.
• debug-symbols=(on|off)
  Steuert, ob pdb-Dateien erzeugt werden.
• runtime-debugging=(on|off)
  Ehrlich gesagt, ich hab keine Ahnung.
• profiling=(on|off)
  Schaltet das Generieren von profile-barem Code an oder aus.

Es gibt natürlich noch mehr Optionen. Bei Bedarf werde ich das Blog-Post entsprechend erweitern. Eine Liste von “eingebauten” Flags gibts auch bei Boost.

STLport

Um Bibliotheken erstellt zu bekommen, die mit STLport zusammenarbeiten, reicht es nicht, stdlib=stlport zu übergeben; man muß einen Schritt weitergehen. Die Datei user-config.jam ist anzupassen und ist in tools/build/v2 zu finden. Folgende Zeile sollte man hinzufügen (bzw. man braucht sie nur einzukommentieren, sie ist schon da):

using stlport : : {Pfad-zu-stlport-include-Folder} {Pfad-zu-stlport-lib-files} ;

Die Zeile könnte in etwa so aussehen:

using stlport : : D:\devel\STLport-5.1.4\stlport D:\devel\STLport-5.1.4\lib ;

Verwendet man mehrere STLport-Versionen, so gehört die Versionsnummer zwischen die ersten beiden Doppelpunkte (z.B. “stlport : 5.1.4 : pfad pfad“). In der bjam-Kommandozeile ist dann stdlib=stlport-{Version} anzugeben (z.B. “stdlib=stlport-5.1.4″).

Die erstellten Bibliotheken enthalten im Dateinamens-Suffix zusätzlich den Buchstaben p, der die Abhängigkeit zu STLport signalisiert. Endungen sind dann z.B. “vc80-mt-gdp-1_35″ oder “vc80-mt-p-1_35″.

Noch ein Hinweis für den Debug-Modus: Boost wird mit definiertem _STLP_DEBUG kompiliert, seine Debug-Targets sollte man also besser auch mit dem gesetzen define kompilieren.

Exceptions

Exceptions sind Ausnahmebedingungen im Programm. In vielen Sprachen gibt es Exceptions, in C++, C# und VB.NET (bzw. alle .NET-Sprachen), Javascript und sogar in PHP ab Version 5. In Visual C unter Win32 gibt es SEH. Eine Exception wird mit einem throw-Schlüsselwort geworfen. Es kann für gewöhnlich ein Objekt jedes beliebigen Typs geworfen werden, wobei viele Sprachen Exception-Klassen und ganze -Hierarchien definieren.

Programmcode, der Exceptions auslösen kann, kann mit einem try-Block umschlossen werden. Aufgefangen wird eine Exception dann im nachfolgenden catch-Block, und man kann meist mehrere Blöcke für verschiedene Typen angeben. Verläßt der Programmfluß den catch-Teil, ohne wieder eine Exception auszulösen, gilt die ursprüngliche Ausnahme als gehandlet. Es kann die aufgefangene meist rethrow’t werden, wenn das benötigt wird. Manche Sprachen erlauben einen finally-Block, der nach der Exception-Behandlung oder dem try-Block ausgeführt wird. C++ braucht das nicht, und Bjarne Stroustrup erklärt, warum.

Wird eine Exception vom Programm nicht gehandlet, wird das Programm beendet, und zwar ohne weitere Meldung. Stellte die Applikation ein Fenster da, scheint das Programm von einem auf den nächsten Moment verschwunden zu sein. Dies gilt es natürlich zu vermeiden. In C++ gibt es eine weitere Verhaltensweise, die ähnlich arbeitet. Wird eine Exception geworfen, während das “stack unwinding” passiert, also z.B. in einem Destruktor, beendet sich das Programm auch (siehe z.B. dieser Artikel von Boris Kolpackov). Selbes passiert, wenn eine Funktion oder Methode eine Exception wirft, die sie nicht in ihrer “exception specification”-Liste erwähnt. Also nicht so ganz trivial in C++.

Nicht ganz einfach ist auch die Frage, wo und wann Exceptions geworfen werden sollen. Dies wird z.B. in einem Artikel von Ned Batchelder aufgegriffen:

http://nedbatchelder.com/text/exceptions-in-the-rainforest.html

Asserts

Asserts ist bestimmt auch schon jeder begegnet. In C++ über den Header <cassert> bereitgestellt kann man die assert()-Methode aufrufen. Sie zeigt z.B. unter Win32 eine MessageBox an, wenn der Ausdruck, die der Funktion mitgegeben wird, gleich 0 oder false ist. “to assert” heißt übersetzt “bestätigen” oder “sich versichern”, und genau dafür wird die Funktion benutzt. In der MFC gibts das Makro ASSERT (und VALIDATE), in ATL heißt es ATLASSERT (bzw. ATLVALIDATE), in der C-Runtime gibts zusätzlich _ASSERT und _ASSERTE, in .NET-Sprachen gibts System.Diagnostics.Debug.Assert, und auch in PHP gibt es eine entsprechende Funktion.

Besonderheit der von Microsoft definierten assert-Makros wie ASSERT und ATLASSERT ist, daß sie über die defines _DEBUG und NDEBUG gesteuert werden. Ist NDEBUG definiert, z.B. beim Kompilieren für das Release-Target, ist ASSERT ein leeres Statement. Mögliche Fehlerquelle ist, wenn man ein Funktionsaufruf in ASSERT verwendet. Dafür hat Microsoft zusätzlich VERIFY erfunden. Die Makros sind im Release-Modus also no-op’s, im Debug-Modus zeigen sie die oft verwünschten Dialogboxen an. In .NET ist es ähnlich, dort wird allerdings im Konfigurationsfile für die Applikation angegeben, ob die System.Diagnostics.Debug-Klasse etwas ausgibt.

Wer Unit-Tests mit den verschiedenen verfügbaren Frameworks (wie CppUnit, NUnit, PHPUnit, etc.) schreibt, ist noch ein anderer Assert untergekommen. Mit CPPUNIT_ASSERT(), NUnit.Assert, etc. wird z.B. in einer Testfunktion ein erwarteter Zustand abgefragt. Da man Unit-Tests auch mit einer Release-Version laufen lassen will, um sicherzustellen, daß es auch dort keine Überraschungen gibt, müssen diese Asserts natürlich immer ausgeführt werden. Sie heißen zwar auch so, sind aber für was anderes gedacht.

Exceptions vs. Asserts

Wann aber verwendet man was? Manche schwören auf Exceptions, andere benutzen (noch) Rückgabewerte zur Fehlerbehandlung. Sie sagen, Exceptions sind unkontrollierbar und setzen sich durchs ganze Programm fort, wenn man nicht aufpaßt. Genauso die Assert-Skeptiker, die bei der Erwähnung der selben schon überall MessageBoxen aufgehen sehen. Beide haben aber Vorteile und sollten so eingesetzt werden, wie die beiden Features angedacht sind. Und das geht sogar gleichzeitig.

Wenn man sich sonst nichts von diesem Post merken braucht, sind es die zwei Kriterien für den Einsatz von Exceptions und Asserts:

• Exceptions werden verwendet, wenn ein vorhersehbarer Fehler eintritt und gehandled werden soll
• Asserts sind zu verwenden, um unvorhersagbare Fehler während der Entwicklung festgestellt werden sollen

Exceptions können z.B. auftreten, wenn eine Datei, die ich an einer bestimmten Stelle erwarte, nicht vorhanden ist. Oder wenn ein Soap-Aufruf ein Datenfeld zurückliefert, das Daten in einem anderen Format beinhaltet, als das Programm es erwartet (Soap-Aufrufe können ja von jedermann generiert werden). Exceptions decken also Fehler auf, mit denen gerechnet werden muß.

Exceptions sind im ausgelieferten Programm immer noch vorhanden, müssen also gehandled werden. Irgendwann muß eine lesbare Meldung formatiert und dem Benutzer präsentiert werden. Möglicherweise kann er das Problem beheben (Datei an die passende Stelle kopieren), möglicherweise kann er aber auch nicht viel machen und muß das Programm beenden.

Vorteil von Exceptions ist, daß man sie nicht ignorieren kann. Solche vorhersehbaren Fehler dürfen auch nicht ignoriert werden. Die Ausnahme wird sonst an übergeordnete Programmteile weitergegeben. Das “Vergessen” des Prüfens eines Return-Wertes gibt es damit nicht mehr. Nachteil ist, daß Exception-Handling Disziplin vom Programmierer erfordert. Es muß jede Exception aufgefangen und in irgend einer Weise behandelt werden. Es muß schon vor dem Schreiben von Programmcode klar sein, in welcher Schicht Exceptions gehandled werden, und wo sie nur durchgelassen werden. Es muß festgelegt sein, welche Exception-Klassen verwendet werden. Daraus resultiert im Ende dann eine stabilere Software.

Asserts sollten verwendet werden, wenn ein bestimmter Zustand abgeprüft werden soll, der einen Bug aufzeigt. Beispiele sind z.B., wenn der Aufrufer einer Funktion einen NULL-Zeiger übergibt, dieser aber nicht erlaubt ist. Ein weiteres Beispiel ist, wenn eine Klasse eine Initialisierungsreihenfolge erwartet, diese aber vom Benutzer der Klasse nicht korrekt ausgeführt wurde. Ein Assert deckt also Bugs im Programm auf. Gern wird ein Assert benutzt, um Eingangsparameter einer Funktion zu prüfen. Ein möglicher Aufrufer erfährt beim Testen dann schon, ob er die Funktion richtig verwendet (nämlich wenn kein Assert auftritt).

Asserts sind im fertigen Programm nicht mehr vorhanden (da durch Makro zum no-op gemacht oder per Konfiguration ausgeschaltet), können also bei Kundensoftware nicht mehr auftreten. An der Stelle, an der ein Assert auftreten würde, würde das Programm dann einfach von falschen Annahmen ausgehen und abstürzen. Ein klarer Bug, der vom Entwickler gefixt werden müßte. Dies verhindet Bananensoftware (reift beim Kunden) und erzwingt, eine gute Qualitätssicherung und Tests der Software durchzuführen. Auch der Entwickler tut gut daran, mit Unit Tests sicherzustellen, daß seine Klassen auch genau das machen, was sie sollen, und möglichst ohne Asserts (und Bugs).

Vorteil von Asserts sind, daß sie einem sofort zeigen, wo ein Bug ist, und (hat man den Quellcode) sie dokumentieren, welche Erwartungen an den aufrufenden Code gemacht werden. Außerdem verbrauchen sie keinen Speicherplatz und Laufzeit in ausgelieferten Versionen der Software. Nachteil an Asserts ist, daß es schwer ist zu entscheiden, wann ein Assert angebracht ist, oder ob eher eine Exception geworfen werden soll. Das muß man sich am Anfang der Entwicklung überlegen und evtl. in Software-Richtlinien für beteiligte Entwickler festlegen.

Der Symbol Server von Microsoft liefert während des Debuggens die Symbol-Informationen von Microsoft-DLLs, z.B. kernel32.dll oder user32.dll. Manchmal kann dies ganz nützlich sein, da man einen Fehler dann besser eingrenzen kann.
Wie man den Symbol Server benutzt, wird in KB 311503 erklärt. Voraussetzung ist, daß man die Debugging Tools for Windows installiert hat. Der Konfigurationsstring ist dabei folgendermaßen aufgebaut:

SRV*Pfadangabe*http://msdl.microsoft.com/download/symbols

Die Angabe für Pfadangabe bezeichnet dabei einen Pfad auf der Festplatte, in dem die Symbol-Dateien abgelegt werden. Der String kann folgendermaßen benutzt werden:

• In die System-Umgebungsvariable _NT_SYMBOL_PATH schreiben. Dadurch wird in jedem Prozess, der per Visual Studio oder WinDbg debuggt wird, mit den Symbolen aus dem Symbol-Cache gearbeitet
• Im Visual Studio eintragen. Dazu gibts für Visual Studio 2003 die Möglichkeit, pro Projekt in den Einstellungen unter “Debug” das Feld “Symbol Info” auszufüllen. In Visual Studio 2005 Express gibts sogar die Möglichkeit unter “Tools -> Options -> Debugging -> Symbols -> ” für alle Projekte den Symbol-Server einzustellen.
• Benutzt man die dbghelp.dll aus den Debugging Tools, um Symbole aufzulösen, kann man in der Funktion SymSetSearchPath den Symbol-Cache angeben.

Startet man den Debugger, so werden die Symbole geladen. Hat eine DLL noch keine Symbole, z.B. durch eine vorhandene PDB-Datei, wird der Symbol Server konsultiert, und falls vorhanden eine entsprechende .pdb (oder .dbg, im Fall von WinDbg) im Symbol-Cache gespeichert. Da man am Anfang einen leeren Cache hat, dauert es beim ersten Start oder wenn die Symbole einer neuen Datei noch nicht nachgeladen ist, etwas länger.

Läßt man den hinteren Teil nach dem zweiten * weg, wird nur der lokale Symbol-Cache benutzt, das Visual Studio versucht auch nicht, weitere Symbole nachzuladen. Dadurch wird das Starten eines zu debuggenden Programms wieder schneller.

1. Die benötigten Klassen sind in <atlframe.h>, also diese Header irgendwo includen.

2. Zusätzlich das gewünschte Fenster von CDialogResize ableiten:

  class CMyDialog: public CDialogImpl<CMyDialog>,
     public CDialogResize<CMyDialog>
  {

3. Die Resize-Map der Klasse hinzufügen:

  BEGIN_DLGRESIZE_MAP(CMyDialog)
      [...]
  END_DLGRESIZE_MAP()

4. Die Resize-Map ist dann auf folgende Weise für alle Controls, die resized oder bewegt werden, zu füllen:

  BEGIN_DLGRESIZE_MAP(CMyDialog)
     DLGRESIZE_CONTROL(IDC_EDIT_NAME, {flags})
     DLGRESIZE_CONTROL(IDC_BUTTON_START, {flags})
     BEGIN_DLGRESIZE_GROUP()
        DLGRESIZE_CONTROL(IDC_COMBO_ITEMS, {flags})
        [...]
     END_DLGRESIZE_GROUP()
  END_DLGRESIZE_MAP()

Es können Untergruppen spezifiziert werden, die die beinhalteten Controls zusammenfassen.

5. Folgende flags sind erlaubt, die auch per oder-Verknüpfung kombiniert werden können:

• DLSZ_SIZE_X Das Control wird in X-Richtung vergrößert oder verkleinert.
• DLSZ_SIZE_Y Das Control wird in Y-Richtung vergrößert oder verkleinert.
• DLSZ_MOVE_X Das Control wird in X-Richtung bewegt.
• DLSZ_MOVE_Y Das Control wird in Y-Richtung bewegt.
• DLSZ_REPAINT Bei Änderungen wird das Control neu gezeichnet, in dem Invalidate() aufgerufen wird.

6. In OnInitDialog() muß folgende Funktion aufgerufen werden:

  DlgResize_Init(bool bAddGripper = true, bool bUseMinTrackSize = true, DWORD dwForceStyle = WS_CLIPCHILDREN);

Die Parameter haben folgende Bedeutung:

• bAddGripper: wenn true, wird ein Gripper-Symbol an der rechte untere Ecke gezeichnet
• bUseMinTrackSize: stellt beim ersten Resize-Aufruf fest, welche die kleinste Größe des Dialogs bzw. Fensters ist
• dwForceStyle: setzt den angegebenen Style für das Fenster. Hinweis: WS_CLIPCHILDREN funktioniert mit Gruppierungs-Rahmen nicht

7. In die Message-Map der Klasse muß folgende Zeile am Ende eingefügt werden, damit die Resize-Klasse mit den nötigen Windows-Messages versorgt werden:

  CHAIN_MSG_MAP(CDialogResize<CMyDialog>)

8. Der Dialog oder das Fenster muß den Style WS_THICKFRAME erhalten, sodaß der Benutzer dann auch die Größe des Fensters verändern kann. Im Visual Studio stellt man im Resource-Editor dazu das Property “Border” auf “Resizing”. Bei Bedarf kann man auch noch “Minimize Box” und “Maximize Box” einschalten, um die entsprechenden Buttons in der Titelleiste zu bekommen.

I already tried to compile cairo once, using the age-old evc4. See cairo mail archives, post 1, post 2 and patch. Since then, much has happened with the cairo project. The main deficiencies with Windows CE unfortunately stayed, though.

Setting up a Visual Studio project

I chose to first set up a project in Visual Studio 2008 (beta 2, still) and compiling cairo for Win32, so that I knew afterwards that I chose the proper files and settings to compile. First, unzip cairo (I used cairo-1.4.14) to a folder of your choice.

1. I created a “win32″ folder besides the other folders like “src” and “pixman” to put all win32-related project files in.

2. In this folder I created a Win32 DLL project with no files and added all *.h and all *.cpp files in the “src” folder that I could find.

3. I created two files in win32, a cairo-features.h and an empty cairo-deprecated.h. Here’s the contents of the cairo-features.h file:

#ifndef CAIRO_FEATURES_H
#define CAIRO_FEATURES_H

#ifdef  __cplusplus
# define CAIRO_BEGIN_DECLS  extern "C" {
# define CAIRO_END_DECLS    }
#else
# define CAIRO_BEGIN_DECLS
# define CAIRO_END_DECLS
#endif

#ifndef cairo_public
# define cairo_public
#endif

#define CAIRO_VERSION_MAJOR 1
#define CAIRO_VERSION_MINOR 4
#define CAIRO_VERSION_MICRO 14

#define CAIRO_VERSION_STRING "1.4.14"

#define CAIRO_HAS_WIN32_SURFACE 1
#define CAIRO_HAS_WIN32_FONT 1

// stuff that normally belongs to a generated config.h:

#define HAVE_WINDOWS_H 1
#define PACKAGE_VERSION "cairo-" CAIRO_VERSION_STRING
#define PACKAGE_BUGREPORT "http://bugs.freedesktop.org/enter_bug.cgi?product=cairo"

#endif

There are more features that can be enabled with CAIRO_HAS_XXX, but as I’m only interested in rendering to a window, these should be enough.

4. I disabled the following files (General -> Excluded from Build: Yes); you can also remove them from the project altogether: cairo-atsui-font.c, cairo-beos-surface.cpp, cairo-directfb-surface.c, cairo-ft-font.c, cairo-glitz-surface.c, cairo-os2-surface.c cairo-pdf-surface.c, cairo-png.c, cairo-ps-surface.c, cairo-quartz-surface.cpp, cairo-svg-surface.cpp, cairo-type1-subset.c, cairo-xcb-surface.c, cairo-xlib-display.c, cairo-xlib-screen.c, cairo-xlib-surface.c

5. Cairo needs zlib, so you have to include the folder containing “zlib.h” and “zconf.h”. Later you have to link against a precompiled version of zlib (I used the Visual Studio projects in the contrib folder of zlib to generate a static linkable .lib file)

6. Before hitting compile, I set some include paths, namely: “.;..\src;..\pixman\src”. Remember that include paths are specified relative to the .vcproj file. I also set some more defines: _CRT_NONSTDC_NO_WARNINGS, to prevent warnings on strdup() usage, and _CRT_SECURE_NO_WARNINGS for silencing warnings on crt functions not considered safe by Microsoft. For proper linking to zlib, I also had to define ZLIB_WINAPI, but that depends on how zlib was compiled. In the linker settings I added in “Input -> Ignore Specific Library” the value “msvcrt” for debug builds, or else the cairo.dll is then linked to msvcr90.dll and msvcr90d.dll. Note that official cairo DLLs are named libcairo-2.dll, so the output file could be changed to this name if necessary.

7. Cairo needs pixman, a library that is provided in the “pixman” subfolder. I created another static lib project and added dependencies for the cairo DLL project. This way cairo.dll automatically links in pixman.lib. It’s magic! The pixman project doesn’t need special settings and is pretty much self-contained.

8. Compiling and linking gives a cairo.dll, but checking with Dependency Walker reveals that it doesn’t export any functions. A cairo.def file is generated by the automake makefiles, but lacking the autotools I just downloaded a developer package from Tor Lillqvist’s GTK+ for Windows page (e.g. cairo-dev-1.4.10.zip, the version number doesn’t have to match exactly, since the exported functions are probably the same), got the cairo.def from the “lib” folder inside the .zip and placed it in our “win32″ folder. An entry in the project settings under “Linker -> Input -> Module Definition File” completes this task. Note that some functions cannot be found while linking, e.g. for svg or png output; I commented out the entries in the .def file with the ; comment character.

Going PocketPC

9. Now we should have a cairo DLL that properly exports its functions. Let’s create the DLL for the PocketPC platform now. Go into the “Build -> Configuration Manager” dialog and add a new solution platform. I chose “Windows Mobile 5.0 Pocket PC SDK (ARMV4I)”. On the next dialog choose “<Empty>” for the “Copy settings from:” combobox, or else you will get wrong compiler and linker settings for your ARM platform. Note that you have to set up compiler and linker settings and build-ignored files again for this platform, but this should be easy.

10. While compiling there are some errors we have to fix for the PocketPC platform. The first is in pixmanint.h, where MAXSHORT and MINSHORT is redefined, since the macros already exist in ARM compiler’s winnt.h include file. I replaced the defines with the following:

#ifndef _WIN32_WCE
#define MAXSHORT SHRT_MAX
#define MINSHORT SHRT_MIN
#endif

The second fix is in cairo-mutex-type-private.h, where mutex stuff is defined. On Win32 the CRITICAL_SECTION type is used for locking, but the structure looks different and has one less member in Windows CE. I replaced the define for CAIRO_MUTEX_NIL_INITIALIZER with this code:

# ifndef _WIN32_WCE
# define CAIRO_MUTEX_NIL_INITIALIZER { NULL, 0, 0, NULL, NULL, 0 }
# else
# define CAIRO_MUTEX_NIL_INITIALIZER { 0, NULL, NULL, 0, 0 }
# endif

Fixing platform deficiencies

11. Compiling should now work for all files except cairo-win32-surface.c and cairo-win32-font.c. The first one should be easier to fix, the second one does more headaches.

The first error in cairo-win32-surface.c is easily fixed, though. In the function _cairo_win32_print_gdi_error the Win32 function FormatMessageA is called. When compiling with unicode settings (in the General settings, choose “Use Unicode Character Set” as “Character Set”; it’s the default setting for new projects in Visual Studio 2005 and 2008) the TCHAR type resolves to WCHAR and LPTSTR resolves to LPWSTR, but FormatMessageA wants LPSTR. The concerning line is changed so that the call looks like:

    if (!FormatMessageA (FORMAT_MESSAGE_ALLOCATE_BUFFER |
             FORMAT_MESSAGE_FROM_SYSTEM,
             NULL,
             last_error,
             MAKELANGID (LANG_NEUTRAL, SUBLANG_DEFAULT),
             (LPSTR) &lpMsgBuf,
             0, NULL)) {

12. The next error one on the list is a warning about an undefined GdiFlush() function. It’s not available under CE, so I ignore it for now. Later at linking stage the function must be there in some form, and be it some empty dummy function.

13. In the function _composite_alpha_blend there is another warning about converting from char [8] to LPCWSTR. It’s the same unicode issue as above, so either “LoadLibraryA(“msimg32″);” or LoadLibraryW(L”msimg32″);” should be used. The GetProcAddress() warning some lines down is a bit tricky. Under Win32 there is only one GetProcAddress() function that always takes an LPCSTR, in the WinCE API there are two versions, GetProcAddressA takes an LPCSTR and GetProcAddressW takes an LPCWSTR. The code again has to be changed to use GetProcAddressA to get it to work on all platforms.

14. Next on the list is usage of HALFTONE in a call to SetStretchBltMode. According to the documentation, the function only supports the flags BLACKONWHITE , COLORONCOLOR and BILINEAR on Windows CE. The Windows Embedded blog states the same. A fix is to either define HALFTONE (value on Win32 would be 4) and hope the function is never called or the functionality isn’t needed, use another value for HALFTONE (e.g. COLORONCOLOR) or just #ifdef out the call to SetStretchBltMode() altogether.

15. The next error is harder; The function ExtTextOutW is called to produce text output. It uses the flags ETO_GLYPH_INDEX and ETO_PDY, which both are not supported on Windows CE (see Win32 documentation counterpart). The flag ETO_GLYPH_INDEX means that the passed lpString pointer contains 16-bit words that represent glyph indices of a certain font. The GetCharacterPlacement function (which is not available in WinCE) is used to produce this array. The ETO_PDY flag specifies that the array passed in lpDx actually consists of pairs of x and y displacement values for each glyph. This is used in cairo for drawing rotated or transformed text (I guess so from the sources).

A possible solution for this problem to work around would be to simulate drawing the glyphs on calculated positions using ExtTextOut, character per character, assuming that the glyph index is the same as the unicode character value (which may not always be the case for some languages and composite characters). Another alternative would be to use Uniscribe, but that is available starting with WM5 and isn’t packaged with every device (see here; note that OEMs build their ROMs using Platform Builder and choose what to include); more interesting reads: about GetCharacterPlacement, and about Uniscribe on WinCE.

Since there is no easy solution for this, I just commented out the function body, so text rendering isn’t supported by cairo on Windows CE for now. Revisiting my changes to cairo, I saw that I tried to reimplement GetCharacterPlacement and some more needed functions, but that code has to be looked upon again. In the end I didn’t manage to bring rendered text onto a cairo surface.

Epilog

For now I’m closing this article. The next one on that topic describes the remaining missing functions that prevent to compile cairo for Windows CE. Workarounds are discussed, too, so in the end it should be possible to at least get something on the screen.

#pragma warning(disable: 4355) // 'this' : used in base member initializer list class Iterator
{
public:
   Iterator()
      :m_this(this)
   {
      OutputDebugString(_T("ctor\n"));
   }

   Iterator(const Iterator&)
      :m_this(this)
   {
      OutputDebugString(_T("copy ctor\n"));
   }

   ~Iterator()
   {
      OutputDebugString(_T("dtor\n"));
      if (m_this != this)
         OutputDebugString(_T("wrong m_this!\n"));
   }

   Iterator& operator=(const Iterator&)
   {
      OutputDebugString(_T("assign operator\n"));
      return *this;
   }
private:
   Iterator* m_this;
};

void ByVal(Iterator i)
{
}

void ByRef(Iterator& i)
{
}

void Test()
{
   Iterator i;
   ByVal(i);
   ByRef(i);
}

Just running this code in the debugger should yield the following output:

ctor
copy-ctor
dtor
wrong m_this! (*)
dtor

(*) Note that this line is only printed when the bug is present, that means all compiler versions before the one in Visual Studio 2008.

Let’s analyze the test code in detail.

#pragma warning(disable: 4355) // 'this' : used in base member initializer list
 class Iterator
 {
 public:
    Iterator()
       :m_this(this)
    {
       OutputDebugString(_T("ctor\n"));
    }

The pragma is needed to prevent a warning about using this in the ctor. It is allowed to store the this pointer, so we can ignore the warning safely (Since the object isn’t fully constructed, the this pointer shouldn’t used for something else). The remainder of the ctor prints out a debug message.

   Iterator(const Iterator&)
       :m_this(this)
    {
       OutputDebugString(_T("copy ctor\n"));
    }

The copy ctor does the same as the ctor, it stores the this pointer in the m_this member and prints out a diagnostic.

   ~Iterator()
    {
       OutputDebugString(_T("dtor\n"));
       if (m_this != this)
          OutputDebugString(_T("wrong m_this!\n"));
    }

The destructor checks the m_this pointer if it’s the same as the address of the object we’re currently destroying. If it’s not, a diagnostic message is output. Since we have two ctors that set the m_this member to this and no other way to set m_this, this should always succeed. Or so we thought.

   Iterator& operator=(const Iterator&)
    {
       OutputDebugString(_T("assign operator\n"));
       return *this;
    }
private:
   Iterator* m_this;
};

As we are good C++ developers, we write an assignment operator along with the copy-ctor, even it isn’t called anywhere. The remaining class lists the m_this member variable. Now on to the test code…

void ByVal(Iterator i)
{
}

void ByRef(Iterator& i)
{
}

void Test()
{
   Iterator i;
   ByVal(i);
   ByRef(i);
}

The first two functions take an object of our test class, either by value or by reference. At the end of the first function the local variable i should be destroyed. The last function calls the two first ones using a local Iterator variable.

Compiling code for the ARM processor (e.g. for the PocketPC devices) is special in case of calling conventions. The compiler passes the first four 32-bit values of all parameters (e.g. 4 pointers or the first four 32-bit-words of a struct) in the registers R0 to R3. If there is more space needed, the caller of a function stores the remaining data on the stack. The first thing that the called function does is storing the registers to the first four 32-bit-words. I didn’t try it out, but I guess the compiler doesn’t store the arguments if they can stay in the registers. For a struct that has to be accessed, e.g. by taking a pointer, the data bytes must be stored somewhere, though. The whole stuff is described in MSDN, in the articles under ARM Calling Sequence Specification, e.g. in ARM Stack Frame Layout. (The topic in the evc4 help even has a fancy image showing the stack; the platform builder version of the second link also has the image)

The bug manifests itself when data is passed by-value to a function. When passing a non-POD type by value, the copy-ctor is called to create a temporary copy of the object, usable inside the function. For POD types the memory bytes are just copied to a temporary. Inside the function the dtor is called, essentially cleaning up the temporary again (at least that is the way the Visual C++ ARM compiler generates the code). The combined effect of passing arguments by register and by value may show the bug. The copy-ctor-constructed temporary is passed in the registers R0 to R3 and then copied to the stack by the function itself. The temporary inside the function has an other address as the temporary that was copy-constructed.

This should normally pose no problem, since the object is properly destroyed afterwards. There is one problem, though, and that occurs when the this pointer in the copy-ctor is stored somewhere. One example could be functions that register and deregister the class, e.g. in an observer pattern:

struct Resource
{
   Resource(){ Register(this); }
   Resource(const Resource&){ Register(this); }
   ~Resource(){ Unregister(this); }
};

In the copy-ctor a wrong pointer would be passed, and at the time of unregistering the pointer wouldn’t be found.As mentioned, the bug was fixed in Visual Studio 2008, but of course it’s interesting what happens under the hood. For this to find out I will dig a bit deeper in the next post. We’re using a test program and ARM disassembly to show what’s going on.

LVITEM lvItem;
lvItem.mask = LVIF_GROUPID;
lvItem.iItem = iItemIndex;
lvItem.iSubItem = 0;
lvItem.iGroupId = iGroupID;
SetItem(&lvItem);

Was auch nicht geht, ist für LVGROUP::uAlign das Flag LVGA_FOOTER_CENTER anzugeben. Der InsertGroup()-Aufruf schlägt dann fehl. Außerdem werden bei einem Aufruf von GetGroupMetrics() nicht alle Felder zurückgeliefert. Die Dokumentation beschreibt, was not implemented ist. Einfacher wäre fast gewesen zu dokumentieren, was überhaupt implementiert ist.