### Linux Embree Installation and Setup

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/thirdparty/embree4/doc/README.md

Installs Embree on Linux by unpacking a tarball and sourcing environment variables. It recommends setting a relative RPATH for dynamic library loading.

```bash
tar xzf embree-4.4.0.x86_64.linux.tar.gz
source embree-4.4.0.x86_64.linux/embree-vars.sh
```

--------------------------------

### Implement Counter-Based Random Number Generation

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/thirdparty/random123/v1.14.0/README.md

Demonstrates how to initialize and use a Philox4x32 generator to produce random values within a loop. The example shows the setup of counter and key types required for generating non-repeating random sequences.

```cpp
#include <Random123/philox.h>

typedef r123::Philox4x32 RNG;
RNG rng;
RNG::ctr_type c={{}};
RNG::ukey_type uk={{}};
uk[0] = user_supplied_seed;
RNG::key_type k=uk;

for(...){
   c[0] = loop_var_1;
   c[1] = loop_var_2;
   RNG::ctr_type r = rng(c, k);
}
```

```c
#include <Random123/philox.h>

philox4x32_ctr_t c={{}};
philox4x32_ukey_t uk={{}};

uk.v[0] = user_supplied_seed;
philox4x32_key_t k = philox4x32keyinit(uk);

for(...){
    c.v[0] = loop_var_1;
    c.v[1] = loop_var_2;
    philox4x32_ctr_t r = philox4x32(c, k);
}
```

--------------------------------

### Install Embree using vcpkg

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/thirdparty/embree4/doc/README.md

Commands to clone the vcpkg repository, bootstrap the tool, and install the Embree dependency.

```bash
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install embree3
```

--------------------------------

### macOS Embree Installation and Setup

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/thirdparty/embree4/doc/README.md

Installs Embree on macOS by unpacking a ZIP file and sourcing environment variables. It highlights the use of relative RPATH for shipping Embree with applications.

```bash
unzip embree-4.4.0.x64.macosx.zip
source embree-4.4.0.x64.macosx/embree-vars.sh
```

--------------------------------

### CMake Installation Rules

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/star-wf/0.0/CMakeLists.txt

Defines the installation rules for the 'swf' library and its public headers. The library is installed to 'lib' and 'bin' directories, while headers are installed under 'include/star'.

```cmake
install(TARGETS swf
    LIBRARY DESTINATION lib
    ARCHIVE DESTINATION lib
    RUNTIME DESTINATION bin
)

install(FILES ${SWF_PUBLIC_HEADERS}
    DESTINATION include/star
)
```

--------------------------------

### Configure SYCL Environment on Linux

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/thirdparty/embree4/src/README.md

Initializes the DPC++ compiler environment on Linux by sourcing the startup script.

```bash
source dpcpp_compiler/startup.sh
```

--------------------------------

### Build and Run Embree Tutorials

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/thirdparty/embree4/src/README.md

Commands to configure, build, and execute Embree tutorials using CMake. The process involves creating a build directory, specifying compiler paths, and running the resulting executables.

```batch
cd minimal
mkdir build
cd build
cmake -G Ninja -D CMAKE_CXX_COMPILER=clang++ -D CMAKE_C_COMPILER=clang -D CMAKE_BUILD_TYPE=Release -D embree_DIR=%cd%\..\..\..\lib\cmake\embree-4.4.0\ -D TBB_DIR=path_to_tbb\oneapi-tbb-2021.2.0\lib\cmake\tbb ..
cmake --build .
set PATH=%cd%\..\..\..\bin;%PATH%
.\minimal.exe
.\minimal_sycl.exe
```

```bash
cd minimal
mkdir build
cd build
cmake -D CMAKE_BUILD_TYPE=Release -D CMAKE_CXX_COMPILER=clang++ -D CMAKE_C_COMPILER=clang -D embree_DIR=`pwd`/../../../lib/cmake/embree-4.4.0/ -D TBB_DIR=path_to_tbb/oneapi-tbb-2021.2.0/lib/cmake/tbb/ ..
cmake --build .
./minimal
./minimal_sycl
```

--------------------------------

### CMake Configuration for Embree Applications

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/thirdparty/embree4/doc/README.md

