ppbuild 1.0.1

A declarative, language-agnostic build system and utility manager

pp

A declarative, language-agnostic build system and utility manager.

pp provides a unified interface for building, testing, and running applications across different programming languages and environments. By defining configurations in a declarative pp.yaml file, you eliminate the need to remember language-specific toolchains and command variations. The system works equally well for managing complex build processes, running simple utility scripts, and orchestrating development workflows.

Whether you're working on a Python web application, a Rust CLI tool, or a Node.js frontend, pp abstracts away the underlying toolchain complexity while providing powerful parameterization and environment management capabilities.

Install

Quick Install

pip install ppbuild

macOS Users (externally-managed-environment error)

If you get an "externally-managed-environment" error on macOS, use one of these methods:

Option 1: Using pipx (Recommended)

# Install pipx if you don't have it
brew install pipx

# Install pp using pipx
pipx install ppbuild

Option 2: Using virtual environment

# Create and activate virtual environment
python3 -m venv ~/.pp-env
source ~/.pp-env/bin/activate

# Install pp
pip install ppbuild

# Add to your shell profile (.zshrc, .bash_profile, etc.)
echo 'alias pp="~/.pp-env/bin/pp"' >> ~/.zshrc
source ~/.zshrc

Verify Installation

pp --help

Development Installation

1. Clone the repository

git clone https://github.com/JoshCap20/pp.git
cd pp

2. Install in development mode

pip install -e .

3. Install development dependencies

pip install pytest pytest-cov black isort flake8 mypy

4. Run tests

pytest

The setup.py file creates a console script entry point, so after installation you can run pp from anywhere in your terminal.

Configuration

Create a pp.yaml configuration file that defines the commands for your applications. The beauty is that you can have:

• A global config at ~/.pp/pp.yaml for system-wide tools
• Project-specific configs that override the global one
• Environment-specific settings via .env files

See TEMPLATE.md for examples of creating your definition file.

Usage

pp <application name> <action> [command]

Examples:

pp myapp build       # Build your application
pp myapp test        # Run tests
pp myapp run dev     # Start development server
pp backend deploy    # Deploy backend services

Advanced Examples with Parameters:

pp ollama run --model deepseek-r1 --temperature 0.8    # Run AI model with specific settings
pp web_server run --port 3000 --debug                  # Start server on custom port with debug
pp database backup --output prod-backup.sql --compress # Create compressed database backup
pp docker scale --service web --replicas 3             # Scale web service to 3 instances

The configuration is overridden by the current directory, so you can drop a pp.yaml in any project and immediately have access to all your build, test, run, lint, docker, and deployment commands through the same simple interface.

Features

• Simple Commands: Define basic commands that just work (pp myapp build)
• Parameterized Commands: Add typed parameters with validation, defaults, and help text
• Environment Management: Automatic virtual environment activation (for python only) and environment variable injection
• Directory Context: Commands run in the right directory with the right environment
• Type Safety: Parameters are validated (strings, integers, floats, booleans) with constraints
• Flexible Configuration: Global configs, project-specific overrides, and environment-specific settings

How it Works

1. pp looks for a pp.yaml in your current directory, then falls back to ~/.pp/pp.yaml
2. It loads your application definitions and creates CLI subcommands automatically
3. When you run a command, it executes the underlying tool (npm, cargo, docker, etc.) with the right arguments
4. Parameters are validated and interpolated into your commands with proper escaping
5. You get consistent logging and error handling across all your projects

This means you can finally stop context-switching between different build tools and just focus on building cool stuff.

How I use it

I define global tools for common CLI operations in ~/.pp/pp.yaml and then define project-specific tools in pp.yaml for each project. This way, I can have a single pp command that works for all my projects.

Todo

• Download github repos and setup commands automatically
• Chain existing commands
• Easy MCP setup integration
• pp utility commands (--init, etc)