Termux

[robertkirkman]

Termux is a complete Terminal Emulator Application and distribution of bash, apt, nodejs, cargo, rustc, clang, lldb, make, cmake, X11 Server and code-oss for Android.

With Termux, cross-compilation becomes optional, instead of required, for writing, building, and debugging C, C++, and Rust on Android.
Unlike the situation near the beginning of Android's lifecycle (2010-2015), a second device other than Android is no longer necessarily required.

I am going to write the full steps that I used to successfully compile, install and use codelldb entirely inside of Termux, which is to say, to use codelldb on Android with cross-compilation entirely disabled, as opposed to the standard Android development workflow which normally requires the use of cross-compilation at some point.

Unfortunately, the steps are a little bit messy, and I am not completely sure yet if all of these steps and patches are absolutely required or if some of them can be removed or refactored to streamline the installation process in a better way, but this is what is initially working for me so I wanted to share this.

Install Dependencies

Note

pkg install tur-repo to get code-oss might not be required in the future eventually after this series of events has concluded:

• new package: electron-host-tools-for-code-oss termux/termux-packages#24688
• new package: electron-for-code-oss termux/termux-packages#24691
• new package: code-oss termux/termux-packages#24695

pkg upgrade
pkg install tur-repo
pkg install x11-repo # if you plan to use an X11-based editor
pkg install termux-x11-nightly xfce code-oss # if you plan to use an X11-based editor
pkg install build-essential git rust lldb nodejs libsecret

Retrieve Code

Note

Last designed and tested for codelldb commit 8aa3be2

git clone https://github.com/vadimcn/codelldb.git
cd codelldb
git checkout 8aa3be20c844bdd88b2b05c3725a498f29a14d39

Apply Patch

Note

I created this patch onto codelldb to implement Android support.
I am not sure about this part: AllowedDependencies. I do not understand what that is for, so the list of things I typed there is just guessing.

git apply -v << 'EOF'
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -34,7 +34,19 @@ set(WithEnv ${CMAKE_COMMAND} -E env)
 set(UpdateFile ${CMAKE_COMMAND} -E copy_if_different)
 
 # General OS-specific definitions
-if (${CMAKE_SYSTEM_NAME} STREQUAL "Linux")
+if (${CMAKE_SYSTEM_NAME} STREQUAL "Android")
+    set(Python python3)
+    set(LibPrefix lib)
+    set(LibSuffix .a)
+    set(DylibSuffix .so)
+    set(NPM npm)
+    set(PathSep ":")
+    set(DefaultTarget aarch64-linux-android)
+    set(DefaultPlatformId linux-arm64)
+    set(AllowedDependencies libdl.so libc++_shared.so
+                            libm.so libc.so libz.so.1 libutil.so
+                            /system/bin/linker64)
+elseif (${CMAKE_SYSTEM_NAME} STREQUAL "Linux")
     set(Python python3)
     set(LibPrefix lib)
     set(LibSuffix .a)
