[CMake] Export a Config.cmake and Version.cmake package information.

CMakeLists.txt

@@ -1,4 +1,4 @@
-# Copyright 2016-2021 Arm Limited. All rights reserved.
+# Copyright 2016-2021,2024 Arm Limited. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -18,6 +18,10 @@ cmake_minimum_required (VERSION 3.5.1)
 
 set(CMAKE_CXX_STANDARD 14)
 
+set(TTU_package_name "TarmacTraceUtilities")
+set(TTU_targets_export_name "${TTU_package_name}Targets")
+set(TTU_version 0.0.0)
+
 project(tarmac-trace-utilities
   LANGUAGES CXX)
 
@@ -160,3 +164,38 @@ if(can_run_tests)
 else()
   message(WARNING "Not running tests (failed to locate Python 3)")
 endif()
+
+# Provide downstream users a package configuration information so they can
+# include, build and use our tarmac-trace-utilities with minimal fuss --- if
+# they work with CMake. The package information can be used with CMake's
+# find_package command.
+set(TTU_config_file "${TTU_package_name}Config.cmake"
+    CACHE STRING "Name of the CMake package config file")
+set(TTU_version_file "${TTU_package_name}ConfigVersion.cmake"
+    CACHE STRING "Name of the CMake package version file")
+set(TTU_generated_dir "${CMAKE_CURRENT_BINARY_DIR}/lib/cmake/${TTU_package_name}"
+    CACHE PATH "Directory where the CMake package information will be generated")
+set(TTU_install_dir "${CMAKE_INSTALL_LIBDIR}/cmake/${TTU_package_name}"
+    CACHE PATH "Directory where the CMake package information will be installed")
+
+include(CMakePackageConfigHelpers)
+write_basic_package_version_file(
+  ${TTU_generated_dir}/${TTU_version_file}
+  VERSION ${TTU_version}
+  COMPATIBILITY AnyNewerVersion)
+install(EXPORT
+    ${TTU_targets_export_name}
+  COMPONENT "${PROJECT_NAME}"
+  NAMESPACE "${TTU_package_name}::"
+  DESTINATION ${TTU_install_dir}
+  EXPORT_LINK_INTERFACE_LIBRARIES)
+configure_package_config_file(
+  ${CMAKE_CURRENT_SOURCE_DIR}/cmake/${TTU_config_file}.in
+  ${TTU_generated_dir}/${TTU_config_file}
+  INSTALL_DESTINATION ${TTU_install_dir})
+install(
+  FILES
+    ${TTU_generated_dir}/${TTU_config_file}
+    ${TTU_generated_dir}/${TTU_version_file}
+  COMPONENT "${PROJECT_NAME}"
+  DESTINATION ${TTU_install_dir})

browser/CMakeLists.txt

@@ -26,6 +26,7 @@ if(CURSES_FOUND)
   target_include_directories(tarmac-browser PRIVATE ${CURSES_INCLUDE_DIRS})
   target_link_libraries(tarmac-browser ${CURSES_LIBRARIES})
   install(TARGETS tarmac-browser
+    EXPORT ${TTU_targets_export_name}
     RUNTIME)
 else()
   message(WARNING "Not building tarmac-browser (failed to locate curses)")
@@ -41,6 +42,7 @@ if (${wxWidgets_FOUND})
       LINK_FLAGS /subsystem:windows)
   endif()
   install(TARGETS tarmac-gui-browser
+    EXPORT ${TTU_targets_export_name}
     RUNTIME)
 else()
   message(WARNING "Not building tarmac-gui-browser (failed to locate wxWidgets)")

cmake/TarmacTraceUtilitiesConfig.cmake.in

@@ -0,0 +1,22 @@
+# Copyright 2024 Arm Limited. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# This file is part of Tarmac Trace Utilities
+
+@PACKAGE_INIT@
+
+set(@TTU_package_name@_HAS_LIBINTL @HAVE_LIBINTL@)
+
+include("${CMAKE_CURRENT_LIST_DIR}/@TTU_targets_export_name@.cmake")
+check_required_components("@PROJECT_NAME@")

cmake/windows.cmake

