### Install RISC-V GNU Toolchain

Source: https://github.com/libriscv/rvscript/blob/master/README.md

Steps to clone the RISC-V GNU toolchain repository, update submodules, configure the build with specific architecture and ABI, and compile the toolchain. Ensure you install necessary system dependencies for GCC beforehand. After installation, update your PATH environment variable.

```sh
git clone https://github.com/riscv/riscv-gnu-toolchain.git
cd riscv-gnu-toolchain
git submodule update --depth 1 --init
<install dependencies for GCC on your particular system here>
./configure --prefix=$HOME/riscv --with-arch=rv64g_zba_zbb_zbc_zbs --with-abi=lp64d
make -j8
```

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

### NanoGUI Build Options

Source: https://github.com/libriscv/rvscript/blob/master/ext/CMakeLists.txt

Configures build options for the NanoGUI library. These options control whether examples, GLFW support, Python bindings, or installation are enabled.

```cmake
option(NANOGUI_BUILD_EXAMPLES "" OFF)
option(NANOGUI_BUILD_GLFW "" OFF)
option(NANOGUI_BUILD_PYTHON "" OFF)
option(NANOGUI_INSTALL "" OFF)
```

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

### Install RISC-V Toolchain and Build Engine (Debian/Ubuntu)

Source: https://github.com/libriscv/rvscript/blob/master/README.md

Steps to install a RISC-V GCC toolchain from system packages on Debian-based systems and then build the RVScript engine.

```bash
sudo apt install g++-12-riscv64-linux-gnu
cd engine
./build.sh
```

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

### Install gdb-multiarch

Source: https://github.com/libriscv/rvscript/blob/master/README.md

Installs the `gdb-multiarch` package, which is necessary for debugging cross-compiled targets, including RISC-V. This command uses the apt package manager, commonly found on Debian-based Linux distributions.

```sh
sudo apt install gdb-multiarch
```

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

### Define and Build Shared Program with CMake

Source: https://github.com/libriscv/rvscript/blob/master/engine/scripts/CMakeLists.txt

This snippet demonstrates how to use the `add_shared_program` CMake function to build a shared ELF binary. It specifies the program name, base address, and source files. The `*[Gg]ameplay*` pattern indicates that source files starting with 'Gameplay' or 'gameplay' should be included.

```cmake
add_shared_program(gameplay.elf 0x50000000
	*[Gg]ameplay*
	"src/gameplay.cpp"
	"src/gameplay_remote.cpp"
	"src/events.cpp"
)
```

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

### Enable Debugging with GDB

Source: https://github.com/libriscv/rvscript/blob/master/README.md

Runs the `build.sh` script with the `DEBUG=1` environment variable to generate debuggable programs. This enables features like remote debugging with GDB, where the engine listens for a debugger connection on breakpoints. It attempts to automatically start GDB and connect.

```sh
DEBUG=1 ./build.sh
```

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

### Verify RISC-V Compiler Version

Source: https://github.com/libriscv/rvscript/blob/master/README.md

Checks the installed version of the RISC-V GCC++ compiler. This command confirms that the toolchain has been successfully installed and added to the PATH, allowing you to verify the specific version of the compiler being used.

```sh
$ riscv64-unknown-elf-g++ --version
```

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

### RISC-V Syscall Configuration

Source: https://github.com/libriscv/rvscript/blob/master/ext/CMakeLists.txt

Sets the maximum number of system calls for the RISC-V target. This definition ensures enough space for custom system calls and standard Linux system calls, starting from a base offset.

```cmake
target_compile_definitions(riscv PUBLIC RISCV_SYSCALLS_MAX=600)
```

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

### Define Public Compile Definitions for libc (CMake)

Source: https://github.com/libriscv/rvscript/blob/master/programs/micro/libc/CMakeLists.txt

This CMake command defines public compile flags for the 'libc' library. It sets base values for native and thread system calls, which are likely used to define the starting points for different syscall categories within the library.

```cmake
target_compile_definitions(libc PUBLIC
	NATIVE_SYSCALLS_BASE=570
	THREAD_SYSCALLS_BASE=590
)
```

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

### Build and Run RVScript Engine

Source: https://github.com/libriscv/rvscript/blob/master/README.md

