exiv2/README-CMAKE

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

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

* The existing automake (./configure), msvc2003 and msvc2005 build files will continue
  to be supported by exiv2 until at least v0.26.
  We will flag them as "deprecated" for at least one release cycle (about 12 months).
  Our plan is to only support CMake when our scripts are feature-complete, stable and documented.
  
  All help is appreciated.  If you know and understand CMake (especially with Visual Studio)
  please consider contributing your time and skill to help Exiv2 and CMake work well together.
  
Robin Mills
robin@clanmills.com
2015-02-23

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

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 Visual Studio 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]
-DEXIV2_ENABLE_CURL          : USE Libcurl for HttpIo                            [default=off]
-DEXIV2_ENABLE_SSH           : USE Libssh for SshIo                              [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 Visual Studio:

msvc2003: 32 bit build environment for MSVC 2003
msvc2005: 32 bit AND 64 bit build environment for MSVC 2005 and later (2008/10/12/13)
cmake:  This environment

CMake doesn't build code.  It generates build environments.
CMake is a language for describing builds and the CMake 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:
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

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 from source
--------------------

There are 3 steps (build zlib/expat, build exiv2, test).
You can skip step 1 if you have prebuilt libraries (see note below)

1) Building the support libraries expat and zlib with cmake
   cd expat-2.1.0
   If you wish to use a static library (shared is default)
   a) set expat-2.1.0/CMakeLists.txt static 
      option(BUILD_shared "build a shared expat library" ON)  <------- Set OFF
   b) 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
   CMake recommend building "out of source" which means building in a clean
   directory BELOW the source tree:
   eg   cd exiv2
   		Edit CMakeLists.txt to specify shared or static library (and other options)
   		You may need to change the path to expat and zlib to match your setup
   		
        mkdir build
        cd    build
        cmake -G "Visual Studio 9 2008 Win64"  ..
        ... rattle roll ...
   	    Open build/exiv2.sln and build all.
   
3) Location of built files (exiv2.exe, exiv2.dll etc)
   exiv2\build\bin\{ x64 | Win32 }\{ Dynamic|Static }\{Config}\exiv2.exe etc....
   Config: Debug | MinSizeRel | Release | RelWithDebInfo
   
   The test suite is a bash script and requires Cygwin.
   
   cd /c/gnu/exiv2/test
   ./testMSVC.sh ${PWD}/../build/bin/x64/Dynamic/Release
   
   or
   ./testMSVC.sh ${PWD}/../build/bin/x64/Dynamic/ | tee foo.txt
   ./verifyMSVC foo.txt
   
   
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.

Note about using prebuilt zlib, expat and iconv
-----------------------------------------------

I expect you to setup the source build tree and build expat and zlib.
However you may wish to use prebuilt versions of zlib, iconv and expat.
Specify the location of the prebuilt libraries on the cmake command line:

For example:
cmake -G "NMake Makefiles" .. -DEXPAT_LIBRARY=%KDE4_INSTALL_DIR%/lib/libexpat.lib

Daniel has provided a patch (SVN:2893) which enables you to specify a ZLIB search path:
Example:
   cmake.exe -G "Visual Studio 11 Win64" -DZLIB_ROOT=..\zlib-1.2.7-dev;..\zlib-1.2.7-dev\Release ...
   
If ZLIB is not located on the path provided, the normal default (..\zlib-1.2.7) will be used.

ToDo: More information about parameters -DEXPAT_LIBRARTY -DZLIB_LIBRARY etc.

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

To be written

# That's all Folks
##