[libpng16] style: Add a cmake-format config file and satisfy cmake-lint

Introduce CMake file linting, based on the cmakelang project by
Josh Bialkowski (@cheshirekow).

Fix various style issues in the CMake files:
 * Add the missing copyright header to PNGConfig.cmake.
 * Resolve a "missing docstring" warning raised by cmake-lint.
 * Rewrite all docstrings in the style of CMake's own documentation.
 * Fix whitespace inconsistencies.

References:
 * https://pypi.org/project/cmakelang
 * https://github.com/cheshirekow/cmake_format

This is a cherry-pick of commit c317fe31114d92d05d44bf98c9b559edf4656b9c
from branch 'libpng18'.

.cmake-format.yaml

@@ -0,0 +1,94 @@
+# https://pypi.org/project/cmakelang
+# https://github.com/cheshirekow/cmake_format
+
+# ----------------------
+# Options for formatting
+# ----------------------
+
+# How wide to allow formatted cmake files
+# TODO: Reflow the CMake files to allow setting the maximum line width to 100.
+line_width: 255
+
+# How many spaces to tab for indent
+tab_size: 2
+
+# If true, lines are indented using tab characters (utf-8 0x09) instead of
+# <tab_size> space characters (utf-8 0x20). In cases where the layout would
+# require a fractional tab character, the behavior of the fractional
+# indentation is governed by <fractional_tab_policy>
+use_tabchars: false
+
+# If <use_tabchars> is True, then the value of this variable indicates how
+# fractional indentions are handled during whitespace replacement. If set to
+# 'use-space', fractional indentation is left as spaces (utf-8 0x20). If set
+# to `round-up` fractional indentation is replaced with a single tab character
+# (utf-8 0x09) effectively shifting the column to the next tabstop
+fractional_tab_policy: "use-space"
+
+# Enable comment markup parsing and reflow
+enable_markup: false
+
+# -------------------
+# Options for linting
+# -------------------
+
+# Lint codes to disable
+disabled_codes: [
+  # TODO:
+  # Reconcile the CMake variable names with the patterns below, then
+  # re-enable the "invalid variable name XXX" messages.
+  "C0103",
+
+  # A custom command with one output doesn't really need a comment because
+  # the default "generating XXX" is a good message already.
+  "C0113",
+]
+
+# Regular expression pattern describing valid function names
+function_pattern: "[0-9a-z_]+"
+
+# Regular expression pattern describing valid macro names
+macro_pattern: "[0-9A-Z_]+"
+
+# Regular expression pattern describing valid names for variables with global
+# (cache) scope
+global_var_pattern: "[A-Z][0-9A-Z_]+"
+
+# Regular expression pattern describing valid names for variables with global
+# scope (but internal semantic)
+internal_var_pattern: "_[A-Z][0-9A-Z_]+"
+
+# Regular expression pattern describing valid names for variables with local
+# scope
+local_var_pattern: "[a-z][a-z0-9_]+"
+
+# Regular expression pattern describing valid names for privatedirectory
+# variables
+private_var_pattern: "_[0-9a-z_]+"
+
+# Regular expression pattern describing valid names for public directory
+# variables
+public_var_pattern: "[A-Z][0-9A-Z_]+"
+
+# Regular expression pattern describing valid names for function/macro
+# arguments and loop variables.
+argument_var_pattern: "[a-z][a-z0-9_]+"
+
+# Regular expression pattern describing valid names for keywords used in
+# functions or macros
+keyword_pattern: "[A-Z][0-9A-Z_]+"
+
+# In the heuristic for C0201, how many conditionals to match within a loop in
+# before considering the loop a parser
+max_conditionals_custom_parser: 2
+
+# Require at least this many newlines between statements
+min_statement_spacing: 1
+
+# Require no more than this many newlines between statements
+max_statement_spacing: 2
+max_returns: 6
+max_branches: 12
+max_arguments: 5
+max_localvars: 15
+max_statements: 50

CMakeLists.txt

@@ -116,7 +116,9 @@ endif()
 
 find_package(ZLIB REQUIRED)
 
-if(UNIX AND NOT APPLE AND NOT BEOS AND NOT HAIKU AND NOT EMSCRIPTEN)
+if(UNIX
+   AND NOT (APPLE OR BEOS OR HAIKU)
+   AND NOT EMSCRIPTEN)
   find_library(M_LIBRARY m)
   if(M_LIBRARY)
     set(M_LIBRARY m)
@@ -310,7 +312,7 @@ endif()
 endif(PNG_HARDWARE_OPTIMIZATIONS)
 
 option(ld-version-script "Enable linker version script" ON)
-if(ld-version-script AND NOT ANDROID AND NOT APPLE)
+if(ld-version-script AND NOT (ANDROID OR APPLE))
   # Check if LD supports linker scripts.
   file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/conftest.map" "
 VERS_1 { global: sym1; local: *; };
@@ -356,7 +358,7 @@ else()
   message(STATUS "Could not find an AWK-compatible program")
 endif()
 
