[ft-devel] Problems building FreeType 2 demo programs on the Windows pla
From:
Colin Fahey
Subject:
[ft-devel] Problems building FreeType 2 demo programs on the Windows platform
Date:
Fri, 13 Oct 2017 09:51:33 -0700
Problems building FreeType 2 demo programs on the Windows platform
2017 October 13
INTRODUCTION
This note describes problems building the FreeType 2 demo programs on the Windows platform, and proposes fixes.
While I believe the proposed fixes should not cause problems for other platforms, I was not able to test this. Therefore, please regard the proposed fixes as hints for possibly better fixes.
In the following sections, I describe:
* Operating system * Compiler * GNU Make * Version of FreeType source code * Preparation for building * Building FreeType 2 library * Building FreeType 2 demo programs : Problems and Workarounds * Testing
I hope the level of detail below does not seem too tedious. I just wanted to be clear about my development conditions.
(3) Extract the contents of "make-3.81-bin.zip" to a folder.
(4) Extract the contents of "make-3.81-dep.zip" to a folder.
(5) Copy the files "libiconv2.dll" and "libintl3.dll" from the "make-3.81-dep\bin\" folder, and put the copies in to the "make-3.81-bin\bin\" folder (alongside the "make.exe" application file).
(7) Click the download link ("freetype2-demos-master.tar.gz").
(8) Note the commit date and time (e.g., "2017-10-10 23:34:00 -0400").
PREPARATION FOR BUILDING
(1) Create a folder named "freetype_build_test".
(2) Extract contents of file "freetype2-demos-master.tar.gz" to an arbitrary location. =============================================== (Result is a folder hierarchy which contains the file "freetype2-demos-master.tar".) ===============================================
(3) Extract contents of file "freetype2-demos-master.tar" to an arbitrary location. =============================================== (Result is a folder hierarchy which contains the folder "freetype2-demos-master", which directly contains the "src\", "graph\", and "obj\" folders, etc., for the demo programs.) ===============================================
(4) Extract contents of file "freetype2-master.tar.gz" to an arbitrary location. =============================================== (Result is a folder hierarchy which contains the file "freetype2-master.tar".) ===============================================
(5) Extract contents of file "freetype2-master.tar" to an arbitrary location. =============================================== (Result is a folder hierarchy which contains the folder "freetype2-master", which directly contains the "src\", "include\", and "builds\" folders, etc., for the FreeType 2 library.) ===============================================
(6) Copy the "freetype2-master" *folder* (which directly contains the "src\" subfolder, etc.) directly in to the "freetype_build_test" folder (from step (1)). =============================================== (Result is that the "freetype_build_test" folder directly contains the folder "freetype2-master" folder, which directly contains "builds\" subfolder, etc.) ===============================================
(7) Rename the "freetype2-master" folder (within the "freetype_build_test" folder) to "freetype2".
(8) Copy the "freetype2-demos-master" *folder* (which directly contains the "graph\" subfolder, etc.) directly in to the "freetype_build_test" folder (from step (1)). =============================================== (Result is that the "freetype_build_test" folder directly contains the folder "freetype2-demos-master" folder, which directly contains "graph\" subfolder, etc.) ===============================================
BUILDING FREETYPE 2 LIBRARY
(1) Start "Visual Studio Command Prompt (2010)":
=============================================== Start menu [icon] --> "All Programs" [link] --> "Microsoft Visual Studio 2010 Express" [folder] --> "Visual Studio Command Prompt (2010)" [icon] ===============================================
(2) Within the Visual Studio command prompt, change directory to the "freetype2" folder:
=============================================== cd [path of "freetype_build_test" folder]
cd freetype2 ===============================================
(3) Within the Visual Studio command prompt, use GNU Make application to configure build system for the Visual C++ compiler. Start "make.exe" with parameters "setup visualc".
=============================================== src\output.c(295) : error C2220: warning treated as error [...] src\output.c(295) : warning C4333: '>>' : right shift by too large amount, data loss src\output.c(296) : warning C4333: '>>' : right shift by too large amount, data loss ===============================================
CAUTION! Although the compiler is "merely" issuing a warning, in fact this is a clue of an actual logical bug in this code!
Note that freetype_build_test\freetype2\include\freetype\fttypes.h defines the following:
A UTC-16BE character from the byte array is put in to the lowest 16 bits of the integer.
If the output format is not UTF-8, then it seems like the intent of the code is to render UTC-16 code points at or beyond 0x80 as escape sequences of the form "\u####".
CAUTION! I am using VC++ 2010 and its associated C Runtime Library (CRT). This problem might not occur for later versions of VC++ (with their associated CRT files).
(4) SOLUTION:
I am using VC++ 2010, which has its C Runtime Library (CRT) "include" files in the following folder:
=============================================== C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\include ===============================================
The "conio.h" file defines "_getch", but not "getch".
The "stdio.h" file defines "_snprintf", but not "snprintf".
CAUTION! Later versions of the VC++ CRT might define the non-underscore symbols, reversing a long-time decision; I don't know.
Consider the following block of code starting at line #44:
So, we can limit the fix to VC++ compilers by first testing whether "_MSC_VER" is defined at all. Then, we can further limit to VC++ 2010 and earlier by testing for "_MSC_VER <= 1600".
If the CRT for VC++ for later versions of VC++ also do not define "getch" and/or "snprintf", then the version number test proposed here can be modified accordingly. I can only say that this problem likely includes versions up to and including VC++ 2010 (i.e., internal version number 1600).
PROBLEM #3
(1) Start "Visual Studio Command Prompt (2010)":
=============================================== Start menu [icon] --> "All Programs" [link] --> "Microsoft Visual Studio 2010 Express" [folder] --> "Visual Studio Command Prompt (2010)" [icon] ===============================================
(2) Within the Visual Studio command prompt, change directory to the "freetype2-demos-master" folder:
=============================================== cd [path of "freetype_build_test" folder]
cd freetype2-demos-master ===============================================
(3) Within the Visual Studio command prompt, use GNU Make application to build the FreeType 2 demo programs. Start "make.exe" without any parameters.
The problem seems to be that VC++ 2010 (and possibly/probably earlier versions of VC++) compile this C source file with old C language expectations, where variable declarations in the body of a function are all before any other kinds of statements, and the statement "(void)color;", which is clearly intended to bypass a compiler warning for some other compiler (e.g., GCC), hilariously/ironically causes the problem for VC++.
(4) SOLUTION:
The fix is actually really easy! Simply put the dummy access to "color" *AFTER* the #include statement!
The ultimate cause of this problem was tricky to find!
First, recall that the procedure for building the FreeType 2 library began by "make setup visualc". This created the file "freetype_build_test\freetype2\config.mk", which, for "visualc" configuration, includes "freetype_build_test\freetype2\builds\windows\win32-def.mk". That "win32-def.mk" file contains the following statement:
=============================================== PLATFORM := windows ===============================================
Meanwhile, for the FreeType 2 demo programs build process, the "freetype_build_test\freetype2-demos-master\Makefile" has the following statement:
=============================================== include $(GRAPH_DIR)/rules.mk
The crucial thing to observe is that the statements in the body of this file will only be processed if $(PLATFORM) is "win32".
However, as mentioned above, the "win32-def.mk" file set PLATFORM to "windows" (and not "win32")!!
The result is that "graph\win32\rules.mk" won't override the definition of the "COMPILE_GRAPH_LIB" with the correct command (i.e., "lib", in this case).
This causes "graph\rules.mk" to use its default choice for COMPILE_GRAPH_LIB, which, if LIBTOOL is not defined, will be the UNIX/Linux "ar" (archive) command, and hence the error described above.
(4) SOLUTION:
The solution is trivial!
In the file "graph\win32\rules.mk", change "win32" to "windows" in the very first statement, resulting in the following line:
=============================================== src\ftgrid.c(1350) : error C2220: warning treated as error [...] src\ftgrid.c(1350) : warning C4244: '*=' : conversion from 'double' to 'FT_F26Dot6', possible loss of data ===============================================
The following is a relevant fragment of "src\ftgrid.c":
is effectively doing "FT_F26Dot6 *= double", or "signed long *= double".
The problem is that the multiplication implicitly promotes the signed long to double, but the subsequent assignment of the product (a double) back to the signed long would lose precision.
Clearly, the loss of precision is acceptable here, given the way this value is used. So...
=============================================== src\ftstring.c(41) : error C2220: warning treated as error [...] src\ftstring.c(41) : warning C4566: character represented by universal-character-name '\u039F' cannot be represented in the current code page (1252) src\ftstring.c(41) : warning C4566: character represented by universal-character-name '\u03BA' cannot be represented in the current code page (1252) src\ftstring.c(41) : warning C4566: character represented by universal-character-name '\u03B1' cannot be represented in the current code page (1252) src\ftstring.c(41) : warning C4566: character represented by universal-character-name '\u03BB' cannot be represented in the current code page (1252) [ . . . and MANY more warnings like this . . . ] ===============================================
The file "freetype_build_test\freetype2-demos-master\src\ftstring.c" contains the following:
(The following is a simplified extract showing a relevant example of the problem.)
For C/C++, sizeof(char)==1 for ALL platforms, including 64-bit Linux.
I think it's rather unclear what *should* happen to 2-byte "\u####" Unicode code points for a "char" string literal. Encode as UTF-8, UTF-16LE, or UTF-16BE ? It seems like some kind of hint would be required for the compiler to decide how to put bytes in to the "char" string.
Testing indicates that this demo apparently relies on each "char" string in the array to be encoded as UTF-8.
(4) SOLUTION:
Convert the original Unicode text (in the comment appearing above each string literal) to UTF-8 where each byte is expressed in an escape sequence of the form "\x##".
For example, each Unicode text string could be converted to UTF-8 (with "\x##" byte format) using the following online converter: =============================================== https://www.branah.com/unicode-converter ===============================================
Resulting modified portion of the file "freetype_build_test\freetype2-demos-master\src\ftstring.c": ===============================================
static const char* Sample[] = { "The quick brown fox jumps over the lazy dog",
This is rather messy, but it fixes the problem for VC++ 2010.
I suppose GCC, and maybe later versions of VC++, would encounter "\u####", and note that the destination is a "char" (byte) string, and assume that UTF-8 should be used. (Whereas, if the destination were a "wchar_t" string, then the Unicode value might be stored as UTF-16LE or UTF-16BE, depending on architecture.)
TESTING
FTSTRING.EXE :
(1) Start regular Windows command prompt window:
=============================================== Start menu [icon] --> "All Programs" [link] --> "Accessories" [folder] --> "Command Prompt" [icon] ===============================================
(2) Within the Windows command prompt window, change directory to the "freetype2-demos-master" folder:
=============================================== cd [path of "freetype_build_test" folder]
cd freetype2-demos-master ===============================================
(3) Within the Windows command prompt window, start the FTSTRING.EXE demo program:
(4) Click the demo program window to ensure it has input focus, and then press the TAB key repeatedly to cycle through the example Unicode strings.
Result: All strings (English, Portuguese, Greek, Russian, Chinese, Japanese, Korean) look identical to the commented text in the "ftstring.c" source file.
FTGRID.EXE :
(1) Start regular Windows command prompt window:
=============================================== Start menu [icon] --> "All Programs" [link] --> "Accessories" [folder] --> "Command Prompt" [icon] ===============================================
(2) Within the Windows command prompt window, change directory to the "freetype2-demos-master" folder:
=============================================== cd [path of "freetype_build_test" folder]
cd freetype2-demos-master ===============================================
(3) Within the Windows command prompt window, start the FTGRID.EXE demo program:
(4) Click the demo program window to ensure it has input focus, and then press the RIGHT ARROW key repeatedly to advance through the glyphs defined by the font. LEFT ARROW key to go to a previous glyph. PAGE UP to magnify the grid. PAGE DOWN to reduce the grid. "I":Move grid upward; "K":Move grid downward. "J":Move grid leftward; "L":Move grid rightward.
Result: Demo program appears to be working correctly!
FTVIEW.EXE :
(1) Start regular Windows command prompt window:
=============================================== Start menu [icon] --> "All Programs" [link] --> "Accessories" [folder] --> "Command Prompt" [icon] ===============================================
(2) Within the Windows command prompt window, change directory to the "freetype2-demos-master" folder:
=============================================== cd [path of "freetype_build_test" folder]
cd freetype2-demos-master ===============================================
(3) Within the Windows command prompt window, start the FTVIEW.EXE demo program:
(4) Click the demo program window to ensure it has input focus, and then press: PAGE UP to magnify the grid. PAGE DOWN to reduce the grid. "L" : Cycle through rendering options (monochrome, normal AA, light AA, LCD...)
Result: Demo program appears to be working correctly!