build: clean up and document CMake file

Issue #471

.github/workflows/code_style.yml

@@ -16,6 +16,8 @@ jobs:
       run: |
         sudo apt-get -y install indent
         sudo ln -s /usr/bin/indent /usr/bin/gindent
+        python -m pip install --upgrade pip
+        pip install gersemi
 
     - name: Make indent
       run: |

CMakeLists.txt

@@ -1,159 +1,213 @@
-#  :copyright: (c) 2017 Alex Huszagh.
+#  :copyright: 2014-2025. John McNamara, Alex Huszagh.
-#  :license: FreeBSD, see LICENSE.txt for more details.
+#  :license: SPDX-License-Identifier: BSD-2-Clause
 
-# Description
+# CMake file for libxlsxwriter
-# ===========
+# ============================
 #
-#   Use:
+# To build libxlsxwriter with CMake move to a custom directory, ideally outside
-#       Move to a custom directory, ideally out of source, and
+# the root of the source tree, and type `cmake $LXW_SOURCE_LOCATION $FLAGS`,
-#       type `cmake $LXW_SOURCE $FLAGS`, where `LXW_SOURCE` is the
+# where `LXW_SOURCE_LOCATION` is the path to the libxlsxwriter project, and
-#       path to the libxlsxwriter project, and `FLAGS` are custom
+# `FLAGS` are custom flags to pass to the compiler.
-#       flags to pass to the compiler.
+#
+# For example, in the project directory, you can build libxlsxwriter as follows:
+#
+# ```
+#     mkdir build
+#     cd build
+#
+#     cmake .. -DCMAKE_BUILD_TYPE=Release
+#     cmake --build . --config Release
+#
+# ```
+#
+# Or to build and run the tests (this can take several minutes):
+#
+# ```
+#     mkdir build
+#     cd build
 #
-#   Example:
-#       For example, in the project directory, to build libxlsxwriter
-#       and the unittests in release mode, type:
-#           mkdir build && cd build
 #     cmake .. -DBUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Release
 #     cmake --build . --config Release
 #     ctest -C Release -V
 #     cmake --build . --config Release --target install
+# ```
 #
-#       If using a Makefile generator, you may use the simpler
+# If the tests run successfully, you can install the library as follows:
-#           mkdir build && cd build
-#           cmake .. -DBUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Release
-#           make
-#           make test
-#           make install
 #
