### Install BehaviorTree.CPP with Vcpkg

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/README.md

Instructions for building and installing BehaviorTree.CPP using the vcpkg dependency manager.

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

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

### Compile Various Examples

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/examples/CMakeLists.txt

Calls the CompileExample function for a series of example executables.

```cmake
CompileExample("t02_basic_ports")
CompileExample("t03_generic_ports")
CompileExample("t04_reactive_sequence")
CompileExample("t05_crossdoor")
CompileExample("t06_subtree_port_remapping")
CompileExample("t07_load_multiple_xml")
CompileExample("t08_additional_node_args")
CompileExample("t09_scripting")
CompileExample("t10_observer")
```

```cmake
if(BTCPP_GROOT_INTERFACE)
  CompileExample("t11_groot_howto")
endif()
```

```cmake
CompileExample("t12_default_ports")
CompileExample("t13_access_by_ref")
CompileExample("t14_subtree_model")
CompileExample("t15_nodes_mocking")
CompileExample("t16_global_blackboard")
CompileExample("t17_blackboard_backup")
CompileExample("t18_waypoints")
CompileExample("t19_polymorphic_ports")
```

```cmake
CompileExample("ex01_wrap_legacy")
CompileExample("ex02_runtime_ports")
```

```cmake
if(BTCPP_SQLITE_LOGGING)
  CompileExample("ex03_sqlite_log")
endif()
```

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

### Install cppzmq with vcpkg

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/cppzmq/README.md

Instructions for installing cppzmq using the vcpkg package manager. This includes bootstrapping vcpkg and integrating it with your system.

```bash
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh (bootstrap-vcpkg.bat for Powershell)
./vcpkg integrate install
./vcpkg install cppzmq
```

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

### Install clang-tidy-21

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/CONTRIBUTORS_GUIDE.md

Follow these steps to install the required clang-tidy version for linting.

```bash
wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 21
sudo apt install clangd-21 clang-tidy-21
```

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

### Install Library and Headers

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/CMakeLists.txt

Installs the built library targets (static, shared, runtime) and header files to their designated destinations. Ensures the library and its public headers are available for external use.

```cmake
INSTALL(TARGETS ${BTCPP_LIBRARY}
    EXPORT ${BTCPP_LIBRARY}Targets
    ARCHIVE DESTINATION ${BTCPP_LIB_DESTINATION}
    LIBRARY DESTINATION ${BTCPP_LIB_DESTINATION}
    RUNTIME DESTINATION ${BTCPP_BIN_DESTINATION}
    INCLUDES DESTINATION ${BTCPP_INCLUDE_DESTINATION}
    )

INSTALL( DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/include/ 
    DESTINATION ${BTCPP_INCLUDE_DESTINATION}
    FILES_MATCHING PATTERN "*.h*" )
```

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

### Valid Instance Names Examples

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/docs/name_validation_rules.md

Examples of instance names that are valid, demonstrating relaxed rules for XML attribute values.

```plaintext
My Action           (spaces allowed)
node.name           (periods allowed)
Success 1           (spaces allowed)
检查门状态          (Unicode allowed)
```

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

### Build libzmq with CMake

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/cppzmq/README.md

Steps to clone, build, and install libzmq using CMake. Ensure libzmq is built and installed before building cppzmq.

```bash
git clone https://github.com/zeromq/libzmq.git
cd libzmq
mkdir build
cd build
cmake ..
sudo make -j4 install
```

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

### Compile Example Function

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/examples/CMakeLists.txt

Defines a reusable function to compile example executables, linking necessary libraries.

```cmake
function(CompileExample name)
    add_executable(${name}  ${name}.cpp )
    target_link_libraries(${name} ${BTCPP_LIBRARY}  bt_sample_nodes )
endfunction()
```

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

### Install Clang-Tidy for Linting

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/CLAUDE.md

Install clang-tidy version 21 and related tools. This is required for running static analysis on the codebase.

```bash
wget https://apt.llvm.org/llvm.sh && chmod +x llvm.sh
sudo ./llvm.sh 21
sudo apt install clangd-21 clang-tidy-21
```

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

### Install BehaviorTree.CPP with Conan

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/README.md

Steps to install BehaviorTree.CPP using the Conan package manager. Requires CMake 3.23 or newer.

```bash
conan install . -s build_type=Release --build=missing
cmake --preset conan-release
cmake --build --preset conan-release
```

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

### Install Pre-commit Hooks

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/CLAUDE.md

Install pre-commit hooks for automated linting and formatting checks before committing code. This ensures code style consistency.

```bash
pre-commit install
```

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

### Basic Coroutine Creation and Execution

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/minicoro/README.md

This example shows how to initialize a coroutine descriptor, create a coroutine, resume it to execute, and then destroy it. It demonstrates the lifecycle of a coroutine, including yielding and resuming.