Instructions to build the RVScript engine using a bash script. It also mentions enabling benchmarks by setting an environment variable.

```bash
bash build.sh
BENCHMARK=1 ./build.sh
```

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

### Build and Run Scripts

Source: https://github.com/libriscv/rvscript/blob/master/README.md

Executes the `build.sh` script located in the engine directory. This script is responsible for compiling script programs from the programs folder and is the primary method for building and running projects within this environment.

```sh
cd engine
./build.sh
```

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

### Define and Build Level Scripts with CMake

Source: https://github.com/libriscv/rvscript/blob/master/engine/scripts/CMakeLists.txt

This snippet shows how to use the `add_level` CMake function to build ELF binaries for level scripts. It includes the program name, base address, and the source files for each level. The `attach_program` function is used to establish dependencies between the level scripts and the main gameplay program.

```cmake
add_level(gui.elf 0x400000
	"src/gui.cpp"
)
attach_program(gui.elf gameplay.elf)

add_level(level1.elf 0x400000
	"src/level1.cpp"
	"src/level1_local.cpp"
	"src/level1_remote.cpp"
	"src/level1_threads.cpp"
	"src/events.cpp"
)
attach_program(level1.elf gameplay.elf)

add_level(level2.elf 0x400000
	"src/level2.cpp"
)
attach_program(level2.elf gameplay.elf)
```

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

### Define RISC-V C Library Sources (CMake)

Source: https://github.com/libriscv/rvscript/blob/master/programs/micro/libc/CMakeLists.txt

This CMake command sets the list of source files for the RISC-V C library. It includes core C++ files and files from a specified build system path for heap, libc, libcxx, and microthread implementations.

```cmake
set(LIBC_SOURCES
	assert.cpp
	engine.cpp
	write.cpp
	${BBLIBCPATH}/heap.cpp
	${BBLIBCPATH}/libc.cpp
	${BBLIBCPATH}/libcxx.cpp
	${BBLIBCPATH}/microthread.cpp
  )
```

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

### Defining dynamic call signature in JSON

Source: https://github.com/libriscv/rvscript/blob/master/README.md

This JSON snippet shows how to declare the signature for a dynamic call. This file is used by the build system to generate the necessary bindings, exposing the host function to the guest script.

```json
{
	"lazy": "void sys_lazy ()"
}
```

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

### Add RISC-V to PATH

Source: https://github.com/libriscv/rvscript/blob/master/README.md

Appends the RISC-V toolchain's bin directory to your PATH environment variable by modifying the .bashrc file. This allows your system to find and execute RISC-V compiler commands. Remember to reload your shell configuration or reopen your terminal for the changes to take effect.

```sh
export PATH=$PATH:$HOME/riscv/bin
```

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

### Check Public Functions with readelf

Source: https://github.com/libriscv/rvscript/blob/master/programs/micro/README.md

This command helps identify if a binary has a specific public function by inspecting its symbol table. It lists all symbols, indicating their type (e.g., FUNC for functions, UND for undefined).

```bash
riscv32-unknown-elf-readelf -a <mybinary>
```

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

### CMake Build Configuration for rvscript Unit Tests

Source: https://github.com/libriscv/rvscript/blob/master/tests/CMakeLists.txt

This snippet details the core CMakeLists.txt file for the rvscript unit tests. It specifies the minimum CMake version, project name, compiler flags, options for RISC-V extensions, includes subdirectories for external code and script engine, and enables testing.

```cmake
cmake_minimum_required(VERSION 3.10)
project(rvscript_unittests C CXX)

set(CMAKE_CXX_FLAGS "-Wall -Wextra -Og -ggdb3 -fsanitize=address,undefined")

option(RISCV_MEMORY_TRAPS "" OFF)
option(RISCV_EXT_C "" ON)
add_subdirectory(../ext ext)
add_subdirectory(../engine/src/script script)
target_compile_definitions(script PUBLIC TESTING_FRAMEWORK=1)

add_subdirectory(Catch2)

enable_testing()

configure_file(${CMAKE_SOURCE_DIR}/codebuilder.sh
	${CMAKE_CURRENT_BINARY_DIR}/codebuilder.sh COPYONLY)

```

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

### Create Static RISC-V C Library (CMake)

Source: https://github.com/libriscv/rvscript/blob/master/programs/micro/libc/CMakeLists.txt