Demonstrates how to configure an Embree application using CMake. It shows how to find the Embree package and link against it, including setting custom paths for Embree and TBB if not installed globally.

```cmake
FIND_PACKAGE(embree 4 REQUIRED)

cmake -D embree_DIR=path_to_embree_package/lib/cmake/embree-4.4.0/ \
      -D TBB_DIR=path_to_tbb_package/lib/cmake/tbb/ \
      ..

TARGET_LINK_LIBRARIES(application embree)
```

--------------------------------

### Install Public Headers using CMake

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/star-2d/0.7/CMakeLists.txt

This CMake command installs the public header files for the 'star' component. The ${S2D_PUBLIC_HEADERS} variable is expected to contain a list of header files. These headers are installed into the 'include/star' directory, making them accessible for external projects.

```cmake
install(FILES ${S2D_PUBLIC_HEADERS}
    DESTINATION include/star
)
```

--------------------------------

### Install Library Targets using CMake

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/star-2d/0.7/CMakeLists.txt

This CMake command installs the 's2d' library target. It specifies the destinations for library files (lib), archive files (lib), and runtime files (bin). This ensures the library is correctly placed for use by other projects.

```cmake
install(TARGETS s2d
    LIBRARY DESTINATION lib
    ARCHIVE DESTINATION lib
    RUNTIME DESTINATION bin
)
```

--------------------------------

### Install Stardis-CUDA Library and Headers in CMake

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/star-sp/0.15/CMakeLists.txt

This CMake snippet defines the installation rules for the Stardis-CUDA project. It installs the 'ssp' library targets (shared library, static library, and runtime components) into the 'lib' and 'bin' directories. It also installs the public header files into the 'include/star' directory.

```cmake
# Install library targets
install(TARGETS ssp
    LIBRARY DESTINATION lib
    ARCHIVE DESTINATION lib
    RUNTIME DESTINATION bin
)

# Install public headers to include/star/
install(FILES ${SSP_PUBLIC_HEADERS}
    DESTINATION include/star
)
```

--------------------------------

### Install senc3d Library Targets (CMake)

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/star-enclosures-3d/0.7.2/CMakeLists.txt

Installs the senc3d library, including shared libraries, static archives, and runtime binaries, to their respective destinations (lib and bin). This is a standard CMake installation procedure for library targets.

```cmake
install(TARGETS senc3d
    LIBRARY DESTINATION lib
    ARCHIVE DESTINATION lib
    RUNTIME DESTINATION bin
)
```

--------------------------------

### C++ API Usage for Philox4x32

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/random123/v1.14.0/README.md

Demonstrates the typical C++ usage of the Random123 library with the Philox4x32 generator. It shows how to initialize the random number generator, set keys and counters, and generate random values. This example is applicable to other CBRNG families as well.

```cpp
#include <Random123/philox.h>

typedef r123::Philox4x32 RNG;
RNG rng;
RNG::ctr_type c={{}};
RNG::ukey_type uk={{}};
uk[0] = ???; // some user_supplied_seed
RNG::key_type k=uk;

for(...){ 
   c[0] = ???; // some loop-dependent application variable 
   c[1] = ???; // another loop-dependent application variable 
   RNG::ctr_type r = rng(c, k);
   // use the random values in r for some operation related to
   // this iteration on objectid
}
```

--------------------------------

### Configure Test Suite and Installation

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/custar-3d/0.10/CMakeLists.txt

Initializes the test environment if enabled and defines installation rules for the s3d library and public header files.

```cmake
if(ENABLE_TESTS)
    enable_testing()
    file(GLOB S3D_TEST_SOURCES src/test_*.c)
    if(S3D_TEST_SOURCES)
        add_module_tests(SOURCES ${S3D_TEST_SOURCES} LIBRARIES s3d)
    endif()
endif()

install(TARGETS s3d LIBRARY DESTINATION lib ARCHIVE DESTINATION lib RUNTIME DESTINATION bin)
install(FILES ${S3D_PUBLIC_HEADERS} DESTINATION include/star)
```

--------------------------------

### Configure SYCL Environment on Windows

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/thirdparty/embree4/src/README.md

