exiv2/README-CMAKE

    @@@Luis@@@@@@b                   ;mm                       /##Michal####\
    j@@@#Robin",                     Brad                     /@@@Thomas@@@@Q
     @@@#       \                     ##                     @@@b     |@@@b
     @@@#          .;;;;,     ,;;;, ,;;;;  ,;;;p      .;;;   7@@      ]Alan
     @@@#           j@@@@,   ]@@#/  '@@@#  j@@@#      ]@@^           ;@@@"
     @@@Andreas@C     "@@@p @@@"     @@@b   j@@@p     @@b           @@@#/
     @@@#^7"7%#\       ^@@@@@#~      Benb    1@@@    {@#          s@@@#
     @@@#                Niels       @@@b     @@@Q  ]@#         ;@@@#/
     @@@#              ,@@##@@m      @@@b      @@@p @@C        #@@#C
     @@@#       ,/    s@@#  @@@@     @@@b       Volker       @Tuan@
    ]@@@Abhinav@@\   /@@@\    \@@@Q  @@@Q       %@@@#      /@@@@Mahesh@@#
   /@@Raphael@@@@@\ /@@@@@\     C++  Metadata  Library    /@Sridhar@@@v0.26.1\

-------------------------------------------------------------------------------
CMake is a cross-platform build system, to control the
compilation process using platform/compiler independent configuration files.

STATUS:

* CMake scripts are functional and used to perform the daily build on the buildserver
  for MacOS-X, Cygwin, Linux and Visual Studio (2005, 8, 10, 12, 13, 15 and 17)

* The existing automake (./configure) is currently still be supported by exiv2.
  The long term plan is to adopt CMake as the only build platform.
  automake and msvc solutions/project are likely to removed with Exiv2 v0.27

* Team Exiv2 no longer provide support for MinGW (with/without CMake)
  Exiv2 is very difficult to build on MinGW with CMake.
  This is discussed in TODO-CMAKE

Luis Díaz Más
piponazo@gmail.com
2017-09-10

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

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

1 CMake resources
2 Building and Installing on UNIX-like systems
3 Building and installing for Visual Studio Users
4 Building and installing for MinGW Users
5 Using conan to build exiv2 and project dependencies

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

You have to install cmake on your target system. The minimum version required is 3.1.0

Home: http://www.cmake.org/

There are some global CMake options that you can use in Exiv2 :

-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.
-DBUILD_SHARED_LIBS=1 : Build DLL (=0 for static library)

More information about Exiv2 CMake options in <exiv2dir>/CMakeLists.txt

2 Building and Installing on UNIX-like systems
==============================================

This process covers MacOS-X, Linux and Cygwin.

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

    $ mkdir build && cd build
    $ cmake .. or cmake-gui ..
    $ make -j
    $ (sudo) make install

Note that the CMake generator used by default on Unix is : 'Makefiles'. However you can chose others like 'Ninja'

To uninstall Exiv2, run:

    $ (sudo) make uninstall

3 Building and installing for Visual Studio Users
=================================================

exiv2 provides three build environment for users of Visual Studio:

cmake:    This environment
msvc:     32 bit AND 64 bit build environment for MSVC 2005 and later (2005/2008/10/12/13/15/17)

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

We have two contributed CMake Build Environments:

1 contrib/cmake/msvc
  The following command will build Exiv2 and dependencies:

  c:\exiv2dir\contrib\cmake\msvc> cmd /c "vcvars 2017 64 && cmakeBuild --build --samples"

  Please read contrib/cmake/msvc/ReadMe.txt for more information.

2 contrib/build/msvc

  The scripts require:
  - Cygwin (in order to download all dependencies (zlib, expat, ssl, curl, ssh), including exiv2 trunk from svn)
  - CMake
  - SVN (optional)

  Then
   - put the two scripts (build.cmd and setenv.cmd) into a completely empty directory
   - adapt the paths in setenv.cmd
   - open the VS command line shell
   - execute build.cmd (if there are any errors, the script should tell you)

  Exiv2 should be packaged in the dist directory with all the .lib, include and binary files you need.

