# SlackBuilds Repository

Personal collection of SlackBuild scripts maintained by Danilo, compatible with
[SlackBuilds.org (SBo)](https://slackbuilds.org) conventions.

---

## Repo Structure

Each package lives in its own top-level subfolder:

```
<package-name>/
├── <package-name>.SlackBuild   # Main build script
├── <package-name>.info         # Metadata (version, checksums, URLs)
├── README                      # Description and usage notes
├── slack-desc                  # Package description (11-line format)
├── <package-name>.desktop      # (optional) Desktop entry for GUI apps
└── [...]                       # other optional files
```

Version tracking is handled by a single file:

```
.extras/nvchecker.toml   # nvchecker config listing all packages
```

### `.extras/` holds all non-package repo files

Anything that is not a SlackBuild package must live under `.extras/`, never at
the repo root. In particular, design docs and specs go in
`.extras/docs/`, NOT a top-level `docs/`. The build repository consumes this
repo as a subtree, and a top-level `docs/` folder leaks into that subtree.
(This has been fixed twice already; keep it in `.extras/`.)

---

## SlackBuild Scripting Guidelines

### Templates live in `~/Templates/SlackBuilds/`

The official SBo templates are kept locally as a git clone at
`~/Templates/SlackBuilds/sbo/` (a second clone, `conraid/`, holds Conraid's
scripts for reference). Both are refreshed by
`~/Templates/SlackBuilds/update-templates.sh`, which pulls each clone; run it to
get the latest upstream templates before starting work.

**Always start from these templates** when authoring a NEW SlackBuild, or when
taking over maintenance of an existing script on SBo. Read the matching template
first, do not copy an existing package from this repo and rename it, an old
package can carry drift the current template has since fixed.

Pick by build system:

| Template | Use for |
|----------|---------|
| `sbo/python-template.SlackBuild` | Python packages (setup.py and pyproject-only paths) |
| `sbo/autotools-template.SlackBuild` | `./configure && make` |
| `sbo/cmake-template.SlackBuild` | CMake |
| `sbo/meson-template.SlackBuild` | Meson |
| `sbo/perl-template.SlackBuild` | Perl modules |
| `sbo/rubygem-template.SlackBuild` | Ruby gems |
| `sbo/haskell-template.SlackBuild` | Haskell |
| `sbo/template.info`, `sbo/slack-desc`, `sbo/README`, `sbo/doinst.sh`, `sbo/douninst.sh` | the other package files |

Strip the template's instructional comment blocks and unused branches (e.g. the
python2/setup.py path, the man-page gzip block when upstream ships no man pages)
before shipping the script.