```c
#define MINICORO_IMPL
#include "minicoro.h"
#include <stdio.h>

// Coroutine entry function.
void coro_entry(mco_coro* co) {
  printf("coroutine 1\n");
  mco_yield(co);
  printf("coroutine 2\n");
}

int main() {
  // First initialize a `desc` object through `mco_desc_init`.
  mco_desc desc = mco_desc_init(coro_entry, 0);
  // Configure `desc` fields when needed (e.g. customize user_data or allocation functions).
  desc.user_data = NULL;
  // Call `mco_create` with the output coroutine pointer and `desc` pointer.
  mco_coro* co;
  mco_result res = mco_create(&co, &desc);
  assert(res == MCO_SUCCESS);
  // The coroutine should be now in suspended state.
  assert(mco_status(co) == MCO_SUSPENDED);
  // Call `mco_resume` to start for the first time, switching to its context.
  res = mco_resume(co); // Should print "coroutine 1".
  assert(res == MCO_SUCCESS);
  // We get back from coroutine context in suspended state (because it's unfinished).
  assert(mco_status(co) == MCO_SUSPENDED);
  // Call `mco_resume` to resume for a second time.
  res = mco_resume(co); // Should print "coroutine 2".
  assert(res == MCO_SUCCESS);
  // The coroutine finished and should be now dead.
  assert(mco_status(co) == MCO_DEAD);
  // Call `mco_destroy` to destroy the coroutine.
  res = mco_destroy(co);
  assert(res == MCO_SUCCESS);
  return 0;
}
```

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

### Basic zmq.hpp Usage

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/cppzmq/README.md

A minimal example demonstrating the inclusion of zmq.hpp, context creation, socket binding, and sending a message. Requires C++11.

```cpp
#include <zmq.hpp>

int main()
{
    zmq::context_t ctx;
    zmq::socket_t sock(ctx, zmq::socket_type::push);
    sock.bind("inproc://test");
    sock.send(zmq::str_buffer("Hello, world"), zmq::send_flags::dontwait);
}
```

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

### Invalid Instance Names Examples

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/docs/name_validation_rules.md

Examples of instance names that are invalid due to containing null or control characters.

```plaintext
name_with_null\0    (null character)
name_with_bell\x07  (control character)
```

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

### Static Linking Example

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/examples/CMakeLists.txt

Compiles an executable with static linking to the BehaviorTree.CPP library and sample nodes.

```cmake
add_executable(t01_first_tree_static  t01_build_your_first_tree.cpp )
target_compile_definitions(t01_first_tree_static PRIVATE "MANUAL_STATIC_LINKING")
target_link_libraries(t01_first_tree_static ${BTCPP_LIBRARY}   bt_sample_nodes )
```

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

### Build libfuzzer Harness for BehaviorTree.CPP

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/fuzzing/README.md

Use this command to configure the build for libfuzzer. Ensure clang is installed.

```bash
mkdir build_libfuzzer && cd build_libfuzzer
cmake -DENABLE_FUZZING=ON ..
```

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

### Example minitrace usage in C

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/minitrace/README.md

Demonstrates initialization, metadata setting, timed blocks, steps, instant events, and shutdown within a C application. Ensure MTR_ENABLED is defined for profiling.

```c
int main(int argc, const char *argv[]) {
  int i;
  mtr_init("trace.json");

  MTR_META_PROCESS_NAME("minitrace_test");
  MTR_META_THREAD_NAME("main thread");

  int long_running_thing_1;
  int long_running_thing_2;

  MTR_START("background", "long_running", &long_running_thing_1);
  MTR_START("background", "long_running", &long_running_thing_2);

  MTR_BEGIN("main", "outer");
  usleep(80000);
  for (i = 0; i < 3; i++) {
    MTR_BEGIN("main", "inner");
    usleep(40000);
    MTR_END("main", "inner");
    usleep(10000);
  }
  MTR_STEP("background", "long_running", &long_running_thing_1, "middle step");
  usleep(80000);
  MTR_END("main", "outer");

  usleep(50000);
  MTR_INSTANT("main", "the end");
  usleep(10000);
  MTR_FINISH("background", "long_running", &long_running_thing_1);
  MTR_FINISH("background", "long_running", &long_running_thing_2);

  mtr_flush();
  mtr_shutdown();
  return 0;
}
```

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

### Build cppzmq with CMake

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/cppzmq/README.md

Steps to clone, build, and install cppzmq using CMake. You can optionally skip building tests.

```bash
git clone https://github.com/zeromq/cppzmq.git
cd cppzmq
mkdir build
cd build
cmake .. or cmake -DCPPZMQ_BUILD_TESTS=OFF ..
```

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

### XML Post-conditions Example

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/docs/pre_postconditions.md

