From ed46adb6cf31a117dc987deb9d094dcdbf022659 Mon Sep 17 00:00:00 2001 From: Peter Kokot Date: Sun, 6 Apr 2025 01:02:36 +0200 Subject: [PATCH] FindICU: Update documentation - Added examples section. - Added some basic descriptions to components. - Variables described as done in other similar find modules. --- Modules/FindICU.cmake | 197 ++++++++++++++++++++++++++++++------------ 1 file changed, 142 insertions(+), 55 deletions(-) diff --git a/Modules/FindICU.cmake b/Modules/FindICU.cmake index a7b05692aa..942a0ae6ab 100644 --- a/Modules/FindICU.cmake +++ b/Modules/FindICU.cmake @@ -7,82 +7,169 @@ FindICU .. versionadded:: 3.7 -Find the International Components for Unicode (ICU) libraries and -programs. - -This module supports multiple components. -Components can include any of: ``data``, ``i18n``, ``io``, ``le``, -``lx``, ``test``, ``tu`` and ``uc``. - -Note that on Windows ``data`` is named ``dt`` and ``i18n`` is named -``in``; any of the names may be used, and the appropriate -platform-specific library name will be automatically selected. +Finds the International Components for Unicode (ICU) libraries and programs. .. versionadded:: 3.11 - Added support for static libraries on Windows. + Support for static libraries on Windows. -This module reports information about the ICU installation in -several variables. General variables:: +Components +^^^^^^^^^^ - ICU_FOUND - true if the main programs and libraries were found - ICU_INCLUDE_DIRS - the directories containing the ICU headers - ICU_LIBRARIES - component libraries to be linked - ICU_VERSION - ICU release version +This module supports the following components: -Imported targets:: +``data`` + Finds the ICU Data library. On Windows, this library component is named + ``dt``, otherwise any of these component names may be used, and the + appropriate platform-specific library name will be automatically selected. - ICU:: +``i18n`` + Finds the ICU Internationalization library. On Windows, this library + component is named ``in``, otherwise any of these component names may be used, + and the appropriate platform-specific library name will be automatically + selected. -Where ```` is the name of an ICU component, for example -``ICU::i18n``; ```` is lower-case. +``io`` + Finds the ICU Stream and I/O (Unicode stdio) library. -ICU programs are reported in:: +``le`` + Finds the deprecated ICU Layout Engine library, which has been removed as of + ICU version 58. - ICU_GENCNVAL_EXECUTABLE - path to gencnval executable - ICU_ICUINFO_EXECUTABLE - path to icuinfo executable - ICU_GENBRK_EXECUTABLE - path to genbrk executable - ICU_ICU-CONFIG_EXECUTABLE - path to icu-config executable - ICU_GENRB_EXECUTABLE - path to genrb executable - ICU_GENDICT_EXECUTABLE - path to gendict executable - ICU_DERB_EXECUTABLE - path to derb executable - ICU_PKGDATA_EXECUTABLE - path to pkgdata executable - ICU_UCONV_EXECUTABLE - path to uconv executable - ICU_GENCFU_EXECUTABLE - path to gencfu executable - ICU_MAKECONV_EXECUTABLE - path to makeconv executable - ICU_GENNORM2_EXECUTABLE - path to gennorm2 executable - ICU_GENCCODE_EXECUTABLE - path to genccode executable - ICU_GENSPREP_EXECUTABLE - path to gensprep executable - ICU_ICUPKG_EXECUTABLE - path to icupkg executable - ICU_GENCMN_EXECUTABLE - path to gencmn executable +``lx`` + Finds the ICU Layout Extensions Engine library, used for paragraph layout. -ICU component libraries are reported in:: +``test`` + Finds the ICU test suits. - ICU__FOUND - ON if component was found; ```` is upper-case. - ICU__LIBRARIES - libraries for component; ```` is upper-case. +``tu`` + Finds the ICU Tool Utility library. -ICU datafiles are reported in:: +``uc`` + Finds the base ICU Common and Data libraries. This library is required by + all other ICU libraries and is recommended to include when working with ICU + components. - ICU_MAKEFILE_INC - Makefile.inc - ICU_PKGDATA_INC - pkgdata.inc +At least one component should be specified for this module to successfully find +ICU: -This module reads hints about search results from:: +.. code-block:: cmake - ICU_ROOT - the root of the ICU installation + find_package(ICU COMPONENTS ...) -The environment variable ``ICU_ROOT`` may also be used; the -ICU_ROOT variable takes precedence. +Imported Targets +^^^^^^^^^^^^^^^^ -The following cache variables may also be set:: +This module provides the following :ref:`Imported Targets`: - ICU_

