The file ReadMe.txt in a Build bundle describes how to install the library on the platform. ReadMe.txt also documents how to compile and link code on the platform.
This will install the library into the "standard locations". The library will be installed in `/usr/local/lib`, executables (including the exiv2 command-line program) in `/usr/local/bin/` and header files in `/usr/local/include/exiv2`
| CMAKE\_INSTALL\_PREFIX<br/>CMAKE\_BUILD\_TYPE<br/>BUILD\_SHARED\_LIBS | Where to install on your computer _**(/usr/local)**_<br/>Type of build _**(Release)**_ See: [Debugging Exiv2](#2-11) <br/>Build exiv2lib as shared or static _**(On)**_ |
On Linux, you may install the dependencies using the distribution's package management system. Install the development package of a dependency to install the header files and static libraries required to build Exiv2.
The default cmake Generator is usually appropriate for your platform. Additional information concerning Generators for Visual Studio in [README-CONAN](README-CONAN.md)
When exiv2 is installed, the file exiv2.pc used by pkg-config is installed in `${CMAKE_INSTALL_PREFIX}/lib/pkgconfig` You will need to set the following in your environment:
To build localisation support, use the CMake option **`-DEXIV2_BUILD_PO=On`**. There are no additional build steps as the normal build commands will compile the library, samples and localisation support. You must install the build to ensure the localisation message files can be found at run-time.
2) About preprocessor symbols **NDEBUG** and **DEBUG**
In accordance with current practice, exiv2 respects the symbol *NDEBUG* which is set for Release builds. There are sequences of code which are defined within:
```C++
#ifdef DEBUG
....
#endif
```
Those blocks of code are not compiled for debug builds. They are provided for additional debugging information. For example, if you are interested in additonal output from webpimage.cpp, you can update your build as follows:
```bash
$ cd <exiv2dir>
$ touch src/webpimage.cpp
$ make CXXFLAGS=-DDEBUG
$ bin/exiv2 ...
-- or --
$ sudo make install
$ exiv2 ...
```
If you are debugging library code, it is recommended that you use the exiv2 command-line as your test harness as Team Exiv2 is very familiar with this tool and able to give support.
[TOC](#TOC)
3) Starting the debugger
This is platform specific. On Linux:
```bash
$ gdb exiv2
```
[TOC](#TOC)
4) Using Debugger IDEs such as Xcode, CLion, Visual Studio, Eclipse or QtCreator
I have used all those IDEs to debug the Exiv2 library and applications. All of them work. You may find it takes initial effort, however I assure you that they all work well.
I personally use CLion which has excellent integration with CMake. It will automatically add **`-DCMAKE_BUILD_TYPE=Debug`** to the cmake command. It keeps build types in separate directories such as **`<exiv2dir>/cmake-build-debug`**.
[TOC](#TOC)
5) cmake --build . options **`--config Release|Debug`** and **`--target install`**
Visual Studio and Xcode can build debug or release builds without using the option **`-DCMAKE_BUILD_TYPE`** because the generated project files can build multiple types. The option **`--config Debug`** can be specified on the command-line to specify the build type. Alternatively, if you prefer to build in the IDE, the UI provides options to select the configuration and target.
With the Unix Makefile generator, the targets can be listed:
```bash
$ make help
The following are some of the valid targets for this Makefile:
... all (the default if no target is provided)
... clean
... depend
... install/local
.........
```
[TOC](#TOC)
<nameid="2-12">
### 2.12 Building Exiv2 with **clang** and other build chains
Apple provide clang with Xcode. GCC has not been supported by Apple since 2013. The _"normal unix build"_ uses Clang.
3) On Cygwin, MinGW/msys2, Windows (using clang-cl) and Visual Studio.
I have been unable to get clang to work on any of those platforms.
4) Cross Compiling
I've never succeeded in getting this to work. I use different VMs for Linux 32 and 64 bit. I've documented how to set up Cygwin and MinGW/msys2 for 64 and 32 bit builds in [README-CONAN](README-CONAN.md)
[TOC](#TOC)
<nameid="2-13">
### 2.13 Building Exiv2 with ccache
To speed up compilation, the utility ccache can be installed to cache the output of the compiler. This greatly speeds up the build when you frequently built code that has not been modified.
Installing and using ccache (and other similar utilities), is platform dependent. On Ubuntu:
```bash
$ sudo apt install --yes ccache
```
To build with ccache, use the cmake option **-DBUILD\_WITH\_CCACHE=On**
Due to the way in which ccache is installed in Fedora (and other Linux distros), ccache effectively replaces the compiler. A default build or **-DBUILD\_WITH\_CCACHE=Off** is not effective and the environment variable CCACHE_DISABLE is required to disable ccache. [https://github.com/Exiv2/exiv2/issues/361](https://github.com/Exiv2/exiv2/issues/361)
You can run individual tests in the test directory using the environment variable EXIV2\_BINDIR to specify the location of the build artifacts. For Cygwin and MinGW/msys builds, also set EXIV2_EXT=.exe
Use the bash interpreter for MinGW/msys2 to run the test suite. It's essential to have a DOS Python3 interpreter on your path called `python3.exe` The variables EXIV2\_BINDIR and EXIV2\_EXT enable the test suite to locate the MSVC build artifacts.
$ for i in base-devel git cmake coreutils python3 man gcc gdb make dos2unix diffutils zlib-devel libexpat-devel libiconv-devel gettext-devel; do (echo y|pacman -S $i); done
You can upgrade all installed packages on your system with the following command. For me, this broke msys32 and I had to reinstall msys32 and all the dependencies. Your experience may be different.
The exiv2 command line program provides an option **`--grep`** to filter output. The implementation requires the header file **`<regex.h>`** and supporting library to be available during the build. When not available, the option **`--grep`** degrades to a substring match. Because there are several versions of **`<regex.h>`** available on the MinGW platform, detection of regex is always disabled on this platform and uses substring match. The following command reveals if regex is included in your build:
Download: [https://cygwin.com/install.html](https://cygwin.com/install.html) and run setup-x86_64.exe for 64 Bit Cygwin, or setup-x86.exe for 32 bit Cygwin. I install into c:\\cygwin64 and c:\\cygwin32
Download and build libiconv-1.15: [https://ftp.gnu.org/pub/gnu/libiconv/libiconv-1.15.tar.gz](https://ftp.gnu.org/pub/gnu/libiconv/libiconv-1.15.tar.gz)
I use the following batch file to start cmd.exe. I do this to reduce the complexity of the path which grows as various tools are installed on Windows. The purpose of this script is to ensure a "stripped down path".
set "PATH=C:\Python34\;C:\Python27\;C:\Python27\Scripts;C:\Perl64\site\bin;C:\Perl64\bin;C:\WINDOWS\system32;C:\Program Files\Git\cmd;C:\Program Files\Git\usr\bin;c:\Program Files\cmake\bin;"
