|
| 1 | +# Bash Scripting - All repos |
| 2 | + |
| 3 | +- avoid set -euo pipefail - instead focus on thorough testing, validation and error handling. |
| 4 | +- ideally error handling should be considered holistically but per function is acceptable. |
| 5 | +- changes and recommendations should be simple, modular, focused on the requirement of the prompt. |
| 6 | +- never make generalized changes that are not specifically required for the prompt. |
| 7 | +- don't over complicated the solution or pollute it with noisy or complex solutions. |
| 8 | +- Always makes changes in stages, a modular approach. |
| 9 | +- use Google style guide for formatting of bash scripts - https://google.github.io/styleguide/shellguide.html |
| 10 | +- Always use `#!/bin/bash` as the shebang. |
| 11 | +- Use `printf '%s'` for printing strings and `printf '%b'` for escape sequences. **Avoid using `echo`.** |
| 12 | +- Comment code to explain changes and logic. |
| 13 | +- always prefer readability of code over complex one lines. Unless that foramt is promoted by the style guide. |
| 14 | +- 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.** |
| 15 | + |
| 16 | +# GitHub Workflows - All repos |
| 17 | + |
| 18 | +- In reusable workflows, jobs that use outputs from other jobs **must** include those jobs in their `needs` section to avoid null variables. |
| 19 | +- Do not use outdated GitHub Actions in workflow code. Always check the version recommended is the current version |
| 20 | +- The `gh` CLI cannot get the ID of a workflow it started with `gh run workflow`; you must list runs after and extract the ID. |
| 21 | + |
| 22 | +# If repo = *-musl-cross-make |
| 23 | +GCC / Binutils |
| 24 | +- Use both `-static` and `--static` to create static toolchain binaries. Using `-static` alone can cause errors (e.g., missing POSIX threads). |
| 25 | +- When working with `../config.mak`, always load options from both `../gcc-configure-options.md` and `../gcc-configure-options-recursive.md`. |
| 26 | +- The binutils gold linker is deprecated. Use `ld=default` and `--disable-gold`. |
| 27 | +- For fully static toolchains linked to musl: |
| 28 | + - Do **not** use `-flto` or `-fuse-linker-plugin` (LTO is not supported; plugins require dynamic loading). |
| 29 | + - Do **not** add any LTO settings. |
| 30 | +- Only set linker options like `LDFLAGS` when linking, **not** when building libraries. |
| 31 | +- GNU libtool redefines `-static`; to ensure static linking, use `--static` or `-Wl,-static` in `LDFLAGS` (possibly with `-static`). |
| 32 | +- When building OpenSSL statically, do **not** use `openssl -static` (it disables threads, PIE, PIC). For `-static-pie` binaries with musl/Alpine, use the correct flags. |
| 33 | +- Do **not** suggest glibc-only flags or glibcisms for musl toolchains. |
| 34 | + |
| 35 | +# Debugging with qemu |
| 36 | + |
| 37 | +- To debug with QEMU: |
| 38 | + Run `qemu -g <port> <binary>` (e.g., `qemu -g 1234 ./qbt-nox-static`), then connect with `gdb ./qbt-nox-static` in another terminal. |
| 39 | + |
| 40 | +# If repo = * qbittorrent-nox-static |
| 41 | + |
| 42 | +## qi.bash script |
| 43 | + |
| 44 | +General features |
| 45 | +- Always use `#!/bin/bash` as the shebang. |
| 46 | +- this script is focused on being a simple installer that verifies installation and binaries. |
| 47 | + |
| 48 | +basic check for supported os |
| 49 | +- use source /etc/os-release |
| 50 | +- if ID = alpine of debian or if the or if ID_LIKE=debian is debian like we can proceed. |
| 51 | +- if not supported os exit with reason. |
| 52 | + |
| 53 | +basic check for wget or curl, default to curl if present. |
| 54 | +- if no tools exit with reason. |
| 55 | +- wget or curl must have, curl default if present but use wget if there. |
| 56 | +- check if gh cli is available to use but no required. |
| 57 | + |
| 58 | +basic check of which arch using |
| 59 | +- alpine use apk --print-arch |
| 60 | +- debian like use dpkg --print-architecture |
| 61 | +- all arches are the same except armhf. on debian this is armv7 and alpine armv6 |
| 62 | +- if not valid arch exit with reason. |
| 63 | + |
| 64 | +create download function based on arch checks. |
| 65 | +- configure download url based on arch. |
| 66 | +- creates sha256 of download. |
| 67 | + |
| 68 | +gh cli function |
| 69 | +- if gh cli exists and is usable use it to very the binaries downloaded |
| 70 | +- if gh attestation verify <INSTALL_PATH> --repo <REPO> 2> /dev/null; then ... |
| 71 | + |
| 72 | +error handling |
| 73 | +- there should be a error handling function to test commands exit the script with helpful explanations when a command or function fails. |
| 74 | + |
| 75 | +ouputs |
| 76 | +- there should be a function to handle printing outputs. |
| 77 | +- It should handle [INFO] (blue) [WARNING] (yellow) [ERROR] (red) [SUCCESS] (Green) [FAILURE] (magenta) |
| 78 | +- Use `printf '%s'` for printing strings and `printf '%b'` for escape sequences. **Avoid using `echo`.** |
| 79 | +- this function will provide end user information understanding or troubleshooting script outcomes. |
| 80 | +- it should be succinct unless there is an error or failure, then it should be verbose enough to help. |
0 commit comments