_EXECUTABLE - the path to executable

; ``

`` is upper-case. - ICU_INCLUDE_DIR - the directory containing the ICU headers - ICU__LIBRARY - the library for component ; ```` is upper-case. +``ICU::`` + + Target encapsulating the usage requirements for the specified ICU component, + available only if that component is found. The ```` should be + written in lowercase, as listed above. For example, use ``ICU::i18n`` for the + Internationalization library. + +Result Variables +^^^^^^^^^^^^^^^^ + +This module defines the following variables: + +``ICU_FOUND`` + Boolean indicating whether the main programs and libraries were found. +``ICU_INCLUDE_DIRS`` + The include directories containing the ICU headers. +``ICU_LIBRARIES`` + Component libraries to be linked. +``ICU_VERSION`` + The version of the ICU release found. + +ICU programs are defined in the following variables: + +``ICU_GENCNVAL_EXECUTABLE`` + The path to the ``gencnval`` executable. +``ICU_ICUINFO_EXECUTABLE`` + The path to the ``icuinfo`` executable. +``ICU_GENBRK_EXECUTABLE`` + The path to the ``genbrk`` executable. +``ICU_ICU-CONFIG_EXECUTABLE`` + The path to the ``icu-config`` executable. +``ICU_GENRB_EXECUTABLE`` + The path to the ``genrb`` executable. +``ICU_GENDICT_EXECUTABLE`` + The path to the ``gendict`` executable. +``ICU_DERB_EXECUTABLE`` + The path to the ``derb`` executable. +``ICU_PKGDATA_EXECUTABLE`` + The path to the ``pkgdata`` executable. +``ICU_UCONV_EXECUTABLE`` + The path to the ``uconv`` executable. +``ICU_GENCFU_EXECUTABLE`` + The path to the ``gencfu`` executable. +``ICU_MAKECONV_EXECUTABLE`` + The path to the ``makeconv`` executable. +``ICU_GENNORM2_EXECUTABLE`` + The path to the ``gennorm2`` executable. +``ICU_GENCCODE_EXECUTABLE`` + The path to the ``genccode`` executable. +``ICU_GENSPREP_EXECUTABLE`` + The path to the ``gensprep`` executable. +``ICU_ICUPKG_EXECUTABLE`` + The path to the ``icupkg`` executable. +``ICU_GENCMN_EXECUTABLE`` + The path to the ``gencmn`` executable. + +ICU component libraries are defined in the following variables: + +``ICU__FOUND`` + Boolean indicating whether the ICU component was found; The ```` + should be written in uppercase. +``ICU__LIBRARIES`` + Libraries for component; The ```` should be written in uppercase. + +ICU datafiles are defined in the following variables: + +``ICU_MAKEFILE_INC`` + The path to the ``Makefile.inc`` file. +``ICU_PKGDATA_INC`` + The path to the ``pkgdata.inc`` file. + +Cache Variables +^^^^^^^^^^^^^^^ + +The following cache variables may also be set: + +``ICU__EXECUTABLE`` + The path to executable ````; The ```` should be written in + uppercase. These variables correspond to the ICU program result variables + listed above. +``ICU_INCLUDE_DIR`` + The directory containing the ICU headers. +``ICU__LIBRARY`` + The library for the ICU component. The ```` should be written in + uppercase. + +Hints +^^^^^ + +This module reads hints about search results from: + +``ICU_ROOT`` + The root of the ICU installation. The environment variable ``ICU_ROOT`` may + also be used; the ``ICU_ROOT`` variable takes precedence. .. note:: - In most cases none of the above variables will require setting, - unless multiple ICU versions are available and a specific version - is required. + In most cases, none of the above variables will need to be set, unless + multiple versions of ICU are available and a specific version is required. + +Examples +^^^^^^^^ + +Finding ICU components and linking them to a project target: + +.. code-block:: cmake + + find_package(ICU COMPONENTS i18n io uc) + target_link_libraries(project_target PRIVATE ICU::i18n ICU::io ICU::uc) #]=======================================================================] cmake_policy(PUSH)