SharpMuPDF/mupdf/thirdparty/zint/backend/tests

% backend/tests/README 2024-11-18

Zint backend test suite
-----------------------

In order to build the zint test suite, zint has to be compiled with the
ZINT_TEST option enabled:

cd
mkdir build
cd build
cmake -DZINT_TEST=ON ..
cmake --build .

When using generators that support multiple build configurations, such as
Visual C++ Project Files (the default generator on win32), the configuration
can be provided via --config:

cd
mkdir build
cd build
cmake -DZINT_TEST=ON -DCMAKE_BUILD_TYPE=Debug ..
cmake --build . --config Debug

Note specifying a matching CMAKE_BUILD_TYPE is required to set the test PATH
environment for Windows.

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

In order to run the test suite, the path of the zint library may need to be
communicated to the runtime linker. On UNIX-like systems, this is done by
exporting LD_LIBRARY_PATH to the path containing the zint library, which is
/backend:

cd
cd build
export LD_LIBRARY_PATH=$(pwd)/backend

Setting LD_LIBRARY_PATH is not required if the zint library to be tested is
installed into a system library path ( /usr/lib for example ) prior to running
the tests, or if the tests are not run individually.

(On Windows, the PATH may need to be set to include the DLL location.)

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

To run all tests (within ):

ctest

When using a generator that does support multiple build configurations, the
configuration that was used to build the project has to be explicitly provided
to ctest, even if it was the default one:

ctest -C Debug

For various useful options, e.g. matching (-R) and excluding (-E) tests, see
https://cmake.org/cmake/help/latest/manual/ctest.1.html#options

Tests can also be run individually, eg:

backend/tests/test_common
backend/tests/test_vector

To run a single test function within an individual test, use '-f ':

backend/tests/test_common -f utf8_to_unicode
backend/tests/test_dotcode -f input

To exclude a single test function, use '-n ':

backend/tests/test_common -n utf8_to_unicode
backend/tests/test_dotcode -n input

To run all test functions that match (i.e. contain) a string, use '-m ':

backend/tests/test_common -m not_sane
backend/tests/test_dotcode -m encode

To run a single dataset item in a single test function, use '-i ':

backend/tests/test_dotcode -f input -i 2

To run a range of dataset items in a single test function, use '-i -':

backend/tests/test_dotcode -f input -i 2-5

The '' or '' can be left out:

backend/tests/test_dotcode -f input -i 2-

To exclude a single dataset item in a single test function, use '-x ':

backend/tests/test_dotcode -f input -x 4

This can also take a range, '-x -':

backend/tests/test_dotcode -f input -x 4-6

Exclude can be used multiple times (unlike '-i'):

backend/tests/test_dotcode -f input -x 4 -x 6-8

The include and exclude options can be used together:

backend/tests/test_dotcode -f input -i 2-7 -x 4 -x 6

To show debug info (if any), use '-d ':

backend/tests/test_dotcode -f input -i 2 -d 1

E.g. to print which dataset items are being run, use '-d 16':

backend/tests/test_dotcode -f input -d 16 -i 2

(for other flags see /backend/tests/testcommon.h)

To run a test against BWIPP (if any), use '-d 128':

backend/tests/test_composite -d 128

(see also /backend/tests/tools/run_bwipp_tests.sh)

To run a test against ZXing-C++ (if any), use '-d 512':

backend/tests/test_rss -d 512

(see also /backend/tests/tools/run_zxingcpp_tests.sh)

To generate test data (if available), use '-g':

backend/tests/test_dotcode -f encode -g

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

If the zint library was built with static linkage support, i.e. ZINT_STATIC
is ON, an additional test executable, which uses the zint-static library, will
be built. The static variant of each test shares the test name, but has a
"-static" suffix. For example,

backend/tests/test_dotcode

would run the dotcode test that uses the shared zint library, while

backend/tests/test_dotcode-static

runs the same test built against the zint-static library.

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

To make with gcc sanitize, first set for libzint and make:

cd
cd build
cmake -DZINT_SANITIZE=ON ..
make && sudo make install

Similarly to make with gcc debug:

cd
cd build
cmake -DZINT_DEBUG=ON ..
make && sudo make install

To undo sanitize/debug, remake each after setting:

cmake -DZINT_SANITIZE=OFF ..
cmake -DZINT_DEBUG=OFF ..

To get a clean libzint, set the above and also:

cmake -DZINT_TEST=OFF ..

(The tests will now fail to link.)