Support adding ipasir2-cpp to CMake projects via add_subdirectory()

.gitmodules

@@ -1,6 +1,6 @@
-[submodule "testdeps/ipasir2"]
-	path = testdeps/ipasir2
-	url = https://github.com/ipasir2/ipasir2
 [submodule "testdeps/Catch2"]
 	path = testdeps/Catch2
 	url = https://github.com/catchorg/Catch2
+[submodule "deps/ipasir2"]
+	path = deps/ipasir2
+	url = https://github.com/ipasir2/ipasir2

CMakeLists.txt

@@ -1,18 +1,26 @@
-# This project contains the ipasir2-cpp tests and examples. Building it is not
-# required for using ipasir2cpp.h in other software.
+# ipasir2-cpp - C++ wrapper for IPASIR-2 solvers
+#
+# In standalone builds, this project contains the ipasir2-cpp tests and examples.
+# Building it is not required for using ipasir2cpp.h in other software.
 
 cmake_minimum_required(VERSION 3.19)
-project(ipasir2-cpp-tests)
 
+if (DEFINED PROJECT_NAME)
+  # ipasir2-cpp has been added via add_subdirectory(), so just define the ipasir2cpp target:
+  add_library(ipasir2cpp INTERFACE)
+  target_include_directories(ipasir2cpp INTERFACE include deps/ipasir2)
+  return()
+endif()
+
+
+project(ipasir2-cpp-tests)
 
 option(WITH_DOXYGEN "Add a target `doxygen` building Doxygen files for ipasir2cpp.h" OFF)
 
 include(buildutils/doxygen.cmake)
 
-# ipasir2cpp.h can be used with C++17, but has extra features when used with C++20
 set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_EXTENSIONS OFF)
-
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
 set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
 set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
@@ -27,14 +35,14 @@ target_link_libraries(ipasir2cpp INTERFACE ipasir2)
 
 
 # Only basic compiler options that are used for all targets are set here. More special
-# options, for instance for sanitizers, are set on a per-target basis.
+# options, for instance for sanitizers, are set on a per-target basis. This project
+# is deliberately light on compiler options to make sure that the headers don't force
+# clients to set any.
 if (MSVC)
   add_compile_options(
-    # Keep Windows.h from #define'ing min() and max():
-    /DNOMINMAX
-
-    /permissive-
-    /W4
+    /DNOMINMAX    # Keep Windows.h from #defining min() and max()
+    /permissive-  # Be strict about C++ conformance
+    /W4           # Use highest warning level
 
     # TODO: fix size types in ipasir2.h, use size_t instead of int32_t
     # The following two warnings are related to possible loss of data when implicitly casting ints
@@ -56,6 +64,8 @@ endif()
 # In this project, ctest executes all testsuites as well as the example code
 enable_testing()
 
+add_subdirectory(deps)
 add_subdirectory(testdeps)
+
 add_subdirectory(tests)
 add_subdirectory(examples)

README.md

@@ -6,18 +6,21 @@ C++ porcelain for IPASIR-2
 **Caveat:** Like IPASIR-2, this project is work in progress. See [changelog](CHANGELOG.md).
 
 
-## How to use
+## Integrating `ipasir2-cpp`
 
-This library is header-only. An easy way for integrating this library is to add it as a Git
-submodule, and add the `include` directory to your include path. Alternatively, you can copy
-the headers into your application.
+This library is header-only. The most convenient way of using this project is to add it as
+a git submodule, and to add `include` to your include path. The headers depend on the main
+IPASIR-2 header `ipasir2.h`, which is provided in `deps/ipasir2`.
+
+In CMake projects, you can also add this project via `add_subdirectory()`, which creates a
+target `ipasir2cpp` carrying all needed include paths (`include` and `deps/ipasir2`).
 
 TODO: link latest release tag
 
 
 ## Example
 
-See the `examples` directory. The most basic one is `01_readme.cpp`:
+See the `examples` directory. `01_readme.cpp` shows how to solve a simple problem instance:
 
 ```
 namespace ip2 = ipasir2;
@@ -74,13 +77,14 @@ catch (ip2::ipasir2_error const& error) {
 
 ## Supported compilers
 
-`ipasir2cpp.h` and the tests require C++17. The code in the `examples` directory requires C++20.
+`ipasir2-cpp` requires a C++17-conformant compiler. The project is regularly tested with
+recent versions of Clang, GCC and MSVC.
 
-**TODO:** minimum compiler versions
+Building the tests and examples requires a C++20-conformant compiler.
 
 
 ## Supported platforms
 
-The platform-agnostic parts of `ipasir2-cpp` are defined in `ipasir2cpp.h`. This header contains
-all functionality except for loading solver libraries at runtime, which is implemented in
-a separate (and optional) header `ipasir2cpp_dl.h` for POSIX and Windows systems.
+`ipasir2cpp.h` is platform-independent. This header contains all functionality except
+for loading solver libraries at runtime, which is implemented in a separate (and optional)
+header `ipasir2cpp_dl.h` for POSIX and Windows systems.

deps/CMakeLists.txt

@@ -0,0 +1,6 @@
+if(NOT EXISTS ${CMAKE_CURRENT_LIST_DIR}/ipasir2/ipasir2.h)
+  message(FATAL_ERROR "git submodules have not been set up yet. Run git submodule update --init")
+endif()
+
+add_library(ipasir2 INTERFACE)
+target_include_directories(ipasir2 INTERFACE ipasir2)

examples/CMakeLists.txt

@@ -4,7 +4,7 @@ if(WIN32)
 endif()
 
 
-include(${CMAKE_CURRENT_LIST_DIR}/../testdeps/ipasir2/buildutils/load_solvers.cmake)
+include(${CMAKE_CURRENT_LIST_DIR}/../deps/ipasir2/buildutils/load_solvers.cmake)
 
 load_minisat()
 

testdeps/CMakeLists.txt

@@ -1,9 +1,5 @@
-if(NOT EXISTS ${CMAKE_CURRENT_LIST_DIR}/Catch2/CMakeLists.txt
-   OR NOT EXISTS ${CMAKE_CURRENT_LIST_DIR}/ipasir2/ipasir2.h)
+if(NOT EXISTS ${CMAKE_CURRENT_LIST_DIR}/Catch2/CMakeLists.txt)
   message(FATAL_ERROR "git submodules have not been set up yet. Run git submodule update --init")
 endif()
 
-add_library(ipasir2 INTERFACE)
-target_include_directories(ipasir2 INTERFACE ipasir2)
-
 add_subdirectory(Catch2)