[SOLVED] What's the right way to read the cmake package description in `Findxxx.cmake`?

Issue

When countered with unfamiliar packages, I need to read the Findxxx.cmake to figure out the pre-defined cached variable. For example, in FindBoost.cmake, the starting lines are like this:

# Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.

#[=======================================================================[.rst:
FindBoost
---------

Find Boost include dirs and libraries

Use this module by invoking :command:`find_package` with the form:

.. code-block:: cmake

  find_package(Boost
    [version] [EXACT]      # Minimum or EXACT version e.g. 1.67.0
    [REQUIRED]             # Fail with error if Boost is not found
    [COMPONENTS <libs>...] # Boost libraries by their canonical name
                           # e.g. "date_time" for "libboost_date_time"
    [OPTIONAL_COMPONENTS <libs>...]
                           # Optional Boost libraries by their canonical name)
    )                      # e.g. "date_time" for "libboost_date_time"

The description is written in .rst, but I don't know what's the right way to read it except for open it using vim.

My ideal way to read is using command line like cmake-show-module boost, then a viewer pops out. Or using vscode, hovering find_package(BOOST), then the description pops out. How can I achieve it?

Solution

CMake's Find<module> files contain their documentation in reStructuredText (rst) format. The online documentation is generated from this data and can be easily viewed with a browser, e.g. using for the FindBoost module the address https://cmake.org/cmake/help/latest/module/FindBoost.html.

To view the documentation from the command line you can use

cmake --help-module FindBoost

For other CMake find modules replace Boost with the appropriate module name, for instance Qt.

Answered By - vre

Answer Checked By - Terry (WPSolving Volunteer)