### Define and Build Example Executables

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/cppdap/CMakeLists.txt

Defines a CMake function `build_example` to create an executable for each example. It also handles optional installation of examples as VSCode extensions.

```cmake
if(CPPDAP_BUILD_EXAMPLES)
    function(build_example target)
        add_executable(${target} "${CMAKE_CURRENT_SOURCE_DIR}/examples/${target}.cpp")
        set_target_properties(${target} PROPERTIES
            FOLDER "Examples"
        )
        cppdap_set_target_options(${target})
        target_link_libraries(${target} PRIVATE cppdap)

        if(CPPDAP_INSTALL_VSCODE_EXAMPLES)
            if(CMAKE_SYSTEM_NAME MATCHES "Windows")
                set(extroot "$ENV{USERPROFILE}\.vscode\extensions")
            else()
                set(extroot "$ENV{HOME}/.vscode/extensions")
            endif()
            if(EXISTS ${extroot})
                set(extdir "${extroot}/google.cppdap-example-${target}-1.0.0")
                configure_file(${CMAKE_CURRENT_SOURCE_DIR}/examples/vscode/package.json ${extdir}/package.json)
                add_custom_command(TARGET ${target}
                   POST_BUILD
                   COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_FILE:${target}> ${extdir})
            else()
                message(WARNING "Could not install vscode example extension as '${extroot}' does not exist")
            endif()
        endif(CPPDAP_INSTALL_VSCODE_EXAMPLES)
    endfunction(build_example)

    build_example(hello_debugger)
    build_example(simple_net_client_server)

endif(CPPDAP_BUILD_EXAMPLES)
```

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

### Install cpplint using pip

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/cppdap/third_party/json/third_party/cpplint/README.rst

Install the cpplint package from the Python Package Index (PyPI). This command is used for initial setup.

```bash
pip install cpplint
```

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

### Install Targets and Headers

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/discordrpc/src/CMakeLists.txt

Configures the installation of the `discord-rpc` target (runtime, library, archive) and header files to their respective installation directories.

```cmake
install(
    TARGETS discord-rpc
    EXPORT "discord-rpc"
    RUNTIME
        DESTINATION "${CMAKE_INSTALL_BINDIR}"
    LIBRARY
        DESTINATION "${CMAKE_INSTALL_LIBDIR}"
    ARCHIVE
        DESTINATION "${CMAKE_INSTALL_LIBDIR}"
    INCLUDES
        DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
)
```

```cmake
install(
    FILES
        "../include/discord_rpc.h"
		"../include/discord_register.h"
    DESTINATION "include"
)
```

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

### Install Documentation

Source: https://github.com/zdoom/gzdoom/blob/master/CMakeLists.txt

Installs the 'docs' directory to the configured destination path, assigning it to the 'Documentation' component.

```cmake
install(DIRECTORY docs/
		DESTINATION ${INSTALL_DOCS_PATH}
		COMPONENT "Documentation")
```

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

### New Small SFX Module for Installers

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/lzma/DOC/lzma-history.txt

Introduces a new, small self-extracting module (SfxSetup) designed for installers.

```text
- New small SFX module for installers (SfxSetup).
```

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

### Install DUMB Libraries with Make

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZMusic/thirdparty/dumb/readme.txt

Run this command after successful compilation to install the DUMB libraries.

```bash
make install
```

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

### Install Click Library

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/discordrpc/README.md

Install the 'click' Python library, which is a dependency for the build.py wrapper script.

```sh
pip install click
```

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

### Install Game Music Emu Library

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZMusic/thirdparty/game-music-emu/readme.txt

Commands to install the Game_Music_Emu library. You can specify the installation prefix using CMake or the DESTDIR variable during 'make install'.

```bash
# To install the library:
make install

# To choose where to install the library to, use the CMake argument:
# -DCMAKE_INSTALL_PREFIX=/usr/local

# Alternately, you can specify the base path to install to when you run "make install"
# by passing 'DESTDIR=/usr/local' on the make install command line
```

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

### Amalgamate.py Example Configuration File Paths

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/cppdap/third_party/json/third_party/amalgamate/README.md

Examples of paths to configuration files for amalgamate.py, demonstrating JSON file usage for source and include definitions.

```bash
test/source.c.json
```

```bash
test/include.h.json
```

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

### Set Documentation Install Path

Source: https://github.com/zdoom/gzdoom/blob/master/CMakeLists.txt

Sets the destination path for installing documentation based on the operating system (Windows vs. others).

```cmake
if( WIN32 )
	set( INSTALL_DOCS_PATH docs CACHE STRING "Directory where the documentation will be placed during install." )
else()
	set( INSTALL_DOCS_PATH share/doc/${ZDOOM_EXE_NAME} CACHE STRING "Directory where the zdoom documentation will be placed during install." )
endif()
```

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

