Building packages
Once the build environment has been properly set up, then packages can be built with the build-package.sh script located at the root of termux-packages repository with one or more package names as arguments.
- The default build architecture is
aarch64, which can be overridden with the-aflag. - If only a package needs to be built, it is recommended to pass the
-Iflag so that its dependencies are not built and are downloaded from termux packages repo instead, as building dependencies would generally take a lot of time. - If a package has already been built, and it needs to be rebuilt, pass the
-fflag. Optionally, the-rflag should be passed if the package sources should be re-downloaded during rebuild. - Passing only the
-fand-Iflags is normally sufficient to build a package being tested or developed. - To build a package whose sources exist on the local filesystem, instead of a remote source URL that is defined in the
$TERMUX_PKG_SRCURLvariable of thebuild.shfile of each package, check Build Local Package docs.
- Build Examples
- Build Command Options
- Build Command Config
- Build Process
- Build Steps
- Build Local Package
./build-package.sh bashTo build the bash package, but download instead of building its dependencies, for the aarch64 architecture
./build-package.sh -I bashTo force build the bash package even if its already built, but download instead of building its dependencies, for the aarch64 architecture
./build-package.sh -f -I bashTo force build the bash package and all its dependencies even if they are already built, for the aarch64 architecture
./build-package.sh -F bash./build-package.sh -a arm bashTo build the bash, coreutils and grep packages, and all their dependencies, for the aarch64 architecture
./build-package.sh bash coreutils grep
The following command options are supported by build-package.sh.
The architecture to build for. Valid values are: aarch64, arm, i686, x86_64. Default is aarch64. For on-device builds, the architecture is determined automatically and this option is not available.
Continue previous build. This skips the source extraction, patching and the configure step, and goes straight to termux_step_make. Only works if normal build has already been run and it fails, or build was stopped during termux_step_make or later.
This is useful when working on a big package that can take hours to build, as it is convenient to be able to build until there is an error, then apply some new patch (manually) to the source, and then continue from where the last build failed.
Build with debug information and turn of compiler optimizations.
Build disabled package, i.e. located in directory ./disabled-packages.
Force build package even if it already built or installed.
Force build package and all its dependencies even if they are already built or installed.
Download dependencies of the build packages defined in $TERMUX_PKG_DEPENDS variable of their build.sh file from Termux package repositories instead of building them locally. Erases data in $TERMUX__PREFIX and /data/data/.built-packages files for all packages before starting build. Not available for on-device builds.
This will be ignored if compiling a package for different core variable values, like for $TERMUX_APP__PACKAGE_NAME or $TERMUX__PREFIX, than the values for which the packages hosted in the packages repository were compiled for. Check $TERMUX_REPO_* variables in properties.sh and Build Command Config docs for more info.
See also -I flag.
Download dependencies of the build packages defined in $TERMUX_PKG_DEPENDS variable of their build.sh file from Termux package repositories instead of building them locally. Unlike -i option, this will not erase data in $TERMUX__PREFIX and /data/data/.built-packages files for all packages, and is available for on-device builds.
This will be ignored if compiling a package for different core variable values, like for $TERMUX_APP__PACKAGE_NAME or $TERMUX__PREFIX, than the values for which the packages hosted in the packages repository were compiled for. Check $TERMUX_REPO_* variables in properties.sh and Build Command Config docs for more info.
See also -i flag.
Specify directory where to place built package files (*.deb/*.pkg.tar.xz). Default is ./output.
Pass necessary arguments to make or similar tool to make build quietly. May not work for all packages.
Remove all package build dependent directories that -f/-F flags alone would not remove. This includes the package cache directory ($TERMUX_PKG_CACHEDIR) containing package sources and host build directory ($TERMUX_PKG_HOSTBUILD_DIR). The -r flag will be ignored if -f/-F flags are not passed.
With -f/-F flags alone, latest package sources will not be re-downloaded on rebuilds if $TERMUX_PKG_SRCURL refers to git+ URL, i.e for a branch (like master) that's being continuously updated on a remote git repository (git+https://) or in a local git repository directory (git+file://) (where any new changes must also be committed to branch to be downloaded).
Skip dependency check.
Install dependencies without version binding.
Specify format of built packages. Valid values are: debian (default) and pacman.
Specify library of package. Valid values are: bionic and glibc
The variables for which Termux packages are compiled for are sourced by the build-package.sh script from the properties.sh file.
Some of the core variables are $TERMUX_APP__PACKAGE_NAME, $TERMUX_APP__DATA_DIR, $TERMUX__PROJECT_DIR, $TERMUX__CORE_DIR, $TERMUX__APPS_DIR, $TERMUX__ROOTFS, $TERMUX__HOME, and $TERMUX__PREFIX so that Termux packages work in the app data directory assigned by Android to the Termux app. If the values are changed, like if forking to compile packages for a different app package name, then packages hosted by Termux package repositories cannot be used, like with -i/-I flags. All packages will need to be compiled for the custom app package name manually and optionally hosted on custom packages repository if required. Packages cannot be mixed with the ones with a different app package name, like com.termux and a custom one, as packages will likely not work at runtime. Check $TERMUX_REPO_* variables in properties.sh for more info.
The following environment variables affect behaviour of Termux build system.
Specifies the base directory for Termux build environment. Standalone toolchain, downloaded sources, package build directories will be created here. Default is $HOME/.termux-build.
Specifies amount of jobs that should be spawned by utility make. Default is output of command nproc.
Specifies Android API level against which packages will be compiled. Default is 24 (Android 7) for master branch and 21 (Android 5) for android-5 branch.
Specifies a value that should be written to package's maintainer field. Default is @termux.
Specifies a root directory of package tree. Default is packages.
The following variables are overridden with command options passed to the build-package.sh script.
Specifies CPU architecture for which packages should be cross-compiled. Default is aarch64. Cannot be changed when building on device.
If set, build will skip source extraction and configure step and go straight to termux_step_make.
Perform debug build. Debug information won't be stripped from binaries and compiler optimizations will be turned off.
If set to true, then dependencies will be installed from the package repositories rather than built.
Special option for use with $TERMUX_INSTALL_DEPS. If set to false, then Termux system root will not be wiped before extracting dependencies. When building on device, this variable should always be false.
If set, additional arguments will be passed to utility make to reduce output in compilation process.
If set, then no dependency checks will be done.
Path to directory where built package files (*.deb/*.pkg.tar.xz) will be placed.
Build starts at the moment of execution of ./build-package.sh script and is split into the following stages (environment initialization steps are omitted):
-
Source the
./packages/$TERMUX_PACKAGE_NAME/build.shfile to obtain metadata such like version, description, dependencies, source URL and package-specific build steps. -
In case if
build-package.shgot arguments-ior-I, download package files (*.deb/*.pkg.tar.xz) from package repositories and extract to$TERMUX__PREFIX. Otherwise obtain the dependency build order from script./scripts/buildorder.pyand execute./build-package.shwith argument-sfor each dependency package. -
Create timestamp file which will be used later.
-
Download package's source code from the URL and verify its SHA-256 checksum. Then extract source code to
$TERMUX_PKG_SRCDIR. This step is omitted if$TERMUX_PKG_SKIP_SRC_EXTRACTis set. -
Build package for the host. This step is performed only when
$TERMUX_PKG_HOSTBUILDis set. -
Set up a standalone Android NDK toolchain and apply NDK sysroot patches. This step is performed only one time.
-
Search for patches in
./packages/$TERMUX_PKG_NAME/*.patchand apply them. -
Configure and compile source code for specified
$TERMUX_ARCH. -
Install everything into
$TERMUX__PREFIX. -
Determine files which are modified from time when timestamp file was created (step 3) and extract them into
$TERMUX_TOPDIR/$TERMUX_PKG_NAME/massage. -
Strip binaries (if non-debug build), gzip manpages, delete unwanted files and fix permissions. Distribute files between subpackages if needed.
-
Archive package data into package files (
*.deb/*.pkg.tar.xz) ready for distribution.
Order specifies function sequence. 0 order specifies utility functions.
Suborder specifies a function triggered by the main function. Functions with different suborders are not executed simultaneously.
| Order | Function Name | Overridable | Description |
|---|---|---|---|
| 0.1 | termux_error_exit |
no | Stop script and output error. |
| 0.2 | termux_download |
no | Utility function to download any file. |
| 0.3 | termux_setup_golang |
no | Setup Go Build environment. |
| 0.4 | termux_setup_cmake |
no | Setup CMake configure system. |
| 0.5 | termux_setup_ninja |
no | Setup Ninja make system. |
| 0.6 | termux_setup_meson |
no | Setup Meson configure system. |
| 0.7 | termux_setup_protobuf |
no | Setup Protobuf compiler. |
| 0.8 | termux_setup_rust |
no | Setup Cargo Build. |
| 0.9 | termux_setup_ghc_cross_compiler |
no | Setup ghc cross-compiler targeting Android. |
| 0.10 | termux_setup_ghc |
no | Setup ghc compiler for host build. |
| 0.11 | termux_setup_jailbreak_cabal |
no | Setup jailbreak-cabal utility. It is used to remove version constraints from Haskell (with cabal build system) |
| 1 | termux_step_setup_variables |
no | Setup essential variables like directory locations and flags. |
| 2 | termux_step_handle_buildarch |
no | Determine architecture to build for. |
| 3 | termux_step_setup_build_folders |
no | Delete old src and build directories if they exist. |
| 4 | termux_step_start_build |
no | Initialize build environment. Source package's build.sh. |
| 5 | termux_step_get_dependencies |
no | Download or build specified dependencies of the package. |
| 5.1 | termux_step_get_repo_files |
no | Fetch package repositories information when -i or -I option was supplied. |
| 5.2 | termux_extract_dep_info |
no | Obtain package architecture and version for downloading. |
| 6 | termux_step_create_timestamp_file |
no | Make timestamp to determine which files have been installed by the build. |
| 5.3 | termux_download_deb_pac |
no | Download dependency package files (*.deb/*.pkg.tar.xz) for installation. |
| 6 | termux_step_get_source |
yes | Obtain package source code and put it in $TERMUX_PKG_SRCDIR. |
| 7.1 | termux_git_clone_src |
no | Obtain source by git clone, is run if $TERMUX_PKG_SRCURL ends with ".git". |
| 7.2 | termux_download_src_archive |
no | Download zip or tar archive with package source code. |
| 7.3 | termux_unpack_src_archive |
no | Extract downloaded archive into $TERMUX_PKG_SRCDIR. |
| 8 | termux_step_post_get_source |
yes | Hook to run commands immediately after obtaining source code. |
| 9 | termux_step_handle_host_build |
yes | Determine whether a host build is required. |
| 9.1 | termux_step_host_build |
yes | Perform a host build. |
| 10 | termux_step_setup_toolchain |
no | Setup NDK standalone toolchain. |
| 11 | termux_step_patch_package |
no | Apply to source code all *.patch files located in package's directory. |
| 12 | termux_step_replace_guess_scripts |
no | Replace config.sub and config.guess scripts. |
| 13 | termux_step_pre_configure |
yes | Hook to run commands before source configuration. |
| 14 | termux_step_configure |
yes | Configure sources. By default, it determines build system automatically. |
| 14.1 | termux_step_configure_haskell_build |
no | Haskell packages build configuration. |
| 14.2 | termux_step_configure_autotools |
no | Autotools build configuration. |
| 14.3 | termux_step_configure_cmake |
no | CMake build configuration. |
| 14.4 | termux_step_configure_meson |
no | Meson build configuration. |
| 15 | termux_step_post_configure |
yes | Hook to run commands immediately after configuration. |
| 16 | termux_step_make |
yes | Compile the source code. |
| 17 | termux_step_make_install |
yes | Install the compiled artifacts. |
| 18 | termux_step_post_make_install |
yes | Hook to run commands immediately after installation. |
| 19 | termux_step_install_service_scripts |
yes | Installs scripts for termux-services |
| 20 | termux_step_install_license |
yes | Link or copy package-specific LICENSE to ./share/doc/$TERMUX_PKG_NAME. |
| 21 | termux_step_extract_into_massagedir |
no with make_install
|
Extract files modified in $TERMUX__PREFIX. |
| 22 | termux_step_massage |
no | Strip binaries, remove unneeded files. |
| 22.1 | termux_create_debian_subpackages |
no | Creates all subpackages (debian format). |
| 22.2 | termux_create_pacman_subpackages |
no | Creates all subpackages (pacman format). |
| 24 | termux_step_post_massage |
yes | Final hook before creating package file(s) (*.deb/*.pkg.tar.xz). |
| 25 | termux_step_create_debian_package |
no | Create debian package file (*.deb). |
| 25.1 | termux_step_create_pacman_package |
no | Create pacman package file (*.pkg.tar.xz). |
| 25.2 | termux_step_create_debscripts |
yes | Create maintainer scripts, e.g. pre/post installation hooks. |
| 25.3 | termux_step_create_pacman_install_hook |
no | Convert result of termux_step_create_debscripts to pacman-compatible format. |
| 26 | termux_step_finish_build |
no | Notification of finish. |
The build-package.sh script can also be used to build a package whose sources exist on the local filesystem, instead of remote source URLs that is defined in the $TERMUX_PKG_SRCURL variable of the build.sh file of each package.
This can also be used to:
- Test a new package before submission to the
termux-packagesrepo, by creating a local directory for its (upstream) sources. - Test the changes that were made to an existing package after downloading its source locally, like
gitcloning its upstream repo. - Test pull requests sent to a package's upstream git repository, by
gitcloning its repo and building the pull request branch locally.
Clone and change current working directory to it.
git clone https://github.com/termux/termux-packages.git
cd termux-packagesThe $TERMUX_PKG_SRCURL in the build.sh file of the package must be be set to the local filesystem path/URL for where to download the package sources from for building the package.
It must be set in the file:///path/to/source/dir, file:///path/to/source/file or git+file:///path/to/source/git/dir formats, and all formats have their own build time behaviour and whatever is chosen will affect how the local source file or directory should to be created in step 3 below. Check the Package Build Local Source URLs docs for more info. Note that 3 forward slashes / are necessary and file://path is not a valid URL. The path must also be normalized with no duplicate or trailing path separators /.
It is recommended to use the file:///path/to/source/dir format as:
- Any uncommitted changes will get built automatically.
- The
-roption will not need to be passed to re-download the sources on rebuilds. - An
tar/ziparchive of a local source directory will not have to manually created. - It wouldn't matter if the local
gitsource directory was originally cloned with ahttpsorssh(git@)originURL. - However, if
$TERMUX_PKG_GIT_BRANCHvariable is set in thebuild.shof the package, then the branch set will have to manually checkout out.
The build.sh file for a package exist under the <repo_channel>/<package_name> directory in the termux-packages repo root directory where repo_channel refers to the repository channel of the package, whose directory is specified in the repo.json file. For our example, we use the main channel for the foo package, so its path would be packages/foo/build.sh.
If creating a new package, check the Package Build Config and Package Build Script docs for info on the paths for build.sh files and what they should contain.
The /home/builder/termux-packages path below is the path in the termux-packages docker container where the termux-packages repo directory is mounted at and sources/foo under it is where the local source directory or file must be created in step 3.
# packages/foo/build.sh
TERMUX_PKG_SRCURL=file:///home/builder/termux-packages/sources/foo
TERMUX_PKG_SHA256=SKIP_CHECKSUM # May not be needed for source file format. Create a source directory or file on the local filesystem for the package that needs to be compiled.
If building inside the termux-packages docker container, like off-device, then the source must be under the termux-packages repo root directory, otherwise it will not be mounted inside the docker container and wouldn't exist (No, a symlink to an outside directory will not work, but there are ways to mount directories into the mount namepsace of an existing docker bash process, which is planned to be supported in future). Termux reserves the sources sub directory for local source directories, but a different directory can be used too, but it will require making appropriate changes to commands below.
Make sure current working directory is the root directory of termux-packages repo directory before running below commands.
For example, for a package named foo, we create its local source at sources/foo. Replace foo in sources/foo with required package name in below commands.
The following ways may be used to get/create the source depending on the format used in $TERMUX_PKG_SRCURL in step 2, as per Package Build Local Source URLs docs.
-
file:///path/to/source/dirURL format.-
Clone the
gitrepo for an existing package. Replacehttps://github.com/termux/foo.gitwith required package's repogiturl.# Git clone the repo mkdir -p sources git clone https://github.com/termux/foo.git sources/foo # (OPTIONAL) Manually switch to different (pull) branch that # exists on origin if required, or to the one defined in # $TERMUX_PKG_GIT_BRANCH variable of build.sh file, as it will # not be automatically checked out. # By default, the repo default/current branch that's cloned # will get built, which is usually `master` or `main`. # Whatever is the current state of the source directory will # be built as is, including any uncommitted changes to current # branch. (cd sources/foo; git checkout <branch_name>)
-
Download a release source
tarfor an existing package and extract it to source directory. Replacehttps://github.com/termux/foo/archive/<release_version>.tar.gzwith required package's releasetar.gzurl. The source files must be extracted directly under thesources/foodirectory, and not a sub directory, likesources/foo/foo-v0.1.0, this is why the--strip-components=1is passed as GitHub release sourcetarcontain a versioned sub directory attarroot.# Download and extract source tar mkdir -p sources/foo curl -sL https://github.com/termux/foo/archive/<release_version>.tar.gz | tar xzf - -C sources/foo --strip-components=1
-
Create a source directory for a new package and then manually create source files under it that need to be built. Optionally, to initialize a new local
gitrepository, run thegit initcommand.mkdir -p sources/foo
-
-
file:///path/to/source/fileURL format.-
Download a release source
tarfor an existing package at source path. Replacehttps://github.com/termux/foo/archive/<release_version>.tar.gzwith required package's releasetar.gzurl.# Download source tar rm -f sources/foo curl -L https://github.com/termux/termux-am-socket/archive/refs/tags/1.5.0.tar.gz -o sources/foo -
Creating a
tar/ziparchive of some local source files manually with some special logic. Preferable,$TERMUX_PKG_SHA256variable should be set toSKIP_CHECKSUMinbuild.shof package so that checksum is not checked and the archive gets re-downloaded every time on rebuilds.
-
-
git+file:///path/to/source/git/dirURL format.-
To clone the
gitrepo for an existing package. Replacehttps://github.com/termux/foo.gitwith required package's repogiturl. The repo must be cloned with ahttpsURL instead of assh(git@) URL if building withtermux-packagesdocker container and$TERMUX_PKG_GIT_BRANCHis set.# Git clone the repo mkdir -p sources git clone https://github.com/termux/foo.git sources/foo # (OPTIONAL) Manually switch to different (pull) branch that # exists on origin if required. # By default, if $TERMUX_PKG_GIT_BRANCH variable of build.sh # file is set, then that branch will automatically be checked # out, otherwise the repo default/current branch that's cloned # will get built, which is usually `master` or `main`. (cd sources/foo; git checkout <branch_name>) # (OPTIONAL) Any uncommitted changes to current branch will NOT # get built and will need to be committed. git add -A && git commit -m "latest changes"
-
Run the build-package.sh script to build the foo package.
The following arguments are passed:
-
-fflag to force rebuild the package even if its already built. Optionally, this may not be passed if package does not need to be rebuilt. -
-Iflag so that dependencies of thefoopackage are downloaded from Termux package repositories instead of being built locally, as that would be time consuming. Optionally, this may not be passed if package dependencies should be built locally as well. -
fooas the package name argument.
The following arguments may need to be passed:
-
-rflag if to re-download the local packagegitdirectory during rebuild, ifgit+file:///path/to/source/git/dirformatted URL is set in$TERMUX_PKG_SRCURL, otherwise new changes to local sources since first download will not get built.
# Run termux-packages docker container if running off-device
./scripts/run-docker.sh
# Build package
./build-package.sh -f -I foo