Welcome to Exiv2
Exiv2 is a C++ library and a command-line utility to read, write, delete and modify Exif, IPTC, XMP and ICC image metadata.
|Releases and Documentation
|User Manual. This document
Conan User Manual click here
Sample Code Manual. click here
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.
TABLE OF CONTENTS
- Welcome to Exiv2
- Building, Installing, Using and Uninstalling Exiv2
- Build, Install, Use and Uninstall Exiv2 on a UNIX-like system
- Build and Install Exiv2 with Visual Studio
- Configure the project with CMake presets
- Build Options
- Building and linking your code with Exiv2
- Consuming Exiv2 with CMake
- Using pkg-config to compile and link your code with Exiv2
- Building Exiv2 Documentation
- Building Exiv2 Tag Webpages
- Building Exiv2 Packages
- Debugging Exiv2
- Building Exiv2 with Clang and other build chains
- Building Exiv2 with ccache
- Thread Safety
- Library Initialisation and Cleanup
- Cross Platform Build and Test on Linux for MinGW
- Static and Shared Libraries
- Support for bmff files (CR3, HEIF, HEIC, and AVIF)
- License and Support
- Test Suite
- Platform Notes
Building, Installing, Using and Uninstalling Exiv2
You need CMake to configure the Exiv2 project, any C++ compiler implementing the C++ 17 standard and the associated tool chain.
Build, Install, Use Exiv2 on a UNIX-like system
$ cd ~/gnu/github/exiv2 # Location of the project code $ mkdir build && cd build # Create a build directory $ cmake -DCMAKE_BUILD_TYPE=Release .. # Configure the project with CMake $ cmake --build . # Compile the project $ ctest --verbose # Run tests $ cmake --install . # Run the install target (install library, public headers, application and CMake files)
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. The target directory for the installation can be modified by using the CMake option
CMake analyzes the project configuration from the source code directory and generates files into the build directory. It generates the project/solution/makefiles required to build the exiv2 library and command line application (and optionally sample applications and test runners). CMake also creates the files
exiv2lib_export.h which contain compiler directives about the build options you have chosen and the availability of libraries on your machine.
Using the exiv2 command-line program
To execute the exiv2 command line program, you should update your path to search /usr/local/bin/
$ export PATH="/usr/local/bin:$PATH"
You will also need to locate libexiv2 at run time:
$ export LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH" # Linux, Cygwin, MinGW/msys2 $ export DYLD_LIBRARY_PATH="/usr/local/lib:$DYLD_LIBRARY_PATH" # macOS
I don't know why anybody would uninstall Exiv2.
$ cd ~/gnu/github/exiv2 # location of the project code $ cd build $ cmake --build . --target uninstall
These commands will run the
uninstall target and remove all the files which were installed by the
Note that this mechanism is not perfect and it is not able to remove the sub-directories created in the installation
Build and Install Exiv2 with Visual Studio
We recommend to use conan to download the Exiv2 external dependencies on Windows. On other platforms (macOS, Linux and others), traditionally the platform package managers have been used. However, conan can be used in any platform/architecture to bring the project dependencies. These are discussed at Platform Notes. The options to configure and compile the project using Visual Studio are similar to UNIX like systems. See README-CONAN for more information about Conan.
When you build, you may install with the following command.
> cmake --install .
This will create and copy the exiv2 build artefacts to
%ProgramFiles%/exiv2. To be able to run the
exiv2 command line application from any terminal you should modify your path to include
Configure the project with the CMake presets
CMake presets (see documentation here) were added recently to the project to ease the CMake configuration process for typical configurations. The presets are defined in the file
CMakePresets.json and they can be used from the terminal or interpreted by different IDEs. Please note that one needs to use a recent version of CMake (>= 3.21) supporting the presets feature.
One can list the available presets using the
# Running the command from a Windows terminal $ cmake --list-presets Available configure presets: "msvc" - Visual Studio cl toolchain (also usable from VS Code) "win-debug" - Windows Debug with configured architecture "win-release" - Windows Release with configured architecture # Running the command from a Linux terminal $ cmake --list-presets Available configure presets: "linux-debug" - Linux Debug with default architecture "linux-release" - Linux Release with default architecture
The project configuration with a specific preset can be choosen with the CMake
--preset option. In the following terminal output we comment out some interesting things happening during the project configuration:
# Configuring the project using a preset $ cmake --preset win-release Preset CMake variables: # Note that with the usage of a preset, we pass many different options to CMake. BUILD_SHARED_LIBS:BOOL="TRUE" CMAKE_BUILD_TYPE="Release" CMAKE_INSTALL_PREFIX:PATH="C:/dev/personal/exiv2/build-win-release/install" # A build & install directory are configured with the preset CONAN_AUTO_INSTALL:BOOL="TRUE" EXIV2_BUILD_SAMPLES:BOOL="TRUE" EXIV2_BUILD_UNIT_TESTS:BOOL="TRUE" EXIV2_ENABLE_BMFF:BOOL="TRUE" EXIV2_ENABLE_CURL:BOOL="TRUE" EXIV2_ENABLE_NLS:BOOL="FALSE" EXIV2_ENABLE_PNG:BOOL="TRUE" EXIV2_ENABLE_WEBREADY:BOOL="TRUE" EXIV2_TEAM_WARNINGS_AS_ERRORS:BOOL="TRUE" # Conan can be automatically detected in your system and it is run automatically to bring the # project dependencies -- Conan: Detected VS runtime: MD -- Conan: checking conan executable -- Conan: Found program C:/dev/envs/conan/Scripts/conan.exe -- Conan: Version found Conan version 1.47.0 -- Conan executing: C:/dev/envs/conan/Scripts/conan.exe install .. --remote conancenter --build missing --options webready=True --settings arch=x86_64 --settings build_type=Release --settings compiler=Visual Studio --settings compiler.version=17 --settings compiler.runtime=MD ... # CMake finds the project dependencies which were automatically handled by conan -- Conan: Using autogenerated FindZLIB.cmake -- Library zlib found C:/Users/luis/.conan/data/zlib/1.2.11/_/_/package/-- Conan: Using autogenerated FindCURL.cmake -- Library libcurl_imp found C:/Users/luis/.conan/data/libcurl/7.79.0/_/_/package/ ... # CMake finish the project configuration and prints a report -- Install prefix: C:/dev/personal/exiv2/build-win-release/install -- ------------------------------------------------------------------ -- CMake Generator: Ninja -- CMAKE_BUILD_TYPE: Release -- Compiler info: MSVC (C:/Program Files/Microsoft Visual Studio/2022/Professional/VC/Tools/MSVC/14.30.30705/bin/Hostx64/x64/cl.exe) ; version: 19.30.30705.0 -- CMAKE_CXX_STANDARD:17 -- --- Compiler flags --- -- General: /DWIN32 /D_WINDOWS /W3 /GR /EHsc /MP /utf-8 /WX -- Extra: -- Debug: /MDd /Zi /Ob0 /Ox /Zo -- Release: /MD /O2 /DNDEBUG -- RelWithDebInfo: /MD /Zi /O2 /DNDEBUG -- MinSizeRel: /MD /O1 /DNDEBUG -- --- Linker flags --- -- General: /machine:x64 /WX -- Debug: /debug /INCREMENTAL -- Release: /INCREMENTAL:NO -- RelWithDebInfo: /debug /INCREMENTAL -- MinSizeRel: /INCREMENTAL:NO -- ... -- Build files have been written to: C:/dev/personal/exiv2/build-win-release
Note that the usage of CMake presets allow the project contributors to use the same set of options easily in different environments (using terminal, IDEs or CI).
There are two groups of CMake options which are relevant to the project: global CMake options and project specific ones. Here are some of the global options which are particularly useful:
|Where to install on your computer (/usr/local)
Type of build (Release) See: Debugging Exiv2
Build exiv2lib as SHARED or STATIC
Options defined at
576 rmills@rmillsmm:~/gnu/github/exiv2/exiv2 $ grep ^option CMakeLists.txt option( BUILD_SHARED_LIBS "Build exiv2lib as a shared library" ON ) option( EXIV2_ENABLE_XMP "Build with XMP metadata support" ON ) option( EXIV2_ENABLE_EXTERNAL_XMP "Use external version of XMP" OFF ) option( EXIV2_ENABLE_PNG "Build with png support (requires libz)" ON ) ... option( EXIV2_ENABLE_BMFF "Build with BMFF support" ON ) 577 rmills@rmillsmm:~/gnu/github/exiv2/exiv2 $
Using the command-line, these variables can be set/updated using the option
$ cmake -DBUILD_SHARED_LIBS=ON -DEXIV2_ENABLE_NLS=OFF
The following Exiv2 features require external libraries:
|Feature||Package||Default||To change default||Availability|
|PNG image support||zlib||ON||-DEXIV2_ENABLE_PNG=OFF||http://zlib.net/|
Use Expat 2.2.6 and later
|Natural language system||gettext||OFF||-DEXIV2_ENABLE_NLS=ON||http://www.gnu.org/software/gettext/|
|Character set conversion||libiconv||Disabled for Visual Studio.
Linked when installed on UNIX like platforms.
On UNIX systems, 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 libraries required to build Exiv2. The script
ci/install_dependencies.sh is used to setup the CI images on which we build and test Exiv2. You may find that helpful in setting up your platform dependencies.
Natural language system is discussed in more detail here: Localisation
Notes about different platforms are included here: Platform Notes
You may choose to install dependences with conan. This is supported on all platforms and is especially useful for users of Visual Studio. See README-CONAN for more information.
The library libiconv is used to perform character set encoding in the tags Exif.Photo.UserComment, Exif.GPSInfo.GPSProcessingMethod and Exif.GPSInfo.GPSAreaInformation. This is documented in the exiv2 man page.
CMake will detect libiconv of all UNIX like systems including Linux, macOS, UNIX, Cygwin64 and MinGW/msys2. If you have installed libiconv on your machine, Exiv2 will link and use it.
The library libiconv is a GNU library and we do not recommend using libiconv with Exiv2 when building with Visual Studio.
Exiv2 includes the file cmake/FindIconv.cmake which contains a guard to prevent CMake from finding libiconv when you build with Visual Studio. This was added because of issues reported when Visual Studio attempted to link libiconv libraries installed by Cygwin, or MinGW or gnuwin32. #1250
There are build instructions about Visual Studio in libiconv-1.16/INSTALL.window require you to install Cygwin. There is an article here about building libiconv with Visual Studio. https://www.codeproject.com/Articles/302012/How-to-Build-libiconv-with-Microsoft-Visual-Studio.
If you wish to use libiconv with Visual Studio you will have to build libiconv and remove the "guard" in cmake/FindIconv.cmake. Team Exiv2 will not provide support concerning libiconv and Visual Studio.