-#   Flags:
+# ```
-#       ZLIB_ROOT
+#     cmake --build . --config Release --target install
-#           The ZLIB root directory can be specified either through
+# ```
-#           an environment variable (`export ZLIB_ROOT=/usr/include`)
-#           or using a flag with CMake (`-DZLIB_ROOT:STRING=/usr/include`).
-#           This sets the preferred search path for the ZLIB installation.
-#
-#       BUILD_TESTS
-#           Build unittests (default off). To build the unittests,
-#           pass `-DBUILD_TESTS=ON` during configuration.
-#
-#       BUILD_EXAMPLES
-#           Build example files (default off). To build the examples,
-#           pass `-DBUILD_EXAMPLES=ON` during configuration.
-#
-#       BUILD_FUZZERS
-#           Build fuzz harnesses (default off). To build the harnesses,
-#           pass `-DBUILD_FUZZERS=ON` during configuration.
-#
-#       USE_STANDARD_TMPFILE
-#           Use the standard tmpfile() function (default off). To enable
-#           the standard tmpfile, pass `-DUSE_STANDARD_TMPFILE=ON`
-#           during configuration. This may produce bugs while cross-
-#           compiling or using MinGW/MSYS.
-#
-#       USE_DTOA_LIBRARY
-#           Use the third party emyg_dtoa() library (default off). The
-#           emyg_dtoa() library is used to avoid sprintf double issues with
-#           different locale settings. To enable this library, pass
-#           `-DUSE_DTOA_LIBRARY=ON` during configuration.
-#
-#       USE_NO_MD5
-#           Compile without third party MD5 support. This will turn off the
-#           functionality of avoiding duplicate image files in the output xlsx
-#           file. To enable this option pass `-DUSE_NO_MD5=ON` during
-#           configuration.
-#
-#       USE_OPENSSL_MD5 Compile with OpenSSL MD5 support. This will link
-#           against libcrypto for MD5 support rather than using the local MD5
-#           support. MD5 support is required to avoid duplicate image files in
-#           the output xlsx file. To enable this option pass
-#           `-DUSE_OPENSSL_MD5=ON` during configuration.
-#
-#       USE_STATIC_MSVC_RUNTIME
-#           Use the static msvc runtime library when compiling with msvc (default off)
-#           To enable, pass `-DUSE_STATIC_MSVC_RUNTIME` during configuration.
-#
-#   Toolchains:
-#       On multiarch Linux systems, which can build and run multiple
-#       binary targets on the same system, we include an `i686-toolchain`
-#       file to enable building i686 (x86 32-bit) targets on x86_64 systems.
-#       To use the i686 toolchain, pass the `-DCMAKE_TOOLCHAIN_FILE` option
-#       during CMake configuration. For example, from the build directory,
-#       you would use:
-#           cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/i686-toolchain.cmake
-#
-#   CMake Options:
-#       CMake sets debug and release builds with the `CMAKE_BUILD_TYPE`
-#       option, which can be set as a flag during configuration.
-#       To build in release mode, pass `-DCMAKE_BUILD_TYPE=Release`
-#       during configuration.
-#
-#       CMake sets the creation of static and shared libraries with the
-#       `BUILD_SHARED_LIBS` option, which can be set as a flag during
-#       configuration. To build a static library, pass
-#       `-DBUILD_SHARED_LIBS=OFF` during configuration.
-#
-#   Generators:
-#       CMake also supports custom build generators, such as MakeFiles,
-#       Ninja, Visual Studio, and XCode. For example, to generate
-#       a Visual Studio solution, configure with:
-#           cmake .. -G "Visual Studio 14 2015 Win64"
-#
-#       For more information on using generators, see:
-#           https://cmake.org/cmake/help/v3.0/manual/cmake-generators.7.html
 #
+# The libxlsxwriter CMake options are shown below.
 
-set(CMAKE_LEGACY_CYGWIN_WIN32 1)
+# ---------------------
-if(MSVC)
+# Project configuration
-    cmake_minimum_required(VERSION 3.4)
+# ---------------------
-else()
+cmake_minimum_required(VERSION 3.16)
-    cmake_minimum_required(VERSION 3.1)
+
-endif()
+set(XLSX_PROJECT_NAME
+    "xlsxwriter"
+    CACHE STRING
+    "Libxlsxwriter is a C library for creating new Excel XLSX files"
+)
 
-SET(XLSX_PROJECT_NAME "xlsxwriter" CACHE STRING "Optional project and binary name")
 set(CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS ON)
 project(${XLSX_PROJECT_NAME} C)
 enable_testing()
 
-# POLICY
+# -------------------
-# ------
+# Compilation options
+# -------------------
 