This example demonstrates the usage of post-condition attributes to execute scripts after a node completes with SUCCESS, FAILURE, or is HALTED.

```xml
<MyAction
    _onSuccess="result := 'ok'"
    _onFailure="result := 'failed'"
    _onHalted="result := 'interrupted'"/>
```

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

### Valid Model/Port Names Examples

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/docs/name_validation_rules.md

Examples of names that adhere to the validation rules for model and port names.

```plaintext
MyAction
my_action
My-Action
检查门状态      (Chinese)
ドアを開ける    (Japanese)
Tür_öffnen      (German)
```

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

### Dynamic Linking Example

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/examples/CMakeLists.txt

Compiles an executable with dynamic linking to the BehaviorTree.CPP library.

```cmake
add_executable(t01_first_tree_dynamic  t01_build_your_first_tree.cpp )
target_link_libraries(t01_first_tree_dynamic ${BTCPP_LIBRARY}  )
```

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

### Build BehaviorTree.CPP with CMake (Manual Dependencies)

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/README.md

Build BehaviorTree.CPP using CMake when dependencies like ZeroMQ and SQLite are already installed and Conan is not used.

```bash
mkdir build_release
cmake -S . -B build_release
cmake --build build_release --parallel
```

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

### Invalid Model/Port Names Examples

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/docs/name_validation_rules.md

Examples of names that violate the validation rules for model and port names, with reasons provided.

```plaintext
My Action       (contains space)
request.name    (contains period)
My<Node>        (contains XML chars)
path/to/node    (contains path separator)
Root            (reserved)
```

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

### Start a timed event with a pointer

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/minitrace/README.md

Starts a timed event that can be later finished or stepped. Requires a pointer to associate with the event. Ensure MTR_ENABLED is defined.

```c
MTR_START("background", "long_running", &long_running_thing_1);
```

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

### Add Executable: bt4_plugin_manifest

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/tools/CMakeLists.txt

Defines the bt4_plugin_manifest executable, linking it to the BehaviorTree.CPP library and installing it to the binary destination.

```cmake
add_executable(bt4_plugin_manifest         bt_plugin_manifest.cpp )
target_link_libraries(bt4_plugin_manifest  ${BTCPP_LIBRARY} )
install(TARGETS bt4_plugin_manifest
        DESTINATION ${BTCPP_BIN_DESTINATION} )
```

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

### Add Executable: bt4_log_cat

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/tools/CMakeLists.txt

Defines the bt4_log_cat executable, linking it to the BehaviorTree.CPP library and installing it to the binary destination.

```cmake
# add_executable(bt4_log_cat         bt_log_cat.cpp )
# target_link_libraries(bt4_log_cat  ${BTCPP_LIBRARY} )
# install(TARGETS bt4_log_cat
#         DESTINATION ${BTCPP_BIN_DESTINATION} )
```

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

### Fibonacci Generator Coroutine Example

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/minicoro/README.md

This example demonstrates how to create a coroutine that generates Fibonacci numbers up to a specified limit. It utilizes `mco_push` and `mco_pop` for inter-coroutine communication and `mco_yield`/`mco_resume` for control flow.

```c
#define MINICORO_IMPL
#include "minicoro.h"
#include <stdio.h>

static void fail(const char* message, mco_result res) {
  printf("%s: %s\n", message, mco_result_description(res));
  exit(-1);
}

static void fibonacci_coro(mco_coro* co) {
  unsigned long m = 1;
  unsigned long n = 1;

  /* Retrieve max value. */
  unsigned long max;
  mco_result res = mco_pop(co, &max, sizeof(max));
  if(res != MCO_SUCCESS)
    fail("Failed to retrieve coroutine storage", res);

  while(1) {
    /* Yield the next Fibonacci number. */
    mco_push(co, &m, sizeof(m));
    res = mco_yield(co);
    if(res != MCO_SUCCESS)
      fail("Failed to yield coroutine", res);

    unsigned long tmp = m + n;
    m = n;
    n = tmp;
    if(m >= max)
      break;
  }

  /* Yield the last Fibonacci number. */
  mco_push(co, &m, sizeof(m));
}

int main() {
  /* Create the coroutine. */
  mco_coro* co;
  mco_desc desc = mco_desc_init(fibonacci_coro, 0);
  mco_result res = mco_create(&co, &desc);
  if(res != MCO_SUCCESS)
    fail("Failed to create coroutine", res);

  /* Set storage. */
  unsigned long max = 1000000000;
  mco_push(co, &max, sizeof(max));

  int counter = 1;
  while(mco_status(co) == MCO_SUSPENDED) {
    /* Resume the coroutine. */
    res = mco_resume(co);
    if(res != MCO_SUCCESS)
      fail("Failed to resume coroutine", res);

    /* Retrieve storage set in last coroutine yield. */
    unsigned long ret = 0;
    res = mco_pop(co, &ret, sizeof(ret));
    if(res != MCO_SUCCESS)
      fail("Failed to retrieve coroutine storage", res);
    printf("fib %d = %lu\n", counter, ret);
    counter = counter + 1;
  }

  /* Destroy the coroutine. */
  res = mco_destroy(co);
  if(res != MCO_SUCCESS)
    fail("Failed to destroy coroutine", res);
  return 0;
}

```

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