### Install Discord RPC using CMake

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/discordrpc/README.md

Use this command to build and install the discord-rpc library. Ensure you have CMake installed and navigate to the discord-rpc directory.

```sh
    cd <path to discord-rpc>
    mkdir build
    cd build
    cmake .. -DCMAKE_INSTALL_PREFIX=<path to install discord-rpc to>
    cmake --build . --config Release --target install
```

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

### Install Soundfont and FM Banks

Source: https://github.com/zdoom/gzdoom/blob/master/src/CMakeLists.txt

Installs soundfont and FM bank directories to a platform-specific location during the installation phase.

```cmake
if( WIN32 )
	set( INSTALL_SOUNDFONT_PATH . CACHE STRING "Directory where soundfonts and WOPL/WOPN banks will be placed during install." )
else()
	set( INSTALL_SOUNDFONT_PATH share/games/doom CACHE STRING "Directory where soundfonts and WOPL/WOPN banks will be placed during install." )
endif()
install(DIRECTORY "${PROJECT_BINARY_DIR}/soundfonts" "${PROJECT_BINARY_DIR}/fm_banks"
		DESTINATION ${INSTALL_SOUNDFONT_PATH}
		COMPONENT "Soundfont resources")
```

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

### Install DUMB Libraries with MinGW

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZMusic/thirdparty/dumb/readme.txt

Run this command after successful compilation with MinGW to install the DUMB libraries.

```bash
mingw32-make install
```

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

### Amalgamate.py Example Prologue File Path

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/cppdap/third_party/json/third_party/amalgamate/README.md

Example of specifying a prologue file path for amalgamate.py, which is an optional file to be prepended to the amalgamation.

```bash
path/to/prologue.(c|h)
```

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

### ZWidget Example Linker and Include Paths

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZWidget/CMakeLists.txt

Configures include directories and links the zwidget library and platform-specific libraries to the zwidget_example executable.

```cmake
target_include_directories(zwidget_example PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/example)
target_link_libraries(zwidget_example PRIVATE zwidget)

	if(WIN32)
		target_compile_definitions(zwidget_example PRIVATE UNICODE _UNICODE)
		target_link_libraries(zwidget_example PRIVATE gdi32 user32 shell32 comdlg32)
	elseif(APPLE)
		target_link_libraries(zwidget_example PRIVATE "-framework Cocoa -framework OpenGL")
	else()
		target_link_libraries(zwidget_example PRIVATE ${ZWIDGET_LIBS})
	endif()
```

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

### Amalgamate.py Test and Install Command

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/cppdap/third_party/json/third_party/amalgamate/README.md

Commands to test the amalgamate.py script using its test suite and then install it to the system's binary path.

```bash
./test.sh && sudo -k cp ./amalgamate.py /usr/local/bin/
```

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

### ZWidget Example Executable Build

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZWidget/CMakeLists.txt

Builds the zwidget example executable, specifying its source files and applying compile options.

```cmake
if(ZWIDGET_BUILD_EXAMPLE)
	add_executable(zwidget_example WIN32
		example/example.cpp
		example/picopng.cpp
		example/picopng.h
	)
	target_compile_options(zwidget_example PRIVATE ${CXX_WARNING_FLAGS})
```

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

### Install Project Targets and Files

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/cppdap/CMakeLists.txt

Installs the built library targets, export files, and header directories to their designated locations on the system. This makes the library and its associated CMake configuration files available for use by other projects.

```cmake
install(
	TARGETS                  "${CPPDAP_TARGET_NAME}"
	EXPORT                   "${CPPDAP_TARGETS_EXPORT_NAME}"
	ARCHIVE DESTINATION      "${CMAKE_INSTALL_LIBDIR}"
	LIBRARY DESTINATION      "${CMAKE_INSTALL_LIBDIR}"
	RUNTIME DESTINATION      "${CMAKE_INSTALL_BINDIR}"
	INCLUDES DESTINATION     "${CPPDAP_INCLUDE_INSTALL_DIR}"
)

install(
	EXPORT "${CPPDAP_TARGETS_EXPORT_NAME}"
	NAMESPACE "${CPPDAP_TARGET_NAME}::"
	DESTINATION "${CPPDAP_CONFIG_INSTALL_DIR}"
)

install(
	DIRECTORY
		"include/dap"
	DESTINATION "${CPPDAP_INCLUDE_INSTALL_DIR}"
)
install(FILES ${CPPDAP_CMAKE_VERSION_CONFIG_FILE} ${CPPDAP_CMAKE_PROJECT_CONFIG_FILE}
DESTINATION ${CPPDAP_CONFIG_INSTALL_DIR})
```

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

