Harden ARM64 CEF bundle handling in deploy_cef_app.sh

README.md

@@ -1 +1,153 @@
-`<!-- placeholder for codex to edit -->`
+<purpose>
+  You are a deployment documentation specialist. 
+
+  Your goal is to create a comprehensive, step-by-step deployment tutorial for a minimal CEF-based application on the RK3588 ARM64 target, using the provided software sources and the device constraints. The tutorial must cover every feature in the source (including browser windows, command-line switches, and the UNIX socket client), and must align with the target’s Debian 11.11, kernel 5.10.198 environment and its graphics stack.
+</purpose>
+
+<context>
+  <role>
+    Documentation Analyst / Technical Revisor.
+    <tone>Formal, coherent, impersonal, and extensive.</tone>
+    <domain>DevOps, embedded deployment, and software enablement.</domain>
+  </role>
+
+  <input_handling>
+      Treat [[software_applications_sources]] as the authoritative inventory of features and code paths. Treat [[hardware_firmware_software-constraints]] as binding operational limits for deployment choices. Assume no attachment files are provided unless explicitly specified.
+  </input_handling>
+
+  <constraints>
+    <constraint type="critical">TOTAL SANITIZATION: No identifier, name, date, location, serial number, license plate, status, or factual description from the template may remain in the result.</constraint>
+    <constraint type="critical">INFERENCE ALLOWED: Deduce, guess, or auto-complete information based on plausibility when the sources are incomplete.</constraint>
+    <constraint type="critical">CONFLICT RESOLUTION: If [[software_applications_sources]] and [[hardware_firmware_software-constraints]] or attachment data provide conflicting information for the same field, record BOTH values and tag the source (e.g., “Value X (Sources) / Value Y (Constraints)”).</constraint>
+    <constraint type="formatting">PRESERVE STRUCTURE: Maintain the hierarchy, section order, list styles, and indentation of this template when possible.</constraint>
+    <constraint type="operational">DEPLOYMENT LIMITS: No Docker/VM. Use native Debian Bullseye packages and systemd/cron where appropriate. Validate ARM64 compatibility or provide alternatives.</constraint>
+  </constraints>
+
+  <environment>
+    <architecture>aarch64 (ARM64)</architecture>
+    <os>Debian GNU/Linux 11.11 (bullseye)</os>
+    <kernel>Linux 5.10.198</kernel>
+    <soc>Rockchip RK3588 (octa-core: 4× Cortex-A76 + 4× Cortex-A55)</soc>
+    <memory>~32 GB LPDDR4 (no swap noted)</memory>
+    <gpu>Mali-G610 MC4 with OpenGL ES 3.2, OpenCL 3.0, Vulkan 1.2.162</gpu>
+    <npu>6 TOPS (INT4/INT8/INT16/FP16/BF16/TF32)</npu>
+    <storage>Primary eMMC ~116.5 GiB; secondary SATA/PCIe storage present</storage>
+    <display>Dual monitors detected (2560×1080 and 1152×864)</display>
+    <network>Gigabit Ethernet + Wi‑Fi 6 (wlan0)</network>
+  </environment>
+
+  <domain_notes>
+    <note>Deployment guidance must favor simplicity and native system services.</note>
+    <note>GPU and graphics guidance must respect ARM Mali support and Wayland/X11 availability.</note>
+    <note>All sections must explicitly map features to implementation steps and include verification.</note>
+  </domain_notes>
+</context>
+
+<variables>
+  <variable name="[[task_request]]" required="true">
+    <description>Create an ordered, detailed deployment tutorial for the minimal CEF application on the RK3588 board, covering all features and constraints.</description>
+  </variable>
+  <variable name="[[software_applications_sources]]" required="true">
+    <description>Source inventory of the CEF sample app, build scripts, and socket client implementation.</description>
+  </variable>
+  <variable name="[[hardware_firmware_software-constraints]]" required="true">
+    <description>Hardware/firmware/software constraints for the RK3588 target (Debian 11.11, kernel 5.10.198, Mali-G610 GPU, etc.).</description>
+  </variable>
+  <variable name="[[attachment_files]]" required="false">
+    <description>Additional textual files; if absent, explicitly note that no attachments were supplied.</description>
+  </variable>
+</variables>
+
+<instructions>
+  <instruction>1. Restate [[task_request]] as a single, concrete goal statement tailored to the RK3588 ARM64 target.</instruction>
+
+  <instruction>2. Extract and summarize the target environment as key–value facts, including OS, kernel, CPU, memory, GPU, and storage details that affect deployment.</instruction>
+
+  <instruction>3. Enumerate all software components from [[software_applications_sources]] (CEF app, build flow, command-line switches, multi-window behavior, UNIX socket client) and list their dependencies.</instruction>
+
+  <instruction>4. Plan tutorial sections from easiest to hardest, mapping every feature to a section.</instruction>
+
+  <instruction>5. For each section, provide:
+    (a) Included Features;
+    (b) Excluded/Deferred Features with reasons;
+    (c) Implementation Plan with numbered steps and commands;
+    (d) Capability Mapping linking features to deployment steps;
+    (e) A text-only pipeline diagram.
+  </instruction>
+
+  <instruction>6. Validate ARM64 compatibility for all dependencies (CEF, X11/Wayland, system libraries). If uncertain, provide alternatives or compilation guidance.</instruction>
+
+  <instruction>7. If any conflicts exist between sources, include an OBSERVATIONS section summarizing them.</instruction>
+
+  <instruction>8. Final pass: ensure all template data is replaced, all features are covered, and no Docker/VM guidance is present.</instruction>
+</instructions>
+
+<output_format_specification>
+  <format>Markdown</format>
+  <requirements>
+    <requirement>Provide a step-by-step deployment guide, ordered by ease of deployment.</requirement>
+    <requirement>Use headings, numbered lists, and code blocks for commands.</requirement>
+    <requirement>Include explicit Capability Mapping subsections in every deployment section.</requirement>
+  </requirements>
+</output_format_specification>
+
+<examples>
+  <example>
+    <input_data>
+      <task_request>Deploy the minimal CEF app on the RK3588 board without containers.</task_request>
+      <software_applications_sources>CEF app with CMake build, Wayland/Ozone flags, and a UNIX socket client.</software_applications_sources>
+      <hardware_firmware_software-constraints>Debian 11.11, kernel 5.10.198, ARM64, Mali-G610 GPU.</hardware_firmware_software-constraints>
+    </input_data>
+    <output>
+      Section 1: Build prerequisites (CMake, X11/Wayland libs)
+      Section 2: Fetch and unpack CEF ARM64 binaries or build from source
+      Section 3: Compile and run the CEF app with GPU/Wayland flags
+      Section 4: Enable UNIX socket client integration and test IPC
+    </output>
+  </example>
+
+  <example>
+    <input_data>
+      <task_request>Map all CEF app features to deployment steps.</task_request>
+    </input_data>
+    <output>
+      Capability Mapping:
+      - Multi-window Views UI: Implemented via CEF Views framework on X11/Wayland.
+      - Command-line URL override: Exposed as "--url" in startup script.
+      - GPU feature toggles: Passed via CEF command-line switches; verify using chrome://gpu.
+      - UNIX socket IPC: Build socket client and ensure /tmp/rovel.sock permissions.
+    </output>
+  </example>
+</examples>
+
+<self_check>
+  <checklist>
+    <item>Did I cover every feature in the source code (multi-window, URL switch, GPU flags, socket client)?</item>
+    <item>Did I order sections from easiest to hardest and include capability mappings?</item>
+    <item>Did I avoid Docker/VMs and use native Debian/systemd guidance?</item>
+    <item>Did I validate ARM64 compatibility or provide alternatives?</item>
+    <item>Did I include an OBSERVATIONS section if conflicts exist?</item>
+  </checklist>
+</self_check>
+
+<evaluation_notes>
+  <test_cases>
+    <case>CEF build on ARM64 with CMake and X11/Wayland dependencies</case>
+    <case>GPU feature flags (Vulkan, VAAPI) on Mali-G610</case>
+    <case>CEF multi-window creation via Views framework</case>
+    <case>UNIX socket client connectivity to /tmp/rovel.sock</case>
+  </test_cases>
+  <success_definition>All features from the source are addressed, and deployment steps are feasible on the RK3588 Debian Bullseye environment.</success_definition>
+</evaluation_notes>
+
+<documentation>
+  <usage>
+    <step>Replace placeholders with real data extracted from [[software_applications_sources]] and [[hardware_firmware_software-constraints]].</step>
+    <step>Provide practical commands and verification steps suitable for Debian 11.11 on ARM64.</step>
+    <step>If external research is required, summarize findings and provide alternatives when ARM64 compatibility is uncertain.</step>
+  </usage>
+  <known_limitations>
+    <limitation>CEF prebuilt binaries may not be available for ARM64; building from source may be required.</limitation>
+    <limitation>GPU acceleration flags can vary by driver support; validate using chrome://gpu.</limitation>
+  </known_limitations>
+</documentation>

