VoTe — Void Templater

VoTe logo

VoTe is a bash-based CLI tool for managing xbps-src package templates in Void Linux.
It streamlines the workflow of building, testing, and submitting packages to Void Linux repositories.

Version: 0.92 beta source: https://codeberg.org/oSoWoSo/vote
xbps repo: https://repo.osowoso.org

VoTe UI screenshot
VoTe UI

Disclaimer

This is an independent project and is not affiliated with or endorsed by the Void Linux project.

It is developed specifically for use on Void Linux, but it is not an official tool.
Please do not report issues related to this project to Void Linux maintainers.

All support and development is handled within this repository.

Features

• Template Management — Create, edit, lint, and build package templates
• Auto-create from URL — Generate a template from any GitHub/GitLab/Codeberg/... URL
• Auto-bump — Automatically update template versions
• AI Wizard — AI-assisted build failure analysis and fix loop (api/cli/openhands)
• gum TUI — Modern terminal UI via gum panel (requires custom gum with panel subcommand)
• Interactive TUI — Full terminal-based user interface with panel layout
• Panel Auto-Navigation — Smart panel selection based on workflow state
• Cross-build — Build for any architecture from the build panel; flags persist via the flag panel
• Build Status Badges — Visual 🟢/🔴 indicators for all architectures in menu header
• Status Tracking — Persistent workflow state across sessions (bump→sum→lint→build→install→push)
• Symlink Management — Auto-sync sub-package symlinks in srcpkgs/
• Dependency Finder — Find packages/files from build log, add to template interactively
• Template Variable Cleaner — Remove empty/commented template variables
• Git Integration — Push changes and create PRs to void-packages
• Repology & Changelog — Check project status on repology.org (inline API data or browser)
• Lazygit Integration — Launch lazygit from the menu (if installed)
• Per-Panel Help (Ctrl+H) — Context-sensitive help overlay for each panel
• Extract Distfiles — Extract sources from the menu
• Custom Build Styles — Support for external build style directories
• Error Pattern Matching — Diagnose build failures with a pattern database
• Companion Tools — vut (template utility), xfzf (fzf helper), xut (xbps utility)

Panel Reference

The gum TUI has 6 panels, each with a set of actions:

Panel ... (Misc)

Bootstrap Options TODO

• Bootstrap — Run xbps-src bootstrap-update
• Options — Interactive VoTe configuration editor
• TODO — View/add TODO items (dev mode only, when TODO.md exists)
• Quit — Press ESC to exit

Panel choose (Template Chooser)

Choose Manual Branch Lazygit Homepage Changelog Repology

• Choose — Select a template from available srcpkgs
• Manual — Open xbps-src Manual.md
• Branch — Switch git branch
• Lazygit — Launch lazygit (if installed)
• Homepage — Open project homepage in browser
• Changelog — Open project changelog (if defined in template)
• Repology — Check package on repology.org (inline API data if curl+jq available)

Panel prepare

Bump Sum Lint Xtract Edit Symlink Wizard Find Tidy Clean

• Bump — Auto-bump template version
• Sum — Update distfile checksums
• Lint — Lint template with xbps-src
• Xtract — Extract distfiles
• Edit — Open template in $EDITOR
• Symlink — Create/update sub-package symlinks in srcpkgs/
• Wizard — AI-assisted build failure analysis (if configured)
• Find — Search for packages/files from build log, add to template deps
• Tidy — Remove empty/commented template variables
• Clean — Clean build directory

Panel flag

-s -Q -C -K cross

Selects build flags only — no build is triggered here.

• -s — Strict mode (turns warnings into errors)
• -Q — Build with tests
• -C — Keep builddir and destdir populated
• -K — Build with longer tests
• cross — Force -A <target> (native masterdir, for nocross= packages)

Selected flags persist between builds until changed.

Panel build

All architectures including host (x86_64, x86_64-musl, i686, i686-musl, aarch64, aarch64-musl, armv7l, armv7l-musl, armv6l, armv6l-musl).

Select a target arch to trigger the build using the flags from the flag panel.

• Selecting the host arch = native build
• x86_64-musl always uses -A x86_64-musl (musl masterdir)
• cross flag forces -A <target> for any arch

Panel pub (Publish)

Install Log Commit Revbump New-PR Push OCO

• Install — Install built package locally using xi
• Log — View build log in your pager/highlighter
• Commit — Commit template changes with proper message (via xbump)
• Revbump — Increment revision= and commit (rebuild for dep change)
• New-PR — Create a pull request on void-linux/void-packages
• Push — Push the current branch to your fork remote
• OCO — Copy template to OCO repository (shown when OCODIR is set)

Requirements

• Bash 4+ — Required for associative arrays and modern features
• Void Linux — Designed for xbps-src workflow
• XBPS_DISTDIR — Path to your void-packages fork

Optional Dependencies

Note on gum: The gum UI backend requires a custom build of gum that includes the panel subcommand.
Standard releases of gum do not include panel.
Use the fork at codeberg.org/oSoWoSo/gum,
or track the upstream PR charmbracelet/gum#1063.
Included in Void Community Repository: https://repo.osowos.org

