summaryrefslogtreecommitdiff
path: root/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst')
-rw-r--r--Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst36
1 files changed, 36 insertions, 0 deletions
diff --git a/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst b/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst
new file mode 100644
index 000000000..ba5f3a8c7
--- /dev/null
+++ b/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst
@@ -0,0 +1,36 @@
+CMAKE_FIND_PACKAGE_SORT_ORDER
+-----------------------------
+
+The default order for sorting packages found using :command:`find_package`.
+It can assume one of the following values:
+
+``NONE``
+ Default. No attempt is done to sort packages.
+ The first valid package found will be selected.
+
+``NAME``
+ Sort packages lexicographically before selecting one.
+
+``NATURAL``
+ Sort packages using natural order (see ``strverscmp(3)`` manual),
+ i.e. such that contiguous digits are compared as whole numbers.
+
+Natural sorting can be employed to return the highest version when multiple
+versions of the same library are found by :command:`find_package`. For
+example suppose that the following libraries have been found:
+
+* libX-1.1.0
+* libX-1.2.9
+* libX-1.2.10
+
+By setting ``NATURAL`` order we can select the one with the highest
+version number ``libX-1.2.10``.
+
+.. code-block:: cmake
+
+ set(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
+ find_package(libX CONFIG)
+
+The sort direction can be controlled using the
+:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION` variable
+(by default decrescent, e.g. lib-B will be tested before lib-A).