1. Edd Dawson
  2. pngxx

Wiki

Clone wiki

pngxx / compilation

Compilation instructions

Prerequisites

Once you have downloaded the required libraries, or cloned them from their mercurial repositories, you should have a directory layout something like this:

my_code/
    pngxx/
    jpegxx/
    imagexx/
    test_o_matic/ (optional, for unit tests)
    doozer_externals/ (mandatory if building with doozer)
    libjpeg/
    libpng/
    zlib/

Compilation with doozer

I developed jpegxx and pngxx using a custom build system, doozer, which is freely available. If you don't want to use doozer, see how to compile the libraries by a different means further down the page.

First, create a doozer config file for the build. The following variables should exist in your config (change as appropriate):

# Assuming that this config file sits alongside the 'my_code' directory.

test_o_matic.root = here/'my_code/test_o_matic'
imagexx.root = here/'my_code/imagexx'
libjpeg.root = here/'my_code/libjpeg'
libpng.root = here/'my_code/libpng'
zlib.root = here/'my_code/zlib'

include(here/'my_code/doozer_externals/defaults.cfg')

# The following variables are optional. The values set below are the defaults.
libjpeg.build_as_cplusplus = False
libpng.build_as_cplusplus = False

The following command will build the pngxx static library, build the included example programs, and build and run the pngxx tests. The dependencies will also be built as a side-effect.

python doozer.py my_code/pngxx/make.py variant=<your-config>.cfg

Replacing 'pngxx' with 'jpegxx' will do the equivalent thing for jpegxx.

Compilation by another means

For either library, we will first need to compile imagexx. To do this:

  1. make sure that you have added my_code/imagexx/include to your compiler's header search paths.
  2. compile all source files in my_code/imagexx/src and any of its subdirectories.
  3. bundle the object files up in to a library.

Let us now assume that you want to compile pngxx. The process for jpegxx is entirely analogous.

  1. make sure that you have added my_code/imagexx/include and my_code/pngxx/include to your compiler's header search paths.
  2. you will also have to make sure that you have set-up/created any configuration headers required by libpng/libjpeg, and that your compiler will find them during the build.
  3. compile all source files in my_code/pngxx/src.
  4. bundle the object files up in to a library.

When building the source files for pngxx/jpegxx, it is important that you #define the appropriate preprocessor variables.

If you have compiled the third party libraries as C++ code (as opposed to C code), you must define for pngxx:

  • PNGXX_CAN_THROW_EXCEPTIONS_THROUGH_C_LIB

and for jpegxx:

  • JPEGXX_CAN_THROW_EXCEPTIONS_THROUGH_C_LIB
  • JPEGXX_C_LIB_COMPILED_AS_CPLUSPLUS

Otherwise, it is assumed that you have compiled the third party C libraries as C code and the following notes apply:

If you know that it is safe to throw C++ exceptions through C code on your machine, then it is best to define PNGXX_CAN_THROW_EXCEPTIONS_THROUGH_C_LIB and JPEGXX_CAN_THROW_EXCEPTIONS_THROUGH_C_LIB. However, there is no guarantee that throwing C++ exceptions through C is supported by your implementation. If in doubt, don't define these variables.

Otherwise, if you happen to have a bleeding edge compiler and standard library that supports std::exception_ptr, you may define PNGXX_HAVE_EXCEPTION_PTR/JPEGXX_HAVE_EXCEPTION_PTR.

If in doubt about any of this, leave these variables undefined. All this means is that pngxx and jpegxx won't be able to propagate custom exception types thrown by your iterators and streams. Instead something more generic will be thrown.

Compiling the unit tests

To compile the unit tests for pngxx (again, the process for jpegxx is the same):

  1. make sure that you have added my_code/test_o_matic, my_code/imagexx/include and my_code/pngxx/include to your compiler's header search paths.
  2. compile all the source files in my_code/pngxx/tests/unit_tests in to object files
  3. compile my_code/test_o_matic/test_o_matic.cpp in to an object file
  4. link all the object files and the pngxx and imagexx library files in to an executable.
  5. run this executable to try out the tests.

Compiling the examples

TODO: give me a nudge if you want to know about this! The process is much the same for these as it is for the unit tests, except that the test-o-matic header search path isn't needed.

Using jpegxx and pngxx in your software

Once you have compiled jpegxx and/or pngxx (and imagexx), you can use these libraries in your own project by adding the following directories to your compiler's header search paths:

  • my_code/imagexx/include
  • my_code/jpegxx/include
  • my_code/pngxx/include

You will also need to link against the pngxx and/or jpegxx libraries that you have compiled, and also against the imagexx library.

Updated