This CMake command creates a static library named 'libc' using the previously defined source files. Static libraries are linked directly into the executable during the build process.

```cmake
add_library(libc STATIC ${LIBC_SOURCES})
```

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

### Registering a dynamic call with a struct argument by reference in C++

Source: https://github.com/libriscv/rvscript/blob/master/README.md

This C++ snippet demonstrates registering a dynamic call that accepts a struct by reference. It accesses members of the struct and prints one of them to standard output.

```C++
Script::set_dynamic_call("struct_by_ref",
	[] (Script& script) {
		struct Something {
			int a, b, c, d;
		};
		const auto [s] = script.args <Something> ();
		strf::to(stdout)("Struct A: ", s.a, "\n");
	});
```

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

### Defining dynamic call signature for buffer/string_view in JSON

Source: https://github.com/libriscv/rvscript/blob/master/README.md

This JSON snippet defines the signature for a dynamic call that handles raw data via a pointer and size. The build system will use this to expose functions capable of passing byte arrays or string-like data.

```json
{
	"big_data": "void sys_big_data (const char*, size_t)"
}
```

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

### Registering a dynamic call with integer argument and return in C++

Source: https://github.com/libriscv/rvscript/blob/master/README.md

This C++ snippet shows how to register a dynamic call that accepts an integer argument from the script and returns an integer result. It also prints the received ID to standard output.

```C++
Script::set_dynamic_call("object_id",
	[] (Script& script) {
		const auto [id] = script.args <int> ();
		strf::to(stdout)("Object ID: ", id, "\n");

		script.machine().set_result(1234);
	});
```

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

### Defining Engine Executable and Linking Libraries

Source: https://github.com/libriscv/rvscript/blob/master/engine/CMakeLists.txt

Adds the main 'engine' executable target, specifying its source files and linking necessary libraries like 'script', 'nanogui', and 'library'. It also sets the runtime output directory for the executable.

```cmake
add_subdirectory(../ext ext)
add_subdirectory(src/script script)

add_executable(engine
	src/main.cpp
	src/main_screen.cpp
	src/renderer.cpp
	src/test_dynamic.cpp
	src/timers.cpp
	src/setup_gui.cpp
	src/setup_timers.cpp
)

target_include_directories(engine PUBLIC .)
target_link_libraries(engine script nanogui library)
set_target_properties(engine PROPERTIES
	RUNTIME_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})

if (SANITIZE)
	if (CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
		target_link_libraries(engine --rtlib=compiler-rt -lgcc_s)
	endif()
endif()

message(STATUS "Binary translation is ${RISCV_BINARY_TRANSLATION}")
```

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

### Calling a dynamic call from C++

Source: https://github.com/libriscv/rvscript/blob/master/README.md

This C++ snippet illustrates how a previously registered dynamic call, like 'sys_lazy', is invoked from within the host application after the bindings have been generated.

```C++
sys_lazy();
```

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

### Set Include Directories for libc Library (CMake)

Source: https://github.com/libriscv/rvscript/blob/master/programs/micro/libc/CMakeLists.txt

This CMake command configures the include directories for the 'libc' library. It makes the current source directory publicly available for header file inclusion by other targets that link against 'libc'.

```cmake
target_include_directories(libc PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
```

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

### Add RISC-V Compiler to PATH

Source: https://github.com/libriscv/rvscript/blob/master/programs/micro/README.md

This snippet shows how to add the RISC-V compiler to your system's PATH environment variable by modifying the .bashrc file. This ensures the compiler is accessible from anywhere in the terminal.

```shell
export PATH=$PATH:$HOME/riscv/bin
```

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

### Registering a dynamic call with buffer/string_view arguments in C++

Source: https://github.com/libriscv/rvscript/blob/master/README.md

This C++ snippet shows how to register a dynamic call that accepts data as a buffer or string view. It processes the incoming data by converting it to a string and passing it to a handler function.

```C++
Script::set_dynamic_call("void sys_big_data (const char*, size_t)",
	[] (Script& script) {
		// A Buffer is a general-purpose container for fragmented virtual memory.
		// The <riscv::Buffer> consumes two registers (A0: pointer, A1: length).
		const auto [buffer] = script.args <riscv::Buffer> ();
		handle_buffer(buffer.to_string());
		// Or, alternatively (also consumes two registers):
		const auto [view] = script.args <std::string_view> ();
		handle_buffer(view);
	});
```

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

