This marks all `<PACKAGENAME>_FOUND` result variables as deprecated
where possible (for `<PackageName>` find modules) to make it clearer
which variable to use.
In CMake 3.3, the FindPackageHandleStandardArgs module was refactored to
set both `<PackageName>_FOUND` and uppercase `<PACKAGENAME>_FOUND`
result variables to the same values. Before that, the FOUND_VAR argument
could be used to set the result variable.
* FindMatlab: Uppercased MATLAB_FOUND is not mentioned as it was never
documented.
* Documentation for FindPythonInterp and FindPythonLibs modules synced
accordingly to their deprecation (3.12 instead of 4.2).
* OPENGL_FOUND: deprecation version synced with other find modules.
* DevIL_FOUND was introduced in CMake 3.8. The uppercased variant not
mentioned as it was previously never documented.
Fixes: #27242
- Added intro code blocks showing how to use find modules.
- Synced modules documentation.
- Extended few examples to make the intro code blocks fit into the
modules descriptions.
- Synced some RST formatting, variables descriptions and positions.
- Removed few redundant internal comments.
Issue: #26555
- Refactored components section.
- Module documentation synced with other similar find modules.
- Added examples section.
- Removed version note for VULKAN_SDK (this environment variable was
used since 3.7 when module got introduced to CMake).
- Added missing volk component.
Since commit d74210a8bd (CMP0017: Remove support for OLD behavior,
2024-11-17) we can rely on CMP0017's NEW behavior unconditionally.
Calling `include(FindPackageHandleStandardArgs)` in a builtin module
will always get the builtin `FindPackageHandleStandardArgs`.
`find_package(Vulkan REQUIRED FATAL_ERROR)` calls exist in the wild, but
`find_package` does not have a `FATAL_ERROR` option. We silently
tolerated such calls prior to commit 6e4d20921d (FindVulkan: Add
component for `shaderc_combined`, 2022-05-18, v3.24.0-rc1~111^2~5), by
treating the argument as a component and ignoring it. Restore tolerance
by removing the component and warning about it.
Fixes: #23849
The `Vulkan::Headers` target complements existing Vulkan::Vulkan target.
It is the same except it omits the Vulkan library which supports
applications that loads the Vulkan library in at runtime.
The `Vulkan::glslangValidator` target provides the glslangValidator
executable which is the tool for converting between shader languages
(GLSL, SPIR-V, etc.).
The GLSL SPIR-V compiler is part of the Vulkan SDK and may be used
by projects for compiling shaders as part of the build process.
This is not strictly required to build a Vulkan application, which
is why the variable is not part of the REQUIRED_VARs for the module.
Before Vulkan 1.0.42, the SDK would add the Bin directory to `PATH`,
which was confusing the 32-bit search on Windows. Avoid such confusion
by ignoring the `PATH` when looking for the 32-bit version.
Vulkan 1.0.42 fixed the whole problem by moving the libraries into Lib,
Lib32, so this is strictly a compatibility fix for old SDKs.
Per-source copyright/license notice headers that spell out copyright holder
names and years are hard to maintain and often out-of-date or plain wrong.
Precise contributor information is already maintained automatically by the
version control tool. Ultimately it is the receiver of a file who is
responsible for determining its licensing status, and per-source notices are
merely a convenience. Therefore it is simpler and more accurate for
each source to have a generic notice of the license name and references to
more detailed information on copyright holders and full license terms.
Our `Copyright.txt` file now contains a list of Contributors whose names
appeared source-level copyright notices. It also references version control
history for more precise information. Therefore we no longer need to spell
out the list of Contributors in each source file notice.
Replace CMake per-source copyright/license notice headers with a short
description of the license and links to `Copyright.txt` and online information
available from "https://cmake.org/licensing". The online URL also handles
cases of modules being copied out of our source into other projects, so we
can drop our notices about replacing links with full license text.
Run the `Utilities/Scripts/filter-notices.bash` script to perform the majority
of the replacements mechanically. Manually fix up shebang lines and trailing
newlines in a few files. Manually update the notices in a few files that the
script does not handle.