### Install Linux Desktop Launcher and Metadata

Source: https://github.com/zdoom/gzdoom/blob/master/src/CMakeLists.txt

Installs desktop entry, icon, and metadata files for Linux systems. Requires post-installation scripts to register MIME types and desktop entries.

```cmake
if( UNIX AND NOT APPLE )
	install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/posix/freedesktop/org.zdoom.GZDoom.desktop
			DESTINATION share/applications
			PERMISSIONS WORLD_EXECUTE WORLD_READ GROUP_READ GROUP_EXECUTE OWNER_READ OWNER_WRITE OWNER_EXECUTE)
	install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/posix/freedesktop/org.zdoom.GZDoom.metainfo.xml
			DESTINATION share/metainfo
			PERMISSIONS WORLD_READ GROUP_READ GROUP_EXECUTE OWNER_READ OWNER_WRITE)
	install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/posix/freedesktop/org.zdoom.GZDoom.svg
			DESTINATION share/icons/hicolor/scalable/apps
			PERMISSIONS WORLD_READ GROUP_READ GROUP_EXECUTE OWNER_READ OWNER_WRITE)
	install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/posix/freedesktop/org.zdoom.GZDoom-mime.xml
			DESTINATION share/mime/packages
			PERMISSIONS WORLD_READ GROUP_READ GROUP_EXECUTE OWNER_READ OWNER_WRITE)
	# note:
	# A post-install script would most likely need to run the following to register the desktop and mime files with the system
	# update-mime-database /usr/local/share/mime
	# update-desktop-database
endif()
```

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

### Copying Example Assets Post-Build

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZWidget/CMakeLists.txt

Adds a custom command to copy necessary assets (banner image and font) to the build directory after the zwidget_example executable is built.

```cmake
add_custom_command(
	TARGET zwidget_example POST_BUILD
	COMMAND ${CMAKE_COMMAND} -E copy
		"${CMAKE_CURRENT_SOURCE_DIR}/example/banner.png"
		"${CMAKE_CURRENT_BINARY_DIR}/banner.png"
	COMMAND ${CMAKE_COMMAND} -E copy
		"${CMAKE_CURRENT_SOURCE_DIR}/example/OpenSans.ttf"
		"${CMAKE_CURRENT_BINARY_DIR}/OpenSans.ttf"
)
```

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

### Install ZMusic Library on Non-Windows/macOS Systems

Source: https://github.com/zdoom/gzdoom/blob/master/src/CMakeLists.txt

Installs the zmusic library to the system's library directory. This is skipped for Windows and macOS, and when ZMUSIC_SYSTEM_INSTALL is defined.

```cmake
if ( NOT ZMUSIC_SYSTEM_INSTALL )
	if ( WIN32 OR APPLE )
		# nothing to do
	else()
		install(TARGETS zmusic
			LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
			COMPONENT "Game executable"
		)
	endif()
endif()
```

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

### ZWidget Example Application Build Option

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZWidget/CMakeLists.txt

Defines a CMake option to control whether the zwidget example application is built.

```cmake
option(ZWIDGET_BUILD_EXAMPLE "Build the zwidget example application" ON)
```

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

### ZWidget Example C++ Standard and MSVC Runtime

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZWidget/CMakeLists.txt

Sets the C++ standard to 20 for the zwidget_example and configures the MSVC runtime library.

```cmake
set_target_properties(zwidget_example PROPERTIES CXX_STANDARD 20)

	if(MSVC)
		set_property(TARGET zwidget_example PROPERTY MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
	endif()
```

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

### RAM to RAM Compression/Decompression Example

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/lzma/DOC/lzma-history.txt

Provides a new example for RAM-to-RAM compression and decompression using LZMA with the BCJ filter for x86 code.

```c
- New example for RAM->RAM compressing/decompressing: 
  LZMA + BCJ (filter for x86 code):
    - LzmaRam.h
    - LzmaRam.cpp
    - LzmaRamDecode.h
    - LzmaRamDecode.c
```

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

### DiscordController.cs - Unity Example

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/discordrpc/README.md

A Unity script demonstrating how to use the DiscordRpc.cs class to set Rich Presence. This example updates the presence with game state and images. It requires the DiscordRpc.cs script and the necessary Discord RPC DLLs to be present in the Unity project.