-# The use of the word ZLIB_ROOT should still work prior to "3.12.0",
+# `USE_SYSTEM_MINIZIP`
-# just it's been generalized for all packages now. Just set the policy
+#
-# to new, so we use it, and it will be used prior to 3.12 anyway.
+# Libxlsxwriter uses the `minizip` component of `zlib`to create the xlsx zip
-if(${CMAKE_VERSION} VERSION_GREATER "3.12" OR ${CMAKE_VERSION} VERSION_EQUAL "3.12")
+# file container. The vendored source files for `minizip` are included in the
-    cmake_policy(SET CMP0074 NEW)
+# src tree of libxlsxwriter and are statically linked by default.
+#
+# You can use this option if you have the `minizip` library already installed on
+# your system and prefer to dynamically link against it.
+#
+# To enable this option pass `-DUSE_SYSTEM_MINIZIP=ON` during configuration.
+option(
+    USE_SYSTEM_MINIZIP
+    "Use system minizip library instead of the vendored copy"
+    OFF
+)
+
+# `USE_STANDARD_TMPFILE`
+#
+# Uses the standard library `tmpfile` function to handle temp files instead of
+# the vendored `tmpfileplus` function. Turning this off eliminates a dependency.
+# This option is not recommended for Windows as it doesn't support a
+# configurable location and the default location may be in a privileged
+# directory.
+#
+# To enable this option pass `-DUSE_STANDARD_TMPFILE=ON` during configuration.
+option(
+    USE_STANDARD_TMPFILE
+    "Use the C standard library tmpfile() instead of tmpfileplus"
+    OFF
+)
+
+# `USE_OPENSSL_MD5`
+#
+# Uses OpenSSL to provide a MD5 digest of image files in order to avoid storing
+# duplicates instead of the vendored OpenWall MD5 functions. This will link
+# against libcrypto for MD5 support rather than using the local MD5 support.
+#
+# To enable this option pass `-DUSE_OPENSSL_MD5=ON` during configuration.
+option(
+    USE_OPENSSL_MD5
+    "Build libxlsxwriter with the OpenSSL MD5 support instead of built in version"
+    OFF
+)
+
+# `USE_NO_MD5`
+#
+# Compile without third party MD5 support. This will turn off the functionality
+# of avoiding duplicate image files in the output xlsx file. This can reduce the
+# executable size slightly if you aren't using images.
+#
+# To enable this option pass `-DUSE_NO_MD5=ON` during configuration.
+option(
+    USE_NO_MD5
+    "Build libxlsxwriter without MD5 support for eliminating duplicate images"
+    OFF
+)
+
+# `USE_DTOA_LIBRARY`
+#
+# Use the third party Milo Yip DTOA library to handle string formatting of
+# doubles. This is used to avoid issues with double formatting in different
+# locales and gives better performance with numeric data.
+#
+# To enable this library, pass `-DUSE_DTOA_LIBRARY=ON` during configuration.
+option(
+    USE_DTOA_LIBRARY
+    "Use the Milo Yip DTOA library to handle string formatting of doubles."
+    OFF
+)
+
+# `USE_MEM_FILE`
+#
+# Use in memory files instead of temp files using the
+# `fmemopen()`/`open_memstream()` functions. This option isn't available with
+# MSVC.
+#
+# To enable this option pass `-DUSE_MEM_FILE=ON` during configuration.
+if(NOT MSVC)
+    option(
+        USE_MEM_FILE
+        "Use fmemopen()/open_memstream() in place of temporary files"
+        OFF
+    )
 endif()
 
-# OPTIONS
+# `BUILD_TESTS`
-# -------
+#
-SET(ZLIB_ROOT "" CACHE STRING "Optional root for the ZLIB installation")
+# Compile the unit and function tests for libxlsxwriter. This functional tests
+# require the Python pytest library. The tests can be run with `ctest` after
+# compilation. The uint tests do not work with MSVC and are turned off for that
+# platform. Note, the tests can take a while to compile and run.
+#
+# To enable this option pass `-DBUILD_TESTS=ON` during configuration.
+option(
+    BUILD_TESTS
+    "Build the libxlsxwriter unit and functional tests (requires pytest)"
+    OFF
+)
 
-option(BUILD_TESTS "Build libxlsxwriter tests" OFF)
+# TODO LXW_TARGET_BIG_ENDIAN
+
+# `BUILD_EXAMPLES`
+#
+# Compile the libxlsxwriter example programs.
+#
+# To enable this option pass `-DBUILD_EXAMPLES=ON` during configuration.
 option(BUILD_EXAMPLES "Build libxlsxwriter examples" OFF)