deploy_cef_app.sh

@@ -0,0 +1,226 @@
+#!/bin/bash
+set -euo pipefail
+
+# Script: Deploy and build the minimal CEF application on Debian 11 (Bullseye) ARM64
+# Target: RK3588 Rockchip bare-metal
+# Purpose: Automate setup steps implied by the prior tutorial content (build prerequisites,
+#          obtain CEF binaries, configure/build the app, and provide run guidance).
+# Note: This script is designed to run from the user's home directory.
+
+# -----------------------------
+# Configuration Variables
+# -----------------------------
+SCRIPT_NAME="deploy_cef_app.sh"
+SOURCE_DIR_DEFAULT="$HOME/renhiyama-cefapp-sample"
+SOURCE_DIR="${SOURCE_DIR:-$SOURCE_DIR_DEFAULT}"
+CEF_VERSION_DEFAULT="130.1.16+g5a7e5ed+chromium-130.0.6723.117"
+CEF_VERSION="${CEF_VERSION:-$CEF_VERSION_DEFAULT}"
+CEF_BINARY_URL_DEFAULT="https://cef-builds.spotifycdn.com/cef_binary_${CEF_VERSION}_linux64_minimal.tar.bz2"
+CEF_BINARY_URL="${CEF_BINARY_URL:-}"
+BUILD_DIR_REL="src/build"
+BUILD_TYPE="Release"
+
+# Temporary directory for downloads
+TEMP_DIR=""
+
+# -----------------------------
+# Helper Functions
+# -----------------------------
+cleanup_temp() {
+  echo "[INFO] Cleaning up temporary files..."
+  if [ -n "${TEMP_DIR}" ] && [ -d "${TEMP_DIR}" ]; then
+    rm -rf "${TEMP_DIR}"
+    echo "[INFO] Removed temporary directory: ${TEMP_DIR}"
+  fi
+}
+trap cleanup_temp EXIT SIGINT SIGTERM
+
+error_exit() {
+  echo "[ERROR] $1" >&2
+  exit 1
+}
+
+run_checked() {
+  local description="$1"
+  shift
+  echo "[INFO] ${description}"
+  if ! "$@"; then
+    error_exit "Failed to ${description}."
+  fi
+}
+
+ensure_command() {
+  local tool_name="$1"
+  local package_name="$2"
+  if ! command -v "$tool_name" >/dev/null 2>&1; then
+    echo "[INFO] Tool '${tool_name}' not found. Installing '${package_name}'..."
+    if ! sudo apt install -y "$package_name"; then
+      error_exit "Failed to install '${package_name}'."
+    fi
+    echo "[INFO] '${package_name}' installed successfully."
+  else
+    echo "[INFO] Tool '${tool_name}' is already installed."
+  fi
+}
+
+ensure_package() {
+  local package_name="$1"
+  if ! dpkg -s "$package_name" >/dev/null 2>&1; then
+    echo "[INFO] Package '${package_name}' not installed. Installing..."
+    if ! sudo apt install -y "$package_name"; then
+      error_exit "Failed to install '${package_name}'."
+    fi
+  else
+    echo "[INFO] Package '${package_name}' is already installed."
+  fi
+}
+
+check_source_dir() {
+  if [ ! -d "$SOURCE_DIR" ]; then
+    echo "[ERROR] Source directory not found at: ${SOURCE_DIR}" >&2
+    echo "[ERROR] Set SOURCE_DIR to the path containing the CEF sample app sources." >&2
+    exit 1
+  fi
+  if [ ! -d "${SOURCE_DIR}/src" ]; then
+    error_exit "Expected 'src' directory not found under ${SOURCE_DIR}."
+  fi
+}
+
+verify_architecture() {
+  local arch
+  arch="$(uname -m)"
+  echo "[INFO] Detected architecture: ${arch}"
+  if [ "${arch}" = "aarch64" ] || [ "${arch}" = "arm64" ]; then
+    echo "[INFO] ARM64 detected. Ensure the CEF bundle matches ARM64."
+    if [ -z "${CEF_BINARY_URL}" ]; then
+      echo "[ERROR] CEF_BINARY_URL is empty on ARM64." >&2
+      echo "[ERROR] Provide an ARM64-compatible CEF tarball URL." >&2
+      exit 1
+    fi
+    if [ "${CEF_BINARY_URL}" = "${CEF_BINARY_URL_DEFAULT}" ]; then
+      echo "[ERROR] The default CEF URL targets linux64 (x86_64)." >&2
+      echo "[ERROR] Set CEF_BINARY_URL to an ARM64-compatible CEF minimal build archive." >&2
+      exit 1
+    fi
+  else
+    if [ -z "${CEF_BINARY_URL}" ]; then
+      CEF_BINARY_URL="${CEF_BINARY_URL_DEFAULT}"
+    fi
+  fi
+}
+
+prepare_build_dependencies() {
+  run_checked "update package lists" sudo apt update
+
+  ensure_command "curl" "curl"
+  ensure_command "wget" "wget"
+  ensure_command "git" "git"
+  ensure_command "cmake" "cmake"
+  ensure_command "make" "build-essential"
+  ensure_command "pkg-config" "pkg-config"
+  ensure_command "tar" "tar"
+
+  # X11 development dependencies needed by CEF on Linux
+  ensure_package "libx11-dev"
+  ensure_package "libxext-dev"
+  ensure_package "libxrender-dev"
+  ensure_package "libxrandr-dev"
+  ensure_package "libxcomposite-dev"
+  ensure_package "libxcursor-dev"
+  ensure_package "libxi-dev"
+  ensure_package "libxtst-dev"
+  ensure_package "libxss-dev"
+  ensure_package "libxdamage-dev"
+  ensure_package "libxfixes-dev"
+}
+
+fetch_cef_binary() {
+  if [ -d "${SOURCE_DIR}/cef_binary" ]; then
+    echo "[INFO] Existing cef_binary directory found at ${SOURCE_DIR}/cef_binary."
+    return 0
+  fi
+
+  if [ -z "${CEF_BINARY_URL}" ]; then
+    if [ -f "${SOURCE_DIR}/download_prebuilt_cef.sh" ]; then
+      echo "[INFO] Running download_prebuilt_cef.sh for CEF version ${CEF_VERSION}..."
+      if ! (cd "${SOURCE_DIR}" && CEF_VERSION="${CEF_VERSION}" ./download_prebuilt_cef.sh); then
+        error_exit "Failed to download CEF binaries via download_prebuilt_cef.sh."
+      fi
+      return 0
+    fi
+    error_exit "CEF_BINARY_URL is empty and download_prebuilt_cef.sh is missing."
+  fi
+
+  TEMP_DIR="$(mktemp -d)"
+  local archive_path="${TEMP_DIR}/cef_binary.tar.bz2"
+
+  echo "[INFO] Downloading CEF binary from: ${CEF_BINARY_URL}"
+  if ! curl -Lfo "${archive_path}" "${CEF_BINARY_URL}"; then
+    error_exit "Failed to download CEF binary archive."
+  fi
+
+  echo "[INFO] Extracting CEF binary archive..."
+  if ! tar -xvf "${archive_path}" -C "${TEMP_DIR}"; then
+    error_exit "Failed to extract CEF binary archive."
+  fi
+
+  local extracted_dir
+  extracted_dir="$(find "${TEMP_DIR}" -maxdepth 1 -type d -name 'cef_binary_*' | head -n 1)"
+  if [ -z "${extracted_dir}" ]; then
+    error_exit "Failed to locate extracted CEF directory."
+  fi
+
+  echo "[INFO] Copying CEF binaries into source tree..."
+
+  if ! mv "${extracted_dir}" "${SOURCE_DIR}/cef_binary"; then
+    error_exit "Failed to move CEF binaries into source tree."
+  fi
+}
+
+build_cef_app() {
+  local build_dir="${SOURCE_DIR}/${BUILD_DIR_REL}"
+  if [ ! -d "${build_dir}" ]; then
+    if ! mkdir -p "${build_dir}"; then
+      error_exit "Failed to create build directory ${build_dir}."
+    fi
+  fi
+
+  echo "[INFO] Configuring CEF app with CMake..."
+  if ! (cd "${build_dir}" && cmake ..); then
+    error_exit "CMake configuration failed."
+  fi
+
+  echo "[INFO] Building CEF app..."
+  if ! (cd "${build_dir}" && make -j"$(nproc)"); then
+    error_exit "Build failed."
+  fi
+}
+
+print_run_instructions() {
+  local exe_path="${SOURCE_DIR}/${BUILD_DIR_REL}/${BUILD_TYPE}/cefapp"
+  echo "[INFO] Build completed."
+  echo "[INFO] To run the application, execute:"
+  echo "  ${exe_path}"
+  echo "[INFO] Example with URL override:"
+  echo "  ${exe_path} --url=chrome://gpu"
+}
+
+# -----------------------------
+# Main Script Execution
+# -----------------------------
+echo "[INFO] Starting ${SCRIPT_NAME}..."
+
+echo "[INFO] Validating source directory..."
+check_source_dir
+
+verify_architecture
+
+prepare_build_dependencies
+
+fetch_cef_binary
+
+build_cef_app
+
+print_run_instructions
+
+echo "[INFO] ${SCRIPT_NAME} completed successfully."