Sets the necessary environment variables for the DPC++ compiler in a Windows command prompt. This ensures the compiler, libraries, and headers are accessible during the build process.

```batch
set "DPCPP_DIR=path_to_dpcpp_compiler"
set "PATH=%DPCPP_DIR%\bin;%PATH%"
set "PATH=%DPCPP_DIR%\lib;%PATH%"
set "CPATH=%DPCPP_DIR%\include;%CPATH%"
set "INCLUDE=%DPCPP_DIR%\include;%INCLUDE%"
set "LIB=%DPCPP_DIR%\lib;%LIB%"
```

--------------------------------

### Loading Helper Functions

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/stardis-solver/0.16.2/CMakeLists.txt

Includes the `HelperFunctions.cmake` script, which is essential for the build process. It checks for the existence of the script and provides a fatal error if it cannot be found, indicating the build must start from the workspace root.

```cmake
if(NOT COMMAND add_module_tests)
    if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/../../cmake/HelperFunctions.cmake")
        include("${CMAKE_CURRENT_SOURCE_DIR}/../../cmake/HelperFunctions.cmake")
    else()
        message(FATAL_ERROR "Cannot find HelperFunctions.cmake - must build from workspace root")
    endif()
endif()
```

--------------------------------

### Enable and Configure Simple Tests in CMake

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/star-sp/0.15/CMakeLists.txt

This snippet shows how to enable testing and define a list of source files for simple tests. It then adds these tests to the build system using `add_module_tests`, linking against the 'ssp' library. This is typically used for unit tests where each source file represents a single test case.

```cmake
if(ENABLE_TESTS)
    enable_testing()
    
    # Simple tests (one test per source file)
    set(SSP_SIMPLE_TESTS
        src/test_ssp_ran_circle.c
        src/test_ssp_ran_discrete.c
        src/test_ssp_ran_gaussian.c
        src/test_ssp_ran_hemisphere.c
        src/test_ssp_ran_hg.c
        src/test_ssp_ran_piecewise_linear.c
        src/test_ssp_ran_sphere.c
        src/test_ssp_ran_sphere_cap.c
        src/test_ssp_ran_spherical_zone.c
        src/test_ssp_ran_tetrahedron.c
        src/test_ssp_ran_triangle.c
        src/test_ssp_ran_uniform_disk.c
        src/test_ssp_rng_proxy.c
    )
    
    add_module_tests(
        SOURCES ${SSP_SIMPLE_TESTS}
        LIBRARIES ssp
    )
endif()
```

--------------------------------

### Install Public Headers for senc3d (CMake)

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/star-enclosures-3d/0.7.2/CMakeLists.txt

Installs the public header files for the senc3d library into the 'include/star' directory. It utilizes the CMake variable SENC3D_PUBLIC_HEADERS to specify which header files to install.

```cmake
install(FILES ${SENC3D_PUBLIC_HEADERS}
    DESTINATION include/star
)
```

--------------------------------

### Configure S3D Backend and Dependencies

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/CMakeLists.txt

This script conditionally selects between OptiX and cuBQL backends for the S3D component based on the S3D_BACKEND variable. It then loads the required modules for the backend and the sampling library.

```cmake
if(S3D_BACKEND STREQUAL "optix")
    load_module("oxstar-3d/0.10" "oxstar-3d v0.10 (s3d) - OptiX GPU backend (replaces star-3d)" "REQUIRED")
else()
    load_module("custar-3d/0.10" "custar-3d v0.10 (s3d) - cuBQL GPU backend (replaces star-3d)" "REQUIRED")
endif()
load_module("star-sp/0.15" "star-sp v0.15 (ssp) - Sampling + Random123" "REQUIRED")
```

--------------------------------

### Install Stardis Library (CMake)

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/stardis-solver/0.16.2/CMakeLists.txt

This snippet defines the installation rules for the 'sdis' target. It specifies the destination directories for the library, archive, runtime components, and public headers when the project is installed.

```cmake
install(TARGETS sdis
    LIBRARY DESTINATION lib
    ARCHIVE DESTINATION lib
    RUNTIME DESTINATION bin
    PUBLIC_HEADER DESTINATION include
)
```

