| 1 | Termux packages |
| 2 | =============== |
| 3 | [![Join the chat at https://gitter.im/termux/termux](https://badges.gitter.im/termux/termux.svg)](https://gitter.im/termux/termux) |
| 4 | |
| 5 | This project contains scripts and patches to build packages for the |
| 6 | [Termux](https://termux.com/) Android application. |
| 7 | |
| 8 | License |
| 9 | ======= |
| 10 | The scripts and patches to build each package is licensed under the same license as |
| 11 | the actual package (so the patches and scripts to build bash are licensed under |
| 12 | the same license as bash, while the patches and scripts to build python are licensed |
| 13 | under the same license as python). |
| 14 | |
| 15 | Build environment on Ubuntu 16.04 |
| 16 | ================================= |
| 17 | Packages are built using Ubuntu 16.04. Perform the following steps to configure a Ubuntu 16.04 installation: |
| 18 | |
| 19 | - Run `scripts/setup-ubuntu.sh` to install required packages and setup the `/data/` folder. |
| 20 | |
| 21 | - Run `scripts/setup-android-sdk.sh` to install the Android SDK and NDK at `$HOME/lib/android-{sdk,ndk}`. |
| 22 | |
| 23 | There is also a [Vagrantfile](scripts/Vagrantfile) available for setting up an Ubuntu environment using a virtual machine on other operating systems. |
| 24 | |
| 25 | Build environment using Docker |
| 26 | ============================== |
| 27 | On other Linux distributions than Ubuntu 16.04 (or on other platforms than Linux) the best course |
| 28 | of action is to setup a Docker container for building packages by executing: |
| 29 | |
| 30 | ./scripts/run-docker.sh |
| 31 | |
| 32 | This will setup a container (from an image created by [scripts/Dockerfile](scripts/Dockerfile)) |
| 33 | suitable for building packages. |
| 34 | |
| 35 | This source folder is mounted as the /root/termux-packages data volume, so changes are kept |
| 36 | in sync between the host and the container when trying things out before committing, and built |
| 37 | deb files will be available on the host in the `debs/` directory just as when building on the host. |
| 38 | |
| 39 | Build commands can be given to be executed in the docker container directly: |
| 40 | |
| 41 | ./scripts/run-docker.sh ./build-package.sh libandroid-support |
| 42 | |
| 43 | will launch the docker container, execute the `./build-package.sh libandroid-support` |
| 44 | command inside it and afterwards return you to the host prompt, with the newly built |
| 45 | deb in `debs/` to try out. |
| 46 | |
| 47 | Building a package |
| 48 | ================== |
| 49 | The basic build operation is to run `./build-package.sh $PKG`, which: |
| 50 | |
| 51 | 1. Sets up a patched stand-alone Android NDK toolchain if necessary. |
| 52 | |
| 53 | 2. Reads `packages/$PKG/build.sh` to find out where to find the source code of the package and how to build it. |
| 54 | |
| 55 | 3. Extracts the source in `$HOME/.termux-build/$PKG/src`. |
| 56 | |
| 57 | 4. Applies all patches in packages/$PKG/\*.patch. |
| 58 | |
| 59 | 5. Builds the package under `$HOME/.termux-build/$PKG/` (either in the build/ directory there or in the |
| 60 | src/ directory if the package is specified to build in the src dir) and installs it to `$PREFIX`. |
| 61 | |
| 62 | 6. Extracts modified files in `$PREFIX` into `$HOME/.termux-build/$PKG/massage` and massages the |
| 63 | files there for distribution (removes some files, splits it up in sub-packages, modifies elf files). |
| 64 | |
| 65 | 7. Creates a deb package file for distribution in `debs/`. |
| 66 | |
| 67 | Reading [build-package.sh](build-package.sh) is the best way to understand what is going on. |
| 68 | |
| 69 | Additional utilities |
| 70 | ==================== |
| 71 | * build-all.sh: used for building all packages in the correct order (using buildorder.py). |
| 72 | |
| 73 | * clean-rebuild-all.sh: used for doing a clean rebuild of all packages. |
| 74 | |
| 75 | * scripts/check-pie.sh: Used for verifying that all binaries are using PIE, which is required for Android 5+. |
| 76 | |
| 77 | * scripts/detect-hardlinks.sh: Used for finding if any packages uses hardlinks, which does not work on Android M. |
| 78 | |
| 79 | * scripts/check-versions.sh: used for checking for package updates. |
| 80 | |
| 81 | * scripts/list-packages.sh: used for listing all packages with a one-line summary. |
| 82 | |
| 83 | |
| 84 | Resources |
| 85 | ========= |
| 86 | * [Android changes for NDK developers](https://android.googlesource.com/platform/bionic/+/master/android-changes-for-ndk-developers.md) |
| 87 | |
| 88 | * [Linux From Scratch](http://www.linuxfromscratch.org/lfs/view/stable/) |
| 89 | |
| 90 | * [Beyond Linux From Scratch](http://www.linuxfromscratch.org/blfs/view/stable/) |
| 91 | |
| 92 | * [Cross-Compiled Linux From Scratch](http://www.clfs.org/view/CLFS-3.0.0-SYSVINIT/mips64-64/) |
| 93 | |
| 94 | * [OpenWrt](https://openwrt.org/) as an embedded Linx distribution contains [patches and build scripts](https://dev.openwrt.org/browser/packages) |
| 95 | |
| 96 | * 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`. |
| 97 | |
| 98 | * [Kivy recipes](https://github.com/kivy/python-for-android/tree/master/pythonforandroid/recipes) contains recipes for building packages for Android. |
| 99 | |
| 100 | |
| 101 | Common porting problems |
| 102 | ======================= |
| 103 | * The Android bionic libc does not have iconv and gettext/libintl functionality built in. A package from the NDK, libandroid-support, contains these and may be used by all packages. |
| 104 | |
| 105 | * "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 |
| 106 | |
| 107 | * rindex(3) is defined in <strings.h> but does not exist in NDK, but strrchr(3) from <string.h> is preferred anyway |
| 108 | |
| 109 | * <sys/termios.h> does not exist, but <termios.h> is the standard location. |
| 110 | |
| 111 | * <sys/fcntl.h> does not exist, but <fcntl.h> is the standard location. |
| 112 | |
| 113 | * glob(3) system function (glob.h) - not in bionic, but use the `libandroid-glob` package |
| 114 | |
| 115 | * [Cmake and cross compiling](http://www.cmake.org/Wiki/CMake_Cross_Compiling). |
| 116 | `CMAKE_FIND_ROOT_PATH=$TERMUX_PREFIX` to search there. |
| 117 | `CMAKE_FIND_ROOT_PATH_MODE_LIBRARY=ONLY` and `CMAKE_FIND_ROOT_PATH_MODE_INCLUDE=ONLY` |
| 118 | for only searching there and don't fall back to build machines |
| 119 | |
| 120 | * Android is removing sys/timeb.h because it was removed in POSIX 2008, but ftime(3) can be replaced with gettimeofday(2) |
| 121 | |
| 122 | * mempcpy(3) is a GNU extension. We have added it to <string.h> provided TERMUX_EXPOSE_MEMPCPY is defined, |
| 123 | so use something like CFLAGS+=" -DTERMUX_EXPOSE_MEMPCPY=1" for packages expecting that function to exist. |
| 124 | |
| 125 | dlopen() and RTLD_* flags |
| 126 | ================================= |
| 127 | <dlfcn.h> originally declares |
| 128 | |
| 129 | enum { RTLD_NOW=0, RTLD_LAZY=1, RTLD_LOCAL=0, RTLD_GLOBAL=2, RTLD_NOLOAD=4}; // 32-bit |
| 130 | enum { RTLD_NOW=2, RTLD_LAZY=1, RTLD_LOCAL=0, RTLD_GLOBAL=0x00100, RTLD_NOLOAD=4}; // 64-bit |
| 131 | |
| 132 | These differs from glibc ones in that |
| 133 | |
| 134 | 1. They are not preprocessor #define:s so cannot be checked for with `#ifdef RTLD_GLOBAL`. Termux patches this to #define values for compatibility with several packages. |
| 135 | 2. They differ in value from glibc ones, so cannot be hardcoded in files (DLFCN.py in python does this) |
| 136 | 3. They are missing some values (`RTLD_BINDING_MASK`, `RTLD_NOLOAD`, ...) |
| 137 | |
| 138 | RPATH, RUNPATH AND LD\_LIBRARY\_PATH |
| 139 | ==================================== |
| 140 | On desktop linux the linker searches for shared libraries in: |
| 141 | |
| 142 | 1. `RPATH` - a list of directories which is linked into the executable, supported on most UNIX systems. It is ignored if `RUNPATH` is present. |
| 143 | 2. `LD_LIBRARY_PATH` - an environment variable which holds a list of directories |
| 144 | 3. `RUNPATH` - same as `RPATH`, but searched after `LD_LIBRARY_PATH`, supported only on most recent UNIX systems |
| 145 | |
| 146 | The Android linker, /system/bin/linker, does not support RPATH or RUNPATH, so we set `LD_LIBRARY_PATH=$PREFIX/lib` and try to avoid building useless rpath entries (which the linker warns about) with --disable-rpath configure flags. NOTE: Starting from Android 7.0 RUNPATH (but not RPATH) is supported. |
| 147 | |
| 148 | Warnings about unused DT entries |
| 149 | ================================ |
| 150 | Starting from 5.1 the Android linker warns about VERNEED (0x6FFFFFFE) and VERNEEDNUM (0x6FFFFFFF) ELF dynamic sections (WARNING: linker: $BINARY: unused DT entry: type 0x6ffffffe/0x6fffffff). These may come from version scripts (`-Wl,--version-script=`). The termux-elf-cleaner utilty is run from build-package.sh and should normally take care of that problem. NOTE: Starting from Android 6.0 symbol versioning is supported. |