revisions

Author: userdocs

.github/copilot-instructions.md

@@ -1,3 +1,104 @@
+# AI Coding Guide for This Repo
+
+Purpose: Make AI contributions precise, minimal, and correct. Follow these rules strictly. Do not expand scope beyond the prompt.
+
+## Bash scripting (applies to all repos)
+
+Do
+- Use `#!/bin/bash` as the shebang for Bash scripts.
+- Use the `.bash` extension for Bash; use `.sh` only for POSIX-only scripts.
+- Prefer `$BASH_SOURCE` over `$0` for script path detection.
+- Use `printf '%s'` for plain strings and `printf '%b'` for escape sequences. Avoid `echo`.
+- Keep changes simple, modular, and scoped to the exact prompt.
+- Write readable code; add concise comments explaining intent and non-obvious logic.
+- Handle errors explicitly (per function is acceptable); return helpful, actionable messages.
+- Structure changes in small stages; keep functions focused.
+- Format using Google’s Shell Style Guide: https://google.github.io/styleguide/shellguide.html
+- For Bash references, consult: https://mywiki.wooledge.org and https://mywiki.wooledge.org/BashFAQ and include a source link when possible. Do not invent links.
+
+Avoid
+- Global “set -euo pipefail”; prefer targeted checks and explicit error handling.
+- Uppercase variable names for general scripting (reserve UPPERCASE for Docker/env settings).
+- Clever one-liners that harm clarity.
+- Generalized or speculative changes not asked for in the prompt.
+- Over-engineering; keep it stable, concise, and C-like in mindset.
+
+Scope and behavior
+- Only implement what the prompt requests.
+- Keep solutions minimal and modular; do not add placeholders or future-proofing unless required.
+- When giving Bash/shell answers, add a relevant wooledge link if helpful; never fabricate links.
+
+## GitHub Workflows (all repos)
+
+- In reusable workflows, any job that uses outputs from another job must declare that job in `needs` to avoid null outputs.
+- Do not use outdated Actions. Check for current recommended versions before editing.
+- The `gh` CLI cannot fetch the ID of a workflow run it just started via `gh run workflow`. List runs afterward and extract the ID.
+
+## If repo name matches `*-musl-cross-make`
+
+Toolchain specifics
+- Use both `-static` and `--static` to produce static toolchain binaries. Using only `-static` can miss POSIX threads.
+- When using `../config.mak`, always load options from both `../gcc-configure-options.md` and `../gcc-configure-options-recursive.md`.
+- The binutils gold linker is deprecated. Use `ld=default` and `--disable-gold`.
+
+Fully static toolchains with musl
+- Do not use LTO: avoid `-flto` and `-fuse-linker-plugin`.
+- Do not add any LTO-related settings.
+- Only set linker options such as `LDFLAGS` at link time, not during library builds.
+- GNU libtool redefines `-static`; to ensure static linking, use `--static` or `-Wl,-static` (optionally with `-static`) in `LDFLAGS`.
+- For static OpenSSL: do not use `openssl -static` (it disables threads/PIE/PIC). For `-static-pie` with musl/Alpine, use the correct flags and approach.
+- Do not use glibc-only flags or glibcisms for musl toolchains.
+
+## Debugging with QEMU
+
+- Start the target under QEMU with gdbstub, then attach with gdb:
+  - `qemu -g <port> <binary>` (e.g., `qemu -g 1234 ./qbt-nox-static`)
+  - In another terminal: `gdb ./qbt-nox-static` and `target remote :1234`
+
+## If repo name matches `*qbittorrent-nox-static`
+
+`qi.bash` script goals
+- Simple installer that verifies installation and binaries.
+- Shebang must be `#!/bin/bash`.
+
+OS detection
+- `source /etc/os-release`.
+- Supported: `ID=alpine`, `ID=debian`, or `ID_LIKE` contains `debian`. Otherwise exit with a clear reason.
+
+Transfer tools
+- Prefer `curl` if present; use `wget` if present and `curl` is not; exit if neither is available.
+- Detect presence of `gh` CLI and use it when available, but it is not required.
+
+Architecture detection
+- Alpine: `apk --print-arch`.
+- Debian-like: `dpkg --print-architecture`.
+- Architectures are the same across distros except `armhf`: Debian uses `armv7`, Alpine uses `armv6`.
+- If architecture is not valid/supported, exit with a reason.
+
+Download function
+- Build the download URL from the detected architecture.
+- Create and store the download’s SHA-256 sum.
+
+Attestation (optional)
+- When `gh` CLI is available and usable, verify downloaded binaries:
+  - `gh attestation verify <INSTALL_PATH> --repo <REPO> 2> /dev/null`
+
+Error handling
+- Provide a helper that checks command exit codes and exits with a concise, helpful message on failure.
+
+Output formatting
+- Provide a print helper that supports:
+  - `[INFO]` (blue), `[WARNING]` (yellow), `[ERROR]` (red), `[SUCCESS]` (green), `[FAILURE]` (magenta)
+- Use `printf '%s'` and `printf '%b'`; do not use `echo`.
+- Keep messages succinct. Be verbose only on errors to aid troubleshooting.
+
+---
+
+Meta for AI contributors
+- Be conservative: do only what the prompt requests. No broad refactors.
+- Prefer small, well-named functions and staged changes.
+- Preserve existing public behavior and style unless the prompt requires changes.
+- If something cannot be done with available context/tools, state why and propose the smallest viable alternative.
 # Bash Scripting - All repos
 
 - use $BASH_SOURCE instead of $0