-option(BUILD_FUZZERS "Build harness(es) for fuzzing" OFF)
-option(USE_SYSTEM_MINIZIP "Use system minizip installation" OFF)
-option(USE_STANDARD_TMPFILE "Use the C standard library's tmpfile()" OFF)
-option(USE_NO_MD5 "Build libxlsxwriter without third party MD5 lib" OFF)
-option(USE_OPENSSL_MD5 "Build libxlsxwriter with the OpenSSL MD5 lib" OFF)
-option(USE_MEM_FILE "Use fmemopen()/open_memstream() in place of temporary files" OFF)
-option(IOAPI_NO_64 "Disable 64-bit filesystem support" OFF)
-option(USE_DTOA_LIBRARY "Use the locale independent third party Milo Yip DTOA library" OFF)
 
+# `BUILD_FUZZERS`
+#
+# Compile the fuzzer harnesses.
+#
+# To enable this option pass `-DBUILD_FUZZERS=ON` during configuration.
+option(BUILD_FUZZERS "Build harness(es) for fuzzing" OFF)
+
+# `IOAPI_NO_64`
+#
+# Turn off `IOAPI_NO_64` support in minizip ioapi.c.
+#
+# To enable this option pass `-DIOAPI_NO_64=ON` during configuration.
+option(IOAPI_NO_64 "Disable 64-bit filesystem support with minizip" OFF)
+
+# `USE_STATIC_MSVC_RUNTIME`
+#
+# Compile as a static library with the static MSVC runtime library.
+#
+# To enable this option pass `-DUSE_STATIC_MSVC_RUNTIME=ON` during configuration.
 if(MSVC)
     option(USE_STATIC_MSVC_RUNTIME "Use the static runtime library" OFF)
 endif()
 
+# `ZLIB_ROOT`
+#
+# The `ZLIB `root directory can be specified either through an environment
+# variable (`export ZLIB_ROOT=/usr/include`) or using a flag with CMake
+# (`-DZLIB_ROOT:STRING=/usr/include`). This sets the preferred search path for
+# the ZLIB installation.
+set(ZLIB_ROOT "" CACHE STRING "Optional root for the ZLIB installation")
 if(DEFINED ENV{ZLIB_ROOT})
     set(ZLIB_ROOT $ENV{ZLIB_ROOT})
 endif()
 
-if(IOAPI_NO_64)
+# -------------------------
-    list(APPEND LXW_PRIVATE_COMPILE_DEFINITIONS IOAPI_NO_64=1)
+# Configure the compilation
+# -------------------------
+if(NOT MSVC)
+    find_package(PkgConfig)
 endif()
 
-# CONFIGURATIONS
-# --------------
 if(USE_SYSTEM_MINIZIP)
     list(APPEND LXW_PRIVATE_COMPILE_DEFINITIONS USE_SYSTEM_MINIZIP)
 endif()
@@ -181,38 +235,52 @@ if(USE_DTOA_LIBRARY)
     list(APPEND LXW_PRIVATE_COMPILE_DEFINITIONS USE_DTOA_LIBRARY)
 endif()
 
+if(IOAPI_NO_64)
+    list(APPEND LXW_PRIVATE_COMPILE_DEFINITIONS IOAPI_NO_64=1)
+endif()
+
 if(NOT BUILD_SHARED_LIBS)
     if(UNIX)
         set(CMAKE_POSITION_INDEPENDENT_CODE ON)
     elseif(MINGW OR MSYS)
-        set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -static -static-libgcc -Wno-char-subscripts -Wno-long-long")
+        set(CMAKE_C_FLAGS
+            "${CMAKE_C_FLAGS} -static -static-libgcc -Wno-char-subscripts -Wno-long-long"
+        )
         list(APPEND LXW_PRIVATE_COMPILE_DEFINITIONS USE_FILE32API)
     elseif(MSVC)
