AGENTS

Agent Instructions — Miyoo Mini+ Cross-Development Environment

This file describes a fully provisioned Ubuntu (WSL) environment for cross-compiling, deploying, and debugging software for the Miyoo Mini+ handheld. Everything documented below is already installed and configured. Do not re-run the provisioning steps unless the user explicitly asks you to repair or reinstall something.

When in doubt about how a component was installed, the source of truth is the companion MMP Wiki (the Provisioning Steps/ articles).

---

Environment Overview

• Host: Windows with WSL; the default WSL distribution is Ubuntu (LTS).
• Purpose: Build C/C++ binaries that run on the Miyoo Mini+ (ARM), deploy them to the device over SSH, and debug them remotely.
• Target device: Miyoo Mini+ running a firmware with SSH support (e.g. Onion OS).
• Critical constraint: Cross-compiled binaries target ARM and run only on the device, not on the Ubuntu host (unless compatible ARM emulation is available). Never assume a freshly built device binary can be executed locally.

---

Cross-Compilation Toolchain

The Miyoo Mini+ toolchain (from GitHub user steward-fu) is installed under /opt:

• /opt/mmiyoo — Miyoo-specific tools and target files.
• /opt/prebuilt — the ARM cross-compiler toolchain.
• /opt/mmiyoo/bin is already on PATH (persisted in ~/.bashrc).

Compiler prefix: arm-linux-gnueabihf- (e.g. arm-linux-gnueabihf-gcc, arm-linux-gnueabihf-g++, arm-linux-gnueabihf-readelf).

Property	Value
Version	GCC 8.2.1 (2018/08/02)
Release	GNU Toolchain for the A-profile Architecture 8.2-2018-08
Target	arm-linux-gnueabihf
Architecture	armv7-a
FPU/Float	NEON, hard-float (--with-float=hard)
Thread Model	POSIX
Languages	C, C++, Fortran

Build a device binary like this:

arm-linux-gnueabihf-gcc \
    --output helloWorld \
    helloWorld.c

Verify a binary targets ARM Linux (expect Class: ELF32 and Machine: ARM):

arm-linux-gnueabihf-readelf \
    --file-header \
    helloWorld \
    | grep --extended-regexp 'Class:|Machine:'

Do not use the host gcc/g++ for device builds — that produces x86-64 binaries the Miyoo Mini+ cannot run.

---

Project Layout Conventions

Source projects live under ~/src:

• ~/src/mmiyoo/<project> — Miyoo Mini+ application projects (the canonical location for new device code).
• ~/src/MMP/src/tools — layout used to rebuild the on-device debugging binaries via build.sh.
• ~/src/bethington/ghidra-mcp — Ghidra MCP Server checkout (optional tooling).

---

Baseline Build Tooling (installed via apt)