@@ -10,10 +111,16 @@
 - Always makes changes in stages, a modular approach.
 - use Google style guide for formatting of bash scripts - https://google.github.io/styleguide/shellguide.html
 - Always use `#!/bin/bash` as the shebang.
+- Always use the extensions `bash` for bash script and `sh` only for posix shell scripts
 - Use `printf '%s'` for printing strings and `printf '%b'` for escape sequences. **Avoid using `echo`.**
 - Comment code to explain changes and logic.
 - always prefer readability of code over complex one lines. Unless that foramt is promoted by the style guide.
 - For Bash/shell questions, consult [mywiki.wooledge.org](https://mywiki.wooledge.org) or [BashFAQ](https://mywiki.wooledge.org/BashFAQ) first. **Provide a source link when possible.**
+- Don't hallucinate <mywiki.wooledge.org> links in comments
+- think like a c developer not a javascript developer. stable, concise, elegant and thoughtful. Not edgy and bleeding edge for the sake of it.
+- when providing a solution to a prompt don't provide solutions outside the scope of the prompt nor add loads checks and fallbacks that quickly become redundant in following prompts.
+- it makes me wast premium tokens making you fix the brken things you added or changed that were outside the scope of the prompt to begin with.
+- provide changes specific to the prompt given.
 
 # GitHub Workflows - All repos
 
@@ -80,3 +187,8 @@ ouputs
 - Use `printf '%s'` for printing strings and `printf '%b'` for escape sequences. **Avoid using `echo`.**
 - this function will provide end user information understanding or troubleshooting script outcomes.
 - it should be succinct unless there is an error or failure, then it should be verbose enough to help.
+
+## Astro and Astro starlight template for documentation
+
+- Always use the mcp server https://mcp.docs.astro.build/mcp
+- Always make sure imported mdx components start with an upper case letter.

.github/workflows/ci-alpine-release.yml

@@ -56,18 +56,22 @@ jobs:
         env:
           lt_version: ${{ matrix.qbt_libtorrent_version }}
         run: |
-          revision="$(jq -r .revision ${lt_version}/*-dependency-version.json | sort -nr | head -n1)"
-          boost="$(jq -r .boost ${lt_version}/*-dependency-version.json | head -n1)"
+          shopt -s nullglob
 
-          for dependency_version_json in ${lt_version}/*-dependency-version.json; do
+          revision="$(jq -r .revision "${lt_version}"/*-dependency-version.json | sort -nr | head -n1)"
+          boost="$(jq -r .boost "${lt_version}"/*-dependency-version.json | head -n1)"
+
+          # this need to check both 1.2 and 2.0 folders to merge the libtorrent versions in the dependency-version.json
+          for dependency_version_json in {1.2,2.0}/*-dependency-version.json; do
             if [[ -f ${dependency_version_json} ]]; then
               sed -r 's/"boost": (.*)/BOOST_PLACEHOLDER/g' -i "${dependency_version_json}"
               sed -r 's/"revision": (.*)/REVISION_PLACEHOLDER/g' -i "${dependency_version_json}"
               dependency_version+=("${dependency_version_json}")
             fi
           done
 
-          for release_md in ${lt_version}/*-release.md; do
+          # This file only needs to merge info specific to the libtorrent matrix running it.
+          for release_md in "${lt_version}"/*-release.md; do
             if [[ -f ${release_md} ]]; then
               sed -r 's/^\|(.*)revision(.*)\|(.*)\|$/REVISION_PLACEHOLDER/g' -i "${release_md}"
               release_md+=("${release_md}")

docs/src/components/buildinfo-introduction.astro

@@ -1,17 +1,17 @@
 ---
 import { Code } from "@astrojs/starlight/components";
 const response = await fetch(
-	"https://github.com/userdocs/qbt-workflow-files/releases/latest/download/dependency-version.json"
+	"https://github.com/userdocs/qbt-workflow-files/releases/latest/download/dependency-version.json",
 );
 
 const data = await response.json();
 
-const codeblock = `qBittorrent ${data.qbittorrent || "4.6.3"} was built with the following libraries:
-Qt: ${data.qt6 || "6.6.2"}
-Libtorrent: ${data.libtorrent_2_0 || "2.0.10"}
-Boost: ${data.boost || "1.84.0"}
-OpenSSL: ${data.openssl || "3.2.1"}
-zlib: ${data.zlib || "1.3.2"}-motley`;
+const codeblock = `qBittorrent ${data.qbittorrent || "5.1.2"} was built with the following libraries:
+Qt: ${data.qt6 || "6.9.1"}
+Libtorrent: ${data.libtorrent_2_0 || "2.0.11"}
+Boost: ${data.boost || "1.89.0"}
+OpenSSL: ${data.openssl || "3.5.2"}
+zlib: ${data.zlib || "1.3.1.1"}-motley`;
 
 // {
 //   "glibc_2_31": "2.31",

docs/src/content/docs/build-help.mdx

@@ -252,7 +252,7 @@ Add your patches there, for example.
 
 ## Build - default profile
 
-Install all default modules (ICU is skipped) and build `qbittorrent-nox` to the default build directory `qbt-build/compelted`.
+Install all default modules (ICU is skipped) and build `qbittorrent-nox` to the default build directory `qbt-build/completed`.
 
 ```bash
 ./qbt-nox-static.bash all
@@ -275,11 +275,11 @@ Here are the list of supported modules:
 ```bash
 glibc (Debian based only)
 zlib (default)
-iconv (default)
+iconv (default libtorrent v1.2 only)
 icu (optional)
 openssl (default)
 boost (default)
-double_conversion (default for Qt6 on a modern OS - Bullseye / Jammy)
+double_conversion (default for Qt6 on a modern OS)
 qtbase (default)
 qttools (default)
 libtorrent (default)

docs/src/content/docs/script-installation.mdx

@@ -29,11 +29,15 @@ Some notes on the dockers method:
 - We use `-e "LANG=C.UTF-8"` with Debian based images to avoid some UTF errors.
 
 :::tip[env file]
+You do not need to configure the env while bootstrapping the container. It can be done after via the `.qbt_env` file or exporting them.
+
 There are multiple ways to pass an env file when using Docker.
 
 - You can use the `--env-file` switch when creating the docker and provide a file with your [envs](/qbittorrent-nox-static/build-help#env-settings).
 - If a `.qbt_env` file is found in the same directory as the script, it will be used automatically.
 - Using ENV in a dockerfile is also possible.
+
+The easist method is the `.qbt_env` as the script has support flags for this purpose.
 :::
 
 </TabItem>
@@ -73,7 +77,7 @@ docker run -it -w /root -p 8080:8080 -e "LANG=C.UTF-8" -v ~/qbt:/root debian:lat
 If you need to download the script use this command
 
 ```bash
-curl --sLO https://raw.githubusercontent.com/userdocs/qbittorrent-nox-static/refs/heads/master/qbt-nox-static.bash && chmod +x qbt-nox-static.bash
+curl -sLO https://raw.githubusercontent.com/userdocs/qbittorrent-nox-static/refs/heads/master/qbt-nox-static.bash && chmod +x qbt-nox-static.bash
 ```
 
 </TabItem>

docs/src/content/docs/script-usage.mdx

@@ -21,6 +21,12 @@ Don't run this directly on the host system unless you know what you are doing. I
 
 ### Execute the script
 
+:::caution[A reminder about the `.qbt_env`]
+If you have a `.qbt_env` in the same folder as the script it will override any custom env settings you provide.
+
+Using flags will override your `.qbt_env`
+:::
+
 ```bash
 ./qbt-nox-static.bash
 ```
@@ -41,7 +47,11 @@ By passing `all` as the first argument, you can build everything based on the de
 ./qbt-nox-static.bash all
 ```
 
-For example, to use `ICU` using `-i`, optimise for the host system CPU using `-o` to set `-march=native` and `-s` to strip the binary and build using libtorrent v1.2.19
+For example of using custom settings,
+
+- to use `ICU` using `-i`
+- optimise for the host system CPU using `-o` to set `-march=native`
+- build using libtorrent v1.2.19
 
 ```bash
 ./qbt-nox-static.bash all -i -o -s -lt v1.2.19
@@ -50,7 +60,7 @@ For example, to use `ICU` using `-i`, optimise for the host system CPU using `-o
 Same as previous command but using `env` settings
 
 ```bash
-qbt_libtorrent_tag="v1.2.19" qbt_skip_icu="yes" qbt_optimise_strip="yes" qbt_optimize="yes" ./qbt-nox-static.bash all
+qbt_libtorrent_tag="v1.2.19" qbt_skip_icu="yes" qbt_optimize="yes" ./qbt-nox-static.bash all
 ```
 
 For an older version of qBittorrent, you can specify the version using `-qt` and the libtorrent version using `-lt`

qbittorrent-nox-static.sh

@@ -2187,8 +2187,8 @@ _release_info() {
 		|           Libtorrent           | ${app_version[libtorrent]}  |
 		|             Boost              |    ${app_version[boost]}    |
 		|            OpenSSL             |   ${app_version[openssl]}   |
-		|         ${qbt_zlib_type}       |    ${app_version[zlib]}     |
-		|            revision            |   ${qbt_revision_version}   |
+		|        ${qbt_zlib_type}        |    ${app_version[zlib]}     |
+		|            revision            | ${qbt_revision_version:-0}  |
 
 		## Architecture and build info
 

qbt-nox-static.bash

@@ -2380,8 +2380,8 @@ _release_info() {
 		|           Libtorrent           | ${app_version[libtorrent]}  |
 		|             Boost              |    ${app_version[boost]}    |
 		|            OpenSSL             |   ${app_version[openssl]}   |
-		|         ${qbt_zlib_type}       |    ${app_version[zlib]}     |
-		|            revision            |   ${qbt_revision_version}   |
+		|        ${qbt_zlib_type}        |    ${app_version[zlib]}     |
+		|            revision            | ${qbt_revision_version:-0}  |
 
 		## Architecture and build info