commit ef47fd365f566fe21ff0b01ec91e03dad34d052e Author: Jozef Steinhübl Date: Fri Mar 29 08:12:19 2024 +0100 add vesktop diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..002ee90 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,22 @@ +root = true + +[*] +indent_style = tab +end_of_line = lf +charset = utf-8 +trim_trailing_whitespace = true +insert_final_newline = true + +[*.md] +indent_size = 4 +indent_style = space + +[*.{yml,yaml}] +indent_size = 2 +indent_style = space + +[*.{patch,diff}] +indent_style = unset +end_of_line = unset +charset = unset +trim_trailing_whitespace = unset diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..8ddae6f --- /dev/null +++ b/.gitattributes @@ -0,0 +1,4 @@ +template linguist-language=bash +common/shlibs merge=union +*.patch whitespace=-space-before-tab,-trailing-space +*.diff whitespace=-space-before-tab,-trailing-space diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml new file mode 100644 index 0000000..7437bc1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -0,0 +1,73 @@ +name: Bug Report +description: File a bug report +labels: ["bug", "needs-testing"] +body: + - type: markdown + attributes: + value: > + #### Don't request an update of a package, + [We have a script for that](https://repo-default.voidlinux.org/void-updates/void-updates.txt). + However, a quality pull request may help. + - id: verified + type: dropdown + attributes: + label: Is this a new report? + description: I verified that there isn't already an open issue for this bug + options: + - "Yes" + - "No" + validations: + required: true + - id: xuname + type: input + attributes: + label: System Info + description: Output of `xuname` (part of [`xtools`](https://man.voidlinux.org/xtools.1)) + placeholder: Void 5.x.y_z x86_64-musl ... + validations: + required: true + - id: packages + type: input + attributes: + label: Package(s) Affected + description: Affected package(s) including version (this can be found with `xbps-query -p pkgver foo`) + placeholder: foo-1.0.2_5, bar-5.6.7_1, baz-0.0.3_5, ... + validations: + required: true + - id: upstream + type: textarea + attributes: + label: Does a report exist for this bug with the project's home (upstream) and/or another distro? + description: If so, link it here (It's fine if there's none) + placeholder: | + For example: + https://bugs.kde.org/show_bug.cgi?id=432975 + https://bugs.gentoo.org/767478 + - id: expected + type: textarea + attributes: + label: Expected behaviour + description: A clear and concise description of what you expected to happen + placeholder: The package is supposed to do this thing. + validations: + required: true + - id: description + type: textarea + attributes: + label: Actual behaviour + description: A clear and concise description of what the bug is + placeholder: There was a crash when... + validations: + required: true + - id: steps + type: textarea + attributes: + label: Steps to reproduce + description: Clear steps to reproduce the bug + placeholder: | + 1. Do the thing + 2. Do the other thing + 3. ??? + 4. Crash :( + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..a580237 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: Other kind of issue + url: https://github.com/void-linux/void-packages/issues/new + about: For RFCs, tracking issues, etc (freeform text) diff --git a/.github/ISSUE_TEMPLATE/pkg-request.yml b/.github/ISSUE_TEMPLATE/pkg-request.yml new file mode 100644 index 0000000..b173d8f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/pkg-request.yml @@ -0,0 +1,59 @@ +name: Package Request +title: "Package request: " +description: Request the addition of a package +labels: ["request"] +body: + - type: markdown + attributes: + value: > + #### Don't request an update of a package, + [We have a script for that](https://repo-default.voidlinux.org/void-updates/void-updates.txt). + However, a quality pull request may help. + - id: name + type: input + attributes: + label: Package name + placeholder: foobar9k + validations: + required: true + - id: homepage + type: input + attributes: + label: Package homepage + placeholder: https://example.com/foobar9k + validations: + required: true + - id: description + type: textarea + attributes: + label: Description + description: What does the package do? + placeholder: > + Foobar9k is a music player that turns your music up to 11. + It provides features X, Y, and Z, which other music players in Void don't. + validations: + required: true + - id: quality + type: dropdown + attributes: + label: Does the requested package meet the package requirements? + description: | + See [CONTRIBUTING.md](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md#package-requirements) for details + multiple: true + options: + - System + - Compiled + - Required + validations: + required: true + - id: released + type: dropdown + attributes: + label: Is the requested package released? + description: | + See [CONTRIBUTING.md](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md#package-requirements) for details + options: + - "Yes" + - "No" + validations: + required: true diff --git a/.github/issue_template.md b/.github/issue_template.md new file mode 100644 index 0000000..9a25a2b --- /dev/null +++ b/.github/issue_template.md @@ -0,0 +1,8 @@ + diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..57f7cc9 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,23 @@ + + +#### Testing the changes +- I tested the changes in this PR: **YES**|**briefly**|**NO** + + + + + diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml new file mode 100644 index 0000000..03b5c27 --- /dev/null +++ b/.github/workflows/build.yaml @@ -0,0 +1,144 @@ +name: Check build + +on: + pull_request: + paths: + - 'srcpkgs/**' + push: + branches: + - 'ci-**' + paths: + - 'srcpkgs/**' + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + # Lint changed templates. + xlint: + name: Lint templates + runs-on: ubuntu-latest + + container: + image: 'ghcr.io/void-linux/void-buildroot-musl:20231230R1' + env: + PATH: '/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/sbin:/usr/local/bin:/tmp/bin' + LICENSE_LIST: common/travis/license.lst + + steps: + - name: Prepare container + run: | + # switch to repo-ci mirror + mkdir -p /etc/xbps.d && cp /usr/share/xbps.d/*-repository-*.conf /etc/xbps.d/ + sed -i 's|repo-default|repo-ci|g' /etc/xbps.d/*-repository-*.conf + # Sync and upgrade once, assume error comes from xbps update + xbps-install -Syu || xbps-install -yu xbps + # Upgrade again (in case there was a xbps update) + xbps-install -yu + # install tools needed for lints + xbps-install -y grep curl git + - name: Clone and checkout + uses: classabbyamp/treeless-checkout-action@v1 + - name: Create hostrepo and prepare masterdir + run: | + ln -s "$(pwd)" /hostrepo && + common/travis/set_mirror.sh && + common/travis/prepare.sh && + common/travis/fetch-xtools.sh + - run: common/travis/changed_templates.sh + - name: Run lints + run: | + rv=0 + common/travis/xlint.sh || rv=1 + common/travis/verify-update-check.sh || rv=1 + exit $rv + + # Build changed packages. + build: + name: Build packages + runs-on: ubuntu-latest + if: "!contains(github.event.pull_request.title, '[ci skip]') && !contains(github.event.pull_request.body, '[ci skip]')" + + container: + image: ghcr.io/void-linux/void-buildroot-${{ matrix.config.libc }}:20231230R1 + options: --platform ${{ matrix.config.platform }} + env: + PATH: '/usr/libexec/chroot-git:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/sbin:/usr/local/bin:/tmp/bin' + ARCH: '${{ matrix.config.arch }}' + BOOTSTRAP: '${{ matrix.config.host }}' + TEST: '${{ matrix.config.test }}' + HOSTREPO: /hostrepo + + strategy: + fail-fast: false + matrix: + config: + - { arch: x86_64, host: x86_64, libc: glibc, platform: linux/amd64, test: 1 } + - { arch: i686, host: i686, libc: glibc, platform: linux/386, test: 1 } + - { arch: aarch64, host: x86_64, libc: glibc, platform: linux/amd64, test: 0 } + - { arch: armv7l, host: x86_64, libc: glibc, platform: linux/amd64, test: 0 } + - { arch: x86_64-musl, host: x86_64-musl, libc: musl, platform: linux/amd64, test: 1 } + - { arch: armv6l-musl, host: x86_64-musl, libc: musl, platform: linux/amd64, test: 0 } + - { arch: aarch64-musl, host: x86_64-musl, libc: musl, platform: linux/amd64, test: 0 } + + steps: + - name: Prepare container + run: | + # switch to repo-ci mirror + mkdir -p /etc/xbps.d && cp /usr/share/xbps.d/*-repository-*.conf /etc/xbps.d/ + sed -i 's|repo-default|repo-ci|g' /etc/xbps.d/*-repository-*.conf + # Sync and upgrade once, assume error comes from xbps update + xbps-install -Syu || xbps-install -yu xbps + # Upgrade again (in case there was a xbps update) + xbps-install -yu + + - name: Clone and checkout + uses: classabbyamp/treeless-checkout-action@v1 + - name: Create hostrepo and prepare masterdir + run: | + ln -s "$(pwd)" /hostrepo && + common/travis/set_mirror.sh && + common/travis/prepare.sh && + common/travis/fetch-xtools.sh + - run: common/travis/changed_templates.sh + + - name: Build and check packages + run: | + ( + here="$(pwd)" + cd / + "$here/common/travis/build.sh" "$BOOTSTRAP" "$ARCH" "$TEST" + ) + + - name: Show files + run: | + ( + here="$(pwd)" + cd / + "$here/common/travis/show_files.sh" "$BOOTSTRAP" "$ARCH" + ) + + - name: Compare to previous + run: | + ( + here="$(pwd)" + cd / + "$here/common/travis/xpkgdiff.sh" "$BOOTSTRAP" "$ARCH" + ) + + - name: Check file conflicts + if: matrix.config.arch == 'x86_64' # the arch indexed in xlocate + run: | + if [ -s /tmp/templates ]; then + xlocate -S && + common/scripts/lint-conflicts $HOME/hostdir/binpkgs + fi + + - name: Verify repository state + run: | + ( + here="$(pwd)" + cd / + "$here/common/travis/check-install.sh" "$BOOTSTRAP" "$ARCH" + ) diff --git a/.github/workflows/container.yaml b/.github/workflows/container.yaml new file mode 100644 index 0000000..957b6e8 --- /dev/null +++ b/.github/workflows/container.yaml @@ -0,0 +1,98 @@ +--- +name: 'Build buildroot containers' + +on: + workflow_dispatch: + pull_request: + branches: + - master + paths: + - common/container/** + push: + branches: + - master + paths: + - common/container/** + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + + permissions: + contents: read + packages: write + + strategy: + matrix: + libc: + - glibc + - musl + + steps: + - name: Checkout + uses: classabbyamp/treeless-checkout-action@v1 + + - name: Get image release + id: release + run: | + # gets the list of all date-shaped tags for the image, finds the most recent one + tag="$(skopeo list-tags "docker://ghcr.io/${{ github.repository_owner }}/void-buildroot-${{ matrix.libc }}" | \ + jq -r '.Tags | sort | reverse | map(select(test("^[0-9]{8}(R[0-9]+)?$")))[0]')" + # tags from a different day or pre-YYYYMMDDRN + if [ "${tag%R*}" != "$(date -u +%Y%m%d)" ] || [ "${tag%R*}" = "${tag}" ]; then + rel=1 + else + rel=$(( ${tag##*R} + 1 )) + fi + echo "rel=${rel}" >> "${GITHUB_OUTPUT}" + + - name: Docker metadata + id: meta + uses: docker/metadata-action@v4 + with: + images: | + ghcr.io/${{ github.repository_owner }}/void-buildroot-${{ matrix.libc }} + tags: | + type=sha,prefix= + type=raw,value=latest,enable={{is_default_branch}} + type=raw,value={{date 'YYYYMMDD'}}R${{ steps.release.outputs.rel }},enable={{is_default_branch}},priority=1000 + flavor: latest=false + labels: | + org.opencontainers.image.authors=Void Linux team and contributors + org.opencontainers.image.url=https://voidlinux.org + org.opencontainers.image.documentation=https://github.com/${{ github.repository }} + org.opencontainers.image.source=https://github.com/${{ github.repository }} + org.opencontainers.image.vendor=Void Linux + org.opencontainers.image.title=Void Linux build root + org.opencontainers.image.description=Image for building packages with xbps-src on Void Linux + + - name: Set up QEMU + uses: docker/setup-qemu-action@v2 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v2 + + - name: Login to GCHR + if: github.event_name != 'pull_request' + uses: docker/login-action@v2 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Build and push images + id: build_and_push + uses: docker/bake-action@v3 + with: + push: ${{ github.event_name != 'pull_request' }} + targets: void-buildroot-${{ matrix.libc }} + files: | + common/container/docker-bake.hcl + ${{ steps.meta.outputs.bake-file }} + set: | + _common.cache-to=type=gha + _common.cache-from=type=gha diff --git a/.github/workflows/cycles.yml b/.github/workflows/cycles.yml new file mode 100644 index 0000000..292282d --- /dev/null +++ b/.github/workflows/cycles.yml @@ -0,0 +1,48 @@ +name: 'Cycle Check' + +on: + schedule: + - cron: '0 18 * * *' + +jobs: + cycles: + runs-on: ubuntu-latest + permissions: + issues: write + container: + image: 'ghcr.io/void-linux/void-buildroot-musl:20231230R1' + env: + PATH: '/usr/libexec/chroot-git:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/sbin:/usr/local/bin:/tmp/bin' + steps: + - name: Prepare container + run: | + # switch to repo-ci mirror + mkdir -p /etc/xbps.d && cp /usr/share/xbps.d/*-repository-*.conf /etc/xbps.d/ + sed -i 's|repo-default|repo-ci|g' /etc/xbps.d/*-repository-*.conf + # Sync and upgrade once, assume error comes from xbps update + xbps-install -Syu || xbps-install -yu xbps + # Upgrade again (in case there was a xbps update) + xbps-install -yu + # Install script dependencies + xbps-install -y python3-networkx github-cli + + - name: Clone and checkout + uses: classabbyamp/treeless-checkout-action@v1 + + - name: Create hostrepo and prepare masterdir + run: | + ln -s "$(pwd)" /hostrepo && + common/travis/set_mirror.sh && + common/travis/prepare.sh + - name: Find cycles and open issues + run: | + common/scripts/xbps-cycles.py | tee cycles + grep 'Cycle:' cycles | while read -r line; do + if gh issue list -R "$GITHUB_REPOSITORY" -S "$line" | grep .; then + printf "Issue on '%s' already exists.\n" "$line" + else + gh issue create -R "$GITHUB_REPOSITORY" -b '' -t "$line" + fi + done + env: + GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml new file mode 100644 index 0000000..b5b1f7d --- /dev/null +++ b/.github/workflows/stale.yml @@ -0,0 +1,25 @@ +--- +name: Stale Cleanup + +on: + workflow_dispatch: + schedule: + - cron: '30 1 * * *' + +jobs: + stale: + runs-on: ubuntu-latest + permissions: + issues: write + pull-requests: write + steps: + - uses: actions/stale@v6 + with: + stale-issue-message: 'Issues become stale 90 days after last activity and are closed 14 days after that. If this issue is still relevant bump it or assign it.' + stale-pr-message: 'Pull Requests become stale 90 days after last activity and are closed 14 days after that. If this pull request is still relevant bump it or assign it.' + days-before-stale: 90 + days-before-close: 14 + exempt-all-assignees: true + ascending: true + operations-per-run: 250 + exempt-issue-labels: 'request,bug,tracking' diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e91ff78 --- /dev/null +++ b/.gitignore @@ -0,0 +1,25 @@ +*.swo +*.swp +*~ +\#*# + +# exclude everything in root except files and directories from void-packages +/* +!/.editorconfig +!/.gitattributes +!/.github +!/.gitignore +!/.mailmap +!/CONTRIBUTING.md +!/COPYING +!/Manual.md +!/README.md +!/common +!/etc +!/srcpkgs +!/xbps-src +etc/conf +etc/conf.* +etc/virtual +etc/xbps.d/custom +etc/repo-keys diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..471b0ed --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,230 @@ +# Contributing to void-packages + +void-packages is the backbone of the Void Linux distribution. It contains all the definitions to build packages from source. + +This document describes how you, as a contributor, can help with adding packages, correcting bugs and adding features to void-packages. + +## Package Requirements + +To be included in the Void repository, software must meet at least one of the following requirements. +Exceptions to the list are possible, and might be accepted, but are extremely unlikely. +If you believe you have an exception, start a PR and make an argument for why that particular piece of software, +while not meeting any of the following requirements, is a good candidate for the Void packages system. + +1. **System**: The software should be installed system-wide, not per-user. + +1. **Compiled**: The software needs to be compiled before being used, even if it is software that is not needed by the whole system. + +1. **Required**: Another package either within the repository or pending inclusion requires the package. + +In particular, new themes are highly unlikely to be accepted. +Simple shell scripts are unlikely to be accepted unless they provide considerable value to a broad user base. +New fonts may be accepted if they provide value beyond aesthetics (e.g. they contain glyphs for a script missing in already packaged fonts). +Packages related to cryptocurrencies (wallets, miners, nodes, etc) are not accepted. + +Browser forks, including those based on Chromium and Firefox, are generally not accepted. +Such forks require heavy patching, maintenance and hours of build time. + +Software need to be used in version announced by authors as ready to use by the general public - usually called releases. +Betas, arbitrary VCS revisions, templates using tip of development branch taken at build time and releases created by the package maintainer won't be accepted. + +## Creating, updating, and modifying packages in Void by yourself + +If you really want to get a new package or package update into Void Linux, we recommend you contribute it yourself. + +We provide a [comprehensive Manual](./Manual.md) on how to create new packages. +There's also a [manual for xbps-src](./README.md), which is used to build package files from templates. + +For this guide, we assume you have basic knowledge about [git](http://git-scm.org), as well as a [GitHub Account](http://github.com) with [SSH set up](https://docs.github.com/en/authentication/connecting-to-github-with-ssh). + +You should also [set the email](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address) on your GitHub account and in git so your commits are associated with your GitHub account properly. + +To get started, [fork](https://help.github.com/articles/fork-a-repo) the void-linux `void-packages` git repository on GitHub and clone it: + + $ git clone git@github.com:/void-packages.git + +To keep your forked repository up to date, setup the `upstream` remote to pull in new changes: + + $ git remote add upstream https://github.com/void-linux/void-packages.git + $ git pull --rebase upstream master + +This can also be done with the `github-cli` tool: + + $ gh repo fork void-linux/void-packages + $ gh repo clone /void-packages + +This automatically sets up the `upstream` remote, so `git pull --rebase upstream master` can still be used to keep your fork up-to-date. + +Using the GitHub web editor for making changes is strongly discouraged, because you will need to clone the repo anyways to edit and test your changes. + +Using the `master` branch of your fork for contributing is also strongly discouraged. +It can cause many issues with updating your pull request (also called a PR), and having multiple PRs open at once. +To create a new branch: + + $ git checkout master -b + +### Creating a new template + +You can use the helper tool `xnew`, from the [xtools](https://github.com/leahneukirchen/xtools) package, to create new templates: + + $ xnew pkgname subpkg1 subpkg2 ... + +Templates must have the name `void-packages/srcpkgs//template`, where `pkgname` is the same as the `pkgname` variable in the template. + +For deeper insights on the contents of template files, please read the [manual](./Manual.md), and be sure to browse the existing template files in the `srcpkgs` directory of this repository for concrete examples. + +### Updating a template + +At minimum, a template update will consist of changing `version` and `checksum`, if there was an upstream version change, and/or `revision`, if a template-specific change (e.g. patch, correction, etc.) is needed. +Other changes to the template may be needed depending on what changes the upstream has made. + +The checksum can be updated automatically with the `xgensum` helper from the [xtools](https://github.com/leahneukirchen/xtools) package: + + $ xgensum -i + +### Adopting a template + +If a template is orphaned (maintained by `orphan@voidlinux.org`) or the current `maintainer` has not contributed to +Void in over a year, template maintainership can be adopted by someone else. To ensure a template gets the care it needs, +template adopters should be familiar with the package and have an established history of contributions to Void. +Those who have contributed several updates, especially for the template in question, are good candidates for template +maintainership. + +It is best to adopt a template when making another change to it. When adopting the template, add your name or username +and email to the `maintainer` field in the template, and mention the adoption in your commit message, for example: + + libfoo: update to 1.2.3, adopt. + +### Orphaning a template + +If you no longer wish to maintain a template, you can remove yourself as maintainer by setting the `maintainer` field in +the template to `Orphaned `. The commit message should mention this, for example: + + libfoo: orphan. + +It is not necessary to make other changes to the template when orphaning, and incrementing the revision (triggering a +rebuild) is not necessary either. + +### Committing your changes + +After making your changes, please check that the package builds successfully. From the top level directory of your local copy of the `void-packages` repository, run: + + $ ./xbps-src pkg + +Your package must build successfully for at least x86, but we recommend also trying a cross-build for armv6l* as well, e.g.: + + $ ./xbps-src -a armv6l pkg + +When building for `x86_64*` or `i686`, building with the `-Q` flag or with `XBPS_CHECK_PKGS=yes` set in `etc/conf` (to run the check phase) is strongly encouraged. +Also, new packages and updates will not be accepted unless they have been runtime tested by installing and running the package. + +When you've finished working on the template file, please check it with `xlint` helper from the [xtools](https://github.com/leahneukirchen/xtools) package: + + $ xlint template + +If `xlint` reports any issues, resolve them before committing. + +Once you have made and verified your changes to the package template and/or other files, make one commit per package (including all changes to its sub-packages). Each commit message should have one of the following formats: + +* for new packages, use `New package: -` ([example](https://github.com/void-linux/void-packages/commit/8ed8d41c40bf6a82cf006c7e207e05942c15bff8)). + +* for package updates, use `: update to .` ([example](https://github.com/void-linux/void-packages/commit/c92203f1d6f33026ae89f3e4c1012fb6450bbac1)). + +* for template modifications without a version change, use `: ` ([example](https://github.com/void-linux/void-packages/commit/ff39c912d412717d17232de9564f659b037e95b5)). + +* for package removals, use `: remove package` and include the removal reason in the commit body ([example](https://github.com/void-linux/void-packages/commit/4322f923bdf5d4e0eb36738d4f4717d72d0a0ca4)). + +* for changes to any other file, use `: ` ([example](https://github.com/void-linux/void-packages/commit/e00bea014c36a70d60acfa1758514b0c7cb0627d), + [example](https://github.com/void-linux/void-packages/commit/93bf159ce10d8e474da5296e5bc98350d00c6c82), [example](https://github.com/void-linux/void-packages/commit/dc62938c67b66a7ff295eab541dc37b92fb9fb78), [example](https://github.com/void-linux/void-packages/commit/e52317e939d41090562cf8f8131a68772245bdde)) + +If you want to describe your changes in more detail, explain in the commit body (separated from the first line with a blank line) ([example](https://github.com/void-linux/void-packages/commit/f1c45a502086ba1952f23ace9084a870ce437bc6)). + +`xbump`, available in the [xtools](https://github.com/leahneukirchen/xtools) package, can be used to commit a new or updated package: + + $ xbump + +`xrevbump`, also available in the [xtools](https://github.com/leahneukirchen/xtools) package, can be used to commit a template modification for a package: + + $ xrevbump '' + +`xbump` and `xrevbump` will use `git commit` to commit the changes with the appropriate commit message. For more fine-grained control over the commit, specific options can be passed to `git commit` by adding them after the package name. + +### Starting a pull request + +Once you have successfully built the package, you can [create a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request). Pull requests are also known as PRs. + +Most pull requests should only contain a single package and dependencies which are not part of void-packages yet. + +If you make updates to packages containing a soname bump, you also need to update `common/shlibs` and revbump all packages that are dependant. +There should be a commit for each package revbump, and those commits should be part of the same pull request. + +When you make changes to your pull request, please *do not close and reopen your pull request*. Instead, just [forcibly git push](#review), overwriting any old commits. Closing and opening your pull requests repeatedly spams the Void maintainers. + +#### Continuous Integration + +Pull requests are automatically submitted for Continuous Integration (CI) testing to ensure packages build and pass their tests (on native builds) on various combinations of C library and architecture. +Packages that take longer than 120 minutes or need more than 14G of storage to complete their build (for example, Firefox or the Linux kernel) will fail CI and should include `[ci skip]` in the PR title or body (the comment field when the PR is being opened) to avoid wasting CI builder time. +Use your best judgment on build times based on your local building experience. If you skip CI when submitting a PR, please build and cross-build for a variety of architectures locally, with both glibc and musl, and note your local results in PR comments. +Make sure to cover 64-bit and 32-bit architectures. + +If you notice a failure in CI that didn't happen locally, that is likely because you didn't run tests locally. +Use `./xbps-src -Q pkg ` to do so. +Some tests won't work in the CI environment or at all, and their templates should encode this information using the `make_check` variable. + +Continuous Integration will also check if the templates you have changed +comply with the our guidelines. At the moment not all packages comply with the rules, so if you update a package, it may report errors about places you haven't touched. Please feel free to fix those errors too. + +#### Review + +It's possible (and common) that a pull request will contain mistakes or reviewers will ask for additional tweaks. +Reviewers will comment on your pull request and point out which changes are needed before the pull request can be merged. + +Most PRs will have a single commit, as seen [above](#committing-your-changes), so if you need to make changes to the commit and already have a pull request open, you can use the following commands: + + $ git add + $ git commit --amend + $ git push -f + +A more powerful way of modifying commits than using `git commit --amend` is with [git-rebase](https://git-scm.com/docs/git-rebase#_interactive_mode), which allows you to join, reorder, change description of past commits and more. + +Alternatively, if there are issues with your git history, you can make another branch and push it to the existing PR: + + $ git checkout master -b + $ # do changes anew + $ git push -f : + +#### Closing the pull request + +Once you have applied all requested changes, the reviewers will merge your request. + +If the pull request becomes inactive for some days, the reviewers may or may not warn you when they are about to close it. +If it stays inactive further, it will be closed. + +Please abstain from temporarily closing a pull request while revising the templates. Instead, leave a comment on the PR describing what still needs work, [mark it as a draft](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#converting-a-pull-request-to-a-draft), or add "[WIP]" to the PR title. Only close your pull request if you're sure you don't want your changes to be included. + +#### Publishing the package + +Once the reviewers have merged the pull request, our [build server](http://build.voidlinux.org) is automatically triggered and builds +all packages in the pull request for all supported platforms. Upon completion, the packages are available to all Void Linux users. + +## Testing Pull Requests + +While it is the responsibility of the PR creator to test changes before sending it, one person can't test all configuration options, usecases, hardware, etc. +Testing new package submissions and updates is always helpful, and is a great way to get started with contributing. +First, [clone the repository](https://github.com/void-linux/void-packages#quick-start) if you haven't done so already. +Then check out the pull request, either with `github-cli`: + + $ gh pr checkout + +Or with `git`: + +If your local void-packages repository is cloned from your fork, you may need to add the main repository as a remote first: + + $ git remote add upstream https://github.com/void-linux/void-packages.git + +Then fetch and check out the PR (replacing `` with either `origin` or `upstream`): + + $ git fetch pull//head: + $ git checkout + +Then [build and install](https://github.com/void-linux/void-packages#building-packages) the package and test its functionality. diff --git a/COPYING b/COPYING new file mode 100644 index 0000000..9f53c19 --- /dev/null +++ b/COPYING @@ -0,0 +1,23 @@ + Copyright (c) 2008-2020 Juan Romero Pardines and contributors + Copyright (c) 2017-2024 The Void Linux team and contributors + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + + THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. + IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, + INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF + THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/Manual.md b/Manual.md new file mode 100644 index 0000000..34c737e --- /dev/null +++ b/Manual.md @@ -0,0 +1,2205 @@ +# The XBPS source packages manual + +This article contains an exhaustive manual of how to create new source +packages for XBPS, the `Void Linux` native packaging system. + +*Table of Contents* + +* The XBPS source packages manual + * [Introduction](#Introduction) + * [Package build phases](#buildphase) + * [Package naming conventions](#namingconventions) + * [Libraries](#libs) + * [Language Modules](#language_modules) + * [Language Bindings](#language_bindings) + * [Programs](#programs) + * [Global functions](#global_funcs) + * [Global variables](#global_vars) + * [Available variables](#available_vars) + * [Mandatory variables](#mandatory_vars) + * [Optional variables](#optional_vars) + * [About the depends variables](#explain_depends) + * [Repositories](#repositories) + * [Repositories defined by Branch](#repo_by_branch) + * [Package defined repositories](#pkg_defined_repo) + * [Checking for new upstream releases](#updates) + * [Handling patches](#patches) + * [Build style scripts](#build_scripts) + * [Build helper scripts](#build_helper) + * [Functions](#functions) + * [Build options](#build_options) + * [INSTALL and REMOVE files](#install_remove_files) + * [INSTALL.msg and REMOVE.msg files](#install_remove_files_msg) + * [Creating system accounts/groups at runtime](#runtime_account_creation) + * [Writing runit services](#writing_runit_services) + * [32bit packages](#32bit_pkgs) + * [Subpackages](#pkgs_sub) + * [Some package classes](#pkgs_classes) + * [Development packages](#pkgs_development) + * [Data packages](#pkgs_data) + * [Documentation packages](#pkgs_documentation) + * [Python packages](#pkgs_python) + * [Go packages](#pkgs_go) + * [Haskell packages](#pkgs_haskell) + * [Font packages](#pkgs_font) + * [Renaming a package](#pkg_rename) + * [Removing a package](#pkg_remove) + * [XBPS Triggers](#xbps_triggers) + * [appstream-cache](#triggers_appstream_cache) + * [binfmts](#triggers_binfmts) + * [dkms](#triggers_dkms) + * [gconf-schemas](#triggers_gconf_schemas) + * [gdk-pixbuf-loaders](#triggers_gdk_pixbuf_loaders) + * [gio-modules](#triggers_gio_modules) + * [gettings-schemas](#triggers_gsettings_schemas) + * [gtk-icon-cache](#triggers_gtk_icon_cache) + * [gtk-immodules](#triggers_gtk_immodules) + * [gtk-pixbuf-loaders](#triggers_gtk_pixbuf_loaders) + * [gtk3-immodules](#triggers_gtk3_immodules) + * [hwdb.d-dir](#triggers_hwdb.d_dir) + * [info-files](#triggers_info_files) + * [initramfs-regenerate](#triggers_initramfs_regenerate) + * [kernel-hooks](#triggers_kernel_hooks) + * [mimedb](#triggers_mimedb) + * [mkdirs](#triggers_mkdirs) + * [pango-modules](#triggers_pango_module) + * [pycompile](#triggers_pycompile) + * [register-shell](#triggers_register_shell) + * [system-accounts](#triggers_system_accounts) + * [texmf-dist](#triggers_texmf_dist) + * [update-desktopdb](#triggers_update_desktopdb) + * [x11-fonts](#triggers_x11_fonts) + * [xml-catalog](#triggers_xml_catalog) + * [Void specific documentation](#documentation) + * [Notes](#notes) + * [Contributing via git](#contributing) + * [Help](#help) + + +### Introduction + +The `void-packages` repository contains all the +recipes to download, compile and build binary packages for Void Linux. +These `source` package files are called `templates`. + +The `template` files are shell scripts that define `variables` and `functions` +to be processed by `xbps-src`, the package builder, to generate binary packages. +The shell used by `xbps-src` is GNU bash; `xbps-src` doesn't aim to be +compatible with POSIX `sh`. + +By convention, all templates start with a comment saying that it is a +`template file` for a certain package. Most of the lines should be kept under 80 +columns; variables that list many values can be split into new lines, with the +continuation in the next line indented by one space. + +A simple `template` example is as follows: + +``` +# Template file for 'foo' +pkgname=foo +version=1.0 +revision=1 +build_style=gnu-configure +short_desc="A short description max 72 chars" +maintainer="name " +license="GPL-3.0-or-later" +homepage="http://www.foo.org" +distfiles="http://www.foo.org/foo-${version}.tar.gz" +checksum="fea0a94d4b605894f3e2d5572e3f96e4413bcad3a085aae7367c2cf07908b2ff" +``` + +The template file contains definitions to download, build and install the +package files to a `fake destdir`, and after this a binary package can be +generated with the definitions specified on it. + +Don't worry if anything is not clear as it should be. The reserved `variables` +and `functions` will be explained later. This `template` file should be created +in a directory matching `$pkgname`, Example: `void-packages/srcpkgs/foo/template`. + +If everything went fine after running + + $ ./xbps-src pkg + +a binary package named `foo-1.0_1..xbps` will be generated in the local repository +`hostdir/binpkgs`. + + +### Package build phases + +Building a package consist of the following phases: + +- `setup` This phase prepares the environment for building a package. + +- `fetch` This phase downloads required sources for a `source package`, as defined by +the `distfiles` variable or `do_fetch()` function. + +- `extract` This phase extracts the `distfiles` files into `$wrksrc` or executes the `do_extract()` +function, which is the directory to be used to compile the `source package`. + +- `patch` This phase applies all patches in the patches directory of the package and +can be used to perform other operations before configuring the package. + +- `configure` This phase executes the `configuration` of a `source package`, i.e `GNU configure scripts`. + +- `build` This phase compiles/prepares the `source files` via `make` or any other compatible method. + +- `check` This optional phase checks the result of the `build` phase by running the testsuite provided by the package. +If the default `do_check` function provided by the build style doesn't do anything, the template should set +`make_check_target` and/or `make_check_args` appropriately or define its own `do_check` function. If tests take too long +or can't run in all environments, `make_check` should be set to fitting value or +`do_check` should be customized to limit testsuite unless `XBPS_CHECK_PKGS` is `full`. + +- `install` This phase installs the `package files` into the package destdir `/destdir/-`, +via `make install` or any other compatible method. + +- `pkg` This phase builds the `binary packages` with files stored in the +`package destdir` and registers them into the local repository. + +- `clean` This phase cleans up the package (if defined). + +`xbps-src` supports running just the specified phase, and if it ran +successfully, the phase will be skipped later (unless its work directory +`${wrksrc}` is removed with `xbps-src clean`). + + +### Package naming conventions + + +#### Libraries + +Libraries are packages which provide shared objects (\*.so) in /usr/lib. +They should be named like their upstream package name with the following +exceptions: + +- The package is a subpackage of a front end application and provides +shared objects used by the base package and other third party libraries. In that +case it should be prefixed with 'lib'. An exception from that rule is: If an +executable is only used for building that package, it moves to the -devel +package. + +Example: wireshark -> subpkg libwireshark + +Libraries have to be split into two sub packages: `` and `-devel`. + +- `` should only contain those parts of a package which are needed to run +a linked program. + +- `-devel` should contain all files which are needed to compile a package +against this package. If the library is a sub package, its corresponding +development package should be named `lib-devel` + + +#### Language Modules + +Language modules are extensions to script or compiled languages. Those packages +do not provide any executables themselves, but can be used by other packages +written in the same language. + +The naming convention to those packages is: + +``` +- +``` + +If a package provides both, a module and a executable, it should be split into +a package providing the executable named `` and the module named +`-`. If a package starts with the languages name itself, the +language prefix can be dropped. Short names for languages are no valid substitute +for the language prefix. + +Example: python-pam, perl-URI, python3-pyside2 + + +#### Language Bindings + +Language Bindings are packages which allow programs or libraries to have +extensions or plugins written in a certain language. + +The naming convention to those packages is: +``` +- +``` + +Example: gimp-python, irssi-perl + + +#### Programs + +Programs put executables under /usr/bin (or in very special cases in other +.../bin directories) + +For those packages the upstream packages name should be used. Remember that +in contrast to many other distributions, void doesn't lowercase package names. +As a rule of thumb, if the tar.gz of a package contains uppercase letter, then +the package name should contain them too; if it doesn't, the package name +is lowercase. + +Programs can be split into program packages and library packages. The program +package should be named as described above. The library package should be +prefixed with "lib" (see section `Libraries`) + + +### Global functions + +The following functions are defined by `xbps-src` and can be used on any template: + +- *vinstall()* `vinstall []` + + Installs `file` with the specified `mode` into `targetdir` in the pkg `$DESTDIR`. + The optional 4th argument can be used to change the `file name`. + +- *vcopy()* `vcopy ` + + Copies recursively all files in `pattern` to `targetdir` in the pkg `$DESTDIR`. + +- *vmove()* `vmove ` + + Moves `pattern` to the specified directory in the pkg `$DESTDIR`. + +- *vmkdir()* `vmkdir []` + + Creates a directory in the pkg `$DESTDIR`. The 2nd optional argument sets the mode of the directory. + +- *vbin()* `vbin []` + + Installs `file` into `usr/bin` in the pkg `$DESTDIR` with the + permissions 0755. The optional 2nd argument can be used to change + the `file name`. + +- *vman()* `vman []` + + Installs `file` as a man page. `vman()` parses the name and + determines the section as well as localization. Also transparently + converts gzipped (.gz) and bzipped (.bz2) manpages into plaintext. + Example mappings: + + - `foo.1` -> `${DESTDIR}/usr/share/man/man1/foo.1` + - `foo.fr.1` -> `${DESTDIR}/usr/share/man/fr/man1/foo.1` + - `foo.1p` -> `${DESTDIR}/usr/share/man/man1/foo.1p` + - `foo.1.gz` -> `${DESTDIR}/usr/share/man/man1/foo.1` + - `foo.1.bz2` -> `${DESTDIR}/usr/share/man/man1/foo.1` + +- *vdoc()* `vdoc []` + + Installs `file` into `usr/share/doc/` in the pkg + `$DESTDIR`. The optional 2nd argument can be used to change the + `file name`. + +- *vconf()* `vconf []` + + Installs `file` into `etc` in the pkg + `$DESTDIR`. The optional 2nd argument can be used to change the + `file name`. + +- *vsconf()* `vsconf []` + + Installs `file` into `usr/share/examples/` in the pkg + `$DESTDIR`. The optional 2nd argument can be used to change the + `file name`. + +- + *vlicense()* `vlicense []` + + Installs `file` into `usr/share/licenses/` in the pkg + `$DESTDIR`. The optional 2nd argument can be used to change the + `file name`. See [license](#var_license) for when to use it. + +- *vsv()* `vsv []` + + Installs `service` from `${FILESDIR}` to /etc/sv. The service must + be a directory containing at least a run script. Note the `supervise` + symlink will be created automatically by `vsv` and that the run script + is automatically made executable by this function. + For further information on how to create a new service directory see + [The corresponding section the FAQ](http://smarden.org/runit/faq.html#create). + A `log` sub-service will be automatically created if one does not exist in + `${FILESDIR}/$service`, containing `exec vlogger -t $service -p $facility`. + if a second argument is not specified, the `daemon` facility is used. + For more information about `vlogger` and available values for the facility, + see [vlogger(8)](https://man.voidlinux.org/vlogger.8). + +- *vsed()* `vsed -i -e ` + + Wrapper around sed that checks sha256sum of a file before and after running + the sed command to detect cases in which the sed call didn't change anything. + Takes any arbitrary amount of files and regexes by calling `-i file` and + `-e regex` repeatedly, at least one file and one regex must be specified. + + Note that vsed will call the sed command for every regex specified against + every file specified, in the order that they are given. + +- *vcompletion()* ` []` + + Installs shell completion from `file` for `command`, in the correct location + and with the appropriate filename for `shell`. If `command` isn't specified, + it will default to `pkgname`. The `shell` argument can be one of `bash`, + `fish` or `zsh`. + +- *vextract()* `[-C ] [--no-strip-components|--strip-components=] ` + + Extracts `file` to `target directory` with `n` directory components stripped. If + `target directory` not specified, defaults to the working directory. If + `--strip-components` or `--no-strip-components` is not specified, defaults to + `--strip-components=1`. + +- *vsrcextract()* `[-C ] [--no-strip-components|--strip-components=] ` + + Extracts `$XBPS_SRCDISTDIR/$pkgname-$version/` to `target directory` + with `n` directory components stripped. If `target directory` not specified, + defaults to the working directory. If `--strip-components` or `--no-strip-components` + is not specified, defaults to `--strip-components=1`. + + This is useful when used in conjunction with `skip_extraction` and for submodule distfiles. + +- *vsrccopy()* `... ` + + Copies `file`s from `$XBPS_SRCDISTDIR/$pkgname-$version/` into the `target` directory, + creating `target` if it does not exist. + + This is useful when used in conjunction with `skip_extraction`. + +> Shell wildcards must be properly quoted, Example: `vmove "usr/lib/*.a"`. + + +### Global variables + +The following variables are defined by `xbps-src` and can be used on any template: + +- `makejobs` Set to `-jX` if `XBPS_MAKEJOBS` is defined, to allow parallel jobs with `GNU make`. + +- `sourcepkg` Set to the to main package name, can be used to match the main package +rather than additional binary package names. + +- `CHROOT_READY` Set if the target chroot (masterdir) is ready for chroot builds. + +- `CROSS_BUILD` Set if `xbps-src` is cross compiling a package. + +- `XBPS_CHECK_PKGS` Set if `xbps-src` is going to run tests for a package. +Longer testsuites should only be run in `do_check()` if it is set to `full`. + +- `DESTDIR` Full path to the fake destdir used by the source pkg, set to +`/destdir/${sourcepkg}-${version}`. + +- `FILESDIR` Full path to the `files` package directory, i.e `srcpkgs/foo/files`. +The `files` directory can be used to store additional files to be installed +as part of the source package. + +- `PKGDESTDIR` Full path to the fake destdir used by the `pkg_install()` function in +`subpackages`, set to `/destdir/${pkgname}-${version}`. + +- `XBPS_BUILDDIR` Directory to store the `source code` of the source package being processed, +set to `/builddir`. The package `wrksrc` is always stored +in this directory such as `${XBPS_BUILDDIR}/${wrksrc}`. + +- `XBPS_MACHINE` The machine architecture as returned by `xbps-uhelper arch`. + +- `XBPS_ENDIAN` The machine's endianness ("le" or "be"). + +- `XBPS_LIBC` The machine's C library ("glibc" or "musl"). + +- `XBPS_WORDSIZE` The machine's word size in bits (32 or 64). + +- `XBPS_NO_ATOMIC8` The machine lacks native 64-bit atomics (needs libatomic emulation). + +- `XBPS_SRCDISTDIR` Full path to where the `source distfiles` are stored, i.e `$XBPS_HOSTDIR/sources`. + +- `XBPS_SRCPKGDIR` Full path to the `srcpkgs` directory. + +- `XBPS_TARGET_MACHINE` The target machine architecture when cross compiling a package. + +- `XBPS_TARGET_ENDIAN` The target machine's endianness ("le" or "be"). + +- `XBPS_TARGET_LIBC` The target machine's C library ("glibc" or "musl"). + +- `XBPS_TARGET_WORDSIZE` The target machine's word size in bits (32 or 64). + +- `XBPS_TARGET_NO_ATOMIC8` The target machine lacks native 64-bit atomics (needs libatomic emulation). + +- `XBPS_FETCH_CMD` The utility to fetch files from `ftp`, `http` of `https` servers. + +- `XBPS_WRAPPERDIR` Full path to where xbps-src's wrappers for utilities are stored. + +- `XBPS_CROSS_BASE` Full path to where cross-compile dependencies are installed, varies according to the target architecture triplet. i.e `aarch64` -> `/usr/aarch64-linux-gnu`. + +- `XBPS_RUST_TARGET` The target architecture triplet used by `rustc` and `cargo`. + +- `XBPS_BUILD_ENVIRONMENT` Enables continuous-integration-specific operations. Set to `void-packages-ci` if in continuous integration. + + +### Available variables + + +#### Mandatory variables + +The list of mandatory variables for a template: + +- `homepage` An URL pointing to the upstream homepage. + + +- +`license` A string matching the license's [SPDX Short identifier](https://spdx.org/licenses), +`Public Domain`, or string prefixed with `custom:` for other licenses. +Multiple licenses should be separated by commas, Example: `GPL-3.0-or-later, custom:Hugware`. + + Empty meta-packages that don't include any files + and thus have and require no license should use + `Public Domain`. + + Note: `AGPL`, `MIT`, `BSD`, `ISC`, `X11`, and custom licenses + require the license file to be supplied with the binary package. + +- `maintainer` A string in the form of `name `. The email for this field +must be a valid email that you can be reached at. Packages using +`users.noreply.github.com` emails will not be accepted. + +- `pkgname` A string with the package name, matching `srcpkgs/`. + +- `revision` A number that must be set to 1 when the `source package` is created, or +updated to a new `upstream version`. This should only be increased when +the generated `binary packages` have been modified. + +- `short_desc` A string with a brief description for this package. Max 72 chars. + +- `version` A string with the package version. Must not contain dashes or underscore +and at least one digit is required. Shell's variable substitution usage is not allowed. + +`pkgname` and `version` are forbidden to contain special characters. Hence, they don't +need to be quoted, and by convention, they shouldn't be. + + +#### Optional variables + +- `hostmakedepends` The list of `host` dependencies required to build the package, and +that will be installed to the master directory. There is no need to specify a version +because the current version in srcpkgs will always be required. +Example: `hostmakedepends="foo blah"`. + +- `makedepends` The list of `target` dependencies required to build the package, and that +will be installed to the master directory. There is no need to specify a version +because the current version in srcpkgs will always be required. +Example: `makedepends="foo blah"`. + +- `checkdepends` The list of dependencies required to run the package checks, i.e. +the script or make rule specified in the template's `do_check()` function. +Example: `checkdepends="gtest"`. + +- `depends` The list of dependencies required to run the package. These dependencies +are not installed to the master directory, rather are only checked if a binary package +in the local repository exists to satisfy the required version. Dependencies +can be specified with the following version comparators: `<`, `>`, `<=`, `>=` +or `foo-1.0_1` to match an exact version. If version comparator is not +defined (just a package name), the version comparator is automatically set to `>=0`. +Example: `depends="foo blah>=1.0"`. See the [Runtime dependencies](#deps_runtime) section +for more information. + +- `bootstrap` If enabled the source package is considered to be part of the `bootstrap` +process and required to be able to build packages in the chroot. Only a +small number of packages must set this property. + +- `conflicts` An optional list of packages conflicting with this package. +Conflicts can be specified with the following version comparators: `<`, `>`, `<=`, `>=` +or `foo-1.0_1` to match an exact version. If version comparator is not +defined (just a package name), the version comparator is automatically set to `>=0`. +Example: `conflicts="foo blah>=0.42.3"`. + +- `distfiles` The full URL to the `upstream` source distribution files. Multiple files +can be separated by whitespaces. The files must end in `.tar.lzma`, `.tar.xz`, +`.txz`, `.tar.bz2`, `.tbz`, `.tar.gz`, `.tgz`, `.gz`, `.bz2`, `.tar` or +`.zip`. To define a target filename, append `>filename` to the URL. +Example: + distfiles="http://foo.org/foo-1.0.tar.gz http://foo.org/bar-1.0.tar.gz>bar.tar.gz" + + To avoid repetition, several variables for common hosting sites + exist: + + | Variable | Value | + |------------------|-------------------------------------------------| + | CPAN_SITE | https://cpan.perl.org/modules/by-module | + | DEBIAN_SITE | http://ftp.debian.org/debian/pool | + | FREEDESKTOP_SITE | https://freedesktop.org/software | + | GNOME_SITE | https://ftp.gnome.org/pub/GNOME/sources | + | GNU_SITE | https://ftp.gnu.org/gnu | + | KERNEL_SITE | https://www.kernel.org/pub/linux | + | MOZILLA_SITE | https://ftp.mozilla.org/pub | + | NONGNU_SITE | https://download.savannah.nongnu.org/releases | + | PYPI_SITE | https://files.pythonhosted.org/packages/source | + | SOURCEFORGE_SITE | https://downloads.sourceforge.net/sourceforge | + | UBUNTU_SITE | http://archive.ubuntu.com/ubuntu/pool | + | XORG_SITE | https://www.x.org/releases/individual | + | KDE_SITE | https://download.kde.org/stable | + | VIDEOLAN_SITE | https://download.videolan.org/pub/videolan | + +- `checksum` The `sha256` digests matching `${distfiles}`. Multiple files can be +separated by blanks. Please note that the order must be the same than +was used in `${distfiles}`. Example: `checksum="kkas00xjkjas"` + +If a distfile changes its checksum for every download because it is packaged +on the fly on the server, like e.g. snapshot tarballs from any of the +`https://*.googlesource.com/` sites, the checksum of the `archive contents` +can be specified by prepending a commercial at (@). +For tarballs you can find the contents checksum by using the command +`tar xf --to-stdout | sha256sum`. + +- `wrksrc` The directory name where the package sources are extracted, set to `${pkgname}-${version}`. + +- `build_wrksrc` A directory relative to `${wrksrc}` that will be used when building the package. + +- `create_wrksrc` Usually, after extracting, if there're multiple top-level + files and/or directories or when there're no directories at all, top-level files, + and directories will be wrapped inside one more layer of directory. + Set `create_wrksrc` to force this behaviour. + +- `build_style` This specifies the `build method` for a package. Read below to know more +about the available package `build methods` or effect of leaving this not set. + +- `build_helper` Whitespace-separated list of files in `common/build-helper` to be +sourced and its variables be made available on the template. i.e. `build_helper="rust"`. + +- `configure_script` The name of the `configure` script to execute at the `configure` phase if +`${build_style}` is set to `configure` or `gnu-configure` build methods. +By default set to `./configure`. + +- `configure_args` The arguments to be passed in to the `configure` script if `${build_style}` +is set to `configure` or `gnu-configure` build methods. By default, prefix +must be set to `/usr`. In `gnu-configure` packages, some options are already +set by default: `--prefix=/usr --sysconfdir=/etc --infodir=/usr/share/info --mandir=/usr/share/man --localstatedir=/var`. + +- `make_cmd` The executable to run at the `build` phase if `${build_style}` is set to +`configure`, `gnu-configure` or `gnu-makefile` build methods. +By default set to `make`. + +- `make_build_args` The arguments to be passed in to `${make_cmd}` at the build phase if +`${build_style}` is set to `configure`, `gnu-configure` or `gnu-makefile` +build methods. Unset by default. + +- `make_check_args` The arguments to be passed in to `${make_cmd}` at the check phase if +`${build_style}` is set to `configure`, `gnu-configure` or `gnu-makefile` +build methods. Unset by default. + +- `make_install_args` The arguments to be passed in to `${make_cmd}` at the `install` +phase if `${build_style}` is set to `configure`, `gnu-configure` or `gnu-makefile` build methods. + +- `make_build_target` The build target. If `${build_style}` is set to `configure`, `gnu-configure` +or `gnu-makefile`, this is the target passed to `${make_cmd}` in the build phase; +when unset the default target is used. +If `${build_style}` is `python3-pep517`, this is the path of the package +directory that should be built as a Python wheel; when unset, defaults to `.` (the current +directory with respect to the build). + +- `make_check_target` The target to be passed in to `${make_cmd}` at the check phase if +`${build_style}` is set to `configure`, `gnu-configure` or `gnu-makefile` +build methods. By default set to `check`. + +- `make_install_target` The installation target. When `${build_style}` is set to `configure`, +`gnu-configure` or `gnu-makefile`, this is the target passed to `${make_command}` in the install +phase; when unset, it defaults to `install`. If `${build_style}` is `python-pep517`, this is the +path of the Python wheel produced by the build phase that will be installed; when unset, the +`python-pep517` build style will look for a wheel matching the package name and version in the +current directory with respect to the install. + +- `make_check_pre` The expression in front of `${make_cmd}`. This can be used for wrapper commands +or for setting environment variables for the check command. By default empty. + +- `patch_args` The arguments to be passed in to the `patch(1)` command when applying +patches to the package sources during `do_patch()`. Patches are stored in +`srcpkgs//patches` and must be in `-p1` format. By default set to `-Np1`. + +- `disable_parallel_build` If set the package won't be built in parallel +and `XBPS_MAKEJOBS` will be set to 1. If a package does not work well with `XBPS_MAKEJOBS` +but still has a mechanism to build in parallel, set `disable_parallel_build` and +use `XBPS_ORIG_MAKEJOBS` (which holds the original value of `XBPS_MAKEJOBS`) in the template. + +- `disable_parallel_check` If set tests for the package won't be built and run in parallel +and `XBPS_MAKEJOBS` will be set to 1. If a package does not work well with `XBPS_MAKEJOBS` +but still has a mechanism to run checks in parallel, set `disable_parallel_check` and +use `XBPS_ORIG_MAKEJOBS` (which holds the original value of `XBPS_MAKEJOBS`) in the template. + +- `make_check` Sets the cases in which the `check` phase is run. +This option has to be accompanied by a comment explaining why the tests fail. +Allowed values: + - `yes` (the default) to run if `XBPS_CHECK_PKGS` is set. + - `extended` to run if `XBPS_CHECK_PKGS` is `full`. + - `ci-skip` to run locally if `XBPS_CHECK_PKGS` is set, but not as part of pull request checks. + - `no` to never run. + + +- `keep_libtool_archives` If enabled the `GNU Libtool` archives won't be removed. By default those +files are always removed automatically. + +- `skip_extraction` A list of filenames that should not be extracted in the `extract` phase. +This must match the basename of any url defined in `${distfiles}`. +Example: `skip_extraction="foo-${version}.tar.gz"`. + +- `nodebug` If enabled -dbg packages won't be generated even if `XBPS_DEBUG_PKGS` is set. + +- `conf_files` A list of configuration files the binary package owns; this expects full +paths, wildcards will be extended, and multiple entries can be separated by blanks. +Example: `conf_files="/etc/foo.conf /etc/foo2.conf /etc/foo/*.conf"`. + +- `mutable_files` A list of files the binary package owns, with the expectation + that those files will be changed. These act a lot like `conf_files` but + without the assumption that a human will edit them. + +- `make_dirs` A list of entries defining directories and permissions to be + created at install time. Each entry should be space separated, and will + itself contain spaces. `make_dirs="/dir 0750 user group"`. User and group and + mode are required on every line, even if they are `755 root root`. By + convention, there is only one entry of `dir perms user group` per line. + +- `repository` Defines the repository in which the package will be placed. See + *Repositories* for a list of valid repositories. + +- `nostrip` If set, the ELF binaries with debugging symbols won't be stripped. By +default all binaries are stripped. + +- `nostrip_files` White-space separated list of ELF binaries that won't be stripped of +debugging symbols. Files can be given by full path or by filename. + +- `noshlibprovides` If set, the ELF binaries won't be inspected to collect the provided +sonames in shared libraries. + +- `noverifyrdeps` If set, the ELF binaries and shared libraries won't be inspected to collect +their reverse dependencies. You need to specify all dependencies in the `depends` when you +need to set this. + +- `skiprdeps` White space separated list of filenames specified by their absolute path in +the `$DESTDIR` which will not be scanned for runtime dependencies. This may be useful to +skip files which are not meant to be run or loaded on the host but are to be sent to some +target device or emulation. + +- `ignore_elf_files` White space separated list of machine code files +in /usr/share directory specified by absolute path, which are expected and allowed. + +- `ignore_elf_dirs` White space separated list of directories in /usr/share directory +specified by absolute path, which are expected and allowed to contain machine code files. + +- `nocross` If set, cross compilation won't be allowed and will exit immediately. +This should be set to a string describing why it fails, or a link to a buildlog (from the official builders, CI buildlogs can vanish) demonstrating the failure. + +- `restricted` If set, xbps-src will refuse to build the package unless +`etc/conf` has `XBPS_ALLOW_RESTRICTED=yes`. The primary builders for Void +Linux do not have this setting, so the primary repositories will not have any +restricted package. This is useful for packages where the license forbids +redistribution. + +- `subpackages` A white space separated list of subpackages (matching `foo_package()`) +to override the guessed list. Only use this if a specific order of subpackages is required, +otherwise the default would work in most cases. + +- `broken` If set, building the package won't be allowed because its state is currently broken. +This should be set to a string describing why it is broken, or a link to a buildlog demonstrating the failure. + +- `shlib_provides` A white space separated list of additional sonames the package provides on. +This appends to the generated file rather than replacing it. + +- `shlib_requires` A white space separated list of additional sonames the package requires. +This appends to the generated file rather than replacing it. + +- `nopie` Only needs to be set to something to make active, disables building the package with hardening + features (PIE, relro, etc). Not necessary for most packages. + +- `nopie_files` White-space separated list of ELF binaries that won't be checked +for PIE. Files must be given by full path. + +- `reverts` xbps supports a unique feature which allows to downgrade from broken +packages automatically. In the `reverts` field one can define a list of broken +pkgver the resulting package should revert. This field *must* be defined before +`version` and `revision` fields in order to work as expected. The versions +defined in `reverts` must be bigger than the one defined in `version`. +Example: + + ``` + reverts="2.0_1 2.0_2" + version=1.9 + revision=2 + ``` + +- `alternatives` A white space separated list of supported alternatives the package provides. +A list is composed of three components separated by a colon: group, symlink and target. +Example: `alternatives="vi:/usr/bin/vi:/usr/bin/nvi ex:/usr/bin/ex:/usr/bin/nvi-ex"`. + +- `font_dirs` A white space separated list of directories specified by an absolute path where a +font package installs its fonts. +It is used in the `x11-fonts` xbps-trigger to rebuild the font cache during install/removal +of the package. +Example: `font_dirs="/usr/share/fonts/TTF /usr/share/fonts/X11/misc"` + +- `dkms_modules` A white space separated list of Dynamic Kernel Module Support (dkms) modules +that will be installed and removed by the `dkms` xbps-trigger with the install/removal of the +package. +The format is a white space separated pair of strings that represent the name of the module, +most of the time `pkgname`, and the version of the module, most of the time `version`. +Example: `dkms_modules="$pkgname $version zfs 4.14"` + +- `register_shell` A white space separated list of shells defined by absolute path to be +registered into the system shells database. It is used by the `register-shell` trigger. +Example: `register_shell="/bin/tcsh /bin/csh"` + +- `tags` A white space separated list of tags (categories) that are registered into the +package metadata and can be queried with `xbps-query` by users. +Example for qutebrowser: `tags="browser chromium-based qt5 python3"` + +- `perl_configure_dirs` A white space separate list of directories relative to `wrksrc` +that contain Makefile.PL files that need to be processes for the package to work. It is +used in the perl-module build_style and has no use outside of it. +Example: `perl_configure_dirs="blob/bob foo/blah"` + +- `preserve` If set, files owned by the package in the system are not removed when +the package is updated, reinstalled or removed. This is mostly useful for kernel packages +that shouldn't remove the kernel files when they are removed in case it might break the +user's booting and module loading. Otherwise in the majority of cases it should not be +used. + +- `fetch_cmd` Executable to be used to fetch URLs in `distfiles` during the `do_fetch` phase. + +- `changelog` An URL pointing to the upstream changelog. Raw text files are preferred. + +- `archs` Whitespace separated list of architectures that a package can be +built for, available architectures can be found under `common/cross-profiles`. +In general, `archs` should only be set if the upstream software explicitly targets +certain architectures or there is a compelling reason why the software should not be +available on some supported architectures. +Prepending pattern with tilde means disallowing build on indicated archs. +First matching pattern is taken to allow/deny build. When no pattern matches, +package is build if last pattern includes tilde. +Examples: + + ``` + # Build package only for musl architectures + archs="*-musl" + # Build package for x86_64-musl and any non-musl architecture + archs="x86_64-musl ~*-musl" + # Default value (all arches) + archs="*" + ``` +A special value `noarch` used to be available, but has since been removed. + +- `nocheckperms` If set, xbps-src will not fail on common permission errors (world writable files, etc.) + +- `nofixperms` If set, xbps-src will not fix common permission errors (executable manpages, etc.) + + +#### About the many types of `depends` variables + +So far, we have listed four types of `depends` variables: `hostmakedepends`, +`makedepends`, `checkdepends` and `depends`. These different kinds of variables +are necessary because `xbps-src` supports cross compilation and to avoid +installing unnecessary packages in the build environment. + +During a build process, there are programs that must be _run_ on the host, such +as `yacc` or the C compiler. The packages that contain these programs should be +listed in `hostmakedepends`, and will be installed on the host when building the +target package. Some of these packages are dependencies of the `base-chroot` +package and don't need to be listed. It is possible that some of the programs +necessary to build a project are located in `-devel` packages. + +The target package can also depend on other packages for libraries to link +against or header files. These packages should be listed in `makedepends` and +will match the target architecture, regardless of the architecture of the build +machine. Typically, `makedepends` will contain mainly `-devel` packages. + +Furthermore, if `XBPS_CHECK_PKGS` is set or the `-Q` option is passed to +`xbps-src`, the target package might require specific dependencies or libraries +that are linked into its test binaries to run its test suite. These dependencies +should be listed in `checkdepends` and will be installed as if they were part of +`hostmakedepends`. Some dependencies that can be included in `checkdepends` are: + +- `dejagnu`: used for some GNU projects +- `cmocka-devel`: linked into test binaries +- `dbus`: makes it possible to run `dbus-run-session ` to provide + a D-Bus session for applications that need it +- `git`: some test suites run the `git` command + + +Lastly, a package may require certain dependencies at runtime, without which it +is unusable. These dependencies, when they aren't detected automatically by +XBPS, should be listed in `depends`. + +Libraries linked by ELF objects are detected automatically by `xbps-src`, hence they +must not be specified in templates via `depends`. This variable should list: + +- executables called as separate processes. +- ELF objects using dlopen(3). +- non-object code, e.g. C headers, perl/python/ruby/etc modules. +- data files. +- overriding the minimal version specified in the `common/shlibs` file. + +The runtime dependencies for ELF objects are detected by checking which SONAMEs +they require and then the SONAMEs are mapped to a binary package name with a minimal +required version. The `common/shlibs` file +sets up the ` >=` mappings. + +For example the `foo-1.0_1` package provides the `libfoo.so.1` SONAME and +software requiring this library will link to `libfoo.so.1`; the resulting binary +package will have a run-time dependency on `foo>=1.0_1` package as specified in +`common/shlibs`: + +``` +# common/shlibs +... +libfoo.so.1 foo-1.0_1 +... +``` + +- The first field specifies the SONAME. +- The second field specified the package name and minimal version required. +- A third optional field (usually set to `ignore`) can be used to skip checks in soname bumps. + +Dependencies declared via `depends` are not installed to the master directory, rather they are +only checked if they exist as binary packages, and are built automatically by `xbps-src` if +the specified version is not in the local repository. + +As a special case, `virtual` dependencies may be specified as runtime dependencies in the +`depends` template variable. Several different packages can provide common functionality by +declaring a virtual name and version in the `provides` template variable (e.g. +`provides="vpkg-0.1_1"`). Packages that rely on the common functionality without concern for the +specific provider can declare a dependency on the virtual package name with the prefix `virtual?` +(e.g., `depends="virtual?vpkg-0.1_1"`). When a package is built by `xbps-src`, providers for any +virtual packages will be confirmed to exist and will be built if necessary. A map from virtual +packages to their default providers is defined in `etc/defaults.virtual`. Individual mappings can be +overridden by local preferences in `etc/virtual`. Comments in `etc/defaults.virtual` provide more +information on this map. + +Finally, as a general rule, if a package is built the exact same way whether or +not a particular package is present in `makedepends` or `hostmakedepends`, that +package shouldn't be added as a build time dependency. + + +### Repositories + + +#### Repositories defined by Branch + +The global repository takes the name of +the current branch, except if the name of the branch is master. Then the resulting +repository will be at the global scope. The usage scenario is that the user can +update multiple packages in a second branch without polluting his local repository. + + +#### Package defined Repositories + +The second way to define a repository is by setting the `repository` variable in +a template. This way the maintainer can define repositories for a specific +package or a group of packages. This is currently used to distinguish between +certain classes of packages. + +The following repository names are valid: + +* `bootstrap`: Repository for xbps-src-specific packages. +* `debug`: Repository for packages containing debug symbols. In almost all cases, + these packages are generated automatically. +* `nonfree`: Repository for packages that are closed source or have nonfree licenses. + + +### Checking for new upstream releases + +New upstream versions can be automatically checked using +`./xbps-src update-check `. In some cases you need to override +the sensible defaults by assigning the following variables in a `update` +file in the same directory as the relevant `template` file: + +- `site` contains the URL where the version number is + mentioned. If unset, defaults to `homepage` and the directories where +`distfiles` reside. + +- `pkgname` is the package name the default pattern checks for. +If unset, defaults to `pkgname` from the template. + +- `pattern` is a perl-compatible regular expression +matching the version number. Anchor the version number using `\K` +and `(?=...)`. Example: `pattern='\K[\d.]+(?=)'`, this +matches a version number enclosed in `...` tags. + +- `ignore` is a space-separated list of shell globs that match +version numbers which are not taken into account for checking newer +versions. Example: `ignore="*b*"` + +- `version` is the version number used to compare against +upstream versions. Example: `version=${version//./_}` + +- `single_directory` can be set to disable +detecting directory containing one version of sources in url, +then searching new version in adjacent directories. + +- `vdprefix` is a perl-compatible regular expression matching +part that precedes numeric part of version directory +in url. Defaults to `(|v|$pkgname)[-_.]*`. + +- `vdsuffix` is a perl-compatible regular expression matching +part that follows numeric part of version directory +in url. Defaults to `(|\.x)`. + +- `disabled` can be set to disable update checking for the package, +in cases where checking for updates is impossible or does not make sense. +This should be set to a string describing why it is disabled. + + +### Handling patches + +Sometimes software needs to be patched, most commonly to fix bugs that have +been found or to fix compilation with new software. + +To handle this, xbps-src has patching functionality. It will look for all files +that match the glob `srcpkgs/$pkgname/patches/*.{diff,patch}` and will +automatically apply all files it finds using `patch(1)` with `-Np1`. This happens +during the `do_patch()` phase. The variable `PATCHESDIR` is +available in the template, pointing to the `patches` directory. + +The patching behaviour can be changed in the following ways: + +- A file called `series` can be created in the `patches` directory with a newline +separated list of patches to be applied in the order presented. When present +xbps-src will only apply patches named in the `series` file. + +- A file with the same name as one of the patches but with `.args` as extension can +be used to set the args passed to `patch(1)`. As an example, if `foo.patch` requires +special arguments to be passed to `patch(1)` that can't be used when applying other +patches, `foo.patch.args` can be created containing those args. + + +### build style scripts + +The `build_style` variable specifies the build method to build and install a +package. It expects the name of any available script in the +`void-packages/common/build-style` directory. Please note that required packages +to execute a `build_style` script must be defined via `$hostmakedepends`. + +The current list of available `build_style` scripts is the following: + +- If `build_style` is not set, the template must (at least) define +`do_install()` function and optionally more build phases such as +`do_configure()`, `do_build()`, etc., and may overwrite default `do_fetch()` and +`do_extract()` that fetch and extract files defined in `distfiles` variable. + +- `cargo` For packages written in rust that use Cargo for building. +Configuration arguments (such as `--features`) can be defined in the variable +`configure_args` and are passed to cargo during `do_build`. + +- `cmake` For packages that use the CMake build system, configuration arguments +can be passed in via `configure_args`. The `cmake_builddir` variable may be +defined to specify the directory for building under `build_wrksrc` instead of +the default `build`. + +- `configure` For packages that use non-GNU configure scripts, at least `--prefix=/usr` +should be passed in via `configure_args`. + +- `fetch` For packages that only fetch files and are installed as is via `do_install()`. + +- `gnu-configure` For packages that use GNU autotools-compatible configure scripts, +additional configuration arguments can be passed in via `configure_args`. + +- `gnu-makefile` For packages that use GNU make, build arguments can be passed in via +`make_build_args` and install arguments via `make_install_args`. The build +target can be overridden via `make_build_target` and the install target +via `make_install_target`. This build style tries to compensate for makefiles +that do not respect environment variables, so well written makefiles, those +that do such things as append (`+=`) to variables, should have `make_use_env` +set in the body of the template. + +- `go` For programs written in Go that follow the standard package +structure. The variable `go_import_path` must be set to the package's +import path, e.g. `github.com/github/hub` for the `hub` program. This +information can be found in the `go.mod` file for modern Go projects. +It's expected that the distfile contains the package, but dependencies +will be downloaded with `go get`. + +- `meta` For `meta-packages`, i.e packages that only install local files or simply +depend on additional packages. This build style does not install +dependencies to the root directory, and only checks if a binary package is +available in repositories. + +- `R-cran` For packages that are available on The Comprehensive R Archive +Network (CRAN). The build style requires the `pkgname` to start with +`R-cran-` and any dashes (`-`) in the CRAN-given version to be replaced +with the character `r` in the `version` variable. The `distfiles` +location will automatically be set as well as the package made to depend +on `R`. + +- `gemspec` For packages that use +[gemspec](https://guides.rubygems.org/specification-reference/) files for building a ruby +gem and then installing it. The gem command can be overridden by `gem_cmd`. `configure_args` +can be used to pass arguments during compilation. If your package does not make use of compiled +extensions consider using the `gem` build style instead. + +- `gem` For packages that are installed using gems from [RubyGems](https://rubygems.org/). +The gem command can be overridden by `gem_cmd`. +`distfiles` is set by the build style if the template does not do so. If your gem +provides extensions which must be compiled consider using the `gemspec` build style instead. + +- `ruby-module` For packages that are ruby modules and are installable via `ruby install.rb`. +Additional install arguments can be specified via `make_install_args`. + +- `perl-ModuleBuild` For packages that use the Perl +[Module::Build](https://metacpan.org/pod/Module::Build) method. + +- `perl-module` For packages that use the Perl +[ExtUtils::MakeMaker](http://perldoc.perl.org/ExtUtils/MakeMaker.html) build method. + +- `raku-dist` For packages that use the Raku `raku-install-dist` build method with rakudo. + +- `waf3` For packages that use the Python3 `waf` build method with python3. + +- `waf` For packages that use the Python `waf` method with python2. + +- `slashpackage` For packages that use the /package hierarchy and package/compile to build, +such as `daemontools` or any `djb` software. + +- `qmake` For packages that use Qt4/Qt5 qmake profiles (`*.pro`), qmake arguments +for the configure phase can be passed in via `configure_args`, make build arguments can +be passed in via `make_build_args` and install arguments via `make_install_args`. The build +target can be overridden via `make_build_target` and the install target +via `make_install_target`. + +- `meson` For packages that use the Meson Build system, configuration options can be passed +via `configure_args`, the meson command can be overridden by `meson_cmd` and the location of +the out of source build by `meson_builddir` + +- `void-cross` For cross-toolchain packages used to build Void systems. There are no +mandatory variables (target triplet is inferred), but you can specify some optional +ones - `cross_gcc_skip_go` can be specified to skip `gccgo`, individual subproject +configure arguments can be specified via `cross_*_configure_args` where `*` is `binutils`, +`gcc_bootstrap` (early gcc), `gcc` (final gcc), `glibc` (or `musl`), `configure_args` is +additionally passed to both early and final `gcc`. You can also specify custom `CFLAGS` +and `LDFLAGS` for the libc as `cross_(glibc|musl)_(cflags|ldflags)`. + +- `zig-build` For packages using [Zig](https://ziglang.org)'s build +system. Additional arguments may be passed to the `zig build` invocation using +`configure_args`. + +For packages that use the Python module build method (`setup.py` or +[PEP 517](https://www.python.org/dev/peps/pep-0517/)), you can choose one of the following: + +- `python2-module` to build Python 2.x modules + +- `python3-module` to build Python 3.x modules + +- `python3-pep517` to build Python 3.x modules that provide a PEP 517 build description without +a `setup.py` script + +Environment variables for a specific `build_style` can be declared in a filename +matching the `build_style` name, Example: + + `common/environment/build-style/gnu-configure.sh` + +- `texmf` For texmf zip/tarballs that need to go into /usr/share/texmf-dist. Includes +duplicates handling. + + +### build helper scripts + +The `build_helper` variable specifies shell snippets to be sourced that will create a +suitable environment for working with certain sets of packages. + +The current list of available `build_helper` scripts is the following: + +- `cmake-wxWidgets-gtk3` sets the `WX_CONFIG` variable which is used by FindwxWidgets.cmake + +- `gir` specifies dependencies for native and cross builds to deal with +GObject Introspection. The following variables may be set in the template to handle +cross builds which require additional hinting or exhibit problems. `GIR_EXTRA_LIBS_PATH` defines +additional paths to be searched when linking target binaries to be introspected. +`GIR_EXTRA_OPTIONS` defines additional options for the `g-ir-scanner-qemuwrapper` calling +`qemu--static` when running the target binary. You can for example specify +`GIR_EXTRA_OPTIONS="-strace"` to see a trace of what happens when running that binary. + +- `meson` creates a cross file, `${XBPS_WRAPPERDIR}/meson/xbps_meson.cross`, which configures +meson for cross builds. This is particularly useful for building packages that wrap meson +invocations (e.g., `python3-pep517` packages that use a meson backend) and is added by default +for packages that use the `meson` build style. + +- `numpy` configures the environment for cross-compilation of python packages that provide +compiled extensions linking to NumPy C libraries. If the `meson` build helper is also +configured, a secondary cross file, `${XBPS_WRAPPERDIR}/meson/xbps_numpy.cross`, will be +written to inform meson where common NumPy components may be found. + +- `python3` configures the cross-build environment to use Python libraries, header files, and +interpreter configurations in the target root. The `python3` helper is added by default for +packages that use the `python3-module` or `python3-pep517` build styles. + +- `qemu` sets additional variables for the `cmake` and `meson` build styles to allow +executing cross-compiled binaries inside qemu. +It sets `CMAKE_CROSSCOMPILING_EMULATOR` for cmake and `exe_wrapper` for meson +to `qemu--static` and `QEMU_LD_PREFIX` to `XBPS_CROSS_BASE`. +It also creates the `vtargetrun` function to wrap commands in a call to +`qemu--static` for the target architecture. + +- `qmake` creates the `qt.conf` configuration file (cf. `qmake` `build_style`) +needed for cross builds and a qmake-wrapper to make `qmake` use this configuration. +This aims to fix cross-builds for when the build-style is mixed: e.g. when in a +`gnu-configure` style the configure script calls `qmake` or a `Makefile` in +`gnu-makefile` style, respectively. + +- `rust` specifies environment variables required for cross-compiling crates via cargo and +for compiling cargo -sys crates. This helper is added by default for packages that use the +`cargo` build style. + + +### Functions + +The following functions can be defined to change the behavior of how the +package is downloaded, compiled and installed. + +- `pre_fetch()` Actions to execute before `do_fetch()`. + +- `do_fetch()` if defined and `distfiles` is not set, use it to fetch the required sources. + +- `post_fetch()` Actions to execute after `do_fetch()`. + +- `pre_extract()` Actions to execute after `post_fetch()`. + +- `do_extract()` if defined and `distfiles` is not set, use it to extract the required sources. + +- `post_extract()` Actions to execute after `do_extract()`. + +- `pre_patch()` Actions to execute after `post_extract()`. + +- `do_patch()` if defined use it to prepare the build environment and run hooks to apply patches. + +- `post_patch()` Actions to execute after `do_patch()`. + +- `pre_configure()` Actions to execute after `post_patch()`. + +- `do_configure()` Actions to execute to configure the package; `${configure_args}` should +still be passed in if it's a GNU configure script. + +- `post_configure()` Actions to execute after `do_configure()`. + +- `pre_build()` Actions to execute after `post_configure()`. + +- `do_build()` Actions to execute to build the package. + +- `post_build()` Actions to execute after `do_build()`. + +- `pre_check()` Actions to execute after `post_build()`. + +- `do_check()` Actions to execute to run checks for the package. + +- `post_check()` Actions to execute after `do_check()`. + +- `pre_install()` Actions to execute after `post_check()`. + +- `do_install()` Actions to execute to install the package files into the `fake destdir`. + +- `post_install()` Actions to execute after `do_install()`. + +- `do_clean()` Actions to execute to clean up after a successful package phase. + +> A function defined in a template has preference over the same function +defined by a `build_style` script. + +Current working directory for functions is set as follows: + +- For pre_fetch, pre_extract, do_clean: ``. + +- For do_fetch, post_fetch: `XBPS_BUILDDIR`. + +- For do_extract through do_patch: `wrksrc`. + +- For post_patch through post_install: `build_wrksrc` +if it is defined, otherwise `wrksrc`. + + +### Build options + +Some packages might be built with different build options to enable/disable +additional features; The XBPS source packages collection allows you to do this with some simple tweaks +to the `template` file. + +The following variables may be set to allow package build options: + +- `build_options` Sets the build options supported by the source package. + +- `build_options_default` Sets the default build options to be used by the source package. + +- `desc_option_