### Add Executable: bt4_recorder

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/tools/CMakeLists.txt

Conditionally defines the bt4_recorder executable, linking it to the BehaviorTree.CPP library and cppzmq, and installs it. This target is enabled when BTCPP_GROOT_INTERFACE is set.

```cmake
# FIXME! This target doesn't build because behaviortree_cpp/flatbuffers/BT_logger_generated.h
# doesn't get generated.
# It was being silently ignored because it was included only if ZMQ_FOUND was set, but that check
# was wrong for two reasons:
# 1) The actual variable name set on FindZeroMQ.cmake is ZeroMQ_FOUND not ZMQ_FOUND
# 2) This target does not depend on ZeroMQ, but actually on its C++ wrapper cppzmq.
# Ideally we should check for cppzmq_FOUND, but because that would be only set in non-vendored mode
# and furthermore it would not be set on this scope, I chose to use BTCPP_GROOT_INTERFACE as the check
# for now.
#if( BTCPP_GROOT_INTERFACE )
#    add_executable(bt4_recorder         bt_recorder.cpp )
#    target_link_libraries(bt4_recorder  ${BTCPP_LIBRARY} cppzmq)
#    install(TARGETS bt4_recorder
#            DESTINATION ${BTCPP_BIN_DESTINATION} )
#endif()
```

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

### Add Executable: bt4_nodes_model

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/tools/CMakeLists.txt

Defines the bt4_nodes_model executable, linking it to the BehaviorTree.CPP library and installing it to the binary destination.

```cmake
add_executable(bt4_nodes_model         bt_nodes_model.cpp )
target_link_libraries(bt4_nodes_model  ${BTCPP_LIBRARY} )
install(TARGETS bt4_nodes_model
        DESTINATION ${BTCPP_BIN_DESTINATION} )
```

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

### Multi-part Message Send/Receive with zmq_addon.hpp

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/cppzmq/README.md

An example using zmq_addon.hpp to send and receive multi-part messages over TCP. It demonstrates dynamic endpoint binding and connection, and uses helper functions for sending/receiving multipart messages. Requires C++11.

```cpp
#include <iostream>
#include <zmq_addon.hpp>

int main()
{
    zmq::context_t ctx;
    zmq::socket_t sock1(ctx, zmq::socket_type::push);
    zmq::socket_t sock2(ctx, zmq::socket_type::pull);
    sock1.bind("tcp://127.0.0.1:*");
    const std::string last_endpoint =
        sock1.get(zmq::sockopt::last_endpoint);
    std::cout << "Connecting to "
              << last_endpoint << std::endl;
    sock2.connect(last_endpoint);

    std::array<zmq::const_buffer, 2> send_msgs = {
        zmq::str_buffer("foo"),
        zmq::str_buffer("bar!")
    };
    if (!zmq::send_multipart(sock1, send_msgs))
        return 1;

    std::vector<zmq::message_t> recv_msgs;
    const auto ret = zmq::recv_multipart(
        sock2, std::back_inserter(recv_msgs));
    if (!ret)
        return 1;
    std::cout << "Got " << *ret
              << " messages" << std::endl;
    return 0;
}
```

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

### Miscellaneous Functions

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/minicoro/README.md

Utility functions for getting the currently running coroutine and result descriptions.

```APIDOC
## mco_running

### Description
Returns the coroutine that is currently executing on the calling thread.

### Signature
mco_coro* mco_running(void)

### Returns
mco_coro* - Pointer to the running coroutine, or NULL if no coroutine is running on the current thread.
```

```APIDOC
## mco_result_description

### Description
Gets a human-readable string description for a given `mco_result` code.

### Signature
const char* mco_result_description(mco_result res)

### Parameters
- **res** (mco_result) - The result code to describe.

### Returns
const char* - A string describing the result code.
```

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

### Profile a C function block

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/minitrace/README.md

Use MTR_BEGIN and MTR_END to mark the start and end of a code block for profiling in C. Ensure MTR_ENABLED is defined.

```c
MTR_BEGIN("GFX", "RasterizeTriangle")
...
MTR_END("GFX", "RasterizeTriangle")
```

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

### XML Example of Type Mismatch Error

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/docs/PORT_CONNECTION_RULES.md

