Разработка и отладка Android NDK‑проектов непосредственно в Termux: clang, ndk‑build и gdb‑server

Termux давно перестал быть «песочницей» для учебных команд: при правильной организации окружения он позволяет выполнять полноценные шаги разработки и отладки Android NDK‑проектов — от подготовки toolchain до запуска gdb‑server на целевом устройстве и подключения отладчика с хоста Termux.

В этой статье я покажу практический, ориентированный на повторяемость подход: как подготовить Termux под сборку NDK‑проекта (clang/ndk-build) и как организовать отладку через gdb-server.

Что понадобится

Android‑устройство (лучше не «слишком старое», с актуальными ABI).
Termux установленный из F-Droid (или официального источника) и доступ к пакетному менеджеру.
NDK SDK (локально на устройстве либо доступный из репозитория).
Устройство для сборки/отладки: в нашем случае — то же Android, только с разными компонентами (сборка в Termux, отладка через gdb‑server).
Порт для отладки (локальная сеть), без привязки к обходу блокировок: при необходимости используйте VPN для создания локальной сети.

1) Подготовка Termux: базовые пакеты

Сначала обновим пакеты и поставим то, что почти всегда требуется для сборки и запуска утилит:

pkg update && pkg upgrade -y
pkg install -y git wget tar clang llvm make autoconf automake libtool ncurses-utils gdb-server gdb

Примечание: на разных версиях Termux набор пакетов может отличаться. Если какой-то пакет недоступен, ориентируйтесь на аналоги. Но ключевое — чтобы были доступны clang и утилиты для сборки, а также gdb/gdb-server.

2) Установка Android NDK в Termux

Есть два подхода:

NDK уже есть в файловой системе устройства (например, после скачивания вручную).
NDK скачивается и распаковывается в Termux‑каталоге.

Ниже пример для второго подхода (вам нужно подставить корректный URL до архива NDK для вашей версии):

mkdir -p ~/android
cd ~/android
wget "https://dl.google.com/android/repository/android-ndk-r26b-linux.zip" -O ndk.zip
tar -xf ndk.zip

Если архив в формате .zip, иногда корректнее использовать unzip. Тогда:

pkg install -y unzip
unzip ndk.zip -d .

Проверьте, что NDK распакован, и определите путь к нему:

ls -la ~/android

Далее будем считать, что NDK расположен по пути ~/android/android-ndk-*. Например, ~/android/android-ndk-r26b.

3) Настройка переменных окружения для сборки

Далее в Termux зададим переменные, которые понадобятся ndk-build и toolchain. Создадим файл env.sh для удобства:

nano env.sh

Вставьте примерно такое (адаптируйте путь к NDK и имена ABI):

export ANDROID_NDK_HOME="$HOME/android/android-ndk-r26b"
export PATH="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin:$PATH"

# Цель (пример): arm64-v8a
export APP_ABI=arm64-v8a
export APP_PLATFORM=android-24

# Путь к вашему NDK-проекту
export PROJECT_DIR="$HOME/projects/ndk-app"

Сохраните и загрузите:

source env.sh

Важно: каталог toolchains/llvm/prebuilt/.../bin в NDK может отличаться по имени платформы (например, darwin-x86_64 или linux-x86_64) — берите тот путь, который соответствует распакованному NDK. На практике проще посмотреть структуру каталогов внутри $ANDROID_NDK_HOME/toolchains/llvm/prebuilt.

4) Сборка NDK-проекта через ndk-build в Termux

Предположим, что ваш проект использует Android.mk и Application.mk и собирается командой ndk-build.

Перейдите в директорию проекта:

cd "$PROJECT_DIR"

Если используется ndk-build, то запускайте:

"$ANDROID_NDK_HOME/ndk-build" \
  NDK_PROJECT_PATH=. \
  APP_ABI="$APP_ABI" \
  APP_PLATFORM="$APP_PLATFORM" \
  NDK_DEBUG=1 \
  V=1

Ключевые параметры:

NDK_DEBUG=1 включает отладочные артефакты (как правило, сохраняются символы для дальнейшей отладки).
APP_ABI и APP_PLATFORM определяют целевую архитектуру и минимальную версию платформы.
V=1 — подробный вывод, полезно при разборе проблем.

Сборка с несколькими ABI может быть реализована через установку APP_ABI строкой, например arm64-v8a,x86_64, но внутри Android без эмулятора обычно важнее выбрать тот ABI, который соответствует вашему устройству. Узнать ABI можно средствами Android (например, через getprop), но универсального способа в рамках одной команды нет.

5) Контроль флагов отладки (debug symbols)

Для gdb критично, чтобы бинарники содержали отладочную информацию. Обычно NDK_DEBUG=1 решает вопрос.

Дополнительно проверьте, что вы не собираете в конфигурации без символов. Если проект использует APP_OPTIM или свои настройки в Application.mk, убедитесь, что оптимизации не «съедают» отладочность. Для отладки часто применяют:

APP_OPTIM := debug

или эквиваленты в зависимости от того, как ваш проект организован. В любом случае ориентируйтесь на наличие информации о строках и символах.

6) Пример: сборка с clang напрямую (когда ndk-build не подходит)