```csharp
using UnityEngine;

public class DiscordController : MonoBehaviour
{
    public DiscordRpc discordRpc;

    void Start()
    {
        if (discordRpc == null)
        {
            discordRpc = DiscordRpc.Instance;
            if (discordRpc == null)
            {
                Debug.LogError("DiscordRpc instance not found!");
                return;
            }
        }

        // Example: Update presence on start
        UpdateDiscordPresence("In Menus", "Browsing options", "main_art", "My Awesome Game");
    }

    void Update()
    {
        // Example: Update presence based on game state
        if (Input.GetKeyDown(KeyCode.Space))
        {
            UpdateDiscordPresence("Playing", "Jumped!", "player_icon", "Player");
        }
    }

    public void UpdateDiscordPresence(string state, string details, string largeImageKey, string largeImageText)
    {
        if (discordRpc != null)
        {
            discordRpc.UpdatePresence(state, details, (long)(DateTime.UtcNow - new DateTime(1970, 1, 1)).TotalSeconds, largeImageKey, largeImageText, null, null);
        }
    }

    // Add methods to handle join/spectate requests if needed
}
```

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

### Set Installation Path for Executable

Source: https://github.com/zdoom/gzdoom/blob/master/src/CMakeLists.txt

Determines the installation path for the main executable based on the operating system. Defaults to 'bin' on non-Windows systems and '.' on Windows.

```cmake
if( WIN32 )
	set( INSTALL_PATH . CACHE STRING "Directory where the executable will be placed during install." )
else()
	set( INSTALL_PATH bin CACHE STRING "Directory where the executable will be placed during install." )
endif()
install(TARGETS zdoom
		DESTINATION ${INSTALL_PATH}
		COMPONENT "Game executable")
```

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

### Install Package Configuration

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZMusic/CMakeLists.txt

Installs the generated CMake package configuration files. These files are essential for other projects to discover and link against this library.

```cmake
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/ZMusicConfig.cmake ${CMAKE_CURRENT_BINARY_DIR}/ZMusicConfigVersion.cmake
		DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/ZMusic
		COMPONENT devel
)
```

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

### Linking SDL2 to ZWidget Example

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZWidget/CMakeLists.txt

Links the SDL2 library to the zwidget_example executable if SDL2 is found.

```cmake
if(SDL2_FOUND)
	target_link_libraries(zwidget_example PRIVATE SDL2::SDL2)
endif()
```

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

### Configure ZMusic Library Handling

Source: https://github.com/zdoom/gzdoom/blob/master/CMakeLists.txt

Manages the inclusion of the ZMusic library, prioritizing system installation but falling back to an internal build. Sets paths and library variables.

```cmake
# ZMUSIC
if( ZMUSIC_FOUND AND NOT FORCE_INTERNAL_ZMUSIC )
	message( STATUS "Using system zmusic library, includes found at ${ZMUSIC_INCLUDE_DIR}" )
	set( ZMUSIC_SYSTEM_INSTALL TRUE )
else()
	message( STATUS "Using internal zmusic library" )
	add_subdirectory( libraries/ZMusic )
	set( ZMUSIC_ROOT_PATH "${CMAKE_CURRENT_SOURCE_DIR}/libraries/zmusic" )
	set( ZMUSIC_INCLUDE_DIR ${ZMUSIC_ROOT_PATH}/include )
	set( ZMUSIC_LIBRARIES zmusic )
	set( ZMUSIC_FOUND TRUE )
endif()
```

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

### Install ZMusic Targets

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZMusic/source/CMakeLists.txt

Installs the zmusic and zmusiclite targets, including headers, libraries, and CMake export files. This section is conditional on the ZMUSIC_INSTALL variable.

```cmake
if(ZMUSIC_INSTALL)
	install(TARGETS zmusic EXPORT ZMusicFullTargets
	PUBLIC_HEADER
		DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
		COMPONENT devel
	LIBRARY
		DESTINATION "${CMAKE_INSTALL_LIBDIR}"
		COMPONENT full
		NAMELINK_COMPONENT devel
	)

	install(TARGETS zmusiclite EXPORT ZMusicLiteTargets
	PUBLIC_HEADER
		DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
		COMPONENT devel
	LIBRARY
		DESTINATION "${CMAKE_INSTALL_LIBDIR}"
		COMPONENT lite
		NAMELINK_COMPONENT devel
	)

	install(EXPORT ZMusicFullTargets
		DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/ZMusic"
		NAMESPACE ZMusic::
		COMPONENT devel
	)

	install(EXPORT ZMusicLiteTargets
		DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/ZMusic"
		NAMESPACE ZMusic::
		COMPONENT devel
	)
endif()
```

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

### Load wad file at startup

Source: https://github.com/zdoom/gzdoom/blob/master/docs/console.html

Loads a wad file when the game starts. This command is only valid within .cfg files executed at startup.

```zdoom-console
pullin _wadfile_
```

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