This XML snippet demonstrates a scenario where a type mismatch between strongly typed ports causes an error during tree creation. NodeA creates an entry as an integer, while NodeB attempts to read it as a string.

```xml
<Sequence>
    <NodeA output_int="{value}" />      <!-- Creates entry as int -->
    <NodeB input_string="{value}" />    <!-- Tries to read as string - ERROR -->
</Sequence>
```

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

### Run BehaviorTree.cpp Tests with Pixi

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/CLAUDE.md

Execute tests using the Pixi environment. This command ensures tests are run with the correct dependencies and configurations.

```bash
pixi run test
```

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

### Initialize minitrace

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/minitrace/README.md

Call this function during application initialization to set up the trace file. Ensure MTR_ENABLED is defined when profiling.

```c
mtr_init("trace.json");
```

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

### String Conversion for Port Connection

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/docs/PORT_CONNECTION_RULES.md

Use XML to set a string value on the blackboard, which can then be read by a typed input port if a `convertFromString<T>()` specialization exists.

```xml
<Sequence>
    <!-- Creates blackboard entry "value" as string with value "42" -->
    <SetBlackboard value="42" output_key="value" />
    <!-- Reads "value" as int - OK because string can convert to int -->
    <NodeExpectingInt input="{value}" />
</Sequence>
```

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

### Build BehaviorTree.CPP with Pixi

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/README.md

Build BehaviorTree.CPP within a Pixi project (conda virtual environment).

```bash
pixi run build
```

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

### Run All Pre-commit Hooks

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/CLAUDE.md

Execute all configured pre-commit hooks across the repository. This is useful for checking code style and quality.

```bash
pre-commit run -a
```

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

### Run Clang-Tidy with BehaviorTree.cpp

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/CLAUDE.md

Execute clang-tidy for static analysis. Ensure the build directory exists and contains compile_commands.json for accurate analysis.

```bash
./run_clang_tidy.sh [build_path]
```

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

### Finish a timed event with a pointer

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/minitrace/README.md

Ends a timed event that was previously started with MTR_START, using its associated pointer. Ensure MTR_ENABLED is defined.

```c
MTR_FINISH("background", "long_running", &long_running_thing_1);
```

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

### Create Plugin Library

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/examples/CMakeLists.txt

Builds a shared library for a BehaviorTree.CPP plugin, defining BT_PLUGIN_EXPORT and linking dependencies.

```cmake
# library must be SHARED
add_library(test_plugin_action SHARED plugin_example/plugin_action.cpp )
# you must set the definition BT_PLUGIN_EXPORT
target_compile_definitions(test_plugin_action PRIVATE  BT_PLUGIN_EXPORT )
# remove the "lib" prefix. Name of the file will be test_plugin_action.so
set_target_properties(test_plugin_action PROPERTIES PREFIX "")
# link dependencies as usual
target_link_libraries(test_plugin_action ${BTCPP_LIBRARY} )
```

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

### Build AFL++ Harness for BehaviorTree.CPP

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/fuzzing/README.md

Configure the build for AFL++ by setting the CC and CXX environment variables and enabling the USE_AFLPLUSPLUS CMake option.

```bash
export CC=afl-clang-fast
export CXX=afl-clang-fast++
mkdir build_afl && cd build_afl
cmake -DENABLE_FUZZING=ON -DUSE_AFLPLUSPLUS=ON ..
```

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

### Create Plugin Executor

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/examples/CMakeLists.txt

Compiles an executable that will load and run the BehaviorTree.CPP plugin.

```cmake
add_executable(test_plugin_executor  plugin_example/plugin_executor.cpp )
target_link_libraries(test_plugin_executor ${BTCPP_LIBRARY})
```

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

### Include Minicoro Implementation

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/minicoro/README.md

To use minicoro, define MINICORO_IMPL in one .c file before including the header. Include the header normally in other parts of your program.

```c
#define MINICORO_IMPL
#include "minicoro.h"
```

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

### JSON Format Support for Custom Types

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/docs/PORT_CONNECTION_RULES.md

Illustrates how to initialize a custom type port (Point2D) using JSON format with a 'json:' prefix. This provides an alternative to string-based conversion for complex types.

```cpp
InputPort<Point2D>("pointE", R"(json:{"x":9,"y":10})")", "description")
```

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

### Run BehaviorTree.cpp Tests Directly

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/CLAUDE.md

Execute the test executable directly from the build directory. This allows for more granular control over test execution.

```bash
./build/tests/behaviortree_cpp_test
```

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

### minicoro Coroutine API Reference

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/minicoro/README.md

This section lists all available functions for managing coroutines, including initialization, creation, destruction, and state management. It also covers the storage interface for passing data between coroutines.