Иногда полезно собрать один файл или минимальный проект напрямую через clang. Это удобно для экспериментов и проверки toolchain.

Примерный шаблон компиляции для NDK обычно требует подбора target‑триплета, sysroot и формата ABI. В большинстве случаев проще использовать ndk-build, но если нужно — ниже структура подхода.

Компиляция условного C-файла в общий объект:

clang \
  --target=aarch64-linux-android \
  --sysroot="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/sysroot" \
  -fPIC -O0 -g \
  -c main.c -o main.o

Затем линковка в shared library:

clang \
  --target=aarch64-linux-android \
  --sysroot="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/sysroot" \
  -shared -fPIC \
  -g -o libnative.so main.o

Предупреждение: пути к sysroot и target‑параметрам могут отличаться в зависимости от версии NDK. Поэтому для «промышленного» проекта лучше держаться ndk-build — там меньше риска упустить совместимые настройки.

7) Подготовка отладки: размещение библиотек и запуск gdb-server

Отладка NDK‑кода на Android требует выполнения двух условий:

Запуск gdb-server на целевом устройстве (или внутри процесса приложения) с корректными правами.
Подключение gdb из Termux к запущенному gdb-server.

В Termux у вас обычно есть gdb-server. Но чтобы отлаживать процесс приложения, важно корректно запустить gdb-server так, чтобы он ожидал соединения и имел доступ к необходимому процессу/библиотекам.

Типовой сценарий (как концепт) выглядит так: стартуем gdb-server и задаём порт:

gdbserver :2345 --attach <PID_ПРОЦЕССА>

Где взять <PID_ПРОЦЕССА> — зависит от того, каким способом вы запускаете/определяете процесс. Если вы контролируете запуск приложения, можно запускать его и затем подхватывать PID, например через инструменты системного уровня (в рамках вашего проекта).

Если у вас не получается --attach, альтернативой является режим «запуск под gdbserver» (когда вы можете напрямую запустить процесс командой), но это зависит от того, как устроено ваше Android-приложение.

8) VPN как локальная сеть (опционально)

Если по топологии сети подключение из Termux к устройству/порту требует сетевой адресации, вы можете использовать VPN только для создания локальной сети и стабилизации обмена трафиком. Это не про обход блокировок, а про корректную маршрутизацию в вашей локальной среде разработки.

9) Подключение gdb из Termux

После того как gdb-server запущен и ожидает подключение, в Termux запускаем gdb и подключаемся к удалённому отладчику.

Важно: gdb нужно запускать с корректным ELF образом (вашим libnative.so или бинарником), и желательно с теми же версиями библиотек, что загружены в процессе.

Пример:

cd "$PROJECT_DIR"

# Пути к собранной библиотеке зависят от структуры проекта.
# Часто: libs/arm64-v8a/libnative.so или app/build/... в Gradle-проектах.

gdb "./path/to/libnative.so"

Далее в интерактивной сессии:

(gdb) set sysroot /
(gdb) target remote 127.0.0.1:2345
(gdb) info files
(gdb) break <имя_функции_или_файл:строка>
(gdb) continue

Если gdb-server запущен на том же устройстве, то часто адрес 127.0.0.1 работает. Если отладка «разносится» между компонентами/инстансами — подставляйте фактический адрес.

10) Типовые проблемы и как их диагностировать

gdb не видит символы: проверьте, что собирали с NDK_DEBUG=1 и что библиотека с символами действительно та, которую вы указали в gdb.
Ошибка совместимости ABI/архитектуры: APP_ABI должен совпадать с архитектурой целевого устройства.
Не удаётся attach к процессу: возможно, ограничения прав/SELinux/особенности запуска. В таком случае используйте режим запуска под контролем gdb-server или подключайтесь к процессу тем способом, который разрешён вашим окружением.
Троит трассировку, «прыжки» по стеку: проверьте оптимизации (-O0/debug-режим) и наличие корректных debuginfo.

Практический рабочий чек-лист

Скачайте/распакуйте NDK и убедитесь, что ndk-build запускается из Termux.
Проверьте ABI вашего устройства и выставьте APP_ABI.
Соберите с NDK_DEBUG=1 и включите подробный вывод V=1.
Убедитесь, что libnative.so (или ваш бинарник) содержит debug symbols.
Запустите gdb-server и поднимите порт.
Откройте gdb с тем же ELF-образом и подключитесь к target remote.
Поставьте точку останова и проверьте, что отладка управляет нужным местом в коде.

Заключение

Разработка и отладка Android NDK‑проектов прямо в Termux вполне реализуемы: ndk-build помогает сохранить совместимые настройки toolchain, а связка gdb-server и gdb позволяет перейти от «сборки без ошибок» к полноценной отладке нативного кода. Начинайте с минимального target‑ABI и debug‑конфигурации, затем усложняйте сценарии (attach/remote запуск), фиксируя соответствие библиотек и символов.

Если хотите быстро привести окружение в рабочее состояние или получить помощь с конкретным проектом/ошибками сборки и отладки, обращайтесь в РыбинскЛАБ — помогаем с настройкой Termux, NDK‑сборками и отладкой под Android.