### Build libdumb with CMake

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZMusic/thirdparty/dumb/cmake/readme.txt

This snippet demonstrates the basic steps to configure, build, and install libdumb using CMake. Ensure you are in the libdumb cmake directory.

```bash
mkdir -p build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local -DBUILD_SHARED_LIBS:BOOL=ON ..
make
make install
```

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

### Compile and Run Unit Tests

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/cppdap/third_party/json/README.md

Instructions for compiling and running the library's unit tests using CMake and CTest. Ensure you have CMake installed.

```shell
mkdir build
cd build
cmake ..
cmake --build .
ctest --output-on-failure
```

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

### Configure libdumb build with CMake flags

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZMusic/thirdparty/dumb/cmake/readme.txt

Example of running the libdumb CMake file with specific configuration flags. Adjust CMAKE_INSTALL_PREFIX and BUILD_SHARED_LIBS as needed.

```bash
cmake -DCMAKE_INSTALL_PREFIX=/install/dir -DBUILD_SHARED_LIBS:BOOL=OFF -DCMAKE_BUILD_TYPE=Release path/to/dumb/cmake/dir
```

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

### Core parsing loop example

Source: https://github.com/zdoom/gzdoom/blob/master/tools/lemon/lemon.html

Illustrates the essential loop for tokenizing input and feeding it to the parser. This is a simplified excerpt from a larger file parsing routine.

```c
ParseFile(){
   pParser = ParseAlloc( malloc );
   while( GetNextToken(pTokenizer,&hTokenId, &sToken) ){

```

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

### Configure Supported Music Types

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZMusic/thirdparty/game-music-emu/gme.txt

Example of how to reduce executable size by defining the GME_TYPE_LIST macro in blargg_config.h to include only specific music types like NSF and GBS.

```c
#define GME_TYPE_LIST \
    gme_nsf_type,\ 
    gme_gbs_type
```

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

### Define ZMusic Include Directories

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZMusic/source/CMakeLists.txt

Configures interface include directories for the zmusic and zmusiclite targets. Use $<INSTALL_INTERFACE:include> for installed targets and $<BUILD_INTERFACE:${ZMusic_SOURCE_DIR}/include> for build-time includes.

```cmake
target_include_directories(zmusic INTERFACE $<INSTALL_INTERFACE:include> $<BUILD_INTERFACE:${ZMusic_SOURCE_DIR}/include>)
target_include_directories(zmusiclite INTERFACE $<INSTALL_INTERFACE:include> $<BUILD_INTERFACE:${ZMusic_SOURCE_DIR}/include>)
```

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

### Example: Parse a file using Lemon

Source: https://github.com/zdoom/gzdoom/blob/master/tools/lemon/lemon.html

This routine demonstrates a typical workflow for parsing a file with Lemon, including tokenizer creation, parser allocation, token processing, and cleanup. Error handling is omitted for brevity.

```c
01 ParseTree *ParseFile(const char *zFilename){
02    Tokenizer *pTokenizer;
03    void *pParser;
04    Token sToken;
05    int hTokenId;
06    ParserState sState;
07
08    pTokenizer = TokenizerCreate(zFilename);
09    pParser = ParseAlloc( malloc );
10    InitParserState(&sState);
11    while( GetNextToken(pTokenizer, &hTokenId, &sToken) ){
12       Parse(pParser, hTokenId, sToken, &sState);
13    }
14    Parse(pParser, 0, sToken, &sState);
15    ParseFree(pParser, free );
16    TokenizerFree(pTokenizer);
17    return sState.treeRoot;
18 }
```

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

### CMake Embedded Integration

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/cppdap/third_party/json/README.md

Embed the nlohmann_json library directly into an existing CMake project by adding its source tree as a subdirectory. This example disables tests and installation for the embedded library.

```cmake
# Typically you don't care so much for a third party library's tests to be
# run from your own project's code.
set(JSON_BuildTests OFF CACHE INTERNAL "")

# If you only include this third party in PRIVATE source files, you do not
# need to install it when your main project gets installed.
# set(JSON_Install OFF CACHE INTERNAL "")

# Don't use include(nlohmann_json/CMakeLists.txt) since that carries with it
# unintended consequences that will break the build.  It's generally
# discouraged (although not necessarily well documented as such) to use
# include(...) for pulling in other CMake projects anyways.
add_subdirectory(nlohmann_json)
...
add_library(foo ...)
...
target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
```

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

### Initialize and Configure ZMusic Audio

Source: https://context7.com/zdoom/gzdoom/llms.txt

Initializes the ZMusic system with custom callbacks and configures FluidSynth for MIDI playback. Requires ZMusic callbacks to be defined.

