diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 57182203be..29f2c6d8b6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -124,7 +124,7 @@ met these conditions: present ones. The more useless packages in repositories, the less overall packaging and - service quality - *remembering that our resources are limited?* + service quality - _remembering that our resources are limited?_ - **Not serving hacking, phishing, spamming, spying, ddos functionality** @@ -148,6 +148,7 @@ provide some help with fixing your pull request or give some recommendations, but that DOES NOT mean they will do all work instead of you. **Minimal requirements:** + - Experience with Linux distribution like Debian (preferred), Arch, Fedora, etc. - Experience with compiling software from source. - Good shell scripting skills. @@ -200,6 +201,7 @@ request with new package. Pay attention to things listed below. other ways to manipulate content referenced through variables. Examples: + ``` TERMUX_PKG_VERSION=1.0 TERMUX_PKG_SRCURL=https://example.com/archive/package-${TERMUX_PKG_VERSION}.tar.gz @@ -231,6 +233,7 @@ request with new package. Pay attention to things listed below. format internals. Patch is usually created by + ``` diff -uNr sourcedir sourcedir.mod > filename.patch ``` @@ -239,23 +242,26 @@ request with new package. Pay attention to things listed below. Software often relies on paths defined by Filesystem Hierarchy Standard: - * `/bin` - * `/etc` - * `/home` - * `/run` - * `/sbin` - * `/tmp` - * `/usr` - * `/var` + - `/bin` + - `/etc` + - `/home` + - `/run` + - `/sbin` + - `/tmp` + - `/usr` + - `/var` These paths do not exist in Termux and have been replaced by prefixed equivalents. Termux installation prefix is + ``` /data/data/com.termux/files/usr ``` + and can be considered as virtual rootfs. Home directory is stored outside of prefix: + ``` /data/data/com.termux/files/home ``` @@ -278,18 +284,18 @@ request with new package. Pay attention to things listed below. package builds using GNU Autotools. Therefore you do not need to specify flags like - * `--prefix` - * `--host` - * `--build` - * `--disable-nls` - * `--disable-rpath` + - `--prefix` + - `--host` + - `--build` + - `--disable-nls` + - `--disable-rpath` and some others. Additional options to `./configure` can be passed through variable `TERMUX_PKG_EXTRA_CONFIGURE_ARGS`. -*** +--- # Working with packages @@ -298,6 +304,154 @@ OS and is built by Android NDK. This often introduces compatibility issues as Android (specifically Termux) is not a standard platform. Do not expect there are exist package recipes available out-of-box. +## Commit guidelines + +Commit messages should describe the changes done, so that maintainers can understand what was done, and to what package or scope, without having to look at the code changes. One good (but not mandatory) way to make sure the commit message fulfills these requirements is to write it on the format: + +``` +(/): (Summary of change(s) made/Short description of the change) + +[An optional but **highly recommended** commit message describing the changes made in the commit] + +[Fixes (termux/repo)#] +[Closes (termux/repo)#] +``` + +Where: + +- `` may be one of `main`, `root` or `x11`. It is the repository in which the package resides. + Other definition for this property can be done as the name property of the package directory as defined in `repo.json` file after removing the 'termux-' prefix (if any). +- `` is the actual name of the package. + +Any line in the commit **should not exceed 80 characters**. In case it does, consider using different wordings or language style which better summarizes the changes done. + +- `` describes the type of commit. Types of commits: + - `addpkg(/)`: A new package was added. + Commit summary should include a short description of the package. Optional extended commit message may include usage instructions for the package and/or reasons for inclusion. + - `upgpkg(/)`: One or more package(s) was/were updated. + Commit summary should include the newer version/tag to which the package was updated to. Optional extended commit message may include new list of features in the new version, and detailed list of changes in build scripts and/or patches + - `fix(/): Fix a Termux specific bug in a package + Commit summary should contain a summary of old incorrect behaviour of the package. Extended commit message may contain a deeper analysis of the bug. + - `dwnpkg(/)`: One or more package(s) was/were downgraded due to build issues or potential bugs + Commit summary should justify the downgrading of the package(s). If the summary can't completely describe the reason for downgrade, extended commit message should contain full reason for downgrade. + - `disable(/)`: A package was disabled. The short description should contain the reason for disabling of the package. + If the reason doesn't fit well in the sunmary, extended commit message should contain the complete reason for disabling. + - `enhance(/)`: Enable a feature in a package that was earlier not enabled. + Optional (but highly recommended) extended commit message may contain detailed summary of the enabled feature(s) and a basic use case + - `chore`: Any housekeeping change or a change which does not affect the user in any way. + - `rebuild`: Rebuild a package to link against newer version of shared library + Special cases: + - When mass rebuilding packages depending on a major package (e.g. openssl), consider using this format: + ``` + rebuild(deps:main/openssl): link against OpenSSL 3.0 + ``` + - `scripts(path/to/script)`: Any change affecting our build scripts or other scripts which are not a part of build recipies including toolchain setup scripts. + - `ci(action_file_without_extension)`: Any change that affects GitHub Actions yaml file(s) and/or scripts used exclusively by it. + +Examples of good commit messages: + +1. ``` + upgpkg(main/nodejs): upgrade to v18.2.0 + ``` + +2. ``` + dwnpkg(main/htop): downgrade to v2.2.0 + + v3.x needs access to /proc/stat which is now restricted by Android + ``` + +3. ``` + enhance,upgpkg(main/nodejs): update to v18.2.0 and use shared libuv + + # Describe the technical reasons of how using shared libuv is beneficial + ``` + +4. ``` + disable(main/nodejs): use LTS version instead + + PS: This won't ever happen. Just an example :P + ``` + +5. ``` + ci(package_updates): panic on invalid versions + ``` + +6. ``` + chore,scripts(bin/revbump): support passing path to build.sh + + Earlier only package directories defined in `repo.json` could be revbumped. + Now you can pass the path to build.sh + ``` + +7. ``` + fix(main/nodejs{,-lts}): test failures for `process.report` + + This shows an example when scope can be minimised if they belong to the + same repository, and have same initials as well as are very similar in + nature. + + The same can also be used for liblua as main/liblua{51,52,53,54} + ``` + +8. ``` + fix(main/vim{,-python},x11/vim-gtk): cursor flickering under certain rare conditions + + Although the above commit message is quite long and also exceeds the + recommended length of a line in commit message. Such commits may be accepted + in cases where the changes are very similar for all three packages. + ``` + +### Special notes for newbies who're just getting started with Open Source + +In order to encourage new contributors and help them contribute to open source, the above mentioned commit requirements should be optionally relaxed. In cases where commit messages need to be changed, the PR may be **Squashed and Merged** or may be merged manually from the command line. + +#### Notes for merging PRs from command line + +1. It is recommended to use the [GitHub CLI (`gh`)](https://cli.github.com) in order to fetch the contributor's branch. + + ```sh + gh pr checkout + ``` + +2. After checking out the branch, amend the commit message and optionally rebase against the master branch (if necessary). + + When merging manually make sure that you give proper credits for the original patch to it's author by adding a `Co-authored-by: ` line. See https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors for more details. Also add a `Closes #`. + + **Note** that the `Closes` and `Co-authored-by` lines are needed only when the PR author has disabled ability for maintainers to push to their branches. If possible, it is recommended to force-push to user's branch and then push the change to master branch since GitHub UI then will detect a merge. + + ```sh + git fetch + git rebase origin/master + + git commit --amend # Will open up your editor to amend the commit message + + # If possible push to PR author's branch + # Note: no need to configure remote branch if you checked + # out using GitHub CLI. + # git push -f + ``` + +3. Note down the branch name + + ```sh + git branch + ``` + +4. Merge the branch manually + + ```sh + git switch master + + # Note depending upon your git configuration, the default + # merge strategy may vary. It is recommended to pass the + # merge strategy as a flag to git. + git merge + ``` + +5. Congratulate the user on sending their (probably) first OSS contribution! + +6. Note that sometimes GitHub UI may fail to detect the merge, in such cases make sure that you tell the contributor that their PR was merged manually and they'll recieve their due credits in the repository contribution graph. + ## Basics Each package is a defined through the `build.sh` script placed into directory @@ -320,6 +474,7 @@ TERMUX_PKG_DEPENDS="libiconv, ncurses" ``` It can contain some additional variables: + - `TERMUX_PKG_BUILD_IN_SRC=true` Use this variable if package supports in-tree builds only, for example if @@ -428,6 +583,7 @@ Here are few things you may to try: by patch. Regenerate patch file, e.g. with: + ``` diff -uNr package-1.0 package-1.0.mod > previously-failed-patch-file.patch ``` @@ -466,7 +622,7 @@ TERMUX_PKG_VERSION=1:5.0.0 ``` Note that if you are not @termux collaborator, pull request must contain a -*description* why you are submitting a package downgrade. All pull requests +_description_ why you are submitting a package downgrade. All pull requests which submit package downgrading without any serious reason will be rejected. ## Common build issues @@ -477,6 +633,7 @@ No files in package. Maybe you need to run autoreconf -fi before configuring? Means that build system cannot find the Makefile. Depending on project, there are some tips for trying: + - Set `TERMUX_PKG_BUILD_IN_SRC=true` - applicable to Makefile-only projects. - Run `./autogen.sh` or `autoreconf -fi` in `termux_step_pre_configure`. This is applicable to projects that use Autotools. diff --git a/scripts/bin/revbump b/scripts/bin/revbump index 9eb39cb090..df35c340ec 100755 --- a/scripts/bin/revbump +++ b/scripts/bin/revbump @@ -15,9 +15,11 @@ ## limitations under the License. ## +echo "WARNING: interface to this script has been changed. Run without any arguments to see the help message" + if [ "${#}" = "0" ]; then echo - echo "Usage: revbump [package name] ..." + echo "Usage: revbump [reason for rebuild] [package names] ..." echo echo "Add or increment TERMUX_PKG_REVISION of package." echo @@ -31,11 +33,13 @@ if git status >/dev/null 2>&1; then IS_GIT_REPOSITORY=true fi -for package in "${@}"; do +for package in "${@:2}"; do package="${package%%/}" buildsh_path= - for repo in $(jq --raw-output 'keys | .[]' ${REPO_ROOT}/repo.json); do - _buildsh_path="${REPO_ROOT}/${repo}/${package}/build.sh" + repo= + for repo_path in $(jq --raw-output 'keys | .[]' ${REPO_ROOT}/repo.json); do + _buildsh_path="${REPO_ROOT}/${repo_path}/${package}/build.sh" + repo=$(jq --raw-output ".[\"${repo_path}\"].repo" ${REPO_ROOT}/repo.json) echo $_buildsh_path if [ -f "${_buildsh_path}" ]; then @@ -76,13 +80,13 @@ for package in "${@}"; do git --no-pager diff --patch "${buildsh_path}" echo "--------------------" echo - echo "${package}: bump revision" + echo "rebuild(${repo}/${package}): $1" echo read -re -p "Do you want to commit these changes ? (y/n) " CHOICE echo if [[ ${CHOICE} =~ (Y|y) ]]; then git add "${buildsh_path}" - git commit -m "${package}: bump revision" + git commit -m "rebuild(${repo}/${package}): $1" else echo "Not committing to Git!" fi diff --git a/scripts/bin/update-checksum b/scripts/bin/update-checksum index 29df3edf50..988ab3b568 100755 --- a/scripts/bin/update-checksum +++ b/scripts/bin/update-checksum @@ -35,12 +35,15 @@ fi for package in "${@}"; do buildsh_path= + repo= if [ -d "${package}" ] && [ -f "${package}/build.sh" ]; then buildsh_path="${package}/build.sh" package=$(basename ${package}) else for repo_path in $(jq --raw-output 'keys | .[]' $REPO_ROOT/repo.json); do if [ -d "${repo_path}/${package}" ] && [ -f "${repo_path}/${package}/build.sh" ]; then + repo=$(jq --raw-output '.["'$repo_path'"].name' $REPO_ROOT/repo.json) + repo=${repo#"termux-"} buildsh_path="${repo_path}/${package}/build.sh" package=$(basename ${package}) fi @@ -90,13 +93,13 @@ for package in "${@}"; do git --no-pager diff --patch "${buildsh_path}" echo "--------------------" echo - echo "${package}: update to $(. "${buildsh_path}"; echo "${TERMUX_PKG_VERSION}" | cut -d: -f2-)" + echo "upgpkg(${repo}/${package}): update to $(. "${buildsh_path}"; echo "${TERMUX_PKG_VERSION}" | cut -d: -f2-)" echo read -re -p "Do you want to commit changes ? (y/n) " CHOICE echo if [[ ${CHOICE} =~ (Y|y) ]]; then git add "${buildsh_path}" - git commit -m "${package}: update to $(. "${buildsh_path}"; echo "${TERMUX_PKG_VERSION}" | cut -d: -f2-)" + git commit -m "upgpkg(${repo}/${package}): update to $(. "${buildsh_path}"; echo "${TERMUX_PKG_VERSION}" | cut -d: -f2-)" else echo "Not committing to Git!" fi diff --git a/scripts/setup-offline-bundle.sh b/scripts/setup-offline-bundle.sh index 160dfc1501..624953a957 100755 --- a/scripts/setup-offline-bundle.sh +++ b/scripts/setup-offline-bundle.sh @@ -14,11 +14,18 @@ fi export TERMUX_SCRIPTDIR="$(dirname "$(readlink -f "$0")")/../" mkdir -p "$TERMUX_SCRIPTDIR"/build-tools +. "$TERMUX_SCRIPTDIR"/scripts/properties.sh +: "${TERMUX_MAKE_PROCESSES:="$(nproc)"}" +export TERMUX_MAKE_PROCESSES export TERMUX_PACKAGES_OFFLINE=true export TERMUX_ARCH=aarch64 export TERMUX_ON_DEVICE_BUILD=false -export TERMUX_PKG_TMPDIR=$TERMUX_SCRIPTDIR/build-tools/_tmp -export TERMUX_COMMON_CACHEDIR=$TERMUX_PKG_TMPDIR +export TERMUX_PKG_TMPDIR="$TERMUX_SCRIPTDIR/build-tools/_tmp" +export TERMUX_COMMON_CACHEDIR="$TERMUX_PKG_TMPDIR" +export TERMUX_HOST_PLATFORM=aarch64-linux-android +export TERMUX_ARCH_BITS=64 +export TERMUX_BUILD_TUPLE=x86_64-pc-linux-gnu +export TERMUX_PKG_API_LEVEL=24 export CC=gcc CXX=g++ LD=ld AR=ar STRIP=strip PKG_CONFIG=pkg-config export CPPFLAGS="" CFLAGS="" CXXFLAGS="" LDFLAGS="" mkdir -p "$TERMUX_PKG_TMPDIR" @@ -65,42 +72,38 @@ rm -rf "${TERMUX_PKG_TMPDIR}" for repo_path in $(jq --raw-output 'keys | .[]' $TERMUX_SCRIPTDIR/repo.json); do for p in "$TERMUX_SCRIPTDIR"/$repo_path/*; do ( - . "$TERMUX_SCRIPTDIR"/scripts/properties.sh . "$TERMUX_SCRIPTDIR"/scripts/build/get_source/termux_step_get_source.sh . "$TERMUX_SCRIPTDIR"/scripts/build/get_source/termux_git_clone_src.sh . "$TERMUX_SCRIPTDIR"/scripts/build/get_source/termux_download_src_archive.sh . "$TERMUX_SCRIPTDIR"/scripts/build/get_source/termux_unpack_src_archive.sh - + # Disable archive extraction in termux_step_get_source.sh. termux_extract_src_archive() { : } - + TERMUX_PKG_NAME=$(basename "$p") TERMUX_PKG_BUILDER_DIR="${p}" TERMUX_PKG_CACHEDIR="${p}/cache" TERMUX_PKG_METAPACKAGE=false - + # Set some variables to dummy values to avoid errors. TERMUX_PKG_TMPDIR="${TERMUX_PKG_CACHEDIR}/.tmp" TERMUX_PKG_SRCDIR="${TERMUX_PKG_CACHEDIR}/.src" TERMUX_PKG_BUILDDIR="$TERMUX_PKG_SRCDIR" - TERMUX_PKG_HOSTBUILD_DIR=$TERMUX_PKG_TMPDIR - TERMUX_HOST_PLATFORM=aarch64-linux-android - TERMUX_ARCH_BITS=64 - TERMUX_BUILD_TUPLE=x86_64-pc-linux-gnu + TERMUX_PKG_HOSTBUILD_DIR="$TERMUX_PKG_TMPDIR" TERMUX_PKG_GIT_BRANCH="" TERMUX_DEBUG_BUILD=false - TERMUX_MAKE_PROCESSES=1 - + + mkdir -p "$TERMUX_PKG_CACHEDIR" "$TERMUX_PKG_TMPDIR" "$TERMUX_PKG_SRCDIR" cd "$TERMUX_PKG_CACHEDIR" - + . "${p}"/build.sh || true if ! ${TERMUX_PKG_METAPACKAGE}; then echo "Downloading sources for '$TERMUX_PKG_NAME'..." termux_step_get_source - + # Delete dummy src and tmp directories. rm -rf "$TERMUX_PKG_TMPDIR" "$TERMUX_PKG_SRCDIR" fi diff --git a/scripts/updates/utils/termux_pkg_upgrade_version.sh b/scripts/updates/utils/termux_pkg_upgrade_version.sh index c78a04a712..ab49a8ef4a 100755 --- a/scripts/updates/utils/termux_pkg_upgrade_version.sh +++ b/scripts/updates/utils/termux_pkg_upgrade_version.sh @@ -63,12 +63,13 @@ termux_pkg_upgrade_version() { fi echo "INFO: Trying to build package." + repo=$(jq --raw-output $(basename $(dirname ${TERMUX_SCRIPTDIR}/*packages/${TERMUX_PKG_NAME})) ${TERMUX_SCRIPTDIR}/repo.json) if "${TERMUX_SCRIPTDIR}/scripts/run-docker.sh" ./build-package.sh -a "${TERMUX_ARCH}" -I "${TERMUX_PKG_NAME}"; then if [[ "${GIT_COMMIT_PACKAGES}" == "true" ]]; then echo "INFO: Committing package." stderr="$( git add "${TERMUX_PKG_BUILDER_DIR}" 2>&1 >/dev/null - git commit -m "${TERMUX_PKG_NAME}: update to ${LATEST_VERSION}" \ + git commit -m "upgpkg(${repo}/${TERMUX_PKG_NAME}): update to ${LATEST_VERSION}" \ -m "This commit has been automatically submitted by Github Actions." 2>&1 >/dev/null )" || { termux_error_exit <<-EndOfError