diff --git a/docs/source/usage/project_integration.md b/docs/source/usage/project_integration.md index 8d3a826d4d3072d678222b53f5b49f4710f98f24..631a4123ba3e43c339ca46dec751e85926ed6893 100644 --- a/docs/source/usage/project_integration.md +++ b/docs/source/usage/project_integration.md @@ -57,25 +57,59 @@ If you are using pystencils-sfg with CMake through the provided CMake module, ### Add the module -To include the module in your CMake source tree, a separate find module is provided. -You can use the global CLI to obtain the find module; simply run +To include the module in your CMake source tree, you must first add the pystencils-sfg *Find-module* +to your CMake module path. +To create the Find-module, navigate to the directory it should be placed in and run the following command: ```shell sfg-cli cmake make-find-module ``` -to create the file `FindPystencilsSfg.cmake` in the current directory. -Add it to the CMake module path, and load the *pystencils-sfg* module via *find_package*: +This will create the `FindPystencilsSfg.cmake` file. +Make sure that its containing directory is added to the CMake module path. + +To load pystencils-sfg into CMake, we first need to set the Python interpreter +of the environment SFG is installed in. +There are several ways of doing this: + +#### Set Python via a Find-Module Hint + +Set the `PystencilsSfg_PYTHON_PATH` hint variable inside your `CMakeLists.txt` to point at the +Python executable which should be used to invoke pystencils-sfg, e.g.: ```CMake -find_package( PystencilsSfg ) +set(PystencilsSfg_PYTHON_PATH ${CMAKE_SOURCE_DIR}/.venv/bin/python) +``` + +This is the recommended way, especially when other parts of your project also use Python. + +#### Set Python via a Cache Variable + +On the command line or in a [CMake configure preset](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html), +set the `PystencilsSfg_PYTHON_INTERPRETER` cache variable to point at the Python executable to be used to invoke pystencils-sfg; +e.g.: + +```bash +cmake -S . -B build -DPystencilsSfg_PYTHON_INTERPRETER=`pwd`/.venv/bin/python ``` -Make sure to set the `Python_ROOT_DIR` cache variable to point to the correct Python interpreter -(i.e. the virtual environment you have installed *pystencils-sfg* into). +If both the cache variable and the `PystencilsSfg_PYTHON_PATH` hint are set, the cache variable takes precedence, +so you can use the cache variable to override the hint. + +#### Automatically Find a Python Installation + +If none of the above is provided, pystencils-sfg will invoke [FindPython](https://cmake.org/cmake/help/latest/module/FindPython.html) +to determine the Python interpreter it should use. +You can affect this process through any of the hints listed in the `FindPython` documentation. + +#### Find pystencils-sfg + +Finally, call `find_package( PystencilsSfg )` from your `CMakeLists.txt` to load the SFG module. +If SFG as a dependency is not optional, add the `REQUIRED` flag such that the call will fail if +the package cannot be found. (cmake_add_generator_scripts)= -### Add generator scripts +### Adding Generator Scripts The primary interaction point in CMake is the function `pystencilssfg_generate_target_sources`, with the following signature: @@ -105,15 +139,21 @@ The function takes the following options: If set, this overrides the value of `PystencilsSfg_CONFIG_MODULE` in the current scope (see [](#cmake_set_config_module)) -### Include generated files +Any C++ header files generated by the above call can be included in any files belonging to `target` via: -The `pystencils-sfg` CMake module creates a subfolder `sfg_sources/gen` at the root of the build tree -and writes all generated source files into it. The directory `sfg_sources` is added to the project's include -path, such that generated header files for a target `<target>` may be included via: ```C++ -#include "gen/<target>/kernels.h" +#include "gen/<file1.hpp>" +#include "gen/<file2.hpp>" +/* ... */ ``` +### Changing the Output Directory + +The CMake function listed above will create a subdirectory `_gen/<target>` at the current point in +the build tree (i.e. [`CMAKE_CURRENT_BINARY_DIR`](https://cmake.org/cmake/help/latest/variable/CMAKE_CURRENT_BINARY_DIR.html)). +This directory is placed on the include path of `<target>`, and the generated files will be written to `_gen/<target>/gen/` +such that they can be included with the `gen` prefix. + (cmake_set_config_module)= ### Set a Configuration Module