CMake option/cache prefix changes

.github/workflows/build.yml

@@ -77,7 +77,7 @@ jobs:
       working-directory: FLAMEGPU2-docs
       run: |
         source .venv/bin/activate
-        cmake . -B build -DWARNINGS_AS_ERRORS=${{ env.werror }}
+        cmake . -B build -DFLAMEGPU_DOCS_WARNINGS_AS_ERRORS=${{ env.werror }}
 
     - name: Build
       working-directory: FLAMEGPU2-docs/build

CMakeLists.txt

@@ -20,14 +20,14 @@ set(SPHINX_CONFIG_DIR "${CMAKE_CURRENT_BINARY_DIR}/src")
 # set(SPHINX_CAHCE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees")
 
 # Option to promote compilation warnings to error, useful for strict CI
-option(WARNINGS_AS_ERRORS "Promote compilation warnings to errors" OFF)
+option(FLAMEGPU_DOCS_WARNINGS_AS_ERRORS "Promote build warnings to errors" OFF)
 
 # Find graphviz which is required for the user guide (sphinx graphviz plugin)
 find_package(Graphviz REQUIRED)
 
-find_package(FLAMEGPU2)
+find_package(FLAMEGPU)
 # Build Doxygen if we can
-if(FLAMEGPU2_FOUND)
+if(FLAMEGPU_FOUND)
     # Load FLAMEGPU2s Doxygen config, implicitly calls find_package(doxygen)
     include(${FLAMEGPU_ROOT}/cmake/dependencies/doxygen.cmake)
     mark_as_advanced(FORCE BUILD_API_DOCUMENTATION)
@@ -130,10 +130,10 @@ endforeach()
 
 # Set the warnings_is_errors value if enabeld.
 set(SPHINX_WARNING_IS_ERROR_FLAG "")
-if (WARNINGS_AS_ERRORS)
+if (FLAMEGPU_DOCS_WARNINGS_AS_ERRORS)
     set(SPHINX_WARNING_IS_ERROR_FLAG "-W")
 endif()
-if(FLAMEGPU2_FOUND AND DOXYGEN_FOUND AND ${BUILD_API_DOCUMENTATION})
+if(FLAMEGPU_FOUND AND DOXYGEN_FOUND AND FLAMEGPU_BUILD_API_DOCUMENTATION)
     # Set the var used when generating conf.py to enable breathe/exhale 
     set(USE_BREATHE_EXHALE "True")
     set(EXCLUDE_API_PATTERN "") # Do not exlude the api dir
@@ -159,7 +159,7 @@ if(FLAMEGPU2_FOUND AND DOXYGEN_FOUND AND ${BUILD_API_DOCUMENTATION})
     unset(API_TOC_PATH)
 
     # Create Doxygen target 'userguide_docs_xml'
