Add cmake build support

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,9 @@ jobs:
     - name: Test (C++20)
       run: |
         "${GITHUB_WORKSPACE}/bin/bazel" test --config=clang --config=cpp20 //...
+
+    - name: Build & Test (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

.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(stb_image STATIC third_party/stb/stb_image.cpp)
+target_include_directories(stb_image PUBLIC third_party)
+target_compile_options(stb_image PRIVATE -Wno-unused-function -Wno-self-assign)
+
+add_library(stb_image_write STATIC third_party/stb/stb_image_write.cpp)
+target_include_directories(stb_image_write PUBLIC third_party)
+target_compile_options(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 stb_image 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"