```c
#include "zmusic.h"

// Initialize ZMusic with callbacks
void InitMusic() {
    ZMusicCallbacks callbacks = {
        .MessageFunc = MyMessageHandler,
        .PathForSoundfont = MySoundfontPath,
        .OpenSoundFont = MyOpenSoundFont,
        .SF_OpenFile = MySFOpenFile,
        .SF_Close = MySFClose
    };
    ZMusic_SetCallbacks(&callbacks);

    // Configure FluidSynth for MIDI playback
    ChangeMusicSettingInt(zmusic_snd_mididevice, NULL, MDEV_FLUIDSYNTH, NULL);
    ChangeMusicSettingString(zmusic_fluid_patchset, NULL, "soundfonts/gzdoom.sf2");
    ChangeMusicSettingInt(zmusic_fluid_voices, NULL, 128, NULL);
    ChangeMusicSettingFloat(zmusic_fluid_gain, NULL, 0.5f, NULL);
}
```

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

### Load Music File from Path

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZMusic/thirdparty/game-music-emu/gme.txt

Use gme_open_file to let the library determine the file's type and load it. Always check the returned error.

```c
error = gme_open_file( pathname, &emu );
```

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

### Right Recursion Example

Source: https://github.com/zdoom/gzdoom/blob/master/tools/lemon/lemon.html

Example demonstrating right-recursion in grammar rules, which should be avoided as it can lead to parser stack overflows.

```lemon
list ::= element list.      // right-recursion.  Bad!
   list ::= . 
```

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

### Configuration File and Include Directories

Source: https://github.com/zdoom/gzdoom/blob/master/tools/re2c/CMakeLists.txt

Configures the build by creating a `config.h` file from a template and setting up include directories for build artifacts and source files.

```cmake
configure_file( ${CMAKE_CURRENT_SOURCE_DIR}/config.h.in ${CMAKE_CURRENT_BINARY_DIR}/config.h )
include_directories( ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_SOURCE_DIR} )
add_definitions( -DHAVE_CONFIG_H )
```

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

### Build Unity Library Files

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/discordrpc/README.md

Run this command from the root directory to build the correct library files for Unity projects.

```sh
python build.py unity
```

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

### Open and Play Game Music File

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZMusic/thirdparty/game-music-emu/gme.txt

Basic steps to open a game music file, start a track, generate samples, and clean up the emulator. Ensure your operating system handles sample playback.

```c
gme_open_file( path, &emu );
gme_start_track();
gme_play( samples, sample_count );
gme_delete( emu );
```

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

### Install Library and Export Targets

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZVulkan/src/glslang/glslang/OSDependent/Unix/CMakeLists.txt

Conditionally installs the 'OSDependent' target and exports its targets for use by other CMake projects. This is controlled by the 'ENABLE_GLSLANG_INSTALL' variable.

```cmake
if(ENABLE_GLSLANG_INSTALL)
    install(TARGETS OSDependent EXPORT OSDependentTargets
            ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
	install(EXPORT OSDependentTargets DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake)
endif(ENABLE_GLSLANG_INSTALL)
```

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

### Left Recursion Example

Source: https://github.com/zdoom/gzdoom/blob/master/tools/lemon/lemon.html

Example demonstrating left-recursion in grammar rules, which is preferred for reducing stack size and preventing parser stack overflows.

```lemon
list ::= list element.      // left-recursion.  Good!
   list ::= . 
```

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

### Define Platform Sound

Source: https://github.com/zdoom/gzdoom/blob/master/wadsrc/static/sndseq.txt

Defines sounds for a platform, playing a starting sound until done, then stopping it. 'playuntildone' plays the start sound fully.

```ACS
:Platform
	playuntildone	plats/pt1_strt
	stopsound	plats/pt1_stop
end
```

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

### Handle Discord Events

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/discordrpc/README.md

This example shows how to set up event handlers for Discord RPC, such as joining or spectating a game. The `Discord_UpdatePresence` function should be called within your game loop to keep the status updated.

```c
void ReadyCallback(const DiscordUser *request) {
    printf("Discord: Logged in as %s\n", request->username);
}

void JoinCallback(const char *secret) {
    printf("Discord: Join request with secret %s\n", secret);
}

void SpectateCallback(const char *secret) {
    printf("Discord: Spectate request with secret %s\n", secret);
}

int main(int argc, char *argv[]) {
    DiscordEventHandlers handlers = {NULL, NULL, NULL, NULL, ReadyCallback, JoinCallback, SpectateCallback};
    Discord_Initialize("YOUR_CLIENT_ID", &handlers, 1, NULL);

    // ... game logic ...

    Discord_RunCallbacks();

    Discord_Shutdown();
    return 0;
}
```

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