```c
/* Structure used to initialize a coroutine. */
typedef struct mco_desc {
  void (*func)(mco_coro* co); /* Entry point function for the coroutine. */
  void* user_data;            /* Coroutine user data, can be get with `mco_get_user_data`. */
  /* Custom allocation interface. */
  void* (*malloc_cb)(size_t size, void* allocator_data); /* Custom allocation function. */
  void  (*free_cb)(void* ptr, void* allocator_data);     /* Custom deallocation function. */
  void* allocator_data;       /* User data pointer passed to `malloc`/`free` allocation functions. */
  size_t storage_size;        /* Coroutine storage size, to be used with the storage APIs. */
  /* These must be initialized only through `mco_init_desc`. */
  size_t coro_size;           /* Coroutine structure size. */
  size_t stack_size;          /* Coroutine stack size. */
} mco_desc;

/* Coroutine functions. */
mco_desc mco_desc_init(void (*func)(mco_coro* co), size_t stack_size);  /* Initialize description of a coroutine. When stack size is 0 then MCO_DEFAULT_STACK_SIZE is used. */
mco_result mco_init(mco_coro* co, mco_desc* desc);                      /* Initialize the coroutine. */
mco_result mco_uninit(mco_coro* co);                                    /* Uninitialize the coroutine, may fail if it's not dead or suspended. */
mco_result mco_create(mco_coro** out_co, mco_desc* desc);               /* Allocates and initializes a new coroutine. */
mco_result mco_destroy(mco_coro* co);                                   /* Uninitialize and deallocate the coroutine, may fail if it's not dead or suspended. */
mco_result mco_resume(mco_coro* co);                                    /* Starts or continues the execution of the coroutine. */
mco_result mco_yield(mco_coro* co);                                     /* Suspends the execution of a coroutine. */
mco_state mco_status(mco_coro* co);                                     /* Returns the status of the coroutine. */
void* mco_get_user_data(mco_coro* co);                                  /* Get coroutine user data supplied on coroutine creation. */

/* Storage interface functions, used to pass values between yield and resume. */
mco_result mco_push(mco_coro* co, const void* src, size_t len); /* Push bytes to the coroutine storage. Use to send values between yield and resume. */
mco_result mco_pop(mco_coro* co, void* dest, size_t len);       /* Pop bytes from the coroutine storage. Use to get values between yield and resume. */
mco_result mco_peek(mco_coro* co, void* dest, size_t len);      /* Like `mco_pop` but it does not consumes the storage. */
size_t mco_get_bytes_stored(mco_coro* co);                      /* Get the available bytes that can be retrieved with a `mco_pop`. */
size_t mco_get_storage_size(mco_coro* co);                      /* Get the total storage size. */

/* Misc functions. */
mco_coro* mco_running(void);                        /* Returns the running coroutine for the current thread. */
const char* mco_result_description(mco_result res); /* Get the description of a result. */
```

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

### Configure Minitrace Include Directories

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/minitrace/CMakeLists.txt

Sets the include directories for the minitrace library, making its headers accessible.

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

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

### Configure TinyXML2 Include Directories

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/tinyxml2/CMakeLists.txt

Sets the public include directories for the TinyXML2 target, making its headers accessible.

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

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

### Build BehaviorTree.cpp with CMake

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/CLAUDE.md

Use plain CMake for development builds. Ensure CMake 3.16.3+ and a C++17 compiler are available. The project exports CMAKE_EXPORT_COMPILE_COMMANDS=ON by default.

```bash
mkdir build && cmake -S . -B build && cmake --build build --parallel
```

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

### Fallback with Early Success

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/docs/pre_postconditions.md

Illustrates using `_successIf` in a Fallback to achieve early success. If `cache_valid` is true, `CachedResult` succeeds immediately without executing its logic.

```xml
<Fallback>
  <CachedResult _successIf="cache_valid"/>
  <ComputeResult/>
</Fallback>
```

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

### Record an instant event

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/minitrace/README.md

Records a single, non-timed event at the current point in execution. Ensure MTR_ENABLED is defined.

```c
MTR_INSTANT("main", "the end");
```

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

### Link cppzmq Static Library

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/cppzmq/README.md

Use this command in your CMakeLists.txt to link the static version of the cppzmq library to your project.

```cmake
target_link_libraries(*Your Project Name* cppzmq-static)
```

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

### Sequence with Conditional Skip

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/docs/pre_postconditions.md

Demonstrates using `_skipIf` in a Sequence to conditionally skip a node. If `already_at_goal` is true, `MoveToGoal` is skipped, and the sequence proceeds to `PickObject`.

```xml
<Sequence>
  <CheckBattery/>
  <MoveToGoal _skipIf="already_at_goal"/>
  <PickObject/>
</Sequence>
```

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

### Configure cppzmq with CMake

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/cppzmq/CMakeLists.txt

This CMake script finds the ZeroMQ library and configures cppzmq as an INTERFACE library. It links against either libzmq-static or libzmq, failing if neither is found.

