From 957988fda6626653d2ffb4086b993ac8c72dd080 Mon Sep 17 00:00:00 2001 From: Robin Mills Date: Fri, 17 Dec 2021 14:01:59 +0000 Subject: [PATCH 1/7] Initial changes to documentation to support CTest. I intend to integrate changes from main/README.md in this PR. --- CMakeLists.txt | 4 +-- README-CONAN.md | 7 ++-- README.md | 90 +++++++++++++++++++++++++++---------------------- 3 files changed, 54 insertions(+), 47 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 209760bade..7908ee55d7 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -119,9 +119,9 @@ if( EXIV2_BUILD_SAMPLES ) WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/tests COMMAND cmake -E env EXIV2_BINDIR=${CMAKE_RUNTIME_OUTPUT_DIRECTORY} ${Python3_EXECUTABLE} runner.py --verbose tiff_test ) - add_test(NAME lensTests + add_test(NAME versionTest WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/tests - COMMAND cmake -E env EXIV2_BINDIR=${CMAKE_RUNTIME_OUTPUT_DIRECTORY} ${Python3_EXECUTABLE} runner.py --verbose lens_tests + COMMAND cmake -E env EXIV2_BINDIR=${CMAKE_RUNTIME_OUTPUT_DIRECTORY} ${Python3_EXECUTABLE} runner.py --verbose bash_tests/version_test.py ) endif() endif() diff --git a/README-CONAN.md b/README-CONAN.md index 7c6a7fe582..37c3d91894 100644 --- a/README-CONAN.md +++ b/README-CONAN.md @@ -108,10 +108,9 @@ _Profiles for Visual Studio are discussed in detail here: [Visual Studio Notes]( | | Build Steps | Linux and macOS | Visual Studio | |:-- |:--------------|--------------------------------|------------------------------| | _**1**_ | Get conan to fetch dependencies

The output can be quite
long as conan downloads and/or builds
zlib, expat, curl and other dependencies.| $ conan install ..
     --build missing | c:\\..\\build> conan install .. --build missing
    --profile msvc2019Release64 | -| _**2**_ | Get cmake to generate
makefiles or sln/vcxproj | $ cmake .. | c:\\..\\build> cmake .. -G "Visual Studio 16 2019" -| _**3**_ | Build | $ cmake --build . | c:\\..\\build> cmake --build . --config Release
You may prefer to open exiv2.sln and build using the IDE. | -| _**4**_ | Optionally Run Test Suite | $ make tests | c:\\..\\build> cmake --build . --config Release --target tests
[README.md](README.md) | - +| _**2**_ | Get cmake to generate
makefiles or sln/vcxproj | $ cmake .. | c:\\..\\build> cmake .. -G "Visual Studio 16 2019" +| _**3**_ | Build | $ cmake --build . | c:\\..\\build> cmake --build . --config Release
You may prefer to open exiv2.sln and build using the IDE. | +| _**4**_ | Optionally Run Test Suite | $ cmake --build . --target test | c:\\..\\build> cmake --build . --config Release --target test
[README.md](README.md) | [TOC](#TOC) diff --git a/README.md b/README.md index 1f70449a95..1b439aabbd 100644 --- a/README.md +++ b/README.md @@ -43,11 +43,11 @@ The file ReadMe.txt in a build bundle describes how to install the library on th 3. [License and Support](#3) 1. [License](#3-1) 2. [Support](#3-2) -4. [Test Suit](#4) +4. [Test Suite](#4) 1. [Running tests on a UNIX-like system](#4-1) 2. [Running tests on Visual Studio builds](#4-2) 3. [Unit tests](#4-3) - 4. [Python tests](#4-4) + 4. [Bugfix tests](#4-4) 5. [Test Summary](#4-5) 5. [Platform Notes](#5) 1. [Linux](#5-1) @@ -71,7 +71,7 @@ $ cd ~/gnu/github/exiv2 # location of the project code $ mkdir build && cd build $ cmake .. -DCMAKE_BUILD_TYPE=Release $ cmake --build . -$ make tests +$ make test $ sudo make install ``` @@ -722,7 +722,7 @@ On MinGW/msys2, I can directly access the share: $ cd //Mac/Home/gnu/github/exiv2/0.27/maintenance/build_mingw_fedora $ export EXIV2_BINDIR=$pwd/bin $ cd ../test -$ make tests +$ make test ``` You will find that 3 tests fail at the end of the test suite. It is safe to ignore those minor exceptions. @@ -830,18 +830,27 @@ For new bug reports, feature requests and support: Please open an issue in Gith [TOC](#TOC)
-## 4 Running the test suite +## 4 Test Suite -#### Different kinds of tests: +The test suite is implemented using CTest. CMake adds the target 'test' to the build. You can run ctest with the command `$ cmake --build . --target test`, or simply with `$ ctest`. The build creates 5 tests: bashTests, bugfixes, tiffTests, unit_tests and versionTest. You can run all tests or a subset. -| Description | Language | Location | Command
_(in build directory)_ | CMake Option to Build | -|:-- |:-- |:-- |:-- |:-- | -| Run all tests | | | $ make tests | | -| Run all tests | | **Visual Studio Users** | > cmake --build . --target tests | | -| Bash tests | python | tests/bash\_tests | $ make bash_tests | -DEXIV2\_BUILD\_SAMPLES=On | -| Python tests | python | tests | $ make python_tests | -DEXIV2\_BUILD\_SAMPLES=On | -| Unit tests | C++ | unitTests | $ make unit_test | -DEXIV2\_BUILD\_UNIT\_TESTS=On | -| Version test | C++ | src/version.cpp | $ make version_test | Always in library | +```bash +$ cmake --build . --target test +$ ctest # run all tests and display summary +$ ctest --output-on-failure # run all tests and output failures +$ ctest -R bugfixes # run only bugfixes and display summary +$ ctest -R bugfixes --verbose # run only bugfixes and display all output +``` + +#### Test Architecture + +| Description | Language | Location | Command
_(in build directory)_ | CMake Option to Build | +|:-- |:-- |:-- |:-- |:-- | +| Bash tests | python | tests/bash\_tests | $ ctest -R bashTests | -DEXIV2\_BUILD\_SAMPLES=On | +| Bugfix tests | python | tests/bugfixes | $ ctest -R bugfixes | -DEXIV2\_BUILD\_SAMPLES=On | +| Tiff tests | python | tests/tiff_test | $ ctest -R unit_tests | -DEXIV2\_BUILD\_SAMPLES=On | +| Unit tests | C++ | unitTests | $ ctest -R unit_tests | -DEXIV2\_BUILD\_UNIT\_TESTS=On | +| Version test | C++ | src/version.cpp | $ ctest -R version | Always in library | The term _**bash scripts**_ is historical. The implementation of the tests in this collection originally required bash. These scripts have been rewritten in python. Visual Studio Users will appreciate the python implementation as it avoids the @@ -865,16 +874,17 @@ The Variable EXIV2\_PORT or EXIV2\_HTTP can be set to None to skip http tests. [TOC](#TOC)
-### 4.1 Running tests on a UNIX-like system +### 4.1 Running tests on Unix-like systems You can run tests directly from the build: ```bash $ cmake .. -G "Unix Makefiles" -DEXIV2_BUILD_UNIT_TESTS=On -$ make -... lots of output ... -$ make tests +... lots of output and build summary ... +$ cmake --build . ... lots of output ... +$ cmake --build . --target test +... test summary ... $ ``` @@ -882,13 +892,13 @@ You can run individual tests in the `test` directory. **Caution:** If you build ```bash $ cd /build -$ make bash_tests +$ ctest -R bash --verbose addmoddel_test (testcases.TestCases) ... ok .... Ran 176 tests in 9.526s OK (skipped=6) -$ make python_tests +$ ctest -R bugfixes --verbose ... lots of output ... test_run (tiff_test.test_tiff_test_program.TestTiffTestProg) ... ok ---------------------------------------------------------------------- @@ -901,7 +911,7 @@ $
### 4.2 Running tests on Visual Studio builds from cmd.exe -**Caution:** _The python3 interpreter must be on the PATH, build for DOS, and called python3.exe. I copied the python.exe program: +**Caution:** _The python3 interpreter must be on the PATH, build for DOS, and called python3.exe._ I copied the python.exe program: ```cmd > copy c:\Python37\python.exe c:\Python37\python3.exe @@ -909,13 +919,11 @@ $ ``` You can execute the test suite as described for UNIX-like systems. -The main difference is that you must use cmake to initiate the test -as make is not a system utility on Windows. ```bash > cd /build -> cmake --build . --target tests -> cmake --build . --target python_tests +> cmake --build . --target test +> ctest -R bugfixes --verbose ``` ##### Running tests from cmd.exe @@ -938,7 +946,7 @@ If you wish to use an environment variables, use set: ``` set VERBOSE=1 -cmake --build . --config Release --target tests +cmake --build . --config Release --target test set VERBOSE= ``` @@ -963,23 +971,23 @@ $ popd [TOC](#TOC)
-### 4.4 Python tests +### 4.4 Bugfix tests -You can run the python tests from the build directory: +You can run the bugfix tests from the build directory: ```bash $ cd /build -$ make python_tests +$ ctest -R bugfix ``` If you wish to run in verbose mode: ```bash $ cd /build -$ make python_tests VERBOSE=1 +$ $ ctest -R bugfix --verbose ``` -The python tests are stored in the directory tests and you can run them all with the command: +The bugfix tests are stored in the directory tests and you can run them all with the command: ```bash $ cd /tests @@ -998,23 +1006,23 @@ You may wish to get a brief summary of failures with commands such as: ```bash $ cd /build -$ make python_tests 2>&1 | grep FAIL +$ ctest -R bugfix --verbose 2>&1 | grep FAIL ``` [TOC](#TOC)
### 4.5 Test Summary -| *Tests* | Unix Style Platforms _(bash)_ | Visual Studio _(cmd.exe)_ | +| *Tests* | Execute using ctest | Execute using cmake | |:-- |:--- |:-- | -| | $ cd \/build | \> cd \/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 | +| | $ cd \/build | \> cd \/build | +| test | $ ctest | \> cmake --build . --config Release --target test | +| bash_tests | $ ctest -R bash | \> cmake --build . --config Release --target bash_tests | +| bugfixes | $ ctest -R bugfixes | \> cmake --build . --config Release --target bugfix_tests | +| unit_test | $ ctest -R unit | \> cmake --build . --config Release --target unit_test | +| version_test | $ ctest -R version | \> cmake --build . --config Release --target version_test | -The name **bash_tests** is historical. They are implemented in python. +The name **bashTests** is historical. The tests are implemented in python. [TOC](#TOC)
@@ -1255,5 +1263,5 @@ $ sudo pkg install developer/gcc-7 [TOC](#TOC) -Written by Robin Mills
robin@clanmills.com
Updated: 2021-11-28 +Written by Robin Mills
robin@clanmills.com
Updated: 2021-12-17 From 04b09e3bf3e18e336c591571d900e1802c512402 Mon Sep 17 00:00:00 2001 From: Robin Mills Date: Fri, 17 Dec 2021 16:12:27 +0000 Subject: [PATCH 2/7] Fixes following review. --- README.md | 41 ++++++++++++++++++----------------------- 1 file changed, 18 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 1b439aabbd..cdb317747a 100644 --- a/README.md +++ b/README.md @@ -71,8 +71,8 @@ $ cd ~/gnu/github/exiv2 # location of the project code $ mkdir build && cd build $ cmake .. -DCMAKE_BUILD_TYPE=Release $ cmake --build . -$ make test -$ sudo make install +$ ctest +$ sudo cmake --build . --target install ``` 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` @@ -372,7 +372,7 @@ Additionally, you will require an additional build step to actually build the do ```bash $ cmake ..options.. -DEXIV2_BUILD_DOC=On -$ make doc +$ cmake -- build . --target doc ``` To build the documentation, you must install the following products: @@ -405,7 +405,7 @@ $ cmake .. -G "Unix Makefiles" -DEXIV2_TEAM_PACKAGING=On $ cmake --build . --config Release ... [100%] Built target addmoddel -$ make package +$ cmake --build . --target package ... CPack: - package: /path/to/exiv2/build/exiv2-0.27.1-Linux.tar.gz generated. ``` @@ -413,15 +413,12 @@ CPack: - package: /path/to/exiv2/build/exiv2-0.27.1-Linux.tar.gz generated. 2) Source Package ```bash -$ make package_source +$ cmake --build . --target package_source Run CPack packaging tool for source... ... CPack: - package: /path/to/exiv2/build/exiv2-0.27.1-Source.tar.gz generated. ``` -You may prefer to run `$ cmake --build . --config Release --target package_source` - - [TOC](#TOC)
### 2.11 Debugging Exiv2 @@ -507,7 +504,7 @@ Visual Studio and Xcode can build debug or release builds without using the opti With the Unix Makefile generator, the targets can be listed: ```bash -$ make help +$ cmake --build . --target help The following are some of the valid targets for this Makefile: ... all (the default if no target is provided) ... clean @@ -566,10 +563,10 @@ To build with ccache, use the cmake option **-DBUILD\_WITH\_CCACHE=On** $ cd $ mkdir build ; cd build ; cd build $ cmake .. -G "Unix Makefiles" -DBUILD_WITH_CCACHE=On -$ make +$ cmake --build . # Build again to appreciate the performance gain -$ make clean -$ make +$ cmake --build . --target clean +$ cmake --build . ``` 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) @@ -842,15 +839,13 @@ $ ctest -R bugfixes # run only bugfixes and display summary $ ctest -R bugfixes --verbose # run only bugfixes and display all output ``` -#### Test Architecture - -| Description | Language | Location | Command
_(in build directory)_ | CMake Option to Build | +| Name | Language | Location | Command
_(in build directory)_ | CMake Option to Build | |:-- |:-- |:-- |:-- |:-- | -| Bash tests | python | tests/bash\_tests | $ ctest -R bashTests | -DEXIV2\_BUILD\_SAMPLES=On | -| Bugfix tests | python | tests/bugfixes | $ ctest -R bugfixes | -DEXIV2\_BUILD\_SAMPLES=On | -| Tiff tests | python | tests/tiff_test | $ ctest -R unit_tests | -DEXIV2\_BUILD\_SAMPLES=On | -| Unit tests | C++ | unitTests | $ ctest -R unit_tests | -DEXIV2\_BUILD\_UNIT\_TESTS=On | -| Version test | C++ | src/version.cpp | $ ctest -R version | Always in library | +| bashTests | python | tests/bash\_tests | $ ctest -R bash | -DEXIV2\_BUILD\_SAMPLES=On | +| bugfixes | python | tests/bugfixes | $ ctest -R bugfixes | -DEXIV2\_BUILD\_SAMPLES=On | +| tiffTests | python | tests/tiff_test | $ ctest -R tiff | -DEXIV2\_BUILD\_SAMPLES=On | +| unit_tests | C++ | unitTests | $ ctest -R unit | -DEXIV2\_BUILD\_UNIT\_TESTS=On | +| versionTest | C++ | src/version.cpp | $ ctest -R version | Always in library | The term _**bash scripts**_ is historical. The implementation of the tests in this collection originally required bash. These scripts have been rewritten in python. Visual Studio Users will appreciate the python implementation as it avoids the @@ -977,14 +972,14 @@ You can run the bugfix tests from the build directory: ```bash $ cd /build -$ ctest -R bugfix +$ ctest -R bugfixes ``` If you wish to run in verbose mode: ```bash $ cd /build -$ $ ctest -R bugfix --verbose +$ $ ctest -R bugfixes --verbose ``` The bugfix tests are stored in the directory tests and you can run them all with the command: @@ -1006,7 +1001,7 @@ You may wish to get a brief summary of failures with commands such as: ```bash $ cd /build -$ ctest -R bugfix --verbose 2>&1 | grep FAIL +$ ctest -R bugfixes --verbose 2>&1 | grep FAIL ``` [TOC](#TOC) From 6156c34b926e8e2602e638bc9297d590fe3dd40d Mon Sep 17 00:00:00 2001 From: Robin Mills Date: Sat, 18 Dec 2021 09:58:39 +0000 Subject: [PATCH 3/7] Bringing format/layout of 0.27-maintenance/README.md very close to main/README.md. --- README.md | 96 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 62 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index cdb317747a..58712fb9b7 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,24 @@ -| Travis | AppVeyor | GitLab| Codecov| Repology| Chat | -|:-------------:|:-------------:|:-----:|:------:|:-------:|:----:| -| [![Build Status](https://travis-ci.org/Exiv2/exiv2.svg?branch=0.27-maintenance)](https://travis-ci.org/Exiv2/exiv2) | [![Build status](https://ci.appveyor.com/api/projects/status/d6vxf2n0cp3v88al/branch/0.27-maintenance?svg=true)](https://ci.appveyor.com/project/piponazo/exiv2-wutfp/branch/0.27-maintenance) | [![pipeline status](https://gitlab.com/D4N/exiv2/badges/0.27-maintenance/pipeline.svg)](https://gitlab.com/D4N/exiv2/commits/0.27-maintenance) | [![codecov](https://codecov.io/gh/Exiv2/exiv2/branch/0.27-maintenance/graph/badge.svg)](https://codecov.io/gh/Exiv2/exiv2) | [![Packaging status](https://repology.org/badge/tiny-repos/exiv2.svg)](https://repology.org/metapackage/exiv2/versions) | [![#exiv2-chat on matrix.org](matrix-standard-vector-logo-xs.png)](https://matrix.to/#/#exiv2-chat:matrix.org) | +| Codecov | OSS-Fuzz | Repology | Chat | +| :----------------------------------------------------------: | :----------------------------------------------------------: | :----------------------------------------------------------: | :----------------------------------------------------------: | +| [![codecov](https://codecov.io/gh/Exiv2/exiv2/branch/main/graph/badge.svg?token=O9G7Iswx26)](https://codecov.io/gh/Exiv2/exiv2) | [![Fuzzing Status](https://oss-fuzz-build-logs.storage.googleapis.com/badges/exiv2.svg)](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:exiv2) | [![Packaging status](https://repology.org/badge/tiny-repos/exiv2.svg)](https://repology.org/metapackage/exiv2/versions) | [![#exiv2-chat on matrix.org](matrix-standard-vector-logo-xs.png)](https://matrix.to/#/#exiv2-chat:matrix.org) | + +CI Status: + +[![Basic CI for all platforms on push](https://github.com/Exiv2/exiv2/actions/workflows/on_push_BasicWinLinMac.yml/badge.svg?branch=main)](https://github.com/Exiv2/exiv2/actions/workflows/on_push_BasicWinLinMac.yml) + +[![CI for different Linux distributions](https://github.com/Exiv2/exiv2/actions/workflows/nightly_Linux_distributions.yml/badge.svg?branch=main)](https://github.com/Exiv2/exiv2/actions/workflows/nightly_Linux_distributions.yml) + +[![Linux Special Builds on PRs](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_linux_special_buils.yml/badge.svg)](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_linux_special_buils.yml) + +[![Linux-Ubuntu Matrix on PRs](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_linux_matrix.yml/badge.svg)](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_linux_matrix.yml) + +[![Mac Matrix on PRs](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_mac_matrix.yml/badge.svg)](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_mac_matrix.yml) + +[![Win Matrix on PRs](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_windows_matrix.yml/badge.svg)](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_windows_matrix.yml)
-# Welcome to Exiv2 +# 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. @@ -16,6 +30,7 @@ write, delete and modify Exif, IPTC, XMP and ICC image metadata. 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 ![Exiv2](exiv2.png) @@ -48,7 +63,6 @@ The file ReadMe.txt in a build bundle describes how to install the library on th 2. [Running tests on Visual Studio builds](#4-2) 3. [Unit tests](#4-3) 4. [Bugfix tests](#4-4) - 5. [Test Summary](#4-5) 5. [Platform Notes](#5) 1. [Linux](#5-1) 2. [macOS](#5-2) @@ -59,11 +73,13 @@ The file ReadMe.txt in a build bundle describes how to install the library on th [TOC](#TOC)
+ ## 2 Building, Installing, Using and Uninstalling Exiv2 You need [CMake](https://cmake.org/download/) to configure the Exiv2 project and the GCC or Clang compiler and associated tool chain.
+ ### 2.1 Build, Install, Use Exiv2 on a UNIX-like system ```bash @@ -108,6 +124,7 @@ These commands will remove the exiv2 executables, library, header files and man [TOC](#TOC)
+ ### 2.2 Build and Install Exiv2 with Visual Studio We recommend that you use conan to download the Exiv2 external dependencies on Windows. On other platforms (maxOS, Ubuntu and others), you should use the platform package manger. These are discussed: [Platform Notes](#5) The options to configure and compile the project using Visual Studio are similar to UNIX like systems. @@ -122,6 +139,7 @@ This will create and copy the exiv2 build artefacts to C:\Program Files (x86)\ex [TOC](#TOC)
+ ### 2.3 Build options There are two groups of CMake options. There are many options defined by CMake. Here are some particularly useful options: @@ -154,6 +172,7 @@ It is planned to set the default -DEXIV2\_ENABLE\_BMFF=On for Exiv2 v1.00. BMFF [TOC](#TOC)
+ ### 2.4 Dependencies The following Exiv2 features require external libraries: @@ -193,6 +212,7 @@ If you wish to use libiconv with Visual Studio you will have to build libiconv a [TOC](#TOC)
+ ### 2.5 Building and linking your code with Exiv2 There are detailed platform notes about compiling and linking in `releasenotes/{platform}/ReadMe.txt` @@ -219,6 +239,7 @@ $ g++ -std=c++98 myprog.cpp -o myprog -I/usr/local/include -L/usr/local/lib -lex [TOC](#TOC)
+ ### 2.6 Consuming Exiv2 with CMake When exiv2 is installed, the files required to consume Exiv2 are installed in `${CMAKE_INSTALL_PREFIX}/lib/cmake/exiv2` @@ -249,6 +270,7 @@ $ [TOC](#TOC)
+ ### 2.7 Using pkg-config to compile and link your code with Exiv2 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: @@ -273,6 +295,7 @@ g++ -std=c++98 myprogram.cpp -o myprogram $(pkg-config exiv2 --libs --cflags) [TOC](#TOC)
+ ### 2.8 Localisation Localisation is supported on a UNIX-like platform: Linux, macOS, Cygwin and MinGW/msys2. Localisation is not supported for Visual Studio builds. @@ -362,6 +385,7 @@ $ [TOC](#TOC)
+ ### 2.9 Building Exiv2 Documentation Building documentation requires installing special tools. You will probably prefer to @@ -383,6 +407,7 @@ To build the documentation, you must install the following products: [TOC](#TOC)
+ ### 2.10 Building Exiv2 Packages To enable the building of Exiv2 packages, use the CMake option `-DEXIV2_TEAM_PACKAGING=On`. @@ -421,6 +446,7 @@ CPack: - package: /path/to/exiv2/build/exiv2-0.27.1-Source.tar.gz generated. [TOC](#TOC)
+ ### 2.11 Debugging Exiv2 1) Generating and installing a debug library @@ -515,6 +541,7 @@ The following are some of the valid targets for this Makefile: [TOC](#TOC)
+ ### 2.12 Building Exiv2 with **clang** and other build chains 1) On Linux @@ -547,6 +574,7 @@ I have been unable to get clang to work on any of those platforms. [TOC](#TOC)
+ ### 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. @@ -563,7 +591,7 @@ To build with ccache, use the cmake option **-DBUILD\_WITH\_CCACHE=On** $ cd $ mkdir build ; cd build ; cd build $ cmake .. -G "Unix Makefiles" -DBUILD_WITH_CCACHE=On -$ cmake --build . +$ cmake --build . # Build again to appreciate the performance gain $ cmake --build . --target clean $ cmake --build . @@ -573,6 +601,7 @@ Due to the way in which ccache is installed in Fedora (and other Linux distros), [TOC](#TOC)
+ ### 2.14 Thread Safety Exiv2 heavily relies on standard C++ containers. Static or global variables are used read-only, with the exception of the XMP namespace registration function (see below). Thus Exiv2 is thread safe in the same sense as C++ containers: @@ -600,6 +629,7 @@ The use of the _**thread unsafe function**_ Exiv2::enableBMFF(true) is discussed [TOC](#TOC)
+ ### 2.15 Library Initialisation and Cleanup As discussed in the section on Thread Safety, Exiv2 classes for Exif and IPTC metadata are fully reentrant and require no initialisation or cleanup. @@ -618,19 +648,20 @@ The exiv2 command-line program and sample applications call the following at the [TOC](#TOC)
+ ### 2.16 Cross Platform Build and Test on Linux for MinGW You can cross compile Exiv2 on Linux for MinGW. We have used the following method on **Fedora** and believe this is also possible on Ubuntu and other distros. Detailed instructions are provided here for **Fedora**. ### Cross Build and Test On Fedora -####1 Install the cross platform build tools +#### 1 Install the cross platform build tools ```bash $ sudo dnf install mingw64-gcc-c++ mingw64-filesystem mingw64-expat mingw64-zlib cmake make ``` -####2 Install Dependancies +#### 2 Install Dependancies You will need to install x86_64 libraries to support the options you wish to use. By default, you will need libz and expat. Your `dnf` command above has installed them for you. If you wish to use features such as `webready` you should install openssl and libcurl as follows: @@ -645,7 +676,7 @@ Installing: ... ``` -####3 Get the code and build +#### 3 Get the code and build ```bash $ git clone://github.com/exiv2/exiv2 --branch 0.27-maintenance exiv2 @@ -667,7 +698,7 @@ $ mingw64-cmake .. -DEXIV2_TEAM_EXTRA_WARNINGS=On \ The options available for cross-compiling are the same as provided for all builds. See: [Build Options](#2-3) -####4 Copy "system dlls" in the bin directory +#### 4 Copy "system dlls" in the bin directory These DLLs are required to execute the cross-platform build in the bin from Windows @@ -677,7 +708,7 @@ for i in libexpat-1.dll libgcc_s_seh-1.dll libstdc++-6.dll libwinpthread-1.dll z done ``` -####5 Executing exiv2 in wine +#### 5 Executing exiv2 in wine You may wish to use wine to execute exiv2 from the command prompt. To do this: @@ -697,7 +728,7 @@ Z:\Home\gnu\github\exiv2\0.27-maintenance\build_mingw_fedora> If you have not installed wine, Fedora will offer to install it for you. -####6 Running the test suite +#### 6 Running the test suite On a default wine installation, you are in the MSDOS/cmd.exe prompt. You cannot execute the exiv2 test suite in this environment as you require python3 and MSYS/bash to run the suite. @@ -726,6 +757,7 @@ You will find that 3 tests fail at the end of the test suite. It is safe to ign [TOC](#TOC)
+ ### 2.17 Building with C++11 and other compilers Exiv2 uses the default compiler for your system. Exiv2 v0.27 was written to the C++ 1998 standard and uses auto\_ptr. The C++11 and C++14 compilers will issue deprecation warnings about auto\_ptr. As _auto\_ptr support has been removed from C++17, you cannot build Exiv2 v0.27 with C++17 or later compilers._ Exiv2 v1.00 and later do not use auto\_ptr and will build with all modern C++ Standard Compilers. @@ -736,7 +768,7 @@ To build with C++11: $ cd $ mkdir build ; cd build $ cmake .. -DCMAKE_CXX_STANDARD=11 -DCMAKE_CXX_FLAGS=-Wno-deprecated -$ make +$ cmake --build . ``` The option -DCMAKE\_CXX\_STANDARD=11 specifies the C++ Language Standard. Possible values are 98, 11 or 14. @@ -747,6 +779,7 @@ The option -DCMAKE\_CXX\_FLAGS=-Wno-deprecated suppresses warnings from C++11 co [TOC](#TOC)
+ ### 2.18 Static and Shared Libraries You can build either static or shared libraries. Both can be linked with either static or shared run-time libraries. You specify the shared/static with the option `-BUILD_SHARED_LIBS=On|Off` You specify the run-time with the option `-DEXIV2_ENABLE_DYNAMIC_RUNTIME=On|Off`. The default for both options default is On. So you build shared and use the shared libraries which are `.dll` on Windows (msvc, Cygwin and MinGW/msys), `.dylib` on macOS and `.so` on Linux and UNIX. @@ -777,6 +810,7 @@ This is discussed: [https://github.com/Exiv2/exiv2/issues/1230](https://github.c [TOC](#TOC)
+ ### 2.19 Support for bmff files (CR3, HEIF, HEIC, and AVIF) **Attention is drawn to the possibility that bmff support may be the subject of patent rights. _Exiv2 shall not be held responsible for identifying any or all such patent rights. Exiv2 shall not be held responsible for the legal consequences of the use of this code_.** @@ -793,12 +827,14 @@ Applications may wish to provide a preference setting to enable bmff support and [TOC](#TOC)
+ ## 3 License and Support All project resources are accessible from the project website. https://github.com/Exiv2/exiv2
+ ### 3.1 License Copyright (C) 2004-2021 Exiv2 authors. @@ -821,12 +857,14 @@ with this program; if not, write to the Free Software Foundation, Inc., [TOC](#TOC)
+ ### 3.2 Support For new bug reports, feature requests and support: Please open an issue in Github. [https://github.com/exiv2/exiv2](https://github.com/exiv2/exiv2) [TOC](#TOC)
+ ## 4 Test Suite The test suite is implemented using CTest. CMake adds the target 'test' to the build. You can run ctest with the command `$ cmake --build . --target test`, or simply with `$ ctest`. The build creates 5 tests: bashTests, bugfixes, tiffTests, unit_tests and versionTest. You can run all tests or a subset. @@ -839,6 +877,8 @@ $ ctest -R bugfixes # run only bugfixes and display summary $ ctest -R bugfixes --verbose # run only bugfixes and display all output ``` +#### Test Architecture + | Name | Language | Location | Command
_(in build directory)_ | CMake Option to Build | |:-- |:-- |:-- |:-- |:-- | | bashTests | python | tests/bash\_tests | $ ctest -R bash | -DEXIV2\_BUILD\_SAMPLES=On | @@ -847,9 +887,7 @@ $ ctest -R bugfixes --verbose # run only bugfixes and display all output | unit_tests | C++ | unitTests | $ ctest -R unit | -DEXIV2\_BUILD\_UNIT\_TESTS=On | | versionTest | C++ | src/version.cpp | $ ctest -R version | Always in library | -The term _**bash scripts**_ is historical. The implementation of the tests in this collection originally required bash. These -scripts have been rewritten in python. Visual Studio Users will appreciate the python implementation as it avoids the -installation of mingw/cygwin and special PATH settings. +The term _**bash**_ is historical. These tests were originally bash scripts and they have been rewritten in python. Visual Studio Users will appreciate the python implementation as it avoids the installation of mingw/cygwin and special PATH settings. #### Environment Variables used by the test suite: @@ -878,7 +916,7 @@ $ cmake .. -G "Unix Makefiles" -DEXIV2_BUILD_UNIT_TESTS=On ... lots of output and build summary ... $ cmake --build . ... lots of output ... -$ cmake --build . --target test +$ ctest ... test summary ... $ ``` @@ -1003,24 +1041,9 @@ You may wish to get a brief summary of failures with commands such as: $ cd /build $ ctest -R bugfixes --verbose 2>&1 | grep FAIL ``` - -[TOC](#TOC) -
-### 4.5 Test Summary - -| *Tests* | Execute using ctest | Execute using cmake | -|:-- |:--- |:-- | -| | $ cd \/build | \> cd \/build | -| test | $ ctest | \> cmake --build . --config Release --target test | -| bash_tests | $ ctest -R bash | \> cmake --build . --config Release --target bash_tests | -| bugfixes | $ ctest -R bugfixes | \> cmake --build . --config Release --target bugfix_tests | -| unit_test | $ ctest -R unit | \> cmake --build . --config Release --target unit_test | -| version_test | $ ctest -R version | \> cmake --build . --config Release --target version_test | - -The name **bashTests** is historical. The tests are implemented in python. - [TOC](#TOC)
+ ## 5 Platform Notes There are many ways to set up and configure your platform. The following notes are provided as a guide. @@ -1051,6 +1074,7 @@ $ make [TOC](#TOC)
+ ### 5.2 macOS You will need to install Xcode and the Xcode command-line tools to build on macOS. @@ -1061,6 +1085,7 @@ 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. @@ -1119,6 +1144,7 @@ $ [TOC](#TOC)
+ ### 5.4 Cygwin/64 Please note that the platform Cygwin/32 is obsolete and superceded by Cygwin/64. @@ -1150,6 +1176,7 @@ The utility apt-cyg can be downloaded and used to install dependencies. The cod [TOC](#TOC)
+ ### 5.5 Visual Studio We recommend that you use Conan to build Exiv2 using Visual Studio. 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. @@ -1169,6 +1196,7 @@ The python3 interpreter must be on your PATH. [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 @@ -1258,5 +1286,5 @@ $ sudo pkg install developer/gcc-7 [TOC](#TOC) -Written by Robin Mills
robin@clanmills.com
Updated: 2021-12-17 +Written by Robin Mills
robin@clanmills.com
Updated: 2021-12-18 From 7b699afe84e43db6613ee1ca304bc43a2cf2bcad Mon Sep 17 00:00:00 2001 From: Robin Mills Date: Sun, 19 Dec 2021 11:11:38 +0000 Subject: [PATCH 4/7] Minor layout improvements. --- README.md | 44 +++++++++++++++++++++++--------------------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 58712fb9b7..d346e0050d 100644 --- a/README.md +++ b/README.md @@ -2,23 +2,19 @@ | :----------------------------------------------------------: | :----------------------------------------------------------: | :----------------------------------------------------------: | :----------------------------------------------------------: | | [![codecov](https://codecov.io/gh/Exiv2/exiv2/branch/main/graph/badge.svg?token=O9G7Iswx26)](https://codecov.io/gh/Exiv2/exiv2) | [![Fuzzing Status](https://oss-fuzz-build-logs.storage.googleapis.com/badges/exiv2.svg)](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:exiv2) | [![Packaging status](https://repology.org/badge/tiny-repos/exiv2.svg)](https://repology.org/metapackage/exiv2/versions) | [![#exiv2-chat on matrix.org](matrix-standard-vector-logo-xs.png)](https://matrix.to/#/#exiv2-chat:matrix.org) | -CI Status: -[![Basic CI for all platforms on push](https://github.com/Exiv2/exiv2/actions/workflows/on_push_BasicWinLinMac.yml/badge.svg?branch=main)](https://github.com/Exiv2/exiv2/actions/workflows/on_push_BasicWinLinMac.yml) -[![CI for different Linux distributions](https://github.com/Exiv2/exiv2/actions/workflows/nightly_Linux_distributions.yml/badge.svg?branch=main)](https://github.com/Exiv2/exiv2/actions/workflows/nightly_Linux_distributions.yml) - -[![Linux Special Builds on PRs](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_linux_special_buils.yml/badge.svg)](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_linux_special_buils.yml) - -[![Linux-Ubuntu Matrix on PRs](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_linux_matrix.yml/badge.svg)](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_linux_matrix.yml) - -[![Mac Matrix on PRs](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_mac_matrix.yml/badge.svg)](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_mac_matrix.yml) - -[![Win Matrix on PRs](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_windows_matrix.yml/badge.svg)](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_windows_matrix.yml) +| **CI Status:** | | | +|:-- |:-- |:-- | +| [![Basic CI for all platforms on push](https://github.com/Exiv2/exiv2/actions/workflows/on_push_BasicWinLinMac.yml/badge.svg?branch=main)](https://github.com/Exiv2/exiv2/actions/workflows/on_push_BasicWinLinMac.yml) | [![CI for different Linux distributions](https://github.com/Exiv2/exiv2/actions/workflows/nightly_Linux_distributions.yml/badge.svg?branch=main)](https://github.com/Exiv2/exiv2/actions/workflows/nightly_Linux_distributions.yml) | [![Linux Special Builds on PRs](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_linux_special_buils.yml/badge.svg)](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_linux_special_buils.yml) | +| [![Linux-Ubuntu Matrix on PRs](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_linux_matrix.yml/badge.svg)](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_linux_matrix.yml) | [![Mac Matrix on PRs](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_mac_matrix.yml/badge.svg)](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_mac_matrix.yml) | [![Win Matrix on PRs](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_windows_matrix.yml/badge.svg)](https://github.com/Exiv2/exiv2/actions/workflows/on_PR_windows_matrix.yml) |
# Welcome to Exiv2 + +![Exiv2](exiv2.png) + Exiv2 is a C++ library and a command-line utility to read, write, delete and modify Exif, IPTC, XMP and ICC image metadata. @@ -32,7 +28,6 @@ The file ReadMe.txt in a build bundle describes how to install the library on th
### TABLE OF CONTENTS -![Exiv2](exiv2.png) 1. [Welcome to Exiv2](#1) 2. [Building, Installing, Using and Uninstalling Exiv2](#2) @@ -948,16 +943,23 @@ $ ```cmd > copy c:\Python37\python.exe c:\Python37\python3.exe -> set "PATH=c:\Python37;%PATH% +> set PATH=c:\Python37;%PATH% ``` -You can execute the test suite as described for UNIX-like systems. +You can execute the test suite in a similar manner to that described for UNIX-like systems. You _**must**_ provide the -C config option to ctest for Visual Studio builds. -```bash +```cmd > cd /build -> cmake --build . --target test -> ctest -R bugfixes --verbose +> ctest -C Release +> ctest -C Release -R bugfixes --verbose +``` +Visual Studio can build different configs as follows: + +```cmd +> cmake --build . --config Release # or Debug or MinSizeRel or RelWithDebInfo +> ctest -C Release ``` +The default for **cmake** config option `--config` is `Release`. **ctest** does not have a default for config option `-C`. ##### Running tests from cmd.exe @@ -972,15 +974,15 @@ c:\...\exiv2\build>conan install .. --build missing --profile msvc2019Release c:\...\exiv2\build>cmake .. -DEXIV2_BUILD_UNIT_TESTS=On -G "Visual Studio 16 2019" c:\...\exiv2\build>cmake --build . --config Release ... lots of output from compiler and linker ... -c:\...\exiv2\build> +c:\...\exiv2\build>ctest -C Release ``` If you wish to use an environment variables, use set: ``` -set VERBOSE=1 -cmake --build . --config Release --target test -set VERBOSE= +set EXIV2_PORT=54321 +ctest -C Release --verbose -R bash +set EXIV2_PORT= ``` [TOC](#TOC) From 939a9101fc2c91c876f8e2be4c682d5d53c3fcfd Mon Sep 17 00:00:00 2001 From: Robin Mills Date: Sun, 19 Dec 2021 11:55:05 +0000 Subject: [PATCH 5/7] I've polished this and minimized the differences with main/README.md. It's not possible to add lensTest into 0.27-maintenance without modifying Exiv2::getExiv2ConfigPath(). --- README.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index d346e0050d..6bd213bb45 100644 --- a/README.md +++ b/README.md @@ -391,7 +391,7 @@ Additionally, you will require an additional build step to actually build the do ```bash $ cmake ..options.. -DEXIV2_BUILD_DOC=On -$ cmake -- build . --target doc +$ cmake --build . --target doc ``` To build the documentation, you must install the following products: @@ -589,7 +589,7 @@ $ cmake .. -G "Unix Makefiles" -DBUILD_WITH_CCACHE=On $ cmake --build . # Build again to appreciate the performance gain $ cmake --build . --target clean -$ cmake --build . +$ cmake --build . ``` 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) @@ -755,7 +755,7 @@ You will find that 3 tests fail at the end of the test suite. It is safe to ign ### 2.17 Building with C++11 and other compilers -Exiv2 uses the default compiler for your system. Exiv2 v0.27 was written to the C++ 1998 standard and uses auto\_ptr. The C++11 and C++14 compilers will issue deprecation warnings about auto\_ptr. As _auto\_ptr support has been removed from C++17, you cannot build Exiv2 v0.27 with C++17 or later compilers._ Exiv2 v1.00 and later do not use auto\_ptr and will build with all modern C++ Standard Compilers. +Exiv2 with use the `-DCMAKE_CXX_STANDARD=98` compiler. Exiv2 v0.27 was written to the C++ 1998 standard and uses auto\_ptr. The C++11 and C++14 compilers will issue deprecation warnings about auto\_ptr. As _auto\_ptr support has been removed from C++17, you cannot build Exiv2 v0.27 with C++17 or later compilers._ Exiv2 v1.00 and later do not use auto\_ptr and will build with all modern C++ Standard Compilers. To build with C++11: @@ -1174,8 +1174,6 @@ bash.exe -norc endlocal ``` -The utility apt-cyg can be downloaded and used to install dependencies. The code to do this is in appveyor\_mingw\_cygwin.yml. - [TOC](#TOC)
@@ -1288,5 +1286,5 @@ $ sudo pkg install developer/gcc-7 [TOC](#TOC) -Written by Robin Mills
robin@clanmills.com
Updated: 2021-12-18 +Written by Robin Mills
robin@clanmills.com
Updated: 2021-12-19 From ee2f9739861c337ab8e5ced7ebb39eabc859e742 Mon Sep 17 00:00:00 2001 From: Robin Mills Date: Mon, 20 Dec 2021 08:15:39 +0000 Subject: [PATCH 6/7] Fixes following review. --- README-CONAN.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README-CONAN.md b/README-CONAN.md index 37c3d91894..46ce747c75 100644 --- a/README-CONAN.md +++ b/README-CONAN.md @@ -99,19 +99,19 @@ os_build=Windows [env] ``` -_Profiles for Visual Studio are discussed in detail here: [Visual Studio Notes](#2-2)__ +_Profiles for Visual Studio are discussed in detail here: [Visual Studio Notes](#2-2)_ + ##### 1.4) Build dependencies, create build environment, build and test -| | Build Steps | Linux and macOS | Visual Studio | -|:-- |:--------------|--------------------------------|------------------------------| +| | Build Steps | Linux and macOS | Visual Studio | +|:-- |:-------------------------------------------------------------------------|-----------------------|------------------------------| | _**1**_ | Get conan to fetch dependencies

The output can be quite
long as conan downloads and/or builds
zlib, expat, curl and other dependencies.| $ conan install ..
     --build missing | c:\\..\\build> conan install .. --build missing
    --profile msvc2019Release64 | -| _**2**_ | Get cmake to generate
makefiles or sln/vcxproj | $ cmake .. | c:\\..\\build> cmake .. -G "Visual Studio 16 2019" -| _**3**_ | Build | $ cmake --build . | c:\\..\\build> cmake --build . --config Release
You may prefer to open exiv2.sln and build using the IDE. | -| _**4**_ | Optionally Run Test Suite | $ cmake --build . --target test | c:\\..\\build> cmake --build . --config Release --target test
[README.md](README.md) | - +| _**2**_ | Get cmake to generate
makefiles or sln/vcxproj | $ cmake .. | c:\\..\\build> cmake .. -G "Visual Studio 16 2019" +| _**3**_ | Build | $ cmake --build . | c:\\..\\build> cmake --build . --config Release
You may prefer to open exiv2.sln and build using the IDE. | +| _**4**_ | Optionally Run Test Suite
Test documentation: [README.md](README.md) | $ ctest | c:\\..\\build> ctest -C Release | [TOC](#TOC) @@ -572,4 +572,4 @@ $ cmake -DEXIV2_ENABLE_WEBREADY=ON -DEXIV2_ENABLE_CURL=ON -DEXIV2_ENABLE_SSH=ON [TOC](#TOC) -Written by Robin Mills
robin@clanmills.com
Updated: 2021-03-18 +Written by Robin Mills
robin@clanmills.com
Updated: 2021-12-19 From 5e2b7774bcfe9cb923ae8244e64cf0dbf546c7ac Mon Sep 17 00:00:00 2001 From: Robin Mills Date: Mon, 20 Dec 2021 11:44:45 +0000 Subject: [PATCH 7/7] Fixes following review. --- CMakeLists.txt | 4 +-- README.md | 76 ++++++++++++++++++++++++---------------- unitTests/CMakeLists.txt | 2 +- 3 files changed, 49 insertions(+), 33 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 7908ee55d7..4a9580f857 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -111,7 +111,7 @@ if( EXIV2_BUILD_SAMPLES ) WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/tests COMMAND cmake -E env EXIV2_BINDIR=${CMAKE_RUNTIME_OUTPUT_DIRECTORY} ${Python3_EXECUTABLE} runner.py --verbose bash_tests ) - add_test(NAME bugfixes + add_test(NAME bugfixTests WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/tests COMMAND cmake -E env EXIV2_BINDIR=${CMAKE_RUNTIME_OUTPUT_DIRECTORY} ${Python3_EXECUTABLE} runner.py --verbose bugfixes ) @@ -119,7 +119,7 @@ if( EXIV2_BUILD_SAMPLES ) WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/tests COMMAND cmake -E env EXIV2_BINDIR=${CMAKE_RUNTIME_OUTPUT_DIRECTORY} ${Python3_EXECUTABLE} runner.py --verbose tiff_test ) - add_test(NAME versionTest + add_test(NAME versionTests WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/tests COMMAND cmake -E env EXIV2_BINDIR=${CMAKE_RUNTIME_OUTPUT_DIRECTORY} ${Python3_EXECUTABLE} runner.py --verbose bash_tests/version_test.py ) diff --git a/README.md b/README.md index 6bd213bb45..d6f3a9d4ff 100644 --- a/README.md +++ b/README.md @@ -56,8 +56,8 @@ The file ReadMe.txt in a build bundle describes how to install the library on th 4. [Test Suite](#4) 1. [Running tests on a UNIX-like system](#4-1) 2. [Running tests on Visual Studio builds](#4-2) - 3. [Unit tests](#4-3) - 4. [Bugfix tests](#4-4) + 3. [Unit Tests](#4-3) + 4. [Bugfix Tests](#4-4) 5. [Platform Notes](#5) 1. [Linux](#5-1) 2. [macOS](#5-2) @@ -862,40 +862,55 @@ For new bug reports, feature requests and support: Please open an issue in Gith ## 4 Test Suite -The test suite is implemented using CTest. CMake adds the target 'test' to the build. You can run ctest with the command `$ cmake --build . --target test`, or simply with `$ ctest`. The build creates 5 tests: bashTests, bugfixes, tiffTests, unit_tests and versionTest. You can run all tests or a subset. +You execute the Test Suite using CTest with the command `$ ctest`. + +The build creates 5 tests: bashTests, bugfixTests, tiffTests, unitTests and versionTests. You can run all tests or a subset. To list all available tests, execute ctest with the `-N` or `--show-only` option, which disables execution: + +```bash +.../build $ ctest -N +Test project .../build + Test #1: bashTests + Test #2: bugfixTests + Test #3: tiffTests + Test #4: versionTests + Test #5: unitTests + +Total Tests: 5 +.../build $ +``` + +ctest provides many option and the following show common use-case scenarios: ```bash -$ cmake --build . --target test $ ctest # run all tests and display summary $ ctest --output-on-failure # run all tests and output failures -$ ctest -R bugfixes # run only bugfixes and display summary -$ ctest -R bugfixes --verbose # run only bugfixes and display all output +$ ctest -R bugfix # run only bugfixTests and display summary +$ ctest -R bugfix --verbose # run only bugfixTests and display all output ``` -#### Test Architecture - | Name | Language | Location | Command
_(in build directory)_ | CMake Option to Build | |:-- |:-- |:-- |:-- |:-- | | bashTests | python | tests/bash\_tests | $ ctest -R bash | -DEXIV2\_BUILD\_SAMPLES=On | -| bugfixes | python | tests/bugfixes | $ ctest -R bugfixes | -DEXIV2\_BUILD\_SAMPLES=On | +| bugfixTests | python | tests/bugfixes | $ ctest -R bugfix | -DEXIV2\_BUILD\_SAMPLES=On | | tiffTests | python | tests/tiff_test | $ ctest -R tiff | -DEXIV2\_BUILD\_SAMPLES=On | -| unit_tests | C++ | unitTests | $ ctest -R unit | -DEXIV2\_BUILD\_UNIT\_TESTS=On | -| versionTest | C++ | src/version.cpp | $ ctest -R version | Always in library | +| unitTests | C++ | unitTests/ | $ ctest -R unit | -DEXIV2\_BUILD\_UNIT\_TESTS=On | +| versionTests | C++ | src/version.cpp | $ ctest -R version | Always in library | -The term _**bash**_ is historical. These tests were originally bash scripts and they have been rewritten in python. Visual Studio Users will appreciate the python implementation as it avoids the installation of mingw/cygwin and special PATH settings. +The term _**bashTests**_ is historical. These tests were originally bash scripts and have been rewritten in python. +Visual Studio Users will appreciate the python implementation as it avoids the installation of mingw/cygwin and special PATH settings. #### Environment Variables used by the test suite: If you build the code in the directory \build, tests will run using the default values of Environment Variables. -| Variable | Default | Platforms | Purpose | -|:-- |:-- |:-- |:-- | -| EXIV2_BINDIR | **\/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_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 | +| Variable | Default | Platforms | Purpose | +|:-- |:-- |:-- |:-- | +| EXIV2_BINDIR | **\/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_ECHO | _**not set**_ | All Platforms | For debugging bashTests | +| VALGRIND | _**not set**_ | All Platforms | For debugging bashTests | +| VERBOSE | _**not set**_ | Makefile platforms | Instructs 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. @@ -926,7 +941,7 @@ addmoddel_test (testcases.TestCases) ... ok Ran 176 tests in 9.526s OK (skipped=6) -$ ctest -R bugfixes --verbose +$ ctest -R bugfix --verbose ... lots of output ... test_run (tiff_test.test_tiff_test_program.TestTiffTestProg) ... ok ---------------------------------------------------------------------- @@ -946,12 +961,12 @@ $ > set PATH=c:\Python37;%PATH% ``` -You can execute the test suite in a similar manner to that described for UNIX-like systems. You _**must**_ provide the -C config option to ctest for Visual Studio builds. +You can execute the test suite in a similar manner to that described for UNIX-like systems. You _**must**_ provide the `-C` config option to ctest for Visual Studio builds. ```cmd > cd /build > ctest -C Release -> ctest -C Release -R bugfixes --verbose +> ctest -C Release -R bugfix --verbose ``` Visual Studio can build different configs as follows: @@ -987,7 +1002,7 @@ set EXIV2_PORT= [TOC](#TOC)
-### 4.3 Unit tests +### 4.3 Unit Tests The code for the unit tests is in `/unitTests`. To include unit tests in the build, use the *cmake* option `-DEXIV2_BUILD_UNIT_TESTS=On`. @@ -1006,23 +1021,23 @@ $ popd [TOC](#TOC)
-### 4.4 Bugfix tests +### 4.4 Bugfix Tests You can run the bugfix tests from the build directory: ```bash $ cd /build -$ ctest -R bugfixes +$ ctest -R bugfix ``` If you wish to run in verbose mode: ```bash $ cd /build -$ $ ctest -R bugfixes --verbose +$ ctest -R bugfix --verbose ``` -The bugfix tests are stored in the directory tests and you can run them all with the command: +The bugfix tests are stored in directory tests/ and you can run them all with the command: ```bash $ cd /tests @@ -1041,8 +1056,9 @@ You may wish to get a brief summary of failures with commands such as: ```bash $ cd /build -$ ctest -R bugfixes --verbose 2>&1 | grep FAIL +$ ctest -R bugfix --verbose 2>&1 | grep FAIL ``` + [TOC](#TOC)
@@ -1286,5 +1302,5 @@ $ sudo pkg install developer/gcc-7 [TOC](#TOC) -Written by Robin Mills
robin@clanmills.com
Updated: 2021-12-19 +Written by Robin Mills
robin@clanmills.com
Updated: 2021-12-20 diff --git a/unitTests/CMakeLists.txt b/unitTests/CMakeLists.txt index 320c3d24e6..a13036c543 100644 --- a/unitTests/CMakeLists.txt +++ b/unitTests/CMakeLists.txt @@ -59,4 +59,4 @@ if (MSVC) set_target_properties(unit_tests PROPERTIES LINK_FLAGS "/ignore:4099") endif() -add_test(NAME unit_tests COMMAND unit_tests) +add_test(NAME unitTests COMMAND unit_tests)