### Installation Bundle Setup

Source: https://github.com/yhan-sun/p2wlan/blob/main/apps/flutter_client/linux/CMakeLists.txt

Configures the installation directory and ensures a clean bundle directory on each build.

```cmake
set(BUILD_BUNDLE_DIR "${PROJECT_BINARY_DIR}/bundle")
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

install(CODE "
  file(REMOVE_RECURSE \"${BUILD_BUNDLE_DIR}/\")
  " COMPONENT Runtime)
```

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

### Install Linux CLI

Source: https://github.com/yhan-sun/p2wlan/blob/main/README.en.md

Download and execute the Linux CLI installation script.

```bash
curl -fsSL https://raw.githubusercontent.com/yhan-sun/p2wlan/main/scripts/install-linux-cli.sh -o /tmp/p2wlan-install.sh
sudo sh /tmp/p2wlan-install.sh
```

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

### Run Acceptance Test Example

Source: https://github.com/yhan-sun/p2wlan/blob/main/scripts/dual-end/mini-air-smoke.md

Example command to execute the acceptance test. Replace placeholder variables with actual staging parameters.

```bash
cd <repo-root>

RUN_ID="dual-real-$(date +%Y%m%d-%H%M%S)"
ARTIFACT_ROOT="$PWD/target/acceptance-artifacts/$RUN_ID"
AB_SEQUENCE_DIR="$PWD/target/acceptance-sequences/$RUN_ID"
mkdir -p "$ARTIFACT_ROOT" "$AB_SEQUENCE_DIR"

env \
  ALLOW_STAGING_TEST=1 \
  ALLOW_REMOTE_RESTART=1 \
  AIR_HOST="<air-management-host>" \
  AIR_USER="<air-user>" \
  AIR_SSH_PORT=22 \
  AIR_SSH_KEY="<absolute-key-path>" \
  AIR_KNOWN_HOSTS_FILE="$HOME/.ssh/known_hosts" \
  REMOTE_CONTROL_URL="https://<control-host>" \
  NETWORK_ID="<dedicated-network>" \
  REAL_TUN=1 \
  ACCEPTANCE_MODE=strict \
  STRICT_PHASE=acceptance \
  ROUNDS=10 \
  DIRECT_TIMEOUT_S=45 \
  DIRECT_SUCCESS_TARGET_MS=3000 \
  PRIVILEGED_SUPERVISOR=1 \
  PERSIST_PRIVILEGED_SUPERVISOR=1 \
  RUN_ID="$RUN_ID" \
  ARTIFACT_ROOT="$ARTIFACT_ROOT" \
  AB_SEQUENCE_DIR="$AB_SEQUENCE_DIR" \
  scripts/dual-end/mini-air-smoke.sh \
  2>&1 | tee "$ARTIFACT_ROOT-terminal.log"
```

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

### Start Listening Node (A)

Source: https://github.com/yhan-sun/p2wlan/blob/main/scripts/punch-research/LIVE_PROTOCOL.md

Initiates the listening node on host A, specifying the port and STUN server, and logs the session output.

```bash
scripts/punch-research/live_run.sh listen 9900 stun.l.google.com:19302 \
    --hold-s 10 --session-out /tmp/live_a.json | tee /tmp/live_a.log
```

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

### Start and verify virtual network

Source: https://github.com/yhan-sun/p2wlan/blob/main/README.en.md

Initialize the network connection and check the current status.

```bash
p2wlan up
p2wlan status
```

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

### Installation of Application and Assets

Source: https://github.com/yhan-sun/p2wlan/blob/main/apps/flutter_client/linux/CMakeLists.txt

Defines installation rules for the binary, ICU data, libraries, plugins, and native assets.

```cmake
set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}/lib")

install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)

foreach(bundled_library ${PLUGIN_BUNDLED_LIBRARIES})
  install(FILES "${bundled_library}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endforeach(bundled_library)

set(NATIVE_ASSETS_DIR "${PROJECT_BUILD_DIR}native_assets/linux/")
install(DIRECTORY "${NATIVE_ASSETS_DIR}"
   DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
   COMPONENT Runtime)
```

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

### Installation Rules

Source: https://github.com/yhan-sun/p2wlan/blob/main/apps/flutter_client/windows/CMakeLists.txt