-if(NOT AWK OR ANDROID OR IOS)
+if(NOT AWK OR (ANDROID OR IOS))
   # No awk available to generate sources; use pre-built pnglibconf.h
   configure_file(${CMAKE_CURRENT_SOURCE_DIR}/scripts/pnglibconf.h.prebuilt
                  ${CMAKE_CURRENT_BINARY_DIR}/pnglibconf.h)
@@ -377,7 +379,7 @@ else()
                  NEWLINE_STYLE LF)
 
   # Generate .chk from .out with awk:
-  # generate_chk(INPUT inputfile OUTPUT outputfile [DEPENDS dep1 [dep2...]])
+  # generate_chk(INPUT <file> OUTPUT <file> [DEPENDS <deps>...])
   function(generate_chk)
     set(options)
     set(oneValueArgs INPUT OUTPUT)
@@ -399,8 +401,8 @@ else()
                        WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}")
   endfunction()
 
-  # Generate .out from .c with awk
+  # Generate .out from .c with awk:
-  # generate_out(INPUT inputfile OUTPUT outputfile [DEPENDS dep1 [dep2...]])
+  # generate_out(INPUT <file> OUTPUT <file> [DEPENDS <deps>...])
   function(generate_out)
     set(options)
     set(oneValueArgs INPUT OUTPUT)
@@ -422,8 +424,8 @@ else()
                        WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}")
   endfunction()
 
-  # Generate specific source file with awk
+  # Generate specific source file with awk:
-  # generate_source(OUTPUT outputfile [DEPENDS dep1 [dep2...]])
+  # generate_source(OUTPUT <file> [DEPENDS <deps>...])
   function(generate_source)
     set(options)
     set(oneValueArgs OUTPUT)
@@ -441,8 +443,8 @@ else()
                        WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}")
   endfunction()
 
-  # Copy file
+  # Copy file:
-  # generate_copy(INPUT inputfile OUTPUT outputfile [DEPENDS dep1 [dep2...]])
+  # generate_copy(INPUT <file> OUTPUT <file> [DEPENDS <deps>...])
   function(generate_copy)
     set(options)
     set(oneValueArgs INPUT OUTPUT)
@@ -584,7 +586,7 @@ else()
                             "${CMAKE_CURRENT_BINARY_DIR}/scripts/symbols.chk" png_scripts_symbols_chk
                             "${CMAKE_CURRENT_BINARY_DIR}/scripts/symbols.out" png_scripts_symbols_out
                             "${CMAKE_CURRENT_BINARY_DIR}/scripts/vers.out" png_scripts_vers_out)
-endif(NOT AWK OR ANDROID OR IOS)
+endif(NOT AWK OR (ANDROID OR IOS))
 
 # List the source code files.
 set(libpng_public_hdrs
@@ -598,7 +600,7 @@ set(libpng_private_hdrs
     pnginfo.h
     pngstruct.h
 )
-if(AWK AND NOT ANDROID AND NOT IOS)
+if(AWK AND NOT (ANDROID OR IOS))
   list(APPEND libpng_private_hdrs "${CMAKE_CURRENT_BINARY_DIR}/pngprefix.h")
 endif()
 set(libpng_sources
@@ -769,6 +771,8 @@ endif()
 if(PNG_TESTS AND PNG_SHARED)
   enable_testing()
 
+  # Add a custom target to run a test:
+  # png_add_test(NAME <test> COMMAND <command> [OPTIONS <options>...] [FILES <files>...])
   function(png_add_test)
     set(options)
     set(oneValueArgs NAME COMMAND)
@@ -966,8 +970,9 @@ if(PNG_SHARED AND PNG_TOOLS)
   list(APPEND PNG_BIN_TARGETS png-fix-itxt)
 endif()
 
-# Create a symlink from src to dest (if possible), or, alternatively,
+# Create a symlink that points to a target file (if symlinking is possible),
-# copy src to dest if different.
+# or make a copy of the target file (if symlinking is not possible):
+# create_symlink(<destfile> [FILE <file> | TARGET <target>])
 function(create_symlink DEST_FILE)
   cmake_parse_arguments(_SYM "" "FILE;TARGET" "" ${ARGN})
   if(NOT _SYM_FILE AND NOT _SYM_TARGET)

scripts/cmake/PNGConfig.cmake

@@ -1,3 +1,16 @@
+# PNGConfig.cmake
+# CMake config file compatible with the FindPNG module.
+
+# Copyright (c) 2024 Cosmin Truta
+# Written by Benjamin Buch, 2024
+#
+# Use, modification and distribution are subject to
+# the same licensing terms and conditions as libpng.
+# Please see the copyright notice in png.h or visit
+# http://libpng.org/pub/png/src/libpng-LICENSE.txt
+#
+# SPDX-License-Identifier: libpng-2.0
+
 include(CMakeFindDependencyMacro)
 
 find_dependency(ZLIB REQUIRED)