### Registering a simple dynamic call in C++

Source: https://github.com/libriscv/rvscript/blob/master/README.md

This snippet demonstrates how to register a simple C++ function as a dynamic call within the rvscript engine. It takes no arguments and prints a message to standard output. The function signature is defined as a string.

```C++
Script::set_dynamic_call("void sys_lazy ()", [] (auto&) {
		strf::to(stdout)("I'm not doing much, tbh.\n");
	});
```

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

### RISC-V Architecture Options

Source: https://github.com/libriscv/rvscript/blob/master/ext/CMakeLists.txt

Configures the target RISC-V architecture and related features. Options like RISCV_32I, RISCV_64I, RISCV_FLAT_RW_ARENA, RISCV_EXPERIMENTAL, and RISCV_MEMORY_TRAPS control the instruction set and memory behavior.

```cmake
option(RISCV_32I "" OFF)
option(RISCV_64I "" ON)
option(RISCV_FLAT_RW_ARENA "" ON)
option(RISCV_EXPERIMENTAL "" OFF)
option(RISCV_MEMORY_TRAPS "" OFF)
```

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

### Enable Newlib Compatibility (CMake)

Source: https://github.com/libriscv/rvscript/blob/master/programs/micro/libc/CMakeLists.txt

This CMake command defines a public compile flag `USE_NEWLIB=1` for the 'libc' library. This likely enables compatibility or specific features related to the Newlib C library implementation.

```cmake
target_compile_definitions(libc PUBLIC
	USE_NEWLIB=1
)
```

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

### Adding Project Subdirectories

Source: https://github.com/libriscv/rvscript/blob/master/ext/CMakeLists.txt

Includes additional project components as subdirectories. These typically contain libraries or modules that extend the core functionality.

```cmake
add_subdirectory(libriscv/lib)
add_subdirectory(strf)
add_subdirectory(library)
add_subdirectory(nanogui)
```

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

### CMake Build Configuration and Options

Source: https://github.com/libriscv/rvscript/blob/master/engine/CMakeLists.txt

Configures the minimum CMake version, project name, and defines various build options such as LTO, sanitizers, profiling, embedded mode, and the use of the Mold linker. It also sets common compiler flags and the C++ standard.

```cmake
cmake_minimum_required (VERSION 3.0.2)
cmake_policy(SET CMP0069 NEW)
project (engine C CXX)

option(FLTO          "Enable LTO builds" OFF)
option(SANITIZE      "Enable sanitizers" OFF)
option(GPROF         "Enable profiling with Gprof" OFF)
option(EMBEDDED_MODE "Embed programs in binary" OFF)
option(USE_MOLD      "Use Mold linker" OFF)
option(MINIMAL_UBSAN "Use minimal UBsan run-time" OFF)

set(COMMON "-Wall -Wextra -march=native -ggdb3")
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${COMMON}")
set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${COMMON}")

if (SANITIZE)
 	set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fsanitize=address -fsanitize=undefined")
elseif (MINIMAL_UBSAN)
	if ("${CMAKE_CXX_COMPILER_ID}" STREQUAL "Clang")
		set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fsanitize=undefined -fsanitize-minimal-runtime")
	else()
		message(FATAL_ERROR "Minimal UBsan run-time is only supported on Clang")
	endif()
endif()

if (GPROF)
 	set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -pg")
endif()

if (FLTO)
	include(CheckIPOSupported)
	check_ipo_supported(RESULT supported OUTPUT error)
	if (supported)
		message(STATUS "IPO / LTO enabled")
		set(CMAKE_INTERPROCEDURAL_OPTIMIZATION TRUE)
	else()
		message(STATUS "IPO / LTO not supported: <${error}>")
		set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -flto")
		set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -fuse-ld=lld")
	endif()
endif()
if (USE_MOLD)
	if ("${CMAKE_CXX_COMPILER_ID}" STREQUAL "Clang")
		set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} --ld-path=/usr/local/bin/mold")
	else()
		set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -fuse-ld=/usr/local/bin/mold")
	endif()
elseif ("${CMAKE_CXX_COMPILER_ID}" STREQUAL "Clang")
	set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -fuse-ld=lld")
endif()
```

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