-    create_doxygen_target("${FLAMEGPU_ROOT}" "${CMAKE_CURRENT_BINARY_DIR}" "src/${API_DOCS_XML_PATH}")
+    flamegpu_create_doxygen_target("${FLAMEGPU_ROOT}" "${CMAKE_CURRENT_BINARY_DIR}" "src/${API_DOCS_XML_PATH}")
     # Create Sphinx target
     add_custom_target(userguide ALL
         COMMAND ${SPHINX_EXECUTABLE} -b html

cmake/FindFLAMEGPU2.cmake → cmake/FindFLAMEGPU.cmake

@@ -15,6 +15,6 @@ find_path(FLAMEGPU_ROOT include/flamegpu/defines.h
 include(FindPackageHandleStandardArgs)
 
 #Handle standard arguments to find_package like REQUIRED and QUIET
-find_package_handle_standard_args(FLAMEGPU2
+find_package_handle_standard_args(FLAMEGPU
                                   "Failed to find FLAMEGPU root"
                                   FLAMEGPU_ROOT)

cmake/FindGraphviz.cmake

@@ -9,4 +9,6 @@ include(FindPackageHandleStandardArgs)
 # Handle standard arguments to find_package like REQUIRED and QUIET
 find_package_handle_standard_args(Graphviz
                                   "Failed to find dot executable"
-                                  GRAPHVIZ_DOT_EXECUTABLE)
+                                  GRAPHVIZ_DOT_EXECUTABLE)
+
+mark_as_advanced(GRAPHVIZ_DOT_EXECUTABLE)

cmake/FindSphinx.cmake

@@ -8,4 +8,6 @@ include(FindPackageHandleStandardArgs)
 #Handle standard arguments to find_package like REQUIRED and QUIET
 find_package_handle_standard_args(Sphinx
                                   "Failed to find sphinx-build executable"
-                                  SPHINX_EXECUTABLE)
+                                  SPHINX_EXECUTABLE)
+
+mark_as_advanced(SPHINX_EXECUTABLE)

readme.md

@@ -63,6 +63,15 @@ You can optionally specify the location of the FLAMEGPU2 source repository:
 ```bash
 mkdir -p build && cd build
 cmake .. -DFLAMEGPU_ROOT="<absolute path to FLAMEGPU2>"
+cmake --build .
+```
+
+Building the API documentation can be disabled, to improve build times via the `FLAMEGPU_BUILD_API_DOCUMENTATION` option set to `OFF`:
+
+```bash
+mkdir -p build && cd build
+cmake .. -DFLAMEGPU_BUILD_API_DOCUMENTATION=OFF
+cmake --build .
 ```
 
 If you lack a build system, executing `windows.bat` inside the directory `cmake` provides an alternative. However, this still requires executing CMake if api documentation is required.

src/guide/agent-functions/agent-birth-death.rst

@@ -64,7 +64,7 @@ To have an agent die, simply return :enumerator:`flamegpu::DEAD<flamegpu::AGENT_
             return pyflamegpu.ALIVE
 
 
-If :enumerator:`flamegpu::DEAD<flamegpu::AGENT_STATUS::DEAD>` (``pyflamegpu.DEAD`` in Python) is returned by an agent function whilst agent death is not enabled the agent will not die. If ``SEATBELTS`` error checking is enabled an exception will be raised.
+If :enumerator:`flamegpu::DEAD<flamegpu::AGENT_STATUS::DEAD>` (``pyflamegpu.DEAD`` in Python) is returned by an agent function whilst agent death is not enabled the agent will not die. If ``FLAMEGPU_SEATBELTS`` error checking is enabled an exception will be raised.
 
 
 Agent Birth
@@ -159,14 +159,14 @@ Agent creation is always optional once enabled, a new agent will only be marked
         # Other agent function code
         ...
 
-If :class:`FLAMEGPU->agent_out<flamegpu::DeviceAPI::AgentOut>` is used in an agent function which has not had agent output enabled, no agent will be created. If ``SEATBELTS`` error checking is enabled, an exception will be raised.
+If :class:`FLAMEGPU->agent_out<flamegpu::DeviceAPI::AgentOut>` is used in an agent function which has not had agent output enabled, no agent will be created. If ``FLAMEGPU_SEATBELTS`` error checking is enabled, an exception will be raised.
 
 Related Links
 -------------
 
 * User Guide Page: :ref:`Defining Agents<Defining Agents>`
 * User Guide Page: :ref:`Agent Operations<Host Agent Operations>` (Host Functions)
-* User Guide Page: :ref:`What is SEATBELTS?<SEATBELTS>`
+* User Guide Page: :ref:`What is FLAMEGPU_SEATBELTS?<FLAMEGPU_SEATBELTS>`
 * Full API documentation for :class:`AgentFunctionDescription<flamegpu::AgentFunctionDescription>`
 * Full API documentation for :class:`AgentOut<flamegpu::DeviceAPI::AgentOut>`
 * Full API documentation for :class:`DeviceAPI<flamegpu::DeviceAPI>`

src/guide/agent-functions/agent-communication.rst

@@ -112,7 +112,7 @@ When outputting bucket messages, the bucket index for the message must be set, u
           pyflamegpu.message_out.setKey(pyflamegpu.getVariableInt("bucket"))
           return pyflamegpu.ALIVE
 
-Messages assigned keys outside of the bounds have undefined behaviour. If using ``SEATBELTS`` error checking, an exception will be raised.
+Messages assigned keys outside of the bounds have undefined behaviour. If using ``FLAMEGPU_SEATBELTS`` error checking, an exception will be raised.
 
 Spatial Messaging
 =================
@@ -155,7 +155,7 @@ If you are using :class:`MessageSpatial2D<flamegpu::MessageSpatial2D>` or :class
 Array Messaging
 ===============
 
-If you are using :class:`MessageArray<flamegpu::MessageArray>`, :class:`MessageArray2D<flamegpu::MessageArray2D>` or :class:`MessageArray3D<flamegpu::MessageArray3D>` then you must specify the corresponding array index when outputting a message. It is important that only 1 agent writes a message to each index. If ``SEATBELTS`` error-checking is enabled then multiple outputs to the same index will raise an exception.
+If you are using :class:`MessageArray<flamegpu::MessageArray>`, :class:`MessageArray2D<flamegpu::MessageArray2D>` or :class:`MessageArray3D<flamegpu::MessageArray3D>` then you must specify the corresponding array index when outputting a message. It is important that only 1 agent writes a message to each index. If ``FLAMEGPU_SEATBELTS`` error-checking is enabled then multiple outputs to the same index will raise an exception.
 
 .. tabs::
 
@@ -259,7 +259,7 @@ Bucket Messaging
 
 If you are using the Bucket messaging strategy, you will also need to supply the bucket key to access the messages from the specific bucket.
 
-If an invalid bucket key is specified (based on the bounds provided when the messagelist was defined) no messages will be returned. If ``SEATBELTS`` error checking is enabled, an exception will be raised.
+If an invalid bucket key is specified (based on the bounds provided when the messagelist was defined) no messages will be returned. If ``FLAMEGPU_SEATBELTS`` error checking is enabled, an exception will be raised.
 
 .. tabs::
 
@@ -314,7 +314,7 @@ Spatial messaging will return all messages within the radius specified at the mo
 
 .. note::
   When spatial messages will be accessed via the wrapped iterator, all messages locations must be within the environment bounds defined for the message list. Accessing out of bounds messages with the wrapped iterator is undefined behaviour. 
-  If using ``SEATBELTS`` error checking an error may be raised whilst using the wrapped iterator if an out of bounds message is read.
+  If using ``FLAMEGPU_SEATBELTS`` error checking an error may be raised whilst using the wrapped iterator if an out of bounds message is read.
 
 .. tabs::
 
@@ -645,7 +645,7 @@ Related Links
 -------------
 
 * User Guide Page: :ref:`Defining Messages (Communication)<Defining Messages>`
-* User Guide Page: :ref:`What is SEATBELTS?<SEATBELTS>`
+* User Guide Page: :ref:`What is FLAMEGPU_SEATBELTS?<FLAMEGPU_SEATBELTS>`
 * Full API documentation for :class:`MessageBruteForce::In<flamegpu::MessageBruteForce::In>` & :class:`MessageBruteForce::Out<flamegpu::MessageBruteForce::Out>`
 * Full API documentation for :class:`MessageBucket::In<flamegpu::MessageBucket::In>` & :class:`MessageBucket::Out<flamegpu::MessageBucket::Out>`
 * Full API documentation for :class:`MessageSpatial2D::In<flamegpu::MessageSpatial2D::In>` & :class:`MessageSpatial2D::Out<flamegpu::MessageSpatial2D::Out>`

src/guide/agent-functions/interacting-with-environment.rst

@@ -74,7 +74,7 @@ Environmental macro properties can be read, via the returned :class:`DeviceMacro
         # Other behaviour code
         ...
 
-They can also be updated with a selection of functions, which execute atomically. These functions will update a single variable and return information related to it's old or new state. This can be useful, for simple actions such as conflict resolution and counting. However, if a basic read is subsequently required, a separate host or agent function in a following layer must be used (otherwise there would be a race condition). If running with ``SEATBELTS`` error checking enabled, an exception should be thrown where potential race conditions are detected.
+They can also be updated with a selection of functions, which execute atomically. These functions will update a single variable and return information related to it's old or new state. This can be useful, for simple actions such as conflict resolution and counting. However, if a basic read is subsequently required, a separate host or agent function in a following layer must be used (otherwise there would be a race condition). If running with ``FLAMEGPU_SEATBELTS`` error checking enabled, an exception should be thrown where potential race conditions are detected.
 
 Macro properties support the normal :func:`+<flamegpu::DeviceMacroProperty::operator+>`, :func:`-<flamegpu::DeviceMacroProperty::operator->`, :func:`+=<flamegpu::DeviceMacroProperty::operator+=>`, :func:`-=<flamegpu::DeviceMacroProperty::operator-=>`, :func:`++<flamegpu::DeviceMacroProperty::operator++>` (only C++ supports pre and post increment), :func:`--<flamegpu::DeviceMacroProperty::operator-->` (only C++ supports pre and post decrement) operations. They also have access to a limited set of additional functions, explained in the table below.
 
@@ -151,6 +151,6 @@ Related Links
 
 * User Guide Page: :ref:`Defining Environmental Properties<defining environmental properties>`
 * User Guide Page: :ref:`Host Functions: Accessing the Environment<host environment>`
-* User Guide Page: :ref:`What is SEATBELTS?<SEATBELTS>`
+* User Guide Page: :ref:`What is FLAMEGPU_SEATBELTS?<FLAMEGPU_SEATBELTS>`
 * Full API documentation for :class:`DeviceEnvironment<flamegpu::DeviceEnvironment>`
 * Full API documentation for :class:`DeviceMacroProperty<flamegpu::DeviceMacroProperty>`

src/guide/debugging-models/seatbelts.rst

@@ -1,32 +1,32 @@
-.. _SEATBELTS:
+.. _FLAMEGPU_SEATBELTS:
 
-What is SEATBELTS?
-==================
+What is FLAMEGPU_SEATBELTS?
+===========================
 
 FLAME GPU 2, unlike FLAME GPU 1, allows models to be fully defined via a C++ API. This means that some algorithmic magic is required to map a variable's name to a memory within agent functions (CUDA device code) at runtime. In order to achieve this, whilst enabling the highest performance it becomes necessary to remove any safety checks (e.g. ensuring the variable exists, has the correct type etc).
 
-From this was born ``SEATBELTS``. Originally named ``NO_SEATBELTS`` after the racing concept of removing weight from a car to allow it to accelerate faster, in combination with the removal of safety checks which in the case of a racing car would be the seatbelts.
+From this was born ``FLAMEGPU_SEATBELTS``. Originally named ``NO_SEATBELTS`` after the racing concept of removing weight from a car to allow it to accelerate faster, in combination with the removal of safety checks which in the case of a racing car would be the seatbelts.
 
-When ``SEATBELTS`` is enabled at CMake configure time Release builds will include any error checking deemed expensive. These builds still run much faster than Debug builds, which always have ``SEATBELTS`` enabled regardless of CMAKE configuration. However, the fastest performance can only be achieved by producing a Release build with ``SEATBELTS`` disabled.
+When ``FLAMEGPU_SEATBELTS`` is enabled at CMake configure time Release builds will include any error checking deemed expensive. These builds still run much faster than Debug builds, which always have ``FLAMEGPU_SEATBELTS`` enabled regardless of CMAKE configuration. However, the fastest performance can only be achieved by producing a Release build with ``FLAMEGPU_SEATBELTS`` disabled.
 
-Most ``SEATBELTS`` checks are limited to device code within agent functions (type checking in host functions is cheap), however there are some additional expensive integrity checks (such as array message output collisions) which are limited to ``SEATBELTS`` enabled builds.
+Most ``FLAMEGPU_SEATBELTS`` checks are limited to device code within agent functions (type checking in host functions is cheap), however there are some additional expensive integrity checks (such as array message output collisions) which are limited to ``FLAMEGPU_SEATBELTS`` enabled builds.
 
 .. note::
 
-    CUDA does not support safely exiting device code early, via an exception or similar. All CUDA errors raised from device code execution are considered fatal, whereby the CUDA runtime is corrupted and data cannot be recovered from device memory. As such, in order to provide exceptions from agent functions, it is necessary for ``SEATBELTS`` to both log detail about the problem to device memory and return a sensible value (normally ``0``) in order to allow the agent function to complete without raising a CUDA error. Our testing has not found any cases where this currently fails, however it may be possible to structure code such that ``SEATBELTS`` does not prevent a CUDA error.
+    CUDA does not support safely exiting device code early, via an exception or similar. All CUDA errors raised from device code execution are considered fatal, whereby the CUDA runtime is corrupted and data cannot be recovered from device memory. As such, in order to provide exceptions from agent functions, it is necessary for ``FLAMEGPU_SEATBELTS`` to both log detail about the problem to device memory and return a sensible value (normally ``0``) in order to allow the agent function to complete without raising a CUDA error. Our testing has not found any cases where this currently fails, ho<SEATwever it may be possible to structure code such that ``FLAMEGPU_SEATBELTS`` does not prevent a CUDA error.
 
-Enabling/Disabling SEATBELTS
-----------------------------
-``SEATBELTS`` is a compile-time feature, whereby the compiler passes the C macro of the same name to all files. As such, it can only be toggled at CMake time (as mentioned above it cannot be disabled for Debug builds).
+Enabling/Disabling FLAMEGPU_SEATBELTS
+-------------------------------------
+``FLAMEGPU_SEATBELTS`` is a compile-time feature, whereby the compiler passes the C macro of the same name to all files. As such, it can only be toggled at CMake time (as mentioned above it cannot be disabled for Debug builds).
 
-By default when configuring CMake ``SEATBELTS`` is ``ON``.
+By default when configuring CMake ``FLAMEGPU_SEATBELTS`` is ``ON``.
 
-In order to disable it, for the fastest performance ``-DSEATBELTS=OFF`` must be passed to ``cmake`` at configure time. If using ``cmake-gui``, you should locate the ``SEATBELTS`` option in the central table, set it to ``OFF`` and press the ``Configure`` button followed by the ``Generate`` button.
+In order to disable it, for the fastest performance ``-DFLAMEGPU_SEATBELTS=OFF`` must be passed to ``cmake`` at configure time. If using ``cmake-gui``, you should locate the ``FLAMEGPU_SEATBELTS`` option in the central table, set it to ``OFF`` and press the ``Configure`` button followed by the ``Generate`` button.
 
 
-Understanding SEATBELTS Exceptions
-----------------------------------
-When ``SEATBELTS`` detects a problem in an agent function it will cause a :class:`DeviceError<flamegpu::exception::DeviceError>` to be raised. This error contains a message detailing the problem, for example:
+Understanding FLAMEGPU_SEATBELTS Exceptions
+-------------------------------------------
+When ``FLAMEGPU_SEATBELTS`` detects a problem in an agent function it will cause a :class:`DeviceError<flamegpu::exception::DeviceError>` to be raised. This error contains a message detailing the problem, for example:
 
 .. code-block:: none
 

src/guide/debugging-models/using-a-debugger.rst

@@ -96,7 +96,7 @@ From here follows the normal ``cuda-gdb`` workflow, such as ``start`` (start the
 
 Python
 ~~~~~~
-In order to produce a debug build of pyflamegpu, it is necessary to specify ``-DCMAKE_BUILD_TYPE=Debug`` when configuring CMake. Additionally, you should pass ``-DEXPORT_RTC_SOURCES=ON``. When compiled this should produce a binary in the ``build/bin/Debug`` directory, and the compiled RTC sources will be exported to the working directory at runtime.
+In order to produce a debug build of pyflamegpu, it is necessary to specify ``-DCMAKE_BUILD_TYPE=Debug`` when configuring CMake. Additionally, you should pass ``-DFLAMEGPU_RTC_EXPORT_SOURCES=ON``. When compiled this should produce a binary in the ``build/bin/Debug`` directory, and the compiled RTC sources will be exported to the working directory at runtime.
 
 .. note::
 

src/guide/defining-messages-communication/index.rst

@@ -167,7 +167,7 @@ Array Specialisation
 
 Array messages work similarly to an array. When an array message type is defined, it's dimensions must be specified. Agents can then output a message to a single unique element within the array.
 
-Multiple agents must not output messages to the same element, if ``SEATBELTS`` error checking is enabled this will be detected and an exception raised.
+Multiple agents must not output messages to the same element, if ``FLAMEGPU_SEATBELTS`` error checking is enabled this will be detected and an exception raised.
 
 Elements which do not have a message output will return ``0`` for all variables, similar to if an agent does not set all variables of a message it outputs.
 
@@ -207,7 +207,7 @@ Related Links
 ^^^^^^^^^^^^^
 
 * User Guide Page: :ref:`Agent Communication<Device Agent Communication>`
-* User Guide Page: :ref:`What is SEATBELTS?<SEATBELTS>`
+* User Guide Page: :ref:`What is FLAMEGPU_SEATBELTS?<FLAMEGPU_SEATBELTS>`
 * Full API documentation for :class:`MessageBruteForce::Description<flamegpu::MessageBruteForce::Description>`
 * Full API documentation for :class:`MessageBucket::Description<flamegpu::MessageBucket::Description>`
 * Full API documentation for :class:`MessageSpatial2D::Description<flamegpu::MessageSpatial2D::Description>`