Ansible Development Setup Generator

This skill helps you work with the Ansible-based development environment setup system in this repository, which generates playbooks for installing development tools across multiple platforms.

Overview

The repository contains a Go-based generator that creates Ansible playbooks for setting up development environments consistently across:

• macOS (using Homebrew)
• Debian/Ubuntu (using apt with PPA support)
• Termux (Android terminal with pkg)

The generator is located in devtools/setup-dev/ansible/ and consists of:

• generate_packages.go - Main generator and entry point
• types.go - Core data structures and interfaces
• install_methods.go - Platform-specific installation method implementations
• templates.go - Ansible playbook templates
• packages_data.go - Package and tool definitions

Key Concepts

Package Types

1. PackageData: Traditional system packages installed via platform package managers (apt, brew, pkg)

   • Supports different package names per platform
   • Supports Ubuntu PPAs and Homebrew taps
   • Example: emacs, git, curl

2. PlatformSpecificTool: Development tools with platform-specific installation methods

   • Uses unified InstallMethod interface
   • Can use different installation approaches per platform
   • Example: starship (brew on macOS, cargo on Debian, pkg on Termux)

Installation Methods

The system supports multiple installation methods via the InstallMethod interface:

• PackageInstallMethod - System package managers (apt, yum, dnf)
• BrewInstallMethod - Homebrew with tap and options support
• TermuxPkgInstallMethod - Termux pkg command
• PipInstallMethod - Python pip packages
• GoInstallMethod - Go install with version checking
• CargoInstallMethod - Rust cargo with cargo-update integration
• NpmInstallMethod - Node.js npm global packages
• UvInstallMethod - Python uv tool
• ShellInstallMethod - Custom shell commands with version checking

Platform-Specific Installation Strategy

The generator follows best practices for each platform:

• Termux: Strongly prefer pkg due to Termux's unconventional setup requiring patches
• Debian/Ubuntu: Prefer alternative methods when packages are outdated; use PPAs for actively developed software
• Python packages: Prefer uv over pip (faster, better dependency resolution)
• Go packages: Use go install with automatic version checking and upgrade logic
• macOS: Use Homebrew with tap and option support

Common Tasks

Adding a New Package

To add a system package that uses platform package managers:

1. Add to the packages array in packages_data.go:

{command: "your-tool", debianPkgName: "debian-name", termuxPkgName: "termux-name", brewPkgName: "brew-name"}

2. For packages with different names per platform, specify each:

{command: "ag", debianPkgName: "silversearcher-ag", termuxPkgName: "silversearcher-ag", brewPkgName: "the_silver_searcher"}

3. For Ubuntu PPAs:

{command: "emacs", UbuntuPPA: "ppa:ubuntuhandhand1/emacs"}

4. For Homebrew taps with options:

{command: "emacs", brewPkgName: "emacs-plus", brewTap: "d12frosted/emacs-plus", brewOptions: []string{"with-native-comp", "with-dbus"}}

Adding a Platform-Specific Tool

To add a tool with different installation methods per platform:

1. For Go tools (simplest case):

GoTool("tool-name", "github.com/user/repo/cmd/tool@latest")

2. For tools with different methods per platform:

{
    command: "tool-name",
    platforms: map[string]InstallMethod{
        "darwin":      BrewInstallMethod{Name: "tool-name"},
        "termux":      TermuxPkgInstallMethod{Name: "tool-name"},
        "debian-like": UvInstallMethod{Name: "tool-name"},
    },
    Imports: nil,
}

3. For cargo packages with auto-update:

{
    command: "tool-name",
    platforms: map[string]InstallMethod{
        "all": CargoInstallMethod{Name: "crate-name"},
    },
    Imports: nil,
}

Regenerating Playbooks

After modifying the package definitions, regenerate the playbooks from the repository root:

make generate-ansible

This will:

1. Generate all .yml playbook files
2. Update the BUILD.bazel file with test targets for each playbook
3. Update README.org's manual playbooks list

Testing Playbooks

After regenerating playbooks, validate them with Bazel syntax tests:

# Test all playbooks
bazel test //devtools/setup-dev/ansible:ansible_syntax_tests

# Test a specific playbook
bazel test //devtools/setup-dev/ansible:emacs_syntax_test

Recommended workflow when adding a new package:

1. Edit packages_data.go to add the package definition
2. Run make generate-ansible from the repo root to regenerate playbooks and BUILD.bazel
3. Run bazel test //devtools/setup-dev/ansible:ansible_syntax_tests to validate syntax
4. Optionally run make from the repo root to run all tests and linting

Important Files

• devtools/setup-dev/ansible/generate_packages.go - Main generator
• devtools/setup-dev/ansible/packages_data.go - Package definitions (edit this to add tools)
• devtools/setup-dev/ansible/types.go - Type definitions
• devtools/setup-dev/ansible/install_methods.go - Installation method implementations
• devtools/setup-dev/ansible/templates.go - Ansible YAML templates
• devtools/setup-dev/ansible/README.org - Detailed documentation
• devtools/setup-dev/ansible/ensure.sh - Script to run playbooks
• devtools/setup-dev/ansible/BUILD.bazel - Generated test targets

Design Patterns

Include Guards

All generated playbooks include guards to prevent multiple inclusion:

- name: Include guard for tool playbook
  block:
    - name: Stop early if the tool playbook is already included
      meta: end_play
      when: tool_playbook_imported is defined
    - name: Ensure the tool playbook is not included
      set_fact:
        tool_playbook_imported: true

Dependency Management

Tools can declare dependencies via the Imports field:

{command: "notmuch", Imports: []Import{{Playbook: "python3-notmuch2"}}}

Dependencies are automatically imported at the beginning of playbooks.

Manual Playbooks

Some playbooks are not generated by the Go program and are maintained manually. These playbooks are typically used for:

• Setup tasks that don't fit the package installation model (e.g., setup-ssh-key.yml, setup-homebrew-env.yml).
• Complex configuration logic (e.g., setup-shell-profile.yml).
• Importing other playbooks (e.g., all.yml).

When creating a manual playbook:

1. Ensure it follows the naming convention setup-<feature>.yml or just <feature>.yml.
2. Manual playbooks are automatically detected by the generator and added to README.org.

Verification

ALWAYS run make in the devtools/setup-dev/ansible directory after making changes, including adding manual playbooks.

cd devtools/setup-dev/ansible
make

The make command:

1. Generates Artifacts: Regenerates .yml files and updates README.org (including the manual playbooks list).
2. Verifies Syntax: Runs syntax checks on all playbooks (generated and manual).
3. Tests: Runs Go tests and Bazel build targets.

Version Checking

Go and Cargo installation methods include automatic version checking:

• Go: Uses go version -m and go list -m to check for updates
• Cargo: Uses cargo-install-update for update detection
• Shell: Supports custom version checking with regex and GitHub API

When to Use This Skill

Use this skill when you need to:

• Add a new development tool to the setup system
• Modify package installation configuration
• Understand how the Ansible playbook generator works
• Add support for a new installation method
• Debug playbook generation issues
• Update package definitions or platform-specific installation strategies
• Work with the BUILD.bazel test generation
• Understand the platform-specific installation strategy

References

For more detailed information, consult:

• devtools/setup-dev/ansible/README.org - Complete documentation with design rationale
• Individual .go files for implementation details
• Generated .yml files for examples of output playbooks