### 3.2 Support
For new bug reports and feature requests, please open an issue in Github.
[TOC](#TOC)
## 4 Running the test suite
#### Different kinds of tests:
| Description | Language | Location | Command
_(in build or test directory)_ | CMake Option to Build |
|:-- |:-- |:-- |:-- |:-- |
| Run all tests | | | $ make tests | |
| Bash scripts | bash | \<exiv2dir\>/test | $ make bash_tests | -DEXIV2\_BUILD\_SAMPLES=On |
| Python scripts | python | \<exiv2dir\>/tests | $ make python_tests | -DEXIV2\_BUILD\_SAMPLES=On |
| Unit tests | C++ | \<exiv2dir\>/unitTests | $ make unit_test | -DEXIV2\_BUILD\_UNIT\_TESTS=On |
| Version test | C++ | \<exiv2dir\>/src/version.cpp | $ make version_test | Always in library |
_**Caution: Visual Studio Users using cmd.exe**_
_You may use MinGW/msys2 `make` to to execute tests in the test directory. To execute tests from the build directory, use `cmake`. This is discussed in detail below: [Running tests on Visual Studio builds](#4-2)_
#### Environment Variables used by the test suite:
If you build the code in the directory \<exiv2dir\>build, tests will run using the default values of Environment Variables.
| Variable | Default | Platforms | Purpose |
|:-- |:-- |:-- |:-- |
| EXIV2_BINDIR | **\<exiv2dir\>/build/bin** | All Platforms | Path of built binaries (exiv2.exe) |
| EXIV2_PORT | **12762**
**12671**
**12760** | Cygwin
MinGW/msys2
Other Platforms | Test TCP/IP Port |
| EXIV2_HTTP | **http://localhost** | All Platforms | Test http server |
| EXIV2_EXT | **.exe** | msvc
Cygwin
MinGW/msys2 | Extension used by executable binaries |
| EXIV2_EXT | _**not set**_ | Linux
macOS
Unix| |
| EXIV2_ECHO | _**not set**_ | All Platforms | For debugging Bash scripts |
| VALGRIND | _**not set**_ | All Platforms | For debugging Bash scripts |
| VERBOSE | _**not set**_ | All Platforms | Causes make to report its actions |
| PATH
DYLD\_LIBRARY\_PATH
LD\_LIBRARY\_PATH | $EXIV2\_BINDIR/../lib | Windows
macOS
Other platforms | Path of dynamic libraries |
The Variable EXIV2\_PORT or EXIV2\_HTTP can be set to None to skip http tests. The http server is started with the command `python3 -m http.server $port`. On Windows, you will need to run this manually _**once**_ to authorise the firewall to permit python to use the port.
[TOC](#TOC)
### 4.1 Running tests on a UNIX-like system
You can run tests directly from the build:
?wzxhzdk:44?
You can run individual tests in the `test` directory. **Caution:** If you build in a directory other than \<exiv2dir\>/build, you must set EXIV2\_BINDIR to run tests from the `test` directory.
?wzxhzdk:45?
[TOC](#TOC)
### 4.2 Running tests on Visual Studio builds
To run the bash scripts you will need to install MinGW/msys2 which provides you with the bash interpreter. You can run the test suite from bash, or from cmd.exe.
##### Running tests from MinGW/msys2 bash
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`
?wzxhzdk:46?
**Caution:** _The python3 interpreter must be for DOS and called python3.exe. I copied the python.exe program:_
?wzxhzdk:47?
You can execute the test suite as described for UNIX-like systems:
?wzxhzdk:48?
**Caution:** If you build in a directory other than \<exiv2dir\>/build, you must set EXIV2\_BINDIR to run tests from the `test` directory.
##### Running tests from cmd.exe
You can build with Visual Studio using Conan. The is described in detail in [README-CONAN.md](README-CONAN.md)
As a summary, the procedure is:
?wzxhzdk:49?
**Caution:** To run the python tests, _You will need a DOS python3 interpreter which must be called python3.exe. I copied the python.exe program:_ You may have to modify the PATH to ensure that the DOS python3 is used. You may have to modify the PATH to access MinGW/msys2 tools such as bash and make. Be careful to ensure the DOS python3.exe is found before the MinGW/msys2 python3.
?wzxhzdk:50?
You can now run the tests from cmd.exe:
?wzxhzdk:51?
You may prefer to run tests in the directory using MinGW/msys2 make.
?wzxhzdk:52?
If you wish to use an environment variables, use env:
?wzxhzdk:53?
When you are in the test directory, MinGW/msys2 make supports the following _(more convenient)_ syntax:
?wzxhzdk:54?
[TOC](#TOC)
### 4.3 Unit tests
The code for the unit tests is in `<exiv2dir>/unitTests`. To include unit tests in the build, use the *cmake* option `-DEXIV2_BUILD_UNIT_TESTS=On`.
There is a discussion on the web about installing GTest: [https://github.com/Exiv2/exiv2/issues/575](https://github.com/Exiv2/exiv2/issues/575)
?wzxhzdk:55?
[TOC](#TOC)
### 4.4 Python tests
You can run the python tests from the build or test directory:
?wzxhzdk:56?
If you wish to run in verbose mode:
?wzxhzdk:57?
The python tests are stored in the directory `tests` and you can run them all with the command:
?wzxhzdk:58?
You can run them individually with the commands such as:
?wzxhzdk:59?
You may wish to get a brief summary of failures with commands such as:
?wzxhzdk:60?
[TOC](#TOC)
### 4.5 Test Summary
| *Tests* | Unix Style Platforms _(bash)_ | Visual Studio _(cmd.exe)_ |
|:-- |:--- |:-- |
| | $ cd \<exiv2dir\>/build **or**
$ cd \<exiv2dir\>/test | \> cd \<exiv2dir\>/build |
| tests | $ make tests | \> cmake --build . --config Release --target tests |
| bash_tests | $ make bash_tests | \> cmake --build . --config Release --target bash_tests |
| python_tests | $ make python_tests | \> cmake --build . --config Release --target python_tests |
| unit_test | $ make unit_test | \> cmake --build . --config Release --target unit_test |
| version_test | $ make version_test | \> cmake --build . --config Release --target version_test |
[TOC](#TOC)
## 5 Platform Notes
There are many ways to set up and configure your platform. The following notes are provided as a guide.
### 5.1 Linux
Update your system and install the build tools and dependencies (zlib, expat, gtest and others)
?wzxhzdk:61?
For users of other platforms, the script <exiv2dir>/ci/install_dependencies.sh has code used to configure many platforms. The code in that file is a useful guide to configuring your platform.
Get the code from GitHub and build
?wzxhzdk:62?
[TOC](#TOC)
### 5.2 macOS
You will need to install Xcode and the Xcode command-line tools to build on macOS.
You should build and install libexpat and zlib. You may use brew, macports, build from source, or use conan.
I recommend that you build and install CMake from source.
[TOC](#TOC)
### 5.3 MinGW/msys2
Please note that the platform MinGW/msys2 32 is obsolete and superceded by MinGW/msys2 64.
#### MinGW/msys2 64 bit
Install: [http://repo.msys2.org/distrib/x86_64/msys2-x86\_64-20190524.exe](http://repo.msys2.org/distrib/x86_64/msys2-x86_64-20190524.exe)
I use the following batch file to start the MinGW/msys2 64 bit bash shell from the Dos Command Prompt (cmd.exe)
?wzxhzdk:63?
#### Install MinGW Dependencies
Install tools and dependencies:
?wzxhzdk:64?
#### Download exiv2 from github and build
?wzxhzdk:65?
#### MinGW and Regex
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:
?wzxhzdk:66?
[TOC](#TOC)
### 5.4 Cygwin/64
Please note that the platform Cygwin/32 is obsolete and superceded by Cygwin/64.
Download: [https://cygwin.com/install.html](https://cygwin.com/install.html) and run setup-x86_64.exe. I install into c:\\cygwin64
You need:
make, cmake, curl, gcc, gettext-devel pkg-config, dos2unix, tar, zlib-devel, libexpat1-devel, git, python3-interpreter, libiconv, libxml2-utils, libncurses.
I use the following batch file "cygwin64.bat" to start the Cygwin/64 bash shell from the Dos Command Prompt (cmd.exe).
?wzxhzdk:67?
[TOC](#TOC)
### 5.5 Microsoft Visual C++
We recommend that you use Conan to build Exiv2 using Microsoft Visual C++. Exiv2 v0.27 can be built with Visual Studio versions 2008 and later. We actively support and build with Visual Studio 2015, 2017 and 2019.
As well as Microsoft Visual Studio, you will need to install CMake, Python3, and Conan.
1) Binary installers for CMake on Windows are availably from [https://cmake.org/download/](https://cmake.org/download/).
2) Binary installers for Python3 are available from [python.org](https://python.org)
3) Conan can be installed using python/pip. Details in [README-CONAN.md](README-CONAN.md)
I use the following batch file `cmd64.bat` to start cmd.exe. I do this to reduce the complexity of the path which grows as various tools are installed on Windows. As well as providing a "stripped down path", it also ensures the DOS python3 and DOS bash are on the path.
?wzxhzdk:68?
**Caution:** _The python3 interpreter must be for DOS and called python3.exe. I copied the python.exe program:_
?wzxhzdk:69?
[TOC](#TOC)
### 5.6 Unix
Exiv2 can be built on many Unix and Linux distros. With v0.27.2, we are starting to actively support the Unix Distributions NetBSD and FreeBSD. For v0.27.3, I have added support for Solaris 11.4
We do not have CI support for these platforms on GitHub. However, I regularly build and test them on my MacMini Buildserver. The device is private and not on the internet.
I have provided notes here based on my experience with these platforms. Feedback is welcome. I am willing to support Exiv2 on other commercial Unix distributions such as AIX, HP-UX and OSF/1 if you provide with an ssh account for your platform. I will require super-user privileges to install software.
For all platforms you will need the following components to build:
1. gcc or clang
2. cmake
3. bash
4. sudo
5. gettext
To run the test suite, you need:
1. python3
2. chksum
3. dos2unix
4. xmllint
#### NetBSD
You can build exiv2 from source using the methods described for linux. I built and installed exiv2 using "Pure CMake" and didn't require conan.
You will want to use the package manager `pkgsrc` to build/install the build and test components listed above.
I entered links into the file system
?wzxhzdk:70?
It's important to ensure that `LD_LIBRARY_PATH` includes `/usr/local/lib` and `/usr/pkg/lib`.
It's important to ensure that `PATH` includes `/usr/local/bin`, `/usr/pkg/bin` and `/usr/pkg/sbin`.
#### FreeBSD
Clang is pre-installed as ``/usr/bin/{cc|c++}` as well as libz and expat. FreeBSD uses pkg as the package manager which I used to install cmake and git.
?wzxhzdk:71?
**Caution**: _The package manager *pkg* is no longer working on FreeBSD 12.0. I will move to 12.1 for future work. Others have reported this issue on 12.1. Broken package manager is very bad news. There are other package managers (such as ports), however installing and getting it to work is formidable._
?wzxhzdk:72?
#### Solaris
Solaris uses the package manager pkg. To get a list of packages:
?wzxhzdk:73?
To install a package:
?wzxhzdk:74?
[TOC](#TOC)
Written by Robin Mills
robin@clanmills.com
Updated: 2020-05-25