```cmake
find_package(ZeroMQ REQUIRED)

add_library(cppzmq INTERFACE)

# This library doesn't use modern targets unfortunately.
#add_library(cppzmq::cppzmq ALIAS cppzmq)

target_include_directories(cppzmq
    INTERFACE
        ${CMAKE_CURRENT_SOURCE_DIR}
)

if(TARGET libzmq-static)
    target_link_libraries(cppzmq INTERFACE libzmq-static)
elseif(TARGET libzmq)
    target_link_libraries(cppzmq INTERFACE libzmq)
else()
    message(FATAL_ERROR "Unknown zeromq target name")
endif()
```

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

### Guarded Action with _while

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/docs/pre_postconditions.md

Shows how the `_while` attribute acts as a guard for an action. The action, `MoveToGoal`, continues execution only as long as the `battery_level` condition remains true.

```xml
<MoveToGoal _while="battery_level > 20"/>
```

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

### Coroutine Initialization and Management

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/minicoro/README.md

Functions for initializing, creating, destroying, and managing the lifecycle of coroutines.

```APIDOC
## mco_desc_init

### Description
Initializes a coroutine description structure. Use this to configure coroutine properties before creation.

### Signature
mco_desc mco_desc_init(void (*func)(mco_coro* co), size_t stack_size)

### Parameters
- **func** (void (*)(mco_coro* co)) - The entry point function for the coroutine.
- **stack_size** (size_t) - The desired stack size for the coroutine. If 0, `MCO_DEFAULT_STACK_SIZE` is used.

### Returns
mco_desc - An initialized coroutine description structure.
```

```APIDOC
## mco_init

### Description
Initializes an already allocated coroutine structure.

### Signature
mco_result mco_init(mco_coro* co, mco_desc* desc)

### Parameters
- **co** (mco_coro*) - Pointer to the coroutine structure to initialize.
- **desc** (mco_desc*) - Pointer to the coroutine description.

### Returns
mco_result - `MCO_SUCCESS` on success, or an error code otherwise.
```

```APIDOC
## mco_uninit

### Description
Uninitializes a coroutine. This function may fail if the coroutine is not in a dead or suspended state.

### Signature
mco_result mco_uninit(mco_coro* co)

### Parameters
- **co** (mco_coro*) - Pointer to the coroutine to uninitialize.

### Returns
mco_result - `MCO_SUCCESS` on success, or an error code otherwise.
```

```APIDOC
## mco_create

### Description
Allocates and initializes a new coroutine.

### Signature
mco_result mco_create(mco_coro** out_co, mco_desc* desc)

### Parameters
- **out_co** (mco_coro**) - Pointer to a pointer that will hold the newly created coroutine.
- **desc** (mco_desc*) - Pointer to the coroutine description.

### Returns
mco_result - `MCO_SUCCESS` on success, or an error code otherwise.
```

```APIDOC
## mco_destroy

### Description
Uninitializes and deallocates a coroutine. This function may fail if the coroutine is not in a dead or suspended state.

### Signature
mco_result mco_destroy(mco_coro* co)

### Parameters
- **co** (mco_coro*) - Pointer to the coroutine to destroy.

### Returns
mco_result - `MCO_SUCCESS` on success, or an error code otherwise.
```

```APIDOC
## mco_resume

### Description
Starts or continues the execution of the coroutine.

### Signature
mco_result mco_resume(mco_coro* co)

### Parameters
- **co** (mco_coro*) - Pointer to the coroutine to resume.

### Returns
mco_result - `MCO_SUCCESS` on success, or an error code otherwise.
```

```APIDOC
## mco_yield

### Description
Suspends the execution of the current coroutine.

### Signature
mco_result mco_yield(mco_coro* co)

### Parameters
- **co** (mco_coro*) - Pointer to the coroutine to yield.

### Returns
mco_result - `MCO_SUCCESS` on success, or an error code otherwise.
```

```APIDOC
## mco_status

### Description
Returns the current status of the coroutine.

### Signature
mco_state mco_status(mco_coro* co)

### Parameters
- **co** (mco_coro*) - Pointer to the coroutine.

### Returns
mco_state - The current state of the coroutine (e.g., `MCO_DEAD`, `MCO_SUSPENDED`, `MCO_RUNNING`).
```

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

### Set Minicoro Include Directories

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/minicoro/CMakeLists.txt

Configures the include directories for the minicoro library. The INTERFACE keyword means these include paths are propagated to targets that link against minicoro.

```cmake
target_include_directories(minicoro
    INTERFACE
        ${CMAKE_CURRENT_SOURCE_DIR}
)
```

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

### Run BehaviorTree.cpp Tests with CTest

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/CLAUDE.md