@@ -1,4 +1,4 @@
-# Copyright 2016-2021 Arm Limited. All rights reserved.
+# Copyright 2016-2021,2024 Arm Limited. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -77,3 +77,12 @@ int main(void) { (void)FOLDERID_AppDataProgramData; }
 # convert them into Windows translation resources.
 find_package(Gettext)
 set(HAVE_LIBINTL 0)
+
+# On Windows, we don't include GNUInstallDirs, but we still want to
+# install things into 'include' and 'lib' subdirectories of the
+# install directory. So we define some of the same variables that
+# GNUInstallDirs would have defined.
+set(CMAKE_INSTALL_LIBDIR "lib"
+  CACHE STR "Subdirectory of the install dir to put the libtarmac library.")
+set(CMAKE_INSTALL_INCLUDEDIR "include"
+  CACHE STR "Subdirectory of the install dir to put the libtarmac headers.")

doc/index.rst

@@ -1,5 +1,5 @@
 ..
-  Copyright 2016-2021,2023 Arm Limited. All rights reserved.
+  Copyright 2016-2021,2023,2024 Arm Limited. All rights reserved.
 
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
@@ -1825,6 +1825,46 @@ the trace output) to a region of memory:
 All the other semihosting calls require no special handling, because
 they only *read* the memory of the Arm CPU, rather than writing it.
 
+Using Arm Tarmac Trace Utilities in your own project
+====================================================
+
+If your own downstream project is using CMake, it is extremely easy to use
+the Arm Tarmac Trace Utilities as it takes advantage of CMake to export 
+package information. This information can be used thanks to CMake's
+``find_package``. Linking against the ``tarmac`` library (from the
+``TarmacTraceUtilities`` namespace) will set the proper search path as well
+for the include files when compiling the programs.
+
+The downstream project only needs the following two steps with CMake
+to use and enjoy Arm's Tarmac trace utilities:
+
+* Fetch, configure, build and install Arm's Tarmac trace utilities:
+
+  .. code-block:: none
+
+    ...
+    include(ExternalProject)
+    ExternalProject_Add(tarmac-trace-utilities
+      GIT_REPOSITORY "https://github.com/ARM-software/tarmac-trace-utilities"
+      GIT_TAG "59d93f724cb836062602612300ac0f609a4753ee")
+    ...
+
+* Use the package configuration information with ``find_package``:
+
+  .. code-block:: none
+
+    ...
+    set(TarmacTraceUtilities_DIR "${CMAKE_BINARY_DIR}/lib/cmake/TarmacTraceUtilities"
+        CACHE PATH "Path to the tarmac-trace-utilities package configuration files")
+    find_package(TarmacTraceUtilities REQUIRED
+      CONFIG
+      NO_DEFAULT_PATH
+      NO_PACKAGE_ROOT_PATH
+      NO_SYSTEM_ENVIRONMENT_PATH
+      )
+    ...
+    target_link_libraries(myprogram TarmacTraceUtilities::tarmac)
+
 Translations
 ============
 

lib/CMakeLists.txt

@@ -27,10 +27,6 @@ add_library(tarmac
   image.cpp index.cpp index_ds.cpp misc.cpp parser.cpp registers.cpp
   tarmacutil.cpp ${platform_sources})
 
-if(HAVE_LIBINTL)
-  target_include_directories(tarmac PRIVATE ${Intl_INCLUDE_DIRS})
-endif()
-
 set(LIBTARMAC_HEADERS
   "${CMAKE_BINARY_DIR}/include/libtarmac/platform.hh"
   "${CMAKE_BINARY_DIR}/include/libtarmac/cmake.h")