-        set(CMAKE_C_FLAGS_DEBUG "${CMAKE_C_FLAGS_DEBUG} /Fd\"${CMAKE_BINARY_DIR}/${PROJECT_NAME}.pdb\"")
+        set(CMAKE_C_FLAGS_DEBUG
-        set(CMAKE_C_FLAGS_RELEASE "${CMAKE_C_FLAGS_RELEASE} /Ox /Zi /Fd\"${CMAKE_BINARY_DIR}/${PROJECT_NAME}.pdb\"")
+            "${CMAKE_C_FLAGS_DEBUG} /Fd\"${CMAKE_BINARY_DIR}/${PROJECT_NAME}.pdb\""
-        set(CMAKE_C_FLAGS_MINSIZEREL "${CMAKE_C_FLAGS_MINSIZEREL} /Zi /Fd\"${CMAKE_BINARY_DIR}/${PROJECT_NAME}.pdb\"")
+        )
-        set(CMAKE_C_FLAGS_RELWITHDEBINFO "${CMAKE_C_FLAGS_RELWITHDEBINFO} /Fd\"${CMAKE_BINARY_DIR}/${PROJECT_NAME}.pdb\"")
+        set(CMAKE_C_FLAGS_RELEASE
+            "${CMAKE_C_FLAGS_RELEASE} /Ox /Zi /Fd\"${CMAKE_BINARY_DIR}/${PROJECT_NAME}.pdb\""
+        )
+        set(CMAKE_C_FLAGS_MINSIZEREL
+            "${CMAKE_C_FLAGS_MINSIZEREL} /Zi /Fd\"${CMAKE_BINARY_DIR}/${PROJECT_NAME}.pdb\""
+        )
+        set(CMAKE_C_FLAGS_RELWITHDEBINFO
+            "${CMAKE_C_FLAGS_RELWITHDEBINFO} /Fd\"${CMAKE_BINARY_DIR}/${PROJECT_NAME}.pdb\""
+        )
     endif()
 endif()
 
 if(MSVC AND USE_STATIC_MSVC_RUNTIME)
-    foreach(flag_var CMAKE_C_FLAGS
+    foreach(
+        flag_var
+        CMAKE_C_FLAGS
         CMAKE_C_FLAGS_DEBUG
         CMAKE_C_FLAGS_RELEASE
         CMAKE_C_FLAGS_MINSIZEREL
-                     CMAKE_C_FLAGS_RELWITHDEBINFO)
+        CMAKE_C_FLAGS_RELWITHDEBINFO
+    )
         if(${flag_var} MATCHES "/MD")
             string(REPLACE "/MD" "/MT" ${flag_var} "${${flag_var}}")
         endif()
     endforeach()
 endif()
 
-if(NOT MSVC)
+# -----------------------------
-    find_package(PkgConfig)
+# Create the xlsxwriter.pc file
-endif()
+# -----------------------------
-
-# Set some variables for the xlsxwriter.pc file and the .so version.
-# ------------------------------------------------------------------
 set(PREFIX ${CMAKE_INSTALL_PREFIX})
 
 file(READ "include/xlsxwriter.h" ver)
@@ -232,13 +300,13 @@ endif()
 # Expand out the xlsxwriter.pc file.
 configure_file(dev/release/pkg-config.txt xlsxwriter.pc @ONLY)
 
-
+# ----------------
-# INCLUDES
+# Set the includes
-# --------
+# ----------------
 enable_language(CXX)
 list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake)
 
-# ZLIB
+# Set the zlib includes.
 if(PKG_CONFIG_FOUND)
     pkg_check_modules(ZLIB zlib)
     list(APPEND LXW_PRIVATE_INCLUDE_DIRS ${ZLIB_INCLUDE_DIRS})
@@ -246,10 +314,9 @@ endif()
 if(NOT ZLIB_FOUND)
     find_package(ZLIB "1.0" REQUIRED)
     list(APPEND LXW_PRIVATE_INCLUDE_DIRS ${ZLIB_INCLUDE_DIRS})
-    message("zlib version: " ${ZLIB_VERSION})
 endif()
 
-# MINIZIP
+# Set the minizip includes.
 if(USE_SYSTEM_MINIZIP)
     if(PKG_CONFIG_FOUND)
         pkg_check_modules(MINIZIP minizip)
@@ -261,37 +328,57 @@ if(USE_SYSTEM_MINIZIP)
     endif()
 endif()
 