--------------------------------

### C++ Key Type Initialization

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/random123/v1.14.0/docs/cbrng.dox

Demonstrates how to initialize G::key_type from G::ukey_type using constructors and assignment operators. This is applicable for most CBRNGs, including AESNI types.

```cpp
G::ukey_type uk1, uk2;
// user code initializes uk1 and uk2
G::key_type  k1(uk1), k2;
k2 = uk2;
```

--------------------------------

### Generate and Install Headers (CMake)

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/star-enclosures-2d/0.6/CMakeLists.txt

Configures the generation of public headers under the 'star/' namespace within the build directory. It copies specified header files and sets up include directories for both build and installation contexts.

```cmake
set(SENC2D_GENERATED_INCLUDE_DIR "${CMAKE_CURRENT_BINARY_DIR}/include")

set(SENC2D_PUBLIC_HEADERS
    src/senc2d.h
    src/sencX2d.h
    src/sencX2d_undefs.h
)

foreach(header ${SENC2D_PUBLIC_HEADERS})
    get_filename_component(header_name ${header} NAME)
    configure_file(
        ${CMAKE_CURRENT_SOURCE_DIR}/${header}
        ${SENC2D_GENERATED_INCLUDE_DIR}/star/${header_name}
        COPYONLY
    )
endforeach()

target_include_directories(senc2d
    PUBLIC
        # Generated structure for <star/senc2d.h>
        $<BUILD_INTERFACE:${SENC2D_GENERATED_INCLUDE_DIR}>
        # Source directory (internal use only)
        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
        $<INSTALL_INTERFACE:include>
)
```

--------------------------------

### Configure Dependencies and Installation in CMake

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/stardis/0.12/CMakeLists.txt

This script manages project dependencies by conditionally linking libraries based on target availability and platform. It also includes logic for deploying Windows runtime dependencies and defining installation rules for project binaries and header files.

```cmake
# Optional dependencies
if(TARGET sg3d)
    target_link_libraries(stardis PRIVATE sg3d)
endif()

if(TARGET sstl)
    target_link_libraries(stardis PRIVATE sstl)
endif()

# Math library (Unix only)
if(UNIX AND NOT APPLE)
    target_link_libraries(stardis PRIVATE m)
endif()

# Windows Runtime Dependency Deployment
if(WIN32 AND COMMAND deploy_runtime_dependencies)
    deploy_runtime_dependencies(stardis)
endif()

# Installation
install(TARGETS stardis
    RUNTIME DESTINATION bin
)

# Install public headers
install(FILES
    src/stardis-green-types.h
    src/stardis-prog-properties.h
    DESTINATION include/stardis
)
```

--------------------------------

### Build and Package Embree

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/thirdparty/embree4/doc/README.md

Commands to compile the configured Embree project and generate a distribution package.

```bash
cmake --build build
cmake --build build --target package
```

--------------------------------

### Configure P3 Wavefront Numerical Tests (CMake)

Source: https://github.com/ericsolshkov/stardis-cuda/blob/main/stardis-solver/0.16.2/CMakeLists.txt

This snippet configures the build process for P3 wavefront numerical correctness tests. It handles basic tests (linking 'sdis_obj') and S3DUT tests (linking 'sdis_obj' and 's3dut'), defining executables, library links, and test properties. It also adjusts the timeout for a specific test ('test_sdis_wf_i1_volumic_power2').

```cmake
add_executable(${p3test} src/${p3test}.c)
target_link_libraries(${p3test} PRIVATE sdis_obj)
add_test(NAME ${p3test} COMMAND ${p3test})
set_tests_properties(${p3test} PROPERTIES
    TIMEOUT 600
    LABELS "wf;p3;numerical")
```

```cmake
set_tests_properties(test_sdis_wf_i1_volumic_power2 PROPERTIES TIMEOUT 1200)
```

```cmake
add_executable(${p3test} src/${p3test}.c)
target_link_libraries(${p3test} PRIVATE sdis_obj s3dut)
add_test(NAME ${p3test} COMMAND ${p3test})
set_tests_properties(${p3test} PROPERTIES
    TIMEOUT 600
    LABELS "wf;p3;numerical")
```