Defines the installation directory and copies necessary files, including the executable, ICU data, libraries, and assets, to the output bundle.

```cmake
set(BUILD_BUNDLE_DIR "$<TARGET_FILE_DIR:${BINARY_NAME}>")
# Make the "install" step default, as it's required to run.
set(CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD 1)
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}")

install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)

if(PLUGIN_BUNDLED_LIBRARIES)
  install(FILES "${PLUGIN_BUNDLED_LIBRARIES}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()

# Copy the native assets provided by the build.dart from all packages.
set(NATIVE_ASSETS_DIR "${PROJECT_BUILD_DIR}native_assets/windows/")
install(DIRECTORY "${NATIVE_ASSETS_DIR}"
   DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
   COMPONENT Runtime)

# Fully re-copy the assets directory on each build to avoid having stale files
# from a previous install.
set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)

# Install the AOT library on non-Debug builds only.
install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  CONFIGURATIONS Profile;Release
  COMPONENT Runtime)
```

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

### Start Connecting Node (B)

Source: https://github.com/yhan-sun/p2wlan/blob/main/scripts/punch-research/LIVE_PROTOCOL.md

Initiates the connecting node on host B after node A is ready, targeting A's IP address.

```bash
scripts/punch-research/live_run.sh connect <A_IP> 9900 stun.l.google.com:19302 \
    --hold-s 10 --session-out /tmp/live_b.json | tee /tmp/live_b.log
```

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

### Install and run cargo-fuzz

Source: https://github.com/yhan-sun/p2wlan/blob/main/fuzz/README.md

Commands to install the cargo-fuzz tool and execute the pnch_parser fuzz target.

```bash
cargo install cargo-fuzz
cargo fuzz run pnch_parser
```

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

### Flutter Library Setup

Source: https://github.com/yhan-sun/p2wlan/blob/main/apps/flutter_client/windows/flutter/CMakeLists.txt

Defines the Flutter library interface, includes necessary headers, and links the required Windows library.

```cmake
# === Flutter Library ===
set(FLUTTER_LIBRARY "${EPHEMERAL_DIR}/flutter_windows.dll")

# Published to parent scope for install step.
set(FLUTTER_LIBRARY ${FLUTTER_LIBRARY} PARENT_SCOPE)
set(FLUTTER_ICU_DATA_FILE "${EPHEMERAL_DIR}/icudtl.dat" PARENT_SCOPE)
set(PROJECT_BUILD_DIR "${PROJECT_DIR}/build/" PARENT_SCOPE)
set(AOT_LIBRARY "${PROJECT_DIR}/build/windows/app.so" PARENT_SCOPE)

list(APPEND FLUTTER_LIBRARY_HEADERS
  "flutter_export.h"
  "flutter_windows.h"
  "flutter_messenger.h"
  "flutter_plugin_registrar.h"
  "flutter_texture_registrar.h"
)
list(TRANSFORM FLUTTER_LIBRARY_HEADERS PREPEND "${EPHEMERAL_DIR}/")
add_library(flutter INTERFACE)
target_include_directories(flutter INTERFACE
  "${EPHEMERAL_DIR}"
)
target_link_libraries(flutter INTERFACE "${FLUTTER_LIBRARY}.lib")
add_dependencies(flutter flutter_assemble)
```

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

### Flutter Assets and AOT Library Installation

Source: https://github.com/yhan-sun/p2wlan/blob/main/apps/flutter_client/linux/CMakeLists.txt

Installs the flutter assets and the AOT library for non-debug builds.

```cmake
set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)

if(NOT CMAKE_BUILD_TYPE MATCHES "Debug")
  install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()
```

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

### Manual build and run commands

Source: https://github.com/yhan-sun/p2wlan/blob/main/apps/flutter_client/README.md

Build the daemon and tray components manually, then launch the Flutter client with the daemon binary path specified.

```bash
# Build the daemon binary used by the Flutter desktop client.
cargo build -p p2wlan-daemon

# Run the lightweight menu bar / tray controller.
cargo build -p p2wlan-tray
target/debug/p2wlan-tray

# Run Flutter.
cd apps/flutter_client
P2WLAN_DAEMON_BIN=../../target/debug/p2wlan-daemon \
flutter run -d macos
```

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