### VCPKG Local Dependency Installation

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZMusic/source/CMakeLists.txt

Installs local dependencies using vcpkg if the VCPKG_TOOLCHAIN variable is set. This is typically used for development or testing environments.

```cmake
if (VCPKG_TOOLCHAIN)
	x_vcpkg_install_local_dependencies(TARGETS zmusic zmusiclite DESTINATION ".")
endif()
```

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

### Build Game Music Emu Library with CMake

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZMusic/thirdparty/game-music-emu/readme.txt

Instructions for building the Game_Music_Emu library using CMake. Ensure you are in the extracted source directory. CMake flags can be passed to customize the build.

```bash
mkdir build
cd build
cmake ../         # <-- Pass any needed CMake flags here
make              # To build the library
cd demo
make              # To build the demo itself
```

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

### Build Unreal Library Files

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/discordrpc/README.md

Execute this command from the root directory to build the necessary library files for Unreal Engine projects.

```sh
python build.py unreal
```

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

### UDMF Map Format Example

Source: https://context7.com/zdoom/gzdoom/llms.txt

Example of a basic room definition in the Universal Doom Map Format (UDMF), including vertices, linedefs, sidedefs, sectors, and things.

```textmap
// TEXTMAP example - basic room with monster and pickup
namespace = "ZDoom";

// Vertices define corner points
vertex { x = 0.0; y = 0.0; }
vertex { x = 256.0; y = 0.0; }
vertex { x = 256.0; y = 256.0; }
vertex { x = 0.0; y = 256.0; }

// Linedefs connect vertices and reference sidedefs
linedef {
    v1 = 0; v2 = 1;
    sidefront = 0;
    blocking = true;
}
linedef {
    v1 = 1; v2 = 2;
    sidefront = 1;
    blocking = true;
}
linedef {
    v1 = 2; v2 = 3;
    sidefront = 2;
    blocking = true;
}
linedef {
    v1 = 3; v2 = 0;
    sidefront = 3;
    blocking = true;
}

// Sidedefs define wall textures
sidedef { sector = 0; texturemiddle = "STARTAN2"; }
sidedef { sector = 0; texturemiddle = "STARTAN2"; }
sidedef { sector = 0; texturemiddle = "STARTAN2"; }
sidedef { sector = 0; texturemiddle = "STARTAN2"; }

// Sector defines floor/ceiling
sector {
    heightfloor = 0;
    heightceiling = 128;
    texturefloor = "FLAT14";
    textureceiling = "FLAT14";
    lightlevel = 192;
}

// Things (entities)
thing {
    x = 128.0; y = 128.0;
    type = 1;          // Player 1 start
    angle = 90;
    skill1 = true; skill2 = true; skill3 = true;
    skill4 = true; skill5 = true;
    single = true; coop = true; dm = true;
}

thing {
    x = 64.0; y = 64.0;
    type = 3004;       // Zombieman
    angle = 45;
    skill3 = true; skill4 = true; skill5 = true;
    single = true; coop = true;
    ambush = true;     // Deaf/ambush flag
}

thing {
    x = 192.0; y = 192.0;
    type = 2018;       // Armor
    skill1 = true; skill2 = true; skill3 = true;
    skill4 = true; skill5 = true;
    single = true; coop = true; dm = true;
}

```

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

### Specify Grammar Start Symbol

Source: https://github.com/zdoom/gzdoom/blob/master/tools/lemon/lemon.html

The %start_symbol directive allows you to explicitly define the start symbol for the grammar, overriding the default behavior of using the first non-terminal defined.

```lemon
%start_symbol  prog
```

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

### Set Include Directories

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZMusic/thirdparty/oplsynth/CMakeLists.txt

Configures interface include directories for the 'oplsynth' target, including the current source directory and the 'oplsynth' subdirectory.

```cmake
target_include_directories(oplsynth INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} PRIVATE oplsynth)
```

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

### Polyobj Specials

Source: https://github.com/zdoom/gzdoom/blob/master/wadsrc/static/xlat/eternity.txt

Specials for controlling polyobjects, including starting, explicit lines, sliding, and swinging.

```APIDOC
## Polyobj Specials

### Description
These specials are used to control the behavior of polyobjects, such as initiating their movement, defining explicit lines for them, or making them slide or swing.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

## Special Definitions

- **348**: `0`, `Polyobj_StartLine(0)`
- **349**: `0`, `Polyobj_ExplicitLine(0)`
- **350**: `0`, `Polyobj_DoorSlide(0)`
- **351**: `0`, `Polyobj_DoorSwing(0)`
```

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

### VCPKG Local Dependencies

Source: https://github.com/zdoom/gzdoom/blob/master/src/CMakeLists.txt