All of the following are present at /usr/bin/*. Verify availability with command -v <name> before assuming something is missing.

• Core build tools: build-essential (gcc, g++, make, libc headers), cmake, ninja-build (ninja).
• Autotools: autoconf, automake, libtool + libtool-bin (the libtool executable), pkg-config.
• Build-script dependencies: gettext, m4, perl, python3.
• Source & file utilities: file, git, patch, rsync, sshpass, unzip, wget.

On Ubuntu, the libtool executable comes from libtool-bin; libtool alone does not provide it.

---

Deployment to the Device (SSH)

The device is reached over SSH. sshpass is installed so deployments can run non-interactively. Connection details depend on the firmware and LAN; common defaults used in the docs:

• User: root
• Example IP: 192.168.1.128
• Remote app dirs: under /mnt/SDCARD/... (e.g. /mnt/SDCARD/helloWorld).

Older firmware SSH stacks need weakened crypto negotiation. The standard option set is:

sshOptions=(
    -o StrictHostKeyChecking=accept-new
    -o MACs=hmac-sha1
    -o IgnoreUnknown=WarnWeakCrypto
    -o WarnWeakCrypto=no
)

Typical pattern: read the SSH password into SSHPASS, then stream a binary to the device with cat over SSH and chmod it executable. Always unset SSHPASS afterward. Remind the user to substitute their real ipAddress, user, and remoteDirectory.

---

On-Device Debugging Toolset

Prebuilt binary-analysis/debugging tools for the Miyoo Mini+ are available from the MMP repository and are deployed to the device at:

/mnt/SDCARD/.tmp_update/bin

Binary	Source / Version	Linkage	Use
addr2line	binutils 2.32	dynamic glibc	Map addresses to source lines (DEBUG info)
nm	binutils 2.32	dynamic glibc	List symbols
objdump	binutils 2.32	dynamic glibc	Disassemble, inspect relocations
readelf	binutils 2.32	dynamic glibc	Inspect ELF headers/sections/deps
file	file 5.39	dynamic glibc	Identify file types (uses magic.mgc)
gdb	gdb 8.3.1	dynamic glibc	On-device debugging
gdbserver	gdb 8.3.1	static	Remote debugging target
strace	strace 5.10	dynamic glibc	Trace system calls
ldd	shell script	--	Show shared-library dependencies
magic.mgc	file 5.39	--	Magic database for file (deployed 644)

Notes:

• On the device, set MAGIC=/mnt/SDCARD/.tmp_update/bin/magic.mgc so file finds its database without --magic-file.
• The dynamic binaries rely on the device's existing glibc loader/libraries (/lib/ld-linux-armhf.so.3, /lib/libc.so.6, and where needed /lib/libdl.so.2 or /lib/libm.so.6).
• gdb was built without TUI/curses/expat/Python/Guile, and statically links libstdc++ and libgcc, so it needs no extra on-device dependencies.
• To regenerate the bundle, run ~/src/MMP/src/tools/build.sh, which downloads sources into src/Downloads/, builds, and stages results under binaries/. Source versions are pinned in build.sh.

Remote GDB Workflow

# On the Miyoo Mini+:
/mnt/SDCARD/.tmp_update/bin/gdbserver :1234 /mnt/SDCARD/path/To/Program

# On the Ubuntu host, from within GDB:
target remote 192.168.1.128:1234

The on-device gdb is available too, but the gdbserver workflow is lighter and more responsive.

---

Python Tooling

Installed: python3, python3-pip, python3-venv, python3-full, and pipx.

• The system interpreter (/usr/bin/python3) is externally managed. Do not pip install (or pip install --user) into it — it will refuse.
• Install project packages inside a virtual environment (python3 -m venv / venv.create(...)), or install standalone CLI apps with pipx.
• pipx-installed tools are exposed via ~/.local/bin, which is on PATH. argcomplete is registered for shell completion.

---

Optional / Specialized Tools

These may or may not be present depending on how the environment was provisioned. Check before using.

Ghidra (reverse engineering)

• Requires openjdk-21-jdk (installed).
• Installed under ~/opt/ghidra_<version>_PUBLIC (docs target 12.1.2).
• GHIDRA_HOME is exported in ~/.bashrc; $GHIDRA_HOME and $GHIDRA_HOME/support are on PATH.
• The user agreement is pre-accepted (USER_AGREEMENT=ACCEPT).
• Launch the UI with "$GHIDRA_HOME/ghidraRun" &, or with CPython scripting via "$GHIDRA_HOME/support/pyghidraRun" &. Run only one of them.

Ghidra MCP Server (AI-assisted RE)

• Repo at ~/src/bethington/ghidra-mcp with its own .venv (docs target 5.14.1).
• System prerequisites: ddd, jq, maven.
• Managed via .venv/bin/python -m tools.setup {preflight,ensure-prereqs,build,deploy} using --ghidra-path "$GHIDRA_HOME".

OpenDataLoader PDF (PDF → Markdown/CSV/JSON)

• A Python wrapper over a Java CLI that extracts structured data from PDFs (docs target 2.4.7); useful for turning PDFs into LLM-friendly text.
• Backed by default-jre plus CJK/Indic font packages.
• Lives in the venv ~/.venvs/OpenDataLoader.
• Exposed via the wrapper script ~/bin/opendataloader-pdf (and ~/bin is on PATH), so it works in non-interactive shells. Prefer the wrapper over shell aliases.

---

Environment Variables & PATH (set in ~/.bashrc)

• PATH additions: /opt/mmiyoo/bin, $HOME/.local/bin, $HOME/bin, and (if Ghidra is installed) $GHIDRA_HOME + $GHIDRA_HOME/support.
• GHIDRA_HOME — Ghidra install root (when Ghidra is installed).

After modifying ~/.bashrc, run source "$HOME/.bashrc" and hash -r so the current shell picks up new commands.

---

Conventions for Agents

• Prefer long-form command flags (e.g. --output, --assume-yes, --extended-regexp) in scripts and examples, matching the wiki's style. For one-off interactive commands, short flags are acceptable.
• Do not reinstall tools that are already present; verify with command -v <name> or ls /opt first.
• Keep host vs. device straight: cross-compile with the arm-linux-gnueabihf- prefix for the device; use the system toolchain only for host-side helpers.
• Respect externally-managed Python: always work inside a venv or via pipx.
• Treat versions as a moving target: Ghidra, Ghidra MCP Server, and OpenDataLoader PDF release frequently. Confirm against their upstream repositories before upgrading.
• For device deployment/debugging, remind the user to substitute their own ipAddress, user, and remote paths.

---

Reference Documentation

The companion wiki articles cover each step in detail:

• WSL setup, Baseline Packages, Optional Packages (Python, Ghidra, Ghidra MCP Server, OpenDataLoader PDF).
• Toolchain Setup, Hello World, Deployment and Testing, Device Debugging Toolset, GDB Usage.