CMake: How can I add a search path for include() from the environment? - cmake

Question

I try to create a collection of CMake scripts that are supposed to provide some useful macros and functions for our group of developers and all the projects we're working on. These scripts should be rolled out to all development machines (Win10 & Centos Linux) and the top-level CMakeLists.txt of the projects can include this collection.
From what I read from the CMake docs, include() is what should be used to import these scripts. But, of course, CMake doesn't know about the location on the file system. The documentation points to CMAKE_MODULE_PATH, but I couldn't figure out a way to set it from "outside" on a global scope, e.g. an environment variable or a CMake configuration value. Setting it from within a project's CMake file would drop portability, as especially on Windows users potentially could choose the install directory of the scripts.
I also don't want to deploy the script collection into CMake's installation directory. Although it would work, it feels dirty to mix up my own scripts with the ones from the CMake distribution.
I could use find_package() instead and also provide a package config file and use the CMAKE_PREFIX_PATH environment variable. But from my understanding of the docu this is meant to be for build dependencies, e.g. libraries.
I also found questions similar to mine here and in other places, but they usually were about importing external projects for building the own one ( -> find_package()). And, of course, about include directories for the compilation process. If I just didn't found the proper question & answer, please point me there.
So, what is the best/proper way to make CMake aware of my script collection? Preferably in a way that just a call to include() is required in a project's CMakeLists.txt.

Answer 1

but I couldn't figure out a way to set it from "outside" on a global scope, e.g. an environment variable or a CMake configuration value.
Just cmake -D CMAKE_MODULE_PATH=/some/path. Works for me:
$ cd /tmp; echo "include(ulumulu)" > CMakeLists.txt ; strace -e trace=file cmake -D CMAKE_MODULE_PATH=/some/path . |& grep access | grep ulumulu
access("/some/path/ulumulu.cmake", R_OK) = -1 ENOENT (No such file or directory)
access("/usr/share/cmake-3.19/Modules/ulumulu.cmake", R_OK) = -1 ENOENT (No such file or directory)
access("/tmp/ulumulu", R_OK) = -1 ENOENT (No such file or directory)
How can I add a search path for include() from the environment?
I would setup my own logic. As simplest as include($ENV{SEARCH_IN_THIS_PATH}), but way better would be with cmake -D PATH_TO_MY_LIBRARY=some_path and then include(${PATH_TO_MY_LIBRARY}).
I could use find_package() instead and also provide a package config file and use the CMAKE_PREFIX_PATH environment variable. But from my understanding of the docu this is meant to be for build dependencies, e.g. libraries.
And module mode find_package( ... MODULE) is for finding modules. I would use it. And I would use it also not for libraries.
what is the best/proper way to make CMake aware of my script collection?
Install your script at /usr/share/cmake/ path on linux and I think c:/Program Files/CMake/share/cmake on windows (I have no experience in windows) and use find_package(the_library MODULE).
If not, I recommend just use find_package anyway and install your Find*.cmake file to <prefix>/<name>/cmake/.