| 1 | termux-packages |
| 2 | =============== |
| 3 | This project contains scripts and patches to cross compile and package packages for |
| 4 | the [Termux](http://termux.com/) Android application. |
| 5 | |
| 6 | NOTE: This is in a rough state - be prepared for some work and frustrations, and give |
| 7 | feedback if you find incorrect our outdated things! |
| 8 | |
| 9 | Initial setup |
| 10 | ============= |
| 11 | Building packages are for now only tested to work on Ubuntu 15.04. Perform the following |
| 12 | setup steps: |
| 13 | |
| 14 | * Run `ubuntu-setup.sh` to install required packages and setup the `/data/` folder (see below). |
| 15 | |
| 16 | * Install the Android SDK at `$HOME/lib/android-sdk`. Override this by setting the environment |
| 17 | variable `$ANDROID_HOME` to point at another location. |
| 18 | |
| 19 | * Install the Android NDK, version r10e, at `$HOME/lib/android-ndk`. Override this by setting |
| 20 | the environment variable `$NDK` to point at another location. |
| 21 | |
| 22 | |
| 23 | Building a package |
| 24 | ================== |
| 25 | In a non-rooted Android device an app such as Termux may not write to system locations, |
| 26 | which is why every package is installed inside the private file area of the Termux app: |
| 27 | |
| 28 | PREFIX=/data/data/com.termux/files/usr |
| 29 | |
| 30 | For simplicity while developing and building, the build scripts here assume that a /data |
| 31 | folder is reserved for use on the host builder and install everything there. |
| 32 | |
| 33 | The basic flow is then to run "./build-package.sh $PKG", which: |
| 34 | * Sets up a patched stand-alone Android NDK toolchain |
| 35 | |
| 36 | * Reads packages/$PKG/build.sh to find out where to find the source code of the package and how to build it. |
| 37 | |
| 38 | * Applies all patches in packages/$PKG/\*.patch |
| 39 | |
| 40 | * Builds the package and installs it to $PREFIX |
| 41 | |
| 42 | * Creates a dpkg package file for distribution. |
| 43 | |
| 44 | Reading and following build-package.sh is the best way to understand what's going on here. |
| 45 | |
| 46 | |
| 47 | Additional utilities |
| 48 | ==================== |
| 49 | * build-all.sh: used for building all packages in the correct order (using buildorder.py) |
| 50 | |
| 51 | * check-pie.sh: Used for verifying that all binaries are using PIE, which is required for Android 5+ |
| 52 | |
| 53 | * detect-hardlinks.sh: Used for finding if any packages uses hardlinks, which does not work on Android M |
| 54 | |
| 55 | * check-versions.sh: used for checking for package updates |
| 56 | |
| 57 | * clean-rebuild-all.sh: used for doing a clean rebuild of all packages (takes a couple of hours) |
| 58 | |
| 59 | * list-packages.sh: used for listing all packages with a one-line summary |
| 60 | |
| 61 | |
| 62 | Resources about cross-compiling packages |
| 63 | ======================================== |
| 64 | * [Linux From Scratch](http://www.linuxfromscratch.org/blfs/view/svn/index.html) |
| 65 | |
| 66 | * [Beyond Linux From Scratch](http://www.linuxfromscratch.org/blfs/view/svn/) |
| 67 | |
| 68 | * [Cross-Compiled Linux From Scratch](http://cross-lfs.org/view/svn/x86_64-64/) |
| 69 | |
| 70 | * [OpenWrt](https://openwrt.org/), an embedded Linx distribution, contains [patches and build scripts](https://dev.openwrt.org/browser/packages) |
| 71 | |
| 72 | * http://dan.drown.org/android contains [patches for cross-compiling to Android](http://dan.drown.org/android/src/) as well as [work notes](http://dan.drown.org/android/worknotes.html), including a modified dynamic linker to avoid messing with LD_LIBRARY_PATH. |
| 73 | |
| 74 | * [CCTools](http://cctools.info/index.php?title=Main_Page) is an Android native IDE containing [patches for several programs](https://code.google.com/p/cctools/source/browse/#svn%2Ftrunk%2Fcctools-repo%2Fpatches) and [a bug tracker](https://code.google.com/p/cctools/issues/list). |
| 75 | |
| 76 | * [BotBrew](http://botbrew.com/) was a package manager for rooted devices with [sources on github](https://github.com/jyio/botbrew). Based on opkg and was transitioning to apt. |
| 77 | |
| 78 | * [Kivy recipes](https://github.com/kivy/python-for-android/tree/master/recipes) contains recipes for building packages for Android. |
| 79 | |
| 80 | |
| 81 | Common porting problems |
| 82 | ======================= |
| 83 | * The Android bionic libc does not have iconv and gettext/libintl functionality built in. A package from the NDK, libandroid-support, |
| 84 | contains these and may be used by all packages. |
| 85 | |
| 86 | * "error: z: no archive symbol table (run ranlib)" usually means that the build machines libz is used instead of the one for cross compilation, due to the builder library -L path being setup incorrectly |
| 87 | |
| 88 | * rindex(3) is defined in <strings.h> but does not exist in NDK, but strrchr(3) from <string.h> is preferred anyway |
| 89 | |
| 90 | * <sys/termios.h> does not exist, but <termios.h> is the standard location. |
| 91 | |
| 92 | * <sys/fcntl.h> does not exist, but <fcntl.h> is the standard location. |
| 93 | |
| 94 | * glob(3) system function (glob.h) - not in bionic, but use the `libandroid-glob` package |
| 95 | |
| 96 | * undefined reference to 'rpl_malloc' and/or 'rpl_realloc': These functions are added by some autoconf setups |
| 97 | when it fails to detect 0-safe malloc and realloc during cross-compilating. Avoided by defining |
| 98 | "ac_cv_func_malloc_0_nonnull=yes ac_cv_func_realloc_0_nonnull=yes". |
| 99 | See http://wiki.buici.com/xwiki/bin/view/Programing+C+and+C%2B%2B/Autoconf+and+RPL_MALLOC |
| 100 | |
| 101 | * cmake and cross compiling: http://www.cmake.org/Wiki/CMake_Cross_Compiling |
| 102 | CMAKE_FIND_ROOT_PATH=$TERMUX_PREFIX to search there. |
| 103 | CMAKE_FIND_ROOT_PATH_MODE_LIBRARY=ONLY and |
| 104 | CMAKE_FIND_ROOT_PATH_MODE_INCLUDE=ONLY |
| 105 | for only searching there and don't fall back to build machines |
| 106 | |
| 107 | * Android is removing sys/timeb.h because it was removed in POSIX 2008, but ftime(3) can be replaced with gettimeofday(2) |
| 108 | |
| 109 | * mempcpy(3) is a GNU extension. We have added it to <string.h> provided TERMUX_EXPOSE_MEMPCPY is defined, |
| 110 | so use something like CFLAGS+=" -DTERMUX_EXPOSE_MEMPCPY=1" for packages expecting that function to exist. |
| 111 | |
| 112 | |
| 113 | dlopen() and RTLD_* flags |
| 114 | ================================= |
| 115 | <dlfn.h> declares |
| 116 | |
| 117 | enum { RTLD_NOW=0, RTLD_LAZY=1, RTLD_LOCAL=0, RTLD_GLOBAL=2, RTLD_NOLOAD=4}; // 32-bit |
| 118 | enum { RTLD_NOW=2, RTLD_LAZY=1, RTLD_LOCAL=0, RTLD_GLOBAL=0x00100, RTLD_NOLOAD=4}; // 64-bit |
| 119 | |
| 120 | These differs from glibc ones in that |
| 121 | |
| 122 | 1. They are not preprocessor #define:s so cannot be checked for with #ifdef RTLD_GLOBAL (dln.c in ruby does this) |
| 123 | 2. They differ in value from glibc ones, so cannot be hardcoded in files (DLFCN.py in python does this) |
| 124 | 3. They are missing some values (RTLD_BINDING_MASK, RTLD_NOLOAD, ...) |
| 125 | |
| 126 | |
| 127 | RPATH, LD_LIBRARY_PATH AND RUNPATH |
| 128 | ================================== |
| 129 | On desktop linux the linker searches for shared libraries in: |
| 130 | |
| 131 | 1. RPATH - a list of directories which is linked into the executable, supported on most UNIX systems. It is ignored if RUNPATH is present. |
| 132 | 2. LD_LIBRARY_PATH - an environment variable which holds a list of directories |
| 133 | 3. RUNPATH - same as RPATH, but searched after LD_LIBRARY_PATH, supported only on most recent UNIX systems |
| 134 | |
| 135 | The Android linker (/system/bin/linker) does not support RPATH or RUNPATH, so we set LD_LIBRARY_PATH=$USR/lib and try to avoid building useless rpath entries with --disable-rpath configure flags. Another option to avoid depending on LD_LIBRARY_PATH would be supplying a custom linker - this is not done due to the overhead of maintaining a custom linker. |
| 136 | |
| 137 | |
| 138 | Warnings about unused DT entries |
| 139 | ================================ |
| 140 | Starting from 5.1 the Android linker warns about VERNEED (0x6FFFFFFE) and VERNEEDNUM (0x6FFFFFFF) ELF dynamic sections: |
| 141 | |
| 142 | WARNING: linker: $BINARY: unused DT entry: type 0x6ffffffe arg ... |
| 143 | WARNING: linker: $BINARY: unused DT entry: type 0x6fffffff arg ... |
| 144 | These may come from version scripts in a Makefile such as: |
| 145 | |
| 146 | -Wl,--version-script=$(top_srcdir)/proc/libprocps.sym |
| 147 | The termux-elf-cleaner utilty is run from build-package.sh and should normally take care of that problem. |