### Path Observability JSON Wire Schema Example

Source: https://github.com/yhan-sun/p2wlan/blob/main/docs/path-observability.md

An example of the path_observability object with schema_version 1, capturing network generations, path lifecycle, and state metrics.

```json
{
  "schema_version": 1,
  "network_epoch": {
    "network_generation": 7,
    "peer_session_generation": 3,
    "remote_candidate_epoch": 11
  },
  "lifecycle": "online",
  "current_path": "direct",
  "previous_path": "relay",
  "transition_reason": "direct_committed",
  "path_age_ms": 42,
  "path_state_revision": 19,
  "direct_state": "committed",
  "relay_state": "usable",
  "recovery_state": "stable",
  "selected_path_mtu": 1360,
  "selected_udp_datagram_size": 1392
}
```

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

### Build and Run p2wlan-tray

Source: https://github.com/yhan-sun/p2wlan/blob/main/client/tray/README.md

Commands to compile the p2wlan-tray package and execute the resulting binary.

```bash
cargo build -p p2wlan-tray
target/debug/p2wlan-tray
```

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

### Sign in via CLI

Source: https://github.com/yhan-sun/p2wlan/blob/main/README.en.md

Use the login command to authenticate your session on servers or headless systems.

```bash
p2wlan login -u you@example.com
```

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

### Project Initialization and Build Configuration

Source: https://github.com/yhan-sun/p2wlan/blob/main/apps/flutter_client/windows/CMakeLists.txt

Sets the project name, minimum CMake version, and defines build configuration types for the Windows build.

```cmake
cmake_minimum_required(VERSION 3.14)
project(p2wlan_flutter_client LANGUAGES CXX)

# The name of the executable created for the application. Change this to change
# the on-disk name of your application.
set(BINARY_NAME "p2wlan_flutter_client")

# Explicitly opt in to modern CMake behaviors to avoid warnings with recent
# versions of CMake.
cmake_policy(VERSION 3.14...3.25)

# Define build configuration option.
get_property(IS_MULTICONFIG GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
if(IS_MULTICONFIG)
  set(CMAKE_CONFIGURATION_TYPES "Debug;Profile;Release"
    CACHE STRING "" FORCE)
else()
  if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
    set(CMAKE_BUILD_TYPE "Debug" CACHE
      STRING "Flutter build mode" FORCE)
    set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS
      "Debug" "Profile" "Release")
  endif()
endif()
```

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

### Project Initialization and Variables

Source: https://github.com/yhan-sun/p2wlan/blob/main/apps/flutter_client/linux/CMakeLists.txt

Sets the minimum CMake version, project name, binary name, and application identifier.

```cmake
cmake_minimum_required(VERSION 3.13)
project(runner LANGUAGES CXX)

# The name of the executable created for the application. Change this to change
# the on-disk name of your application.
set(BINARY_NAME "p2wlan_flutter_client")
# The unique GTK application identifier for this application. See:
# https://wiki.gnome.org/HowDoI/ChooseApplicationID
set(APPLICATION_ID "com.p2wlan.diagnostics")
```

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

### Flutter Library Path and Scope Configuration

Source: https://github.com/yhan-sun/p2wlan/blob/main/apps/flutter_client/linux/flutter/CMakeLists.txt

Defines the path to the Flutter library and exports necessary variables to the parent scope for the installation step.

```cmake
set(FLUTTER_LIBRARY "${EPHEMERAL_DIR}/libflutter_linux_gtk.so")

# Published to parent scope for install step.
set(FLUTTER_LIBRARY ${FLUTTER_LIBRARY} PARENT_SCOPE)
set(FLUTTER_ICU_DATA_FILE "${EPHEMERAL_DIR}/icudtl.dat" PARENT_SCOPE)
set(PROJECT_BUILD_DIR "${PROJECT_DIR}/build/" PARENT_SCOPE)
set(AOT_LIBRARY "${PROJECT_DIR}/build/lib/libapp.so" PARENT_SCOPE)
```

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

### Application Build and Output Configuration

Source: https://github.com/yhan-sun/p2wlan/blob/main/apps/flutter_client/linux/CMakeLists.txt

Adds the runner subdirectory, sets build dependencies, and configures the runtime output directory.