-# LIBRARY
+# Set the openssl includes.
-# -------
+if(USE_OPENSSL_MD5)
+    if(PKG_CONFIG_FOUND)
+        pkg_check_modules(LIBCRYPTO libcrypto)
+        include_directories(${LIBCRYPTO_INCLUDE_DIRS})
+    else()
+        find_package(OpenSSL REQUIRED)
+        include_directories(${OPENSSL_INCLUDE_DIR})
+    endif()
+endif()
+
+# ----------------------------
+# Set the library dependencies
+# ----------------------------
 list(APPEND LXW_PRIVATE_COMPILE_DEFINITIONS NOCRYPT NOUNCRYPT)
 
-# Ensure CRT Secure warnings are disabled
+# Ensure CRT Secure warnings are disabled.
 if(MSVC)
     list(APPEND LXW_PRIVATE_COMPILE_DEFINITIONS _CRT_SECURE_NO_WARNINGS)
 endif()
 
-# Ensure "TESTING" macro is defined if building tests
+# Ensure "TESTING" macro is defined if building tests.
 if(BUILD_TESTS)
     list(APPEND LXW_PRIVATE_COMPILE_DEFINITIONS TESTING)
 endif()
 
-# Define "LXW_BIG_ENDIAN" macro on big-endian architectures
+# Define "LXW_BIG_ENDIAN" macro on big-endian architectures.
 include(TestBigEndian)
-TEST_BIG_ENDIAN(LXW_TARGET_BIG_ENDIAN)
+test_big_endian(LXW_TARGET_BIG_ENDIAN)
 if(LXW_TARGET_BIG_ENDIAN)
     list(APPEND LXW_PRIVATE_COMPILE_DEFINITIONS LXW_BIG_ENDIAN)
 endif()
 