--- a/adapter/codelldb/bin/main.rs
+++ b/adapter/codelldb/bin/main.rs
@@ -32,6 +32,6 @@ fn main() -> Result<(), Error> {
             #[cfg(windows)]
             pub const DYLIB_SUBDIR: &str = "bin";
 
-            #[cfg(target_os = "linux")]
+            #[cfg(any(target_os = "linux", target_os = "android"))]
             pub const DYLIB_EXTENSION: &str = "so";
             #[cfg(target_os = "macos")]
EOF

Fetch Cargo Crates and sed-patch weaklink

Note

This Cargo Crate, https://github.com/vadimcn/weaklink, was designed only for GNU/Linux, and must be patched in the "treat Android as Linux" style in order to avoid build errors.

cargo fetch
find ~/.cargo/git/checkouts/weaklink-*/ -type f | \
    xargs -n 1 sed -i \
    -e 's|linux|android|g' \
    -e 's|Linux|Android|g'

Set Environment Variables

Note

These environment variables helped me bypass errors during the build process

export GYP_DEFINES="android_ndk_path=''" RUSTFLAGS=" -C link-arg=-lc++_shared"

Configure and Build

Note

The codelldb documentation states "You will get linker errors if you don't use the toolchain file", but for some reason, it seems to still work for me even though I didn't technically use -DCMAKE_TOOLCHAIN_FILE. I am not sure exactly why.

mkdir build
cd build
cmake .. -DLLDB_PACKAGE="$PREFIX"
make vsix_full

Install .vsix

Note

For some reason, the lldb binary does not get placed in the necessary location automatically after --install-extension, so I use another command to create a symbolic link to the original location, which appears to work.

code-oss --install-extension ./codelldb-full.vsix
cd ~/.vscode-oss/extensions/vadimcn.vscode-lldb*/
ln -sf "$(command -v lldb)" ./lldb

Done

Note

After the above steps, code-oss shows that codelldb is installed for me, and it begins working in the "run and debug" menu exactly the same as it works on VSCodium on GNU/Linux! Here is an example of how to launch code-oss in the Termux:X11 app, but I suspect that other editors that do not necessarily require X11, like code-server from pkg install code-server, might also work with it!

export DISPLAY=:0 TERMUX_X11_XSTARTUP=xfce4-session
LIBGL_ALWAYS_SOFTWARE=1 termux-x11 &
code-oss &

[vadimcn]

Interesting! May I ask what is the motivation for wanting to run VSCode directly on the Android device?

I am not sure about this part: AllowedDependencies.

One of my goals is to make CodeLLDB as portable as practically possible across various Linux distros and their versions. So I'm linking everything statically, except for the required and very common shared libraries. To ensure that nothing else creeps in, the test suite validates that CodeLLDB has only whitelisted runtime dependencies.

[robertkirkman]

May I ask what is the motivation for wanting to run VSCode directly on the Android device?

The reason is because I believe that the most popular consumer operating system in the world, Android, has the ability to run almost all of the same development tools, productivity tools, server software and software in general that GNU/Linux, Alpine Linux and FreeBSD are already known for, but in an extremely portable and convenient form factor that can be used anywhere without the need for a full laptop computer, at full performance without the need for resource-intensive steps like installing a completely separate operating system in a dual boot, VM, or container, and I want to make as many guides, tools and packages as possible to help everyone else who also needs to run software on Android that was written for GNU/Linux, Alpine Linux or FreeBSD, and in doing so, I believe that I can help make the lives of economically disadvantaged people around the world better by making it easier for them to access and participate in the global software development and software productivity ecosystem even if they only have an Android device and not a standard laptop or desktop computer.

One of my goals is to make CodeLLDB as portable as practically possible across various Linux distros and their versions. So I'm linking everything statically, except for the required and very common shared libraries. To ensure that nothing else creeps in, the test suite validates that CodeLLDB has only whitelisted runtime dependencies.

I see, I hadn't yet run the test suite but now I have, and it does appear that if I want the test suite to pass in the build I set up here, I will need to locally modify some of the tests and make sure that both the AllowedDependencies and the relevant tests for the Android target are matching correctly, because when I use make check in the build directory, the tests do indeed fail:

3: Test command: /data/data/com.termux/files/usr/bin/python3 "/data/data/com.termux/files/home/codelldb/tools/check_dependencies.py" "/data/data/com.termux/files/home/codelldb/build/adapter" "libdl.so|libc++_shared.so|libm.so|libc.so|libz.so.1|libutil.so|/system/bin/linker64"
3: Working Directory: /data/data/com.termux/files/home/codelldb/build/adapter
3: Test timeout computed to be: 10000000
3: Checking /data/data/com.termux/files/home/codelldb/build/adapter/codelldb
3:   libc++_shared.so is not in the whitelist
3:   ld-android.so is not in the whitelist
3/3 Test #3: dependencies:adapter ...............***Failed    0.82 sec

33% tests passed, 2 tests failed out of 3

Total Test time (real) =  95.50 sec

The following tests FAILED:
	 1 - adapter:x86_64-unknown-linux-gnu (Failed)
	 3 - dependencies:adapter (Failed)
Errors while running CTest
Output from these tests are in: /data/data/com.termux/files/home/codelldb/build/Testing/Temporary/LastTest.log
Use "--rerun-failed --output-on-failure" to re-run the failed cases verbosely.
make[3]: *** [CMakeFiles/check.dir/build.make:70: CMakeFiles/check] Error 8
make[2]: *** [CMakeFiles/Makefile2:491: CMakeFiles/check.dir/all] Error 2
make[1]: *** [CMakeFiles/Makefile2:498: CMakeFiles/check.dir/rule] Error 2
make: *** [Makefile:296: check] Error 2
~/codelldb/build $ file $PREFIX/lib/libc++_shared.so 
/data/data/com.termux/files/usr/lib/libc++_shared.so: ELF 64-bit LSB shared object, ARM aarch64, version 1 (SYSV), dynamically linked, for Android 21, built by NDK r27-beta1 (11883388), BuildID[sha1]=b04675a35ad96f8a9dcaa073e3bd31d4536f00ad, stripped
~/codelldb/build $ file /system/lib64/ld-android.so 
/system/lib64/ld-android.so: ELF 64-bit LSB shared object, ARM aarch64, version 1 (SYSV), dynamically linked, BuildID[md5/uuid]=6edf5abd68763c3b4e829b3e4077f487, stripped
~/codelldb/build $ 

I can see that something about the tests is accurately identifying the presence of Android and Termux system library dependencies in the resulting build, which is expected to happen since they are slightly different from those of GNU/Linux (as are those of Alpine Linux), but the changes I have made so far aren't sufficient to allow the tests to pass yet.

Typically, in Android, it is standard for .apk packages (the traditional Android App format) that contain code written in C and C++ to depend on the libc.so, libm.so, ld-android.so and a few others located in the /system/lib64 folder, which is part of the Android ROM and is outside of the files provided by the .apk package, but also the libc++_shared.so from within the app's own files rather than the one in /system/lib64, so that is why /data/data/com.termux/files/usr/lib/libc++_shared.so is a normal place for libc++_shared.so to be in this context. However, it appears that simply adding libc++_shared.so to the AllowedDependencies list is not sufficient on its own to pass these tests, since it is being flagged as a disallowed dependency anyway.

On the other hand, it might not be a super high priority to make all of the tests that were intended for GNU/Linux work by manually changing the tests, it would just be an unimportant exercise in completeness of this custom build of codelldb, because I understand completely that this target is out of scope for the goals of the upstream project. For comparison, I can see that the Alpine Linux version here, #391 (comment), around which some discussion very similar to some of the things I have talked about here has already taken place (but from the Alpine Linux perspective rather than the Android perspective), does not appear to make any attempt to pass the testsuite.

In general, I am aware that this kind of "alternative UNIX-like OS target" is not really a priority for the upstream of most projects, which is completely understandable - I can see similar discussions regarding FreeBSD support in the issues and PRs, in which it is explained that FreeBSD support is also out of scope for the upstream project, partly due to the lack of an easy way to build in CI. This is the reason why I decided to post these steps in the discussions page rather than in an issue or a PR.

In the Termux project, many packages are being built, patched, and deployed in a CI system that is set up to be entirely suitable for Android (we are essentially using a specialized variant format of .deb files nested inside .apk files there), but the reason I have not yet submitted a build script for codelldb there is because I am not yet quite sure about the details of packaging a .vsix extension in a .deb file in such a way that it should be globally and automatically accessible to all installed VSCode-based editors in the system. I did see that Arch Linux has a way of packaging codelldb on AUR (https://aur.archlinux.org/cgit/aur.git/tree/PKGBUILD?h=codelldb), but I am not sure whether that way of installing codelldb is automatically detected and available by VSCodium and other editors on Arch Linux. In my example here on Android, I did have to manually use code-oss --install-extension ./codelldb-full.vsix and create a symbolic link in the ~/.vscode-oss folder, which are both specific to a VSCode-based editor built with the name "code-oss" and I am not yet sure how to abstract this setup in such a way that explicitly hardcoding the process of installation into each desired editor is not required. I will probably try to figure out if there is a better way of doing this, and if so then I will probably eventually try to create a build script for this which can be submitted to the Termux project and deployed using Termux-specific CI workflows.