Execute all tests within the build directory using CTest. This is a standard way to run tests in CMake-based projects.

```bash
ctest --test-dir build
```

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

### Run Specific BehaviorTree.cpp Test

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/CLAUDE.md

Filter and run specific tests using Google Test's filtering mechanism. Replace 'TestName*' with the desired test suite or test case name.

```bash
./build/tests/behaviortree_cpp_test --gtest_filter="TestName*"
```

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

### Add Minitrace Static Library

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/minitrace/CMakeLists.txt

Defines the minitrace library as a static library and specifies its source files.

```cmake
add_library(minitrace STATIC
    minitrace.cpp
)
```

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

### Set Flatbuffers Include Directories

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/flatbuffers/CMakeLists.txt

Configures the include directories for the Flatbuffers library. The `${CMAKE_CURRENT_SOURCE_DIR}` is added as an interface include directory, making its headers available to targets that link against Flatbuffers.

```cmake
target_include_directories(flatbuffers
    INTERFACE
        ${CMAKE_CURRENT_SOURCE_DIR}
)

```

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

### Connect Generic Port to Any Type

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/docs/PORT_CONNECTION_RULES.md

A generic port can connect to any other port, regardless of its type.

```cpp
// Connection: OK - generic port accepts any type
OutputPort<>("output")           // generic, can write anything
InputPort<int>("input_int")      // expects int
```

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

### Add TinyXML2 Static Library

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/tinyxml2/CMakeLists.txt

Defines the TinyXML2 library as a static library, compiling the specified source files.

```cmake
add_library(tinyxml2 STATIC
    tinyxml2.cpp
)
```

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

### Generate .clangd Configuration

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/CMakeLists.txt

Generates a .clangd configuration file to specify compile flags for standalone header checking. This is useful for IDEs and static analysis tools.

```cmake
file(WRITE ${PROJECT_SOURCE_DIR}/.clangd
"CompileFlags:
  Add:
    - -xc++
    - -std=c++17
    - -I${PROJECT_SOURCE_DIR}/include
    - -I${PROJECT_SOURCE_DIR}/3rdparty
    - -I${PROJECT_SOURCE_DIR}/3rdparty/minitrace
    - -I${PROJECT_SOURCE_DIR}/3rdparty/tinyxml2
    - -I${PROJECT_SOURCE_DIR}/3rdparty/minicoro
")
```

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

### Connect Ports of the Same Type

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/docs/PORT_CONNECTION_RULES.md

Ports with the exact same data type are always compatible for connection.

```cpp
// Connection allowed
OutputPort<int>("value")    // writes int
InputPort<int>("value")     // reads int
```

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

### Flush trace data

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/minitrace/README.md

Manually flushes any buffered trace data to the output file. Ensure MTR_ENABLED is defined.

```c
mtr_flush();
```

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

### Create Minitrace Alias Target

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/minitrace/CMakeLists.txt

Creates an alias target for the minitrace library for easier referencing.

```cmake
add_library(minitrace::minitrace ALIAS minitrace)
```

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

### Set process name metadata

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/minitrace/README.md

Adds metadata to the trace to identify the process name. Ensure MTR_ENABLED is defined.

```c
MTR_META_PROCESS_NAME("minitrace_test");
```

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

### Include cppzmq in CMake Project

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/cppzmq/README.md

How to find and link the cppzmq library in your CMakeLists.txt file. This will automatically include libzmq.

```cmake
#find cppzmq wrapper, installed by make of cppzmq
find_package(cppzmq)
target_link_libraries(*Your Project Name* cppzmq)
```

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

### Create TinyXML2 Alias Target

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/tinyxml2/CMakeLists.txt

Creates an alias target for the TinyXML2 library, simplifying its usage in other CMake targets.

```cmake
add_library(tinyxml2::tinyxml2 ALIAS tinyxml2)
```

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

### Shutdown minitrace

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/minitrace/README.md

Call this function during application exit to finalize and write the trace data. Ensure MTR_ENABLED is defined when profiling.

```c
mtr_shutdown();
```

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

### XML Precondition Decorator

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/docs/pre_postconditions.md

Use the `<Precondition>` decorator node when a condition needs to be checked on every tick, even while the child node is RUNNING. With `else="RUNNING"`, the decorator returns RUNNING if the condition is false, keeping the tree active.

```xml
<!-- This checks the condition on every tick while child is RUNNING -->
<Precondition if="my_condition" else="RUNNING">
  <MyAction/>
</Precondition>
```

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

### Set Minitrace Compile Definitions

Source: https://github.com/behaviortree/behaviortree.cpp/blob/master/3rdparty/minitrace/CMakeLists.txt

Defines compilation flags for the minitrace library, enabling specific features.

```cmake
target_compile_definitions(minitrace
    PRIVATE
        MTR_ENABLED=True
)
```