[ft-devel] more on the preferred setup for `make tests'

[Werner LEMBERG]

Kushal,


attached is a revised version of your `README' file.[*] I think you
still haven't fully grasped how I would like the setup, so I've tried
to be quite explicit – in particular, you are still talking about
`installing', which I don't want...  I now ask you to implement
everything according to the README :-) If necessary, please adapt to
your needs.  And please don't hesitate to ask questions!

Looking into `make_sprite.c' I see that you use a single function not
derived from the dlopen API: `FT_Get_Glyph_Name'.  Please fix that!
Otherwise it is necessary to directly link your program with FreeType,
AFAIK, which is an additional complication.


    Werner


[*] BTW, please don't use tabs within the FreeType project except in
    Makefiles!  Similarly, please avoid trailing spaces, and the last
    line in a text file should always be ended with a newline
    character.

HOW TO SET UP `MAKE TESTS'
==========================


TODO: Generate HTML page for detailed comparison


---------------------------------------------------------------------


INSTRUCTIONS

One version of FreeType is referred as `base' version; normally, this is the
older one.  The other one is called the `test' version, usually the newer
one; we run `make tests' within the `test' version to compare rendering
results with the `base' version.  As a result, you get one or more HTML
pages and a lot of images that shows rendering differences between the
`base' and `test' versions.


1. Prepare the `base' version
-----------------------------

Download and unpack a version of FreeType you want to use as the base
version (for example, version 2.6.5).

Within the base version, go to `include/freetype/ftoption.h' and uncomment
this line

  #define FT_CONFIG_OPTION_SUBPIXEL_RENDERING

Now configure and compile FreeType so that a DLL gets created, for example with

  ./configure --enable-shared --disable-static
  make

Later on we need the make variable `FT_TEST_BASE_DLL' set to the created
DLL, for example

  FT_TEST_BASE_DLL=/home/foo/freetype-2.6.5/objs/.libs/libfreetype.so.6.12.5

It is expected that all dependencies of `libfreetype.so' (for example,
`HarfBuzz' or `zlib') can be found; if necessary, set the `LD_LIBRARY_PATH'
environment variable accordingly.  More details can be found in the
`dlopen(3)' manpage.


2. Prepare the `test' version
-----------------------------

Now change to the test version's directory.  Configure and compile FreeType
again so that a DLL gets created, for example with

  ./configure --enable-shared --disable-static
  make


3. Compile the testing code
---------------------------

Return to this folder (in the `test' version) and compile the testing binary
with

  make


4. Running the tests
--------------------

You are now ready to run the tests.  To do so it is necessary to set up some
make variables.

  FT_TEST_BASE_DLL      The base version's DLL, see above.

  FT_TEST_DPI           The rendering resolution; if not specified, 72dpi
                        gets used.

  FT_TEST_RENDER_MODES  A space-separated list of rendering modes to test.
                        Possible values are

                          MONO    monochrome rendering, default hinting
                          NORMAL  anti-aliased rendering, default hinting
                          LIGHT   anti-aliased rendering, light hinting
                          LCD     LCD rendering with light hinting
                          VLCD    vertical LCD rendering with default hinting

  FT_TEST_PT_SIZES      A space-separated list of point sizes to test (the
                        values can be fractional).  If not set, it defaults
                        to 16pt.

  FT_TEST_FONTS         A space-separated list of fonts to test.

  FT_TEST_OUT_DIR       A directory where the created HTML and images files
                        are put into (using subdirectories `html' and
                        `images', respectively).  If not set, it defaults to
                        `out'.

It's probably easiest to put everything into a shell script.  Here is an
example call.

  make tests \
    FT_TEST_BASE_DLL=/home/foo/freetype-2.6.5/objs/.libs/libfreetype.so.6.12.5 \
    FT_TEST_DPI=96 \
    FT_TEST_RENDER_MODES="NORMAL LIGHT" \
    FT_TEST_PT_SIZES="12 13 14.5 16 20" \
    FT_TEST_FONTS="/home/foo/NotoSans-Regular.ttf /home/foo/LinLibertine_R.otf"

After a successful run the file `out/html/index.html' is the top-level entry
file to show all differences.  By clicking on the headers of the respective
columns, they can be arranged (in increasing/decreasing order) based on
glyph index, name, or difference metrics


end of README