FindPNG: Create an imported PNG::PNG target (#15911)

Imported targets are now the recommended way of dealing with external
library dependencies.  Add one for FindPNG and update documentation
accordingly.  Also add a test case activated by CMake_TEST_FindPNG.

Help/release/dev/FindPNG-imported-targets.rst

@@ -0,0 +1,4 @@
+FindPNG-imported-targets
+------------------------
+
+* The :module:`FindPNG` module now provides imported targets.

Modules/FindPNG.cmake

@@ -2,13 +2,20 @@
 # FindPNG
 # -------
 #
-# Find the native PNG includes and library
+# Find libpng, the official reference library for the PNG image format.
 #
+# Imported targets
+# ^^^^^^^^^^^^^^^^
 #
+# This module defines the following :prop_tgt:`IMPORTED` target:
 #
-# This module searches libpng, the library for working with PNG images.
+# ``PNG::PNG``
+#   The libpng library, if found.
 #
-# It defines the following variables
+# Result variables
+# ^^^^^^^^^^^^^^^^
+#
+# This module will set the following variables in your project:
 #
 # ``PNG_INCLUDE_DIRS``
 #   where to find png.h, etc.
@@ -22,19 +29,22 @@
 # ``PNG_VERSION_STRING``
 #   the version of the PNG library found (since CMake 2.8.8)
 #
-# Also defined, but not for general use are
+# Obsolete variables
+# ^^^^^^^^^^^^^^^^^^
+#
+# The following variables may also be set, for backwards compatibility:
 #
 # ``PNG_LIBRARY``
 #   where to find the PNG library.
-#
-# For backward compatiblity the variable PNG_INCLUDE_DIR is also set.
-# It has the same value as PNG_INCLUDE_DIRS.
+# ``PNG_INCLUDE_DIR``
+#   where to find the PNG headers (same as PNG_INCLUDE_DIRS)
 #
 # Since PNG depends on the ZLib compression library, none of the above
 # will be defined unless ZLib can be found.
 
 #=============================================================================
 # Copyright 2002-2009 Kitware, Inc.
+# Copyright 2016 Raumfeld
 #
 # Distributed under the OSI-approved BSD License (the "License");
 # see accompanying file Copyright.txt for details.
@@ -105,6 +115,32 @@ if(ZLIB_FOUND)
         endif()
       endif ()
 
+      if(NOT TARGET PNG::PNG)
+        add_library(PNG::PNG UNKNOWN IMPORTED)
+        set_target_properties(PNG::PNG PROPERTIES
+          INTERFACE_COMPILE_DEFINITIONS "${PNG_DEFINITIONS}"
+          INTERFACE_INCLUDE_DIRECTORIES "${PNG_INCLUDE_DIRS}"
+          INTERFACE_LINK_LIBRARIES ZLIB::ZLIB)
+        if(EXISTS "${PNG_LIBRARY}")
+          set_target_properties(PNG::PNG PROPERTIES
+            IMPORTED_LINK_INTERFACE_LANGUAGES "C"
+            IMPORTED_LOCATION "${PNG_LIBRARY}")
+        endif()
+        if(EXISTS "${PNG_LIBRARY_DEBUG}")
+          set_property(TARGET PNG::PNG APPEND PROPERTY
+            IMPORTED_CONFIGURATIONS DEBUG)
+          set_target_properties(PNG::PNG PROPERTIES
+            IMPORTED_LINK_INTERFACE_LANGUAGES_DEBUG "C"
+            IMPORTED_LOCATION_DEBUG "${PNG_LIBRARY_DEBUG}")
+        endif()
+        if(EXISTS "${PNG_LIBRARY_RELEASE}")
+          set_property(TARGET PNG::PNG APPEND PROPERTY
+            IMPORTED_CONFIGURATIONS RELEASE)
+          set_target_properties(PNG::PNG PROPERTIES
+            IMPORTED_LINK_INTERFACE_LANGUAGES_RELEASE "C"
+            IMPORTED_LOCATION_RELEASE "${PNG_LIBRARY_RELEASE}")
+        endif()
+      endif()
   endif ()
 
   if (PNG_PNG_INCLUDE_DIR AND EXISTS "${PNG_PNG_INCLUDE_DIR}/png.h")

Tests/CMakeLists.txt

@@ -1375,6 +1375,10 @@ ${CMake_BINARY_DIR}/bin/cmake -DDIR=dev -P ${CMake_SOURCE_DIR}/Utilities/Release
     add_subdirectory(FindOpenSSL)
   endif()
 
+  if(CMake_TEST_FindPNG)
+    add_subdirectory(FindPNG)
+  endif()
+
   if(CMake_TEST_FindTIFF)
     add_subdirectory(FindTIFF)
   endif()

Tests/FindPNG/CMakeLists.txt

@@ -0,0 +1,10 @@
+add_test(NAME FindPNG.Test COMMAND
+  ${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>
+  --build-and-test
+  "${CMake_SOURCE_DIR}/Tests/FindPNG/Test"
+  "${CMake_BINARY_DIR}/Tests/FindPNG/Test"
+  ${build_generator_args}
+  --build-project TestFindPNG
+  --build-options ${build_options}
+  --test-command ${CMAKE_CTEST_COMMAND} -V -C $<CONFIGURATION>
+  )

Tests/FindPNG/Test/CMakeLists.txt

@@ -0,0 +1,16 @@
+cmake_minimum_required(VERSION 3.4)
+project(TestFindPNG C)
+include(CTest)
+
+find_package(PNG REQUIRED)
+
+add_definitions(-DCMAKE_EXPECTED_PNG_VERSION="${PNG_VERSION_STRING}")
+
+add_executable(test_tgt main.c)
+target_link_libraries(test_tgt PNG::PNG)
+add_test(NAME test_tgt COMMAND test_tgt)
+
+add_executable(test_var main.c)
+target_include_directories(test_var PRIVATE ${PNG_INCLUDE_DIRS})
+target_link_libraries(test_var PRIVATE ${PNG_LIBRARIES})
+add_test(NAME test_var COMMAND test_var)

Tests/FindPNG/Test/main.c

@@ -0,0 +1,20 @@
+#include <assert.h>
+#include <string.h>
+#include <png.h>
+
+int main()
+{
+  png_uint_32 png_version;
+  char png_version_string[16];
+
+  png_version = png_access_version_number ();
+
+  snprintf (png_version_string, 16, "%i.%i.%i",
+            png_version / 10000,
+            (png_version % 10000) / 100,
+            png_version % 100);
+
+  assert (strcmp(png_version_string, CMAKE_EXPECTED_PNG_VERSION) == 0);
+
+  return 0;
+}