Add CMake build support (#73)

Support building with CMake, both with and without tests.

Add new build type to CI.

Update the README with instructions on how to build with cmake and depend on the project.

Author: jwmcglynn

.github/workflows/main.yml

@@ -40,6 +40,11 @@ jobs:
         sudo apt-get install -y clang-16 libc++-16-dev libc++abi-16-dev
         echo "/usr/lib/llvm-16/bin" >> $GITHUB_PATH
 
+    - name: Install cmake
+      run: |
+        sudo apt-get install -y cmake ninja-build
+        echo "/usr/bin/cmake" >> $GITHUB_PATH
+
     # Enable tmate debugging of manually-triggered workflows if the input option was provided
     - name: Setup tmate session
       uses: mxschmitt/action-tmate@v3
@@ -62,3 +67,16 @@ jobs:
     - name: Test (C++20)
       run: |
         "${GITHUB_WORKSPACE}/bin/bazel" test --config=clang --config=cpp20 //...
+
+    - name: Build (CMake)
+      run: |
+        cmake -S . -B build -G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
+        cmake --build build
+        ctest --test-dir build --output-on-failure
+
+    - name: Build w/ Tests (CMake)
+      run: |
+        rm -rf build
+        cmake -S . -B build -G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DPIXELMATCH_BUILD_TESTS=ON
+        cmake --build build
+        ctest --test-dir build --output-on-failure

.gitignore

@@ -17,3 +17,29 @@ coverage-report
 # The Bzlmod lockfile is platform-dependent with Python and thus hard
 # to keep up-to-date in CI. It still speeds up local development.
 MODULE.bazel.lock
+
+# CMake
+# Created by https://www.toptal.com/developers/gitignore/api/cmake
+# Edit at https://www.toptal.com/developers/gitignore?templates=cmake
+
+### CMake ###
+/build/
+CMakeLists.txt.user
+CMakeCache.txt
+CMakeFiles
+CMakeScripts
+Testing
+Makefile
+cmake_install.cmake
+install_manifest.txt
+compile_commands.json
+CTestTestfile.cmake
+_deps
+
+### CMake Patch ###
+CMakeUserPresets.json
+
+# External projects
+*-prefix/
+
+# End of https://www.toptal.com/developers/gitignore/api/cmake

CMakeLists.txt

@@ -0,0 +1,50 @@
+cmake_minimum_required(VERSION 3.16)
+project(pixelmatch-cpp17 LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+option(PIXELMATCH_BUILD_TESTS "Enable building tests" OFF)
+
+# stb libraries for tests and image_utils. Not used in pixelmatch-cpp17 itself.
+add_library(pixelmatch_third_party_stb_image STATIC third_party/stb/stb_image.cpp)
+target_include_directories(pixelmatch_third_party_stb_image PUBLIC third_party)
+target_compile_options(pixelmatch_third_party_stb_image PRIVATE -Wno-unused-function -Wno-self-assign)
+
+add_library(pixelmatch_third_party_stb_image_write STATIC third_party/stb/stb_image_write.cpp)
+target_include_directories(pixelmatch_third_party_stb_image_write PUBLIC third_party)
+target_compile_options(pixelmatch_third_party_stb_image_write PRIVATE -Wno-unused-function -Wno-self-assign)
+
+# Main library
+add_library(pixelmatch-cpp17 src/pixelmatch/pixelmatch.cc)
+target_include_directories(pixelmatch-cpp17 PUBLIC src)
+
+# image_utils helper library (uses stb to load and save images)
+add_library(image_utils src/pixelmatch/image_utils.cc)
+target_include_directories(image_utils PUBLIC src)
+target_link_libraries(image_utils PUBLIC pixelmatch-cpp17 pixelmatch_third_party_stb_image pixelmatch_third_party_stb_image_write)
+
+if(PIXELMATCH_BUILD_TESTS)
+include(FetchContent)
+FetchContent_Declare(
+  googletest
+  URL https://github.com/google/googletest/archive/refs/tags/v1.14.0.zip
+)
+set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+FetchContent_MakeAvailable(googletest)
+
+enable_testing()
+add_library(test_base INTERFACE)
+target_link_libraries(test_base INTERFACE GTest::gtest_main GTest::gmock_main m)
+
+add_executable(pixelmatch_tests tests/pixelmatch_tests.cc)
+target_link_libraries(pixelmatch_tests PRIVATE test_base pixelmatch-cpp17 image_utils)
+add_test(NAME pixelmatch_tests COMMAND pixelmatch_tests)
+set_tests_properties(pixelmatch_tests PROPERTIES WORKING_DIRECTORY ${CMAKE_SOURCE_DIR})
+
+add_executable(image_utils_tests tests/image_utils_tests.cc)
+target_link_libraries(image_utils_tests PRIVATE test_base image_utils)
+add_test(NAME image_utils_tests COMMAND image_utils_tests)
+set_tests_properties(image_utils_tests PROPERTIES WORKING_DIRECTORY ${CMAKE_SOURCE_DIR})
+
+endif() # PIXELMATCH_BUILD_TESTS

README.md

@@ -73,28 +73,58 @@ git_override(
 )
 ```
 
-#### Adding the dependency
+### CMake
 
-Then add a dependency on `@pixelmatch-cpp17`:
-```py
-cc_test(
-    name = "my_test",
-    # ...
-    data = glob([
-      "testdata/*.png",
-    ]),
-    deps = [
-        "@pixelmatch-cpp17",
-        # ...
-    ],
+To take a dependency on `pixelmatch-cpp17` with `FetchContent`, add the following
+to your project's `CMakeLists.txt`:
+
+```cmake
+include(FetchContent)
+FetchContent_Declare(
+  pixelmatch-cpp17
+  GIT_REPOSITORY https://github.com/jwmcglynn/pixelmatch-cpp17.git
+  GIT_TAG <commit or tag>
 )
+FetchContent_MakeAvailable(pixelmatch-cpp17)
+
+target_link_libraries(your_target PRIVATE pixelmatch-cpp17)
 ```
 
+#### Running the tests
+
+
+This repository also provides CMake build files.  A typical workflow is:
+
+```sh
+cmake -S . -B build -DPIXELMATCH_BUILD_TESTS=ON
+cmake --build build
+ctest --test-dir build
+```
+
+### Calling from C++
+
 In your test file, include pixelmatch with:
 ```cpp
 #include <pixelmatch/pixelmatch.h>
 ```
 
+Then, you can use the `pixelmatch::pixelmatch` function.
+
+```cpp
+// Pass an options struct to configure the comparison. If not specified, defaults will be used.
+pixelmatch::Options options;
+options.threshold = 0.1f;
+
+// Load two images as RGBA-encoded byte arrays. The images must have the same dimensions and stride.
+const std::vector<uint8_t> img1 = ...;
+const std::vector<uint8_t> img2 = ...;
+// Output image will be saved in this buffer.
+std::vector<uint8_t> diffImage(img1.size());
+
+// Pass the image buffers and call with the width, height, and stride of the images.
+const int numDiffPixels = pixelmatch::pixelmatch(img1, img2, diffImage, width, height, stride, options);
+```
+
 ## Projects using pixelmatch-cpp17
 
 - Python bindings: https://github.com/cubao/pybind11_pixelmatch

third_party/stb/stb_image.cpp

@@ -0,0 +1,2 @@
+#define STB_IMAGE_IMPLEMENTATION
+#include "stb_image.h"

third_party/stb/stb_image_write.cpp

@@ -0,0 +1,2 @@
+#define STB_IMAGE_WRITE_IMPLEMENTATION
+#include "stb_image_write.h"