Installs local dependencies for the zdoom target using VCPKG if the VCPKG toolchain is defined.

```cmake
if (VCPKG_TOOLCHAIN)
	x_vcpkg_install_local_dependencies(TARGETS zdoom DESTINATION ".")
endif()
```

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

### Define Red Key Light

Source: https://github.com/zdoom/gzdoom/blob/master/wadsrc_lights/static/filter/doom.id/gldefs.txt

Defines a pointlight for the Red Key actor. No specific setup or constraints are mentioned.

```gzdoom-lump
frame RSKU { light REDKEY }
}
```

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

### Set include directories for zmusic-obj

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZMusic/source/CMakeLists.txt

Configures the include paths for the 'zmusic-obj' library. It adds '../include', the current source directory, and the 'zmusic' subdirectory to the INTERFACE include directories.

```cmake
target_include_directories(zmusic-obj
INTERFACE
	../include
	${CMAKE_CURRENT_SOURCE_DIR}
	zmusic
)
```

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

### Send Message to Everyone

Source: https://github.com/zdoom/gzdoom/blob/master/docs/console.html

Sends a message to all players. If the message starts with \"/me\", it will be formatted like an IRC action.

```zdoom-console
say _message_
```

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

### Changes in IStream.h Interfaces

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/lzma/DOC/lzma-history.txt

Details changes in GUIDs and interfaces within IStream.h, specifically how ISequentialInStream::Read and ISequentialOutStream::Write now function.

```c
 IStream.h:
   ISequentialInStream::Read now works as old ReadPart
   ISequentialOutStream::Write now works as old WritePart
```

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

### Configure Project Libraries

Source: https://github.com/zdoom/gzdoom/blob/master/src/CMakeLists.txt

Sets up the main list of libraries required for the project, including miniz, bzip2, dl, and drpc. It conditionally adds 'zvulkan' if Vulkan support is enabled.

```cmake
set( PROJECT_LIBRARIES ${PROJECT_LIBRARIES} miniz "${BZIP2_LIBRARIES}" "${CMAKE_DL_LIBS}" "${DRPC_LIBRARIES}")
if (HAVE_VULKAN)
	list( APPEND PROJECT_LIBRARIES "zvulkan" )
endif()

list( APPEND PROJECT_LIBRARIES "zwidget" )
list( APPEND PROJECT_LIBRARIES "webp" )
```

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

### Switch Definition Example

Source: https://github.com/zdoom/gzdoom/blob/master/wadsrc/static/animdefs.txt

This defines a switch that triggers an event. It specifies the sprite to use for the switch, the event it triggers, and the sound to play when activated.

```zdoom-script
switch strife SWTELP01 on pic SWTELP02 tics 0
```

```zdoom-script
switch strife BRNSCN01 quest on sound switches/sizzle pic BRNSCN05 tics 0
```

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

### Compile DUMB with Make

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZMusic/thirdparty/dumb/readme.txt

Use this command if you are not using MinGW or have renamed 'mingw32-make'.

```bash
make
```

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

### Serialize and Deserialize JSON to UBJSON

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/cppdap/third_party/json/README.md

Provides an example of converting a JSON value to UBJSON format and then back. UBJSON is designed for high performance and compactness.

```cpp
// serialize to UBJSON
std::vector<std::uint8_t> v_ubjson = json::to_ubjson(j);

// 0x7B, 0x69, 0x07, 0x63, 0x6F, 0x6D, 0x70, 0x61, 0x63, 0x74, 0x54, 0x69, 0x06, 0x73, 0x63, 0x68, 0x65, 0x6D, 0x61, 0x69, 0x00, 0x7D

// roundtrip
json j_from_ubjson = json::from_ubjson(v_ubjson);
```

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

### Lemon Rule with Unused Symbol

Source: https://github.com/zdoom/gzdoom/blob/master/tools/lemon/lemon.html

Shows an example where a linking symbol ('C') is used in the grammar rule but not in the reduce action, which generates an error in Lemon.

```lemon
expr(A) ::= expr(B) PLUS expr(C).  { A = B; }
```

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

### Configure GZDoom Build with ZMusic

Source: https://github.com/zdoom/gzdoom/blob/master/libraries/ZMusic/samples/list_midi_devices/CMakeLists.txt

Sets up the CMake build for the GZDoom project, ensuring ZMusic is found and linked.

```cmake
cmake_minimum_required(VERSION 2.8.7...3.19)
project(list_midi_devices)

find_package(ZMusic REQUIRED)

add_executable(list_midi_devices list_midi_devices.cpp)
target_link_libraries(list_midi_devices PRIVATE ZMusic::zmusic)
```