Other Tools

• xbps-src — From void-packages
• git — For push/PR operations
• jq — For JSON processing (auto-create, AI wizard)
• curl — For fetching release info and AI calls
• ssh — For remote operations

Installation

From repository

REPO
(templates repository: oco)

From source

1. Clone the Repository

git clone https://codeberg.org/oSoWoSo/vote.git ~/vote
cd ~/vote

2. Set Up Configuration

mkdir -p ~/.config/vote
# Create vote.conf — see Configuration section below

3. Configure XBPS_DISTDIR

export XBPS_DISTDIR="$HOME/void" # or your preferred path
export PATH="$HOME/vote:$PATH"

4. (Optional) Install System-wide

sudo make install # VoTe only
sudo make install-all # VoTe + vut + xut
sudo make install-vut # vut only
sudo make install-xut # xut only

Companion tools:

• vut — Template utility helper (template info, formatting)
• xfzf — Fzf helper for template selection
• xut — XBPS utility tool (GPL-2.0)

The assets/vote.kdl is an PLANNED optional zellij layout
Copy it to your zellij config if you want the split-pane build view.

Usage

Quick Start

# Launch interactive TUI
./vote
# Auto-create template from a git URL
./vote create https://github.com/owner/repo
# Build a package
./vote build <template>
# Lint a template
./vote lint <template>
# Update checksum
./vote sum <template>
# Auto-bump version
./vote autobump <template>

Command Reference

Global Options

--ui, -U BACKEND Force UI backend: gum
--debug, -d Enable debug mode
--help, -h Show help
--version, -v Show version

Build Flags

vote build <template> [OPTIONS]
 -s Strict mode (warnings→errors)
 -Q Run tests
 -K Run long tests
 -C Keep build dir
 -j N Use N parallel jobs
 -o opt Pass build option
 -r repo Use alternative repository
 -a arch Target architecture (cross-build)
 -A arch Use native masterdir for arch (nocross= packages)

In the TUI, flags are set via the flag panel and persist until changed. Build is triggered from the build panel.

Configuration

Default location: ~/.config/vote/vote.conf

# Required: your void-packages fork
XBPS_DISTDIR="$HOME/void"
# Your fork remote
MY_XBPS_REPO="git@github.com:username/void-packages.git"
# UI
UI_BACKEND="gum"
EDITOR="hx"
TERMINAL="kitty"
# Build flags are selected interactively from the BUILD panel.
# Output mode for builds
VOTE_SPINNER_MODE="zellij" # zellij | gum | none

AI Wizard

The Wizard uses an AI backend to analyze build logs and suggest fixes.
Configure in vote.conf:

VOTE_AI_MODE="api" # api | cli | openhands
VOTE_AI_URL="http://localhost:4000" # OpenAI-compatible endpoint
VOTE_AI_KEY="your-key"
VOTE_AI_MODEL="gemini/gemini-2.5-flash"
VOTE_AI_MAX_RETRIES=3 # -1 = unlimited

Three modes:

For CLI mode:

VOTE_AI_MODE="cli"
VOTE_AI_CMD="claude"

The Wizard appears in the Prepare panel and is only visible when VOTE_AI_MAX_RETRIES is set (non-empty).

File Structure

vote/
├── vote # Main executable
├── vut # Template utility helper
├── xut # xbps utility tool (GPL-2.0)
├── run.sh # Dev helper: bump version, run tests
├── assets/
│ ├── vote.svg # Logo
│ ├── vote.desktop # Desktop entry
│ ├── vote.kdl # Zellij layout
│ └── VoTe-0.75.mp4 # Demo video
├── lib/
│ ├── init.sh # Initialization
│ ├── core/ # Core libraries (colors, errors, UI stubs...)
│ ├── xbps/ # XBPS integration (build, deps, git, wizard, vm...)
├── frontends/ # TUI frontend
│ └── menu-gum.sh
├── etc/
│ ├── vote.conf # Default config template
│ └── error-patterns.json
├── lang/ # Localization (en, cs)
├── void-20250202-musl/ # VM disk, ISO, launch script
├── void-20250202-musl.conf # Quickemu VM config
├── void-musl-vm.qcow2 # VM disk image
├── TESTS.md # Unit test suite (clitest)
├── INTEGRATION-TESTS.md # Integration tests (require real void-packages)
└── TODO.md # Development notes

License

VoTe is dual-licensed depending on how it is distributed:

• GNU AGPL-3.0 — standalone distribution. See LICENSE.agpl.
• GNU GPL-2.0 — when bundled with QEMU or other GPLv2-only components. See LICENSE.gpl.

See NOTICE for full details.

Links

• Repository: https://codeberg.org/oSoWoSo/vote
• Issues: https://codeberg.org/oSoWoSo/vote/issues
• Void Linux: https://voidlinux.org
• void-packages: https://github.com/void-linux/void-packages