+# Set the source files.
 file(GLOB LXW_SOURCES src/*.c)
 file(GLOB_RECURSE LXW_HEADERS RELATIVE include *.h)
 
+# If not using the system minizip, add the vendored minizip source files.
 if(NOT USE_SYSTEM_MINIZIP)
-    list(APPEND LXW_SOURCES third_party/minizip/ioapi.c third_party/minizip/zip.c)
+    list(
+        APPEND
+        LXW_SOURCES
+        third_party/minizip/ioapi.c
+        third_party/minizip/zip.c
+    )
     if(MSVC)
         list(APPEND LXW_SOURCES third_party/minizip/iowin32.c)
     endif()
 endif()
 
+# If not using the system tmpfile, add the vendored tmpfileplus files.
 if(NOT USE_STANDARD_TMPFILE)
     list(APPEND LXW_SOURCES third_party/tmpfileplus/tmpfileplus.c)
 endif()
@@ -300,30 +387,17 @@ if(NOT USE_OPENSSL_MD5 AND NOT USE_NO_MD5)
     list(APPEND LXW_SOURCES third_party/md5/md5.c)
 endif()
 
-if(USE_OPENSSL_MD5)
-    if(PKG_CONFIG_FOUND)
-        pkg_check_modules(LIBCRYPTO libcrypto)
-        include_directories(${LIBCRYPTO_INCLUDE_DIRS})
-    else()
-        find_package(OpenSSL REQUIRED)
-        include_directories(${OPENSSL_INCLUDE_DIR})
-        message(STATUS "OpenSSL version: ${OPENSSL_VERSION}")
-    endif()
-endif()
-
 if(USE_DTOA_LIBRARY)
     list(APPEND LXW_SOURCES third_party/dtoa/emyg_dtoa.c)
 endif()
 
+# Set project metadata.
 set(LXW_PROJECT_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
 set(LXW_LIB_DIR "${LXW_PROJECT_DIR}/lib")
 add_library(${PROJECT_NAME} "")
-
 set_target_properties(${PROJECT_NAME} PROPERTIES SOVERSION ${SOVERSION})
-target_sources(${PROJECT_NAME}
+target_sources(${PROJECT_NAME} PRIVATE ${LXW_SOURCES} PUBLIC ${LXW_HEADERS})
-    PRIVATE ${LXW_SOURCES}
+
-    PUBLIC ${LXW_HEADERS}
-)
 if(ZLIB_LDFLAGS)
     target_link_libraries(${PROJECT_NAME} LINK_PUBLIC ${ZLIB_LDFLAGS})
 else()
@@ -337,47 +411,53 @@ endif()
 if(LIBCRYPTO_LDFLAGS)
     target_link_libraries(${PROJECT_NAME} LINK_PUBLIC ${LIBCRYPTO_LDFLAGS})
 else()
-    target_link_libraries(${PROJECT_NAME} LINK_PUBLIC ${LIB_CRYPTO} ${OPENSSL_CRYPTO_LIBRARY})
+    target_link_libraries(
+        ${PROJECT_NAME}
+        LINK_PUBLIC ${LIB_CRYPTO} ${OPENSSL_CRYPTO_LIBRARY}
+    )
 endif()
-target_compile_definitions(${PROJECT_NAME} PRIVATE ${LXW_PRIVATE_COMPILE_DEFINITIONS})
 
-# /utf-8 needs VS2015 Update 2 or above.
+target_compile_definitions(
-# In CMake 3.7 and above, we can use (MSVC_VERSION GREATER_EQUAL 1900) here.
+    ${PROJECT_NAME}
-if(MSVC AND NOT (MSVC_VERSION LESS 1900))
+    PRIVATE ${LXW_PRIVATE_COMPILE_DEFINITIONS}
+)
+
+# Ensure MSVC supports /utf-8.
+if(MSVC AND MSVC_VERSION GREATER_EQUAL 1900)
     target_compile_options(${PROJECT_NAME} PRIVATE /utf-8)
 endif()
 
 if(WINDOWSSTORE)
-  target_compile_definitions(${PROJECT_NAME} PRIVATE -DIOWIN32_USING_WINRT_API)
+    target_compile_definitions(
+        ${PROJECT_NAME}
+        PRIVATE -DIOWIN32_USING_WINRT_API
+    )
 endif()
 
-target_include_directories(${PROJECT_NAME}
+target_include_directories(
+    ${PROJECT_NAME}
     PRIVATE ${LXW_PRIVATE_INCLUDE_DIRS}
     PUBLIC include include/xlsxwriter
 )
 
-# TESTS
+# ------------------------
-# -----
+# Set up and run the tests
+# ------------------------
 
-# Create test and runner.
+# Macro for handling unit tests.
-#
+macro(create_test sources target)
-# Args:
-#   sources       Name of variable holding source files
-#   target        Test name
-#
-
-macro(CreateTest sources target)
     set(output_name xlsxwriter_${target})
     set(dependencies ${output_name})
 
     add_executable(${output_name} ${${sources}})
     target_link_libraries(${output_name} ${PROJECT_NAME})
     target_compile_definitions(${output_name} PRIVATE TESTING COLOR_OK)
-    add_test(NAME ${output_name}
+    add_test(
+        NAME ${output_name}
         COMMAND ${output_name}
         WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
     )
-endmacro(CreateTest)
+endmacro(create_test)
 
 file(GLOB LXW_UTILITY_SOURCES test/unit/utility/test*.c)
 file(GLOB LXW_XMLWRITER_SOURCES test/unit/xmlwriter/test*.c)
@@ -415,21 +495,21 @@ set(LXW_UNIT_SOURCES
         ${LXW_CUSTOM_SOURCES}
     )
 else()
-set(LXW_UNIT_SOURCES
+    set(LXW_UNIT_SOURCES test/cpp/test_compilation.cpp)
-    test/cpp/test_compilation.cpp
-)
 endif()
 
 if(BUILD_TESTS)
-    # unit tests
+    # Unit tests.
-    CreateTest(LXW_UNIT_SOURCES unit)
+    create_test(LXW_UNIT_SOURCES unit)
 
-    # functional tests
+    # Functional tests.
     find_package(Python COMPONENTS Interpreter REQUIRED)
     find_program(Pytest_EXECUTABLE NAMES pytest)
 
     if(NOT Pytest_EXECUTABLE)
-        message("Please install the Python pytest library to run functional tests:")
+        message(
+            "Please install the Python pytest library to run the functional tests:"
+        )
         message("    pip install pytest\n")
     endif()
 
@@ -437,29 +517,39 @@ if(BUILD_TESTS)
         get_filename_component(basename ${source} NAME_WE)
         add_executable(${basename} ${source})
         target_link_libraries(${basename} xlsxwriter)
-       set_target_properties(${basename} PROPERTIES RUNTIME_OUTPUT_DIRECTORY "test/functional/src")
+        set_target_properties(
+            ${basename}
+            PROPERTIES RUNTIME_OUTPUT_DIRECTORY "test/functional/src"
+        )
     endforeach(source)
 
-    add_custom_command(TARGET xlsxwriter_unit POST_BUILD
+    add_custom_command(
-        COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_SOURCE_DIR}/test/functional test/functional
+        TARGET xlsxwriter_unit
+        POST_BUILD
+        COMMAND
+            ${CMAKE_COMMAND} -E copy_directory
+            ${CMAKE_SOURCE_DIR}/test/functional test/functional
     )
 
     if(USE_NO_MD5)
-        add_test(NAME functional
+        add_test(
+            NAME functional
             COMMAND pytest -v test/functional -m "not skipif"
             WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
         )
     else()
-        add_test(NAME functional
+        add_test(
+            NAME functional
             COMMAND pytest -v test/functional
             WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
         )
     endif()
-
 endif()
 
-# EXAMPLES
+# ------------------------------------
-# --------
+# Compile and run the example programs
+# ------------------------------------
+
 file(GLOB LXW_EXAMPLE_SOURCES examples/*.c)
 
 if(BUILD_EXAMPLES)
@@ -467,28 +557,41 @@ if(BUILD_EXAMPLES)
         get_filename_component(basename ${source} NAME_WE)
         add_executable(${basename} ${source})
         target_link_libraries(${basename} ${PROJECT_NAME})
-        set_target_properties(${basename} PROPERTIES RUNTIME_OUTPUT_DIRECTORY "examples")
+        set_target_properties(
+            ${basename}
+            PROPERTIES RUNTIME_OUTPUT_DIRECTORY "examples"
+        )
     endforeach(source)
 endif()
 
-# FUZZING
+# -----------------
-# -------
+# Fuzzing harnesses
+# -----------------
 if(BUILD_FUZZERS AND DEFINED ENV{LIB_FUZZING_ENGINE})
     add_subdirectory(dev/fuzzing)
 endif()
 
-# INSTALL
+# -------------------
-# -------
+# Install the library
+# -------------------
 include(GNUInstallDirs)
 
-install(TARGETS ${PROJECT_NAME}
+install(
+    TARGETS ${PROJECT_NAME}
     LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
     ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
     RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
 )
+
 install(FILES include/xlsxwriter.h DESTINATION include)
-install(DIRECTORY include/xlsxwriter
+
+install(
+    DIRECTORY include/xlsxwriter
     DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
-    FILES_MATCHING PATTERN "*.h"
+    FILES_MATCHING
+    PATTERN "*.h"
+)
+install(
+    FILES ${CMAKE_CURRENT_BINARY_DIR}/xlsxwriter.pc
+    DESTINATION ${CMAKE_INSTALL_LIBDIR}/pkgconfig
 )
-install(FILES ${CMAKE_CURRENT_BINARY_DIR}/xlsxwriter.pc DESTINATION ${CMAKE_INSTALL_LIBDIR}/pkgconfig)

Makefile

@@ -148,6 +148,7 @@ test_compile :
 # Indent the source files with the .indent.pro settings.
 indent:
 	$(Q)gindent src/*.c include/*.h include/xlsxwriter/*.h
+	$(Q)gersemi --no-warn-about-unknown-commands -i CMakeLists.txt
 
 tags:
 	$(Q)rm -f TAGS