3 Running CMake commands manually from command line (new)

  From Exiv2 0.26.0 to 0.26.1 the CMake code of the project was rewritten and now it is possible to configure
  project from the command line as we do in the Unix sytems. As in the UNIX case, we can run the following
  commands from the top directory to configure, build and install the library and utilities:

    $ mkdir build && cd build
    $ cmake .. or cmake-gui ..
    $ make -j
    $ make install

  However there are some particularities on Windows that might cause the CMake command does not find
  the compiler correctly.

  Previous versions of Visual Studio were creating an environment variable (VSCOMNTOOLS140, for example) that
  points at the compiler and other resources relevant to that version of the compiler. However in Visual Studio
  2017, they do not do that anymore.

  We recommend you to call the vcvarsall.bat Visual Studio configuration script before running CMake.
  For example, with Visual Studio 2017 installed on your system, you will need to run

  c:\exiv2dir> call "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat"

  Afterwards, CMake will identify correctly your Build Tools.

  It is also important to note that the default CMake configuration assumes the existence of some libraries
  in your system. If they are not available, the configuration will fail. It is possible to disable some
  features, or provide the paths to the INCLUDE folders, or libraries, at the moment of calling CMake the
  first time.

  In this example, we disable the NLS and PNG support, and we specify the path where we have the EXPAT library:

  c:\exiv2dir> cmake -DEXIV2_ENABLE_NLS=OFF -DEXIV2_ENABLE_PNG=OFF -DCMAKE_PREFIX_PATH="C:\pathToExpat\ ../

  CMake Generators
  ----------------

  It is also important to note that the default CMake generator is 'Visual Studio' (The version will depend
  on the vcvarsall.bat script called before running CMake).

  If you are not a big fan of Visual Studio you can use other generators like: 'Ninja'. In order to use them
  you just need to pass the option -GNinja at the moment of calling CMake for the first time:

  $ cmake -GNinja -DEXIV2_ENABLE_NLS=OFF -DEXIV2_ENABLE_PNG=OFF -DCMAKE_PREFIX_PATH="C:\pathToExpat\ ../

  Note: For using the Ninja generator you will need to have the ninja build system executable in your
  $PATH. More info at https://ninja-build.org/.

4 Building and installing for MinGW Users
=========================================

  CMake/MinGW has a number of serious issues.  This will be reported to Kitware.

  It is possible to use CMake/MinGW if you put in some effort.  This is documented in TODO-CMAKE.

5 Using conan to build exiv2 and project dependencies
=====================================================

Conan is a portable package manager for c++ (https://www.conan.io/). We added the option to use it
in Exiv2 so you can get all the Exiv2 dependencies (Expat, Zlib, Libcurl, Libssh) in a very easy
way. Basically, all you need to do is to have conan installed on your system and run the command
`conan install` before calling CMake:

    $ mkdir build && cd build
    $ conan install ..
    $ cmake .. or cmake-gui ..

Conan will search for the dependencies in different repositories. At the moment of writing this
text, the conan-expat is not available in the official conan repositories, so you have to add the
following remote to your conan configuration:

    $ conan remote add conan-pix4d https://api.bintray.com/conan/pix4d/conan

In case there are not available packages for your setup (OS + Compiler) you will see error messages
like this one:

```
    PROJECT: WARN: Can't find a 'zlib/1.2.8@lasote/stable' package for the specified options and settings:
    - Settings: arch=x86_64, build_type=Release, compiler=clang, compiler.version=3.9, os=Macos
    - Options: shared=False

    ERROR: Missing prebuilt package for 'zlib/1.2.8@lasote/stable'
    Try to build it from sources with "--build zlib"
    Or read "http://docs.conan.io/en/latest/faq/troubleshooting.html#error-missing-prebuilt-package"
```

To compile the dependencies from sources you will need to run the conan install command like this:

    $ conan install ../ --profile clang --build missing

To learn more about Conan, please visit their documentation page:
    http://docs.conan.io/en/latest/

# That's all Folks
##