```cmake
add_subdirectory("runner")

# Run the Flutter tool portions of the build. This must not be removed.
add_dependencies(${BINARY_NAME} flutter_assemble)

set_target_properties(${BINARY_NAME}
  PROPERTIES
  RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/intermediates_do_not_run"
)
```

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

### Define Application Target

Source: https://github.com/yhan-sun/p2wlan/blob/main/apps/flutter_client/windows/runner/CMakeLists.txt

Sets up the executable target for the Windows build, including all necessary source files and resources.

```cmake
cmake_minimum_required(VERSION 3.14)
project(runner LANGUAGES CXX)

# Define the application target. To change its name, change BINARY_NAME in the
# top-level CMakeLists.txt, not the value here, or `flutter run` will no longer
# work.
#
# Any new source files that you add to the application should be added here.
add_executable(${BINARY_NAME} WIN32
  "flutter_window.cpp"
  "main.cpp"
  "utils.cpp"
  "win32_window.cpp"
  "${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
  "Runner.rc"
  "runner.exe.manifest"
)
```

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

### Run P2WLAN macOS development app

Source: https://github.com/yhan-sun/p2wlan/blob/main/apps/flutter_client/README.md

Use the one-command launcher to build the Rust daemon and launch the Flutter app on macOS.

```bash
./apps/flutter_client/scripts/run_test_app_macos.sh
```

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

### Apply Build Settings

Source: https://github.com/yhan-sun/p2wlan/blob/main/apps/flutter_client/windows/runner/CMakeLists.txt

Applies standard build settings to the defined binary target.

```cmake
# Apply the standard set of build settings. This can be removed for applications
# that need different build settings.
apply_standard_settings(${BINARY_NAME})
```

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

### Build p2wlan Control Plane and Relay

Source: https://github.com/yhan-sun/p2wlan/blob/main/README.en.md

Commands to build the Go-based control plane and relay binaries from the server directory.

```bash
cd server
go build -o p2wlan-control .
go build -o p2wlan-relay ./relay
```

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

### Run CLI diagnostics

Source: https://github.com/yhan-sun/p2wlan/blob/main/README.en.md

Use diagnostic tools to check connection paths and view real-time logs.

```bash
p2wlan doctor
p2wlan logs -f
```

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

### Define CMake Minimum Version and Project

Source: https://github.com/yhan-sun/p2wlan/blob/main/apps/flutter_client/linux/runner/CMakeLists.txt

Sets the minimum required CMake version and initializes the project with CXX language support.

```cmake
cmake_minimum_required(VERSION 3.13)
project(runner LANGUAGES CXX)
```

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

### CMake Minimum Version and Configuration

Source: https://github.com/yhan-sun/p2wlan/blob/main/apps/flutter_client/linux/flutter/CMakeLists.txt

Sets the required CMake version and includes generated configuration files from the ephemeral directory.

```cmake
cmake_minimum_required(VERSION 3.10)

set(EPHEMERAL_DIR "${CMAKE_CURRENT_SOURCE_DIR}/ephemeral")

# Configuration provided via flutter tool.
include(${EPHEMERAL_DIR}/generated_config.cmake)
```

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

### Bundle daemon for macOS

Source: https://github.com/yhan-sun/p2wlan/blob/main/apps/flutter_client/README.md

Run the build phase script to include the Rust daemon in the macOS app bundle.

```bash
apps/flutter_client/scripts/bundle_daemon_macos.sh
```

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

### Apply Standard Build Settings

Source: https://github.com/yhan-sun/p2wlan/blob/main/apps/flutter_client/linux/runner/CMakeLists.txt

Applies the standard set of build settings to the defined executable target.

```cmake
apply_standard_settings(${BINARY_NAME})
```

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

### System Dependency Configuration

Source: https://github.com/yhan-sun/p2wlan/blob/main/apps/flutter_client/linux/flutter/CMakeLists.txt

Finds and configures required system-level dependencies including GTK, GLIB, and GIO.

```cmake
find_package(PkgConfig REQUIRED)
pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk+-3.0)
pkg_check_modules(GLIB REQUIRED IMPORTED_TARGET glib-2.0)
pkg_check_modules(GIO REQUIRED IMPORTED_TARGET gio-2.0)
```