### Connect to Remote GDB

Source: https://github.com/libriscv/rvscript/blob/master/README.md

Manually connects a GDB session to a running program via a remote target. This is typically used when the program is running on a different machine or in a separate process, and GDB is attached to it using a specific port.

```sh
gdb-multiarch myprogram.elf
target remote :2159
```

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

### Set Compile Properties for libc.cpp (CMake)

Source: https://github.com/libriscv/rvscript/blob/master/programs/micro/libc/CMakeLists.txt

This CMake command applies specific compile properties to the 'libc.cpp' file. It sets the COMPILE_FLAGS to '-fno-builtin', which instructs the compiler not to replace built-in functions with their intrinsic equivalents, potentially allowing for custom implementations.

```cmake
set_source_files_properties(${BBLIBCPATH}/libc.cpp
	PROPERTIES COMPILE_FLAGS -fno-builtin)
```

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

### CMake Function to Add Unit Tests

Source: https://github.com/libriscv/rvscript/blob/master/tests/CMakeLists.txt

Defines a reusable CMake function `add_unit_test` to simplify adding new unit tests. It creates an executable for each test, sets necessary compile definitions, links against required libraries (script and Catch2), and registers the test with the testing framework.

```cmake
function(add_unit_test NAME)
	add_executable(${NAME}
		${ARGN}
		codebuilder.cpp
	)
	target_compile_definitions(${NAME} PUBLIC SRCDIR="${CMAKE_CURRENT_SOURCE_DIR}")
	target_link_libraries(${NAME} script Catch2WithMain)
	add_test(
		NAME test_${NAME}
		COMMAND ${NAME}
	)
endfunction()

add_unit_test(basic    basic.cpp)
add_unit_test(evloop   event_loop.cpp)
add_unit_test(events   events.cpp)
add_unit_test(timers   timers.cpp)
add_unit_test(limits   limits.cpp)

```

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

### Link External Library to libc (CMake)

Source: https://github.com/libriscv/rvscript/blob/master/programs/micro/libc/CMakeLists.txt

This CMake command links the 'strf-header-only' library to the 'libc' library as a public dependency. This means that any target linking against 'libc' will also have access to the 'strf-header-only' library.

```cmake
target_link_libraries(libc PUBLIC strf-header-only)
```

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

### Define Private Compile Definitions for libc (CMake)

Source: https://github.com/libriscv/rvscript/blob/master/programs/micro/libc/CMakeLists.txt

This CMake command defines private compile flags for the 'libc' library. `NATIVE_MEM_SYSCALLS=1` is set, indicating that native memory system calls are enabled for this library's internal use.

```cmake
target_compile_definitions(libc PRIVATE
	NATIVE_MEM_SYSCALLS=1
)
```

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

### Embedding Files into Executable

Source: https://github.com/libriscv/rvscript/blob/master/engine/CMakeLists.txt

Defines a CMake function `embed_file` that uses `objcopy` to convert binary files into object files, which are then linked into the target executable. This is used to embed resources like scripts or symbol maps.

```cmake
function (embed_file NAME PATH BINARY)
	get_filename_component(FILENAME ${BINARY} NAME)
	set(OUTFILE ${CMAKE_CURRENT_BINARY_DIR}/${FILENAME}.o)
	add_custom_command(
		WORKING_DIRECTORY ${PATH}
		COMMAND ${CMAKE_OBJCOPY} -Ibinary -Oelf64-x86-64 -Bi386 ${BINARY} ${OUTFILE}
		OUTPUT  ${OUTFILE}
		DEPENDS ${PATH}/${BINARY}
	)
	set_source_files_properties(${OUTFILE} PROPERTIES GENERATED TRUE)
	target_sources (${NAME} PRIVATE ${OUTFILE})
endfunction()

if (EMBEDDED_MODE)
	embed_file(engine "${CMAKE_SOURCE_DIR}/mods/hello_world/scripts" "gameplay.elf")
	embed_file(engine "${CMAKE_SOURCE_DIR}/../programs" "symbols.map")
	target_compile_definitions(engine PUBLIC EMBEDDED_MODE=1)
endif()
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.