- Follow the [SBo template](https://slackbuilds.org/templates/) as the base for all scripts
- Use `set -e` to abort on errors
- Honor `$TMP`, `$BUILD`, `$TAG`, `$OUTPUT` variables; default values must be set if unset
- Use `$ARCH` detection with proper `SLKCFLAGS` and `LIBDIRSUFFIX`
- Strip binaries and libraries unless upstream explicitly discourages it
- Install docs to `/usr/doc/$PRGNAM-$VERSION/`
- Always include `find -L` + `chown`/`chmod` cleanup block before packaging
- Copy repo files into `$PKG` with `cat src > dest`, never `cp`. `cat` writes
  through a fresh destination so the build's umask/root ownership sets the
  perms; `cp` bleeds the git working-tree mode/ownership into the package.
  Applies to `slack-desc`, `doinst.sh`, and any file staged from `$CWD`
  (SlackBuild, README, `.nvchecker`) into `$PKG`.
- Use `makepkg -l y -c n` to create the final package

### `.info` file

Must contain:
```
PRGNAM, VERSION, HOMEPAGE, DOWNLOAD, MD5SUM (or SHA256SUM), REQUIRES, MAINTAINER, EMAIL
```
- Checksums must match the exact source archive
- Use `REQUIRES=""` if no SBo dependencies; list space-separated SBo package names otherwise

### `slack-desc`

- Exactly 11 lines in the `package-name: description` format
- First line: `package-name: package-name (short one-liner)`
- Lines 2–11: description, leave blank lines as `package-name:`
- Handy ruler line must be included (but not shipped)

---

## Version Tracking: nvchecker

A single `nvchecker.toml` at the repo root tracks upstream versions for all packages. Each package defines its own source type (GitHub releases, PyPI, etc.).

Example entry for a GitHub-hosted package:

```toml
[package-name]
source = "github"
github = "owner/repo"
use_max_tag = true
```

To check for new upstream versions:

```bash
nvchecker -c .extras/nvchecker.toml
```

When a new version is detected, update `VERSION` in both `.SlackBuild` and `.info`, then run `sbofixinfo` to refresh checksums.

**Every new package added to this repo must have a corresponding entry in `.extras/nvchecker.toml`.**

---

## Tooling: sbo-maintainer-tools

Source: https://slackware.uk/~urchlay/repos/sbo-maintainer-tools

### Tools used

| Tool | Purpose |
|------|---------|
| `sbolint` | Lint `.SlackBuild`, `README`, `.info`, `slack-desc` |
| `sbopkglint` | Lint the built package |
| `sbofixinfo` | Auto-fix common `.info` file issues |
| `sbodl` | Download sources and verify `MD5SUM`/`SHA256SUM` from `.info` |
| `pre-commit-sbolint` | Git pre-commit hook — blocks commits that fail `sbolint` |

### Git hook setup

Both hooks are tracked in the `.extras/hooks/` directory. Install them after cloning:

```bash
cp .extras/hooks/pre-commit .git/hooks/pre-commit
cp .extras/hooks/post-commit .git/hooks/post-commit
chmod +x .git/hooks/pre-commit .git/hooks/post-commit
```

| Hook | Trigger | Purpose |
|------|---------|---------|
| `pre-commit` | Before every commit | Runs `sbolint` on staged packages; blocks commit on errors. Also checks for staged source archives: symlinks are auto-removed, real files block the commit. |
| `post-commit` | After every commit | Offers to create a `SBo/<pkg>.tar.gz` archive for submission |

To bypass the pre-commit lint check in exceptional cases:
```bash
SBOLINT=no git commit -m'Message here'
```

### Workflow per package

> **Before creating a NEW package: check the name is free on SlackBuilds.org.**
> SBo enforces unique package names across all categories, and a clash causes
> confusion even in this personal repo. Search https://slackbuilds.org/result/?search=<name>
> (or browse the category). If the name is taken by an unrelated project, pick a
> distinct name (e.g. gitea-cli instead of tea, whose slot is a text editor) and
> keep the upstream binary name via a SRCNAM variable in the SlackBuild.

```bash
# 1. Fix any .info issues automatically
cd <package-name> && sbofixinfo

# 2. Download sources and verify checksums
# NOTE: when updating to a new version, sbodl will download the source but fail
# because the .info file still has the old (or placeholder) MD5SUM. In that case:
#   a) compute the checksum manually: md5sum <source-file>
#   b) update MD5SUM in the .info file
#   c) run sbodl again — it should now report "md5sum matches OK"
cd <package-name> && sbodl

# 3. Lint the script and metadata
cd <package-name> && sbolint

# 4. Build the package
cd <package-name> && sudo bash <package-name>.SlackBuild

# 5. Lint the built package
cd <package-name> && sbopkglint

# 6. Add an entry for the package in the repo-level nvchecker.toml

# 7. Remove symlinks created by sbodl before staging
# sbodl creates symlinks in the package directory pointing to downloaded sources.
# These must never be committed to git.
find . -type l -delete

# 8. Commit (pre-commit hook runs sbolint automatically)
git add <package-name>/ .extras/nvchecker.toml
git commit -m'<package-name>: add version X.Y.Z'
```

---

## SBo Submission Guidelines

Before submitting or updating a package on SlackBuilds.org:

1. **Pass all lint checks** — `sbolint` and `sbopkglint` must report no errors
2. **Test the build** on a clean Slackware installation (or VM snapshot)
3. **Verify checksums** via `sbodl` before committing
4. **Check `README`** includes all non-SBo dependencies and any special build notes
5. **Follow the SBo submission guidelines**: https://slackbuilds.org/guidelines/
6. **Bump `VERSION`** in both `.SlackBuild` and `.info` when updating
7. **Run `sbofixinfo`** after every version bump to catch stale checksums/URLs

---

## Commit Conventions

- One commit per package add/update
- Commit message format: `<package-name>: add version X.Y.Z` or `<package-name>: update to X.Y.Z`
- For fixes: `<package-name>: fix <short description>`

---

## Maintainer

danix