@@ -40,9 +36,18 @@ foreach(H argparse.hh callinfo.hh calltree.hh disktree.hh elf.hh expr.hh
     list(APPEND LIBTARMAC_HEADERS ${CMAKE_SOURCE_DIR}/include/libtarmac/${H})
 endforeach()
 set_target_properties(tarmac PROPERTIES PUBLIC_HEADER "${LIBTARMAC_HEADERS}")
-target_include_directories(tarmac PUBLIC ${CMAKE_SOURCE_DIR}/include ${CMAKE_BINARY_DIR}/include)
+target_compile_features(tarmac PUBLIC cxx_std_14)
+target_include_directories(tarmac
+  PUBLIC
+  "$<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/include;${CMAKE_BINARY_DIR}/include;$<${HAVE_LIBINTL}:${Intl_INCLUDE_DIRS}>>"
+  INTERFACE
+  "$<INSTALL_INTERFACE:$<INSTALL_PREFIX>/${CMAKE_INSTALL_INCLUDEDIR}>")
+if(HAVE_LIBINTL)
+  target_link_libraries(tarmac PUBLIC ${Intl_LIBRARIES})
+endif()
 
 install(TARGETS tarmac
-  LIBRARY DESTINATION lib
-  ARCHIVE DESTINATION lib
+  EXPORT ${TTU_targets_export_name}
+  LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+  ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
   PUBLIC_HEADER DESTINATION include/libtarmac)

tests/CMakeLists.txt

@@ -1,4 +1,4 @@
-# Copyright 2016-2021,2023 Arm Limited. All rights reserved.
+# Copyright 2016-2021,2023,2024 Arm Limited. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -232,3 +232,43 @@ add_test(NAME format
       --compare reffile:${CMAKE_CURRENT_SOURCE_DIR}/formattest.ref stdout
       ${CMAKE_BINARY_DIR}/formattest
   )
+
+# Test that TTU can be exported and subsequently imported in a CMake project.
+# This is slightly involved because we first need to configure/build/install
+# a snapshot of the *current* tarmac-trace-utilities checkout outside of the
+# current build tree (in order not to mess it up) and use the just installed
+# libraries in a sample application (ttu-import) that we build to ensure the
+# build just worked and that the sample application runs fine.
+set(TTU_IMPORT_CMAKE_ARGS
+  -G ${CMAKE_GENERATOR}
+  -DCMAKE_CXX_COMPILER:PATH=${CMAKE_CXX_COMPILER}
+  -DCMAKE_BUILD_TYPE:STRING=${CMAKE_BUILD_TYPE}
+  -DCMAKE_INSTALL_PREFIX:PATH=${CMAKE_CURRENT_BINARY_DIR}/ttu-import
+  -DTTU_SOURCE_DIR:PATH=${CMAKE_CURRENT_LIST_DIR}/../..
+  -DUSE_LIBINTL:BOOL=${USE_LIBINTL})
+if(DEFINED CMAKE_EXPORT_COMPILE_COMMANDS)
+  set(TTU_IMPORT_CMAKE_ARGS ${TTU_IMPORT_CMAKE_ARGS} -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=${CMAKE_EXPORT_COMPILE_COMMANDS})
+endif()
+
+add_test(NAME ttu-import-clean-dir
+  COMMAND ${CMAKE_COMMAND} -E remove_directory ${CMAKE_CURRENT_BINARY_DIR}/ttu-import
+  )
+
+add_test(NAME ttu-import-configure
+  COMMAND ${CMAKE_COMMAND} -G ${CMAKE_GENERATOR} -S ${CMAKE_CURRENT_SOURCE_DIR}/ttu-import -B ${CMAKE_CURRENT_BINARY_DIR}/ttu-import ${TTU_IMPORT_CMAKE_ARGS}
+  )
+
+add_test(NAME ttu-import-build
+  COMMAND ${CMAKE_COMMAND} --build ${CMAKE_CURRENT_BINARY_DIR}/ttu-import
+  )
+
+add_test(NAME ttu-import
+  COMMAND ${test_driver_cmd}
+      --compare reffile:${CMAKE_CURRENT_SOURCE_DIR}/ttu-import.ref stdout
+      ${CMAKE_CURRENT_BINARY_DIR}/ttu-import/ttu-import --hello
+  )
+
+# Enforce test ordering (but does not take into account test success or failure).
+set_tests_properties(ttu-import-configure PROPERTIES DEPENDS ttu-import-clean-dir)
+set_tests_properties(ttu-import-build PROPERTIES DEPENDS ttu-import-configure)
+set_tests_properties(ttu-import PROPERTIES DEPENDS ttu-import-build)

tests/ttu-import.ref

@@ -0,0 +1 @@
+Hello from ttu-import !

tests/ttu-import/CMakeLists.txt

@@ -0,0 +1,60 @@
+# Copyright 2024 Arm Limited. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# This file is part of Tarmac Trace Utilities
+
+# The purpose of this CMakeLists.txt is to configure, build and install
+# (at this CMakeLists.txt configuration time) the current working tree
+# of tarmac-trace-utilities, and then build a smaple application using
+# the headers and libraries we just installed.
+
+cmake_minimum_required (VERSION 3.5.1)
+
+project(ttu-import LANGUAGES CXX)
+
+option(USE_LIBINTL "Enable i18n" OFF)
+
+# 
+set(TTU_CMAKE_ARGS
+  -G ${CMAKE_GENERATOR}
+  -DCMAKE_CXX_COMPILER:PATH=${CMAKE_CXX_COMPILER}
+  -DCMAKE_BUILD_TYPE:STRING=${CMAKE_BUILD_TYPE}
+  -DCMAKE_INSTALL_PREFIX:PATH=${CMAKE_BINARY_DIR}
+  -DTTU_SOURCE_DIR:PATH=${CMAKE_CURRENT_LIST_DIR}/../..
+  -DUSE_LIBINTL:BOOL=${USE_LIBINTL})
+if(DEFINED CMAKE_EXPORT_COMPILE_COMMANDS)
+  set(TTU_CMAKE_ARGS ${TTU_CMAKE_ARGS} -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=${CMAKE_EXPORT_COMPILE_COMMANDS})
+endif()
+
+execute_process(
+  COMMAND ${CMAKE_COMMAND} -S ${CMAKE_SOURCE_DIR}/export-ttu -B ${CMAKE_BINARY_DIR}/ttu ${TTU_CMAKE_ARGS} 
+)
+execute_process(
+  COMMAND ${CMAKE_COMMAND} --build ${CMAKE_BINARY_DIR}/ttu
+)
+execute_process(
+  COMMAND ${CMAKE_COMMAND} --install ${CMAKE_BINARY_DIR}/ttu
+)
+
+set(TarmacTraceUtilities_DIR "${CMAKE_BINARY_DIR}/lib/cmake/TarmacTraceUtilities"
+    CACHE PATH "Path to the tarmac-trace-utilities package configuration files")
+find_package(TarmacTraceUtilities REQUIRED
+  CONFIG
+  NO_DEFAULT_PATH
+  NO_PACKAGE_ROOT_PATH
+  NO_SYSTEM_ENVIRONMENT_PATH
+)
+
+add_executable(ttu-import ttu-import.cpp)
+target_link_libraries(ttu-import TarmacTraceUtilities::tarmac)

tests/ttu-import/export-ttu/CMakeLists.txt

@@ -0,0 +1,45 @@
+# Copyright 2024 Arm Limited. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# This file is part of Tarmac Trace Utilities
+
+# The purpose of this CMakeLists.txt is to configure, build and install the
+# tarmac-trace-utilities, as if it was an external dependency, like a
+# downstream project would do. Real users of the tarmac-trace-utilities would
+# fetch the sources from our github repository whereas for test purposes we
+# use the local checkout we already have.
+
+cmake_minimum_required (VERSION 3.5.1)
+
+project(export-ttu LANGUAGES CXX)
+
+option(USE_LIBINTL "Enable i18n" OFF)
+
+set(TTU_CMAKE_ARGS
+  -G ${CMAKE_GENERATOR}
+  -DCMAKE_CXX_COMPILER:PATH=${CMAKE_CXX_COMPILER}
+  -DCMAKE_BUILD_TYPE:STRING=${CMAKE_BUILD_TYPE}
+  -DCMAKE_INSTALL_PREFIX:PATH=${CMAKE_INSTALL_PREFIX}
+  -DUSE_LIBINTL:BOOL=${USE_LIBINTL})
+if(DEFINED CMAKE_EXPORT_COMPILE_COMMANDS)
+  set(TTU_CMAKE_ARGS ${TTU_CMAKE_ARGS} -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=${CMAKE_EXPORT_COMPILE_COMMANDS})
+endif()
+
+include(ExternalProject)
+
+ExternalProject_Add(tarmac-trace-utilities
+  PREFIX "external"
+  SOURCE_DIR ${TTU_SOURCE_DIR}
+  CMAKE_ARGS ${TTU_CMAKE_ARGS}
+)