exiv2/README-CMAKE

-------------------------------------------------------------------------------
NOTE: 

* CMake scripts are "work in progress".
  Use them only if you're prepared to fix them.
  See TODO-CMAKE for pending tasks. 

* The existing make, msvc and msvc64 build files will continue
  to be supported by exiv2 until at least v0.25.
  We will flag them as "deprecated" for at least one release cycle (about 6 months).
  Our plan is to only support CMake when our scripts are feature-complete, stable and documented.
  
  All help is appreciated - especially if you are willing to run
  builds and tests on any platform.  Thanks for your help.
  
Robin Mills
robin@clanmills.com
2012-06-01

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

Exiv2 uses cmake, a cross-platform build system, to control the
compilation process using platform/compiler independent
configuration files.

TABLE OF CONTENTS
-----------------

1 CMake resources
2 Building and Installing for Unix type systems
3 Building and Installing for DevStudio Users
4 Building and Installing for other users (Xcode, Eclipse, Qt)

1 CMake resources
=================

You have to install cmake on your target system.

Home: http://www.cmake.org/
Help: http://www.cmake.org/cmake/help/help.html
Doc:  http://www.cmake.org/cmake/help/documentation.html
Wiki: http://www.cmake.org/Wiki/CMake
FAQ:  http://www.cmake.org/Wiki/CMake_FAQ

2 Building and Installing on Linux
==================================

This process also covers MacOS-X Terminal, Cygwin and MinGW users.

a) From the command line 

Run the following commands from the top directory (containing this
file) to configure, build and install the library and utility:

    $ mkdir build
    $ cd build
    $ cmake ..
    $ make
    $ make install

To modify the configuration

    $ ccmake ..

Usual CMake options :

-DCMAKE_INSTALL_PREFIX : decide where the program will be install on your computer.
-DCMAKE_BUILD_TYPE     : decide which type of build you want. You can chose between:
                         "debugfull".     : for hacking. Include all debug information.
                         "debug".
                         "profile".
                         "relwithdebinfo" : default. use gcc -O2 -g options.
                         "release"        : generate stripped and optimized bin files. For packaging.

Specific Exiv2 options :

-DEXIV2_ENABLE_SHARED        : Build exiv2 as a shared library (dll).            [default=on ]
-DEXIV2_ENABLE_XMP           : Build with XMP metadata support.                  [default=on ]
-DEXIV2_ENABLE_LIBXMP        : Build a static convenience Library for XMP.       [default=on ]
-DEXIV2_ENABLE_PNG           : Build with png support (requires libz).           [default=on ]
-DEXIV2_ENABLE_NLS           : Build native language support (requires gettext). [default=on ]
-DEXIV2_ENABLE_PRINTUCS2     : Build with Printucs2.                             [default=on ]
-DEXIV2_ENABLE_LENSDATA      : Build including lens data.                        [default=on ]
-DEXIV2_ENABLE_COMMERCIAL    : Build with the EXV_COMMERCIAL_VERSION symbol set. [default=off]
-DEXIV2_ENABLE_BUILD_SAMPLES : Build the unit tests.                             [default=off]
-DEXIV2_ENABLE_BUILD_PO      : Build translations files.                         [default=off]

Default install locations

Use -DCMAKE_INSTALL_PREFIX like this :

"cmake . -DCMAKE_INSTALL_PREFIX=/usr"  is equivalent to "./configure --prefix=/usr" with automake/configure.

To uninstall Exiv2, run:

    $ make uninstall

b) Using the cmake GUI

   ccmake

3 Building and installing for DevStudio Users
=============================================

exiv2 provides three build environment for users of DevStudio:

msvc:	32 bit build environment for MSVC 2003 (and 2005 and 2008)
msvc64: 32 bit AND 64 bit build environment for MSVC 2005 (and 2008 and 2010)
cmake:  This environment

CMake doesn't build code.  It generates build environments.
CMake is a language for describing builds and the language interpreter generates
the build environment for your system.

CMake generates MSVC .sln and .vcproj files for your target environment.
The files generated by CMake provide 4 configs: Debug|Release|RelWithDebInfo|MinSizeRel
The current architecture of CMake requires you to decide before running cmake about:
1)	The version of DevStudio
2)  32bit or 64 bit builds
3)  Building static or shared libraries

Code FileSystem Layout
----------------------

I set up my environment as follows:
 Directory of C:\gnu.cmake

2012-05-31  09:49    <DIR>          exiv2           Vanilla
2012-05-31  09:45    <DIR>          expat-2.1.0     source
2012-05-30  16:22    <DIR>          zlib-1.2.7      trees

Other versions of expat and zlib make be used (although I've never tested them)
2012-05-19  21:29    <DIR>          expat-2.0.1
2012-05-19  21:29    <DIR>          zlib-1.2.3
2012-05-19  21:29    <DIR>          zlib-1.2.5

The command to run cmake is of the form:
cmake CMakeLists.txt -G "Visual Studio 9 2008 Win64"

There are many options for the cmake command, and many generators.  I've added a little
batch file cm.bat for my convenience.
c:\> cm 2008 64 == cmake CMakeLists.txt -G "Visual Studio 9 2008 Win64" 

Building with cmake involves 3 steps (build zlib/expat, build exiv2, test):

1) Building the support libraries expat and zlib (with cmake)
   cd expat-2.1.0
   Edit CMakeLists.txt to specify shared or static library
   If you wish to use static libries, you'll need the following patch (around line 23)
   See "Note about expat-2.1.0/CMakeLists.txt"
   
   --- extract from CMakeLists.txt ---
   option(XML_NS "Define to make XML Namespaces functionality available"  ON)
   
   # rmills patch begin
   include(../exiv2/CMake_msvc.txt)
   msvc_runtime_configure(${BUILD_shared})
   # rmills patch end
   
   if(XML_DTD)
   --- extract end ---
   
   cmake CMakeLists.txt -G "Visual Studio 9 2008 Win64"
   .... rattle roll ....
   Open expat.sln and build all.
   
   Similar process for zlib-1.2.7
   You will not need to edit CMakeLists.txt (zlib builds shared and dynamic libraries)
   cmake CMakeLists.txt -G "Visual Studio 9 2008 Win64"
   .... rattle roll ....
   Open zlib.sln and build all.
   
2) Building exiv2
   cd exiv2
   Edit CMakeLists.txt to specify shared or static library (and other options)
   You may need to change the path specifications to expat and zlib to match your setup
   
   You will find path references in the three files:
   CMakeLists.txt ./src/CMakeLists.txt and ./samples/CMakeLists.txt  
   
   cmake CMakeLists.txt -G "Visual Studio 9 2008 Win64"
   .... rattle roll ....
   Open exiv2.sln and build all.
   
3) Location of built files (exiv2.exe, exiv2.dll etc)
   exiv2\bin\{ x64 | Win32 }\{ Dynamic|Static }\{Config}\exiv2.exe etc....
   Config: Debug | MinSizeRel | Release | RelWithDebInfo

Note about expat-2.1.0/CMakeLists.txt
-------------------------------------
   expat-2.1.0/CMakeLists.txt can build static or dynamic libraries.
   However expat's CMakeLists.txt links with MSVCRTx.dll for both static and dynamic.
   I've taken a decision to either link "All static" or "All dynamic" with no mixing.
   This patch enforces my design and avoids linker headaches.


4 Building and Installing for other users (Xcode, Eclipse, Qt)
==============================================================

To be written

# That's all Folks
##