protox

README

Protox

Protox is a command-line tool for working with Protocol Buffers (protobuf) in Go projects. It provides utilities for compiling .proto files, managing generated code, and streamlining protobuf workflows for Go developers.

Features

• Unified Tool Management: Automatically installs and manages, generators, and other tools
• Multiple Installation Sources: Support for GitHub releases and Go modules
• Version Management: Install and manage multiple versions of the same tool
• Cross-Platform Support: Works on Linux, macOS, and Windows
• Built-in Tools: Pre-configured support for protoc-gen-go
• Compile .proto files to Go code
• Manage protobuf project structure
• Example projects included (album, todo, tool-management)

Getting Started

Prerequisites

Protox automatically manages generator tools for you. No manual installation required!

• Go 1.25+ (for building from source)
• Network access (for downloading tools and dependencies)

Installation

Download the latest release for your platform from the Releases page, or build from source:

go install gitlab.com/osechet/protox@latest

Usage

Run the executable from your terminal:

./protox [command] [flags]

Common Commands

• update — Download and update project dependencies and tools
• build — Compile protobuf files in your project using the information in protox.yaml
• clean — Remove downloaded dependencies and tools
• compile — Compile .proto files directly
• help — Show help for commands

Configuration

Protox supports flexible configuration through multiple sources:

# Using command-line flags
protox --tools-dir /custom/tools --deps-dir /custom/deps update

# Using environment variables
export PROTOX_TOOLS_DIR=/custom/tools
export PROTOX_DEPENDENCIES_DIR=/custom/deps
protox update

# Using configuration file (.protox.yaml)
tools_dir: /custom/tools
dependencies_dir: /custom/deps

Available configuration options:

• --tools-dir: Directory for downloaded tools (default: ~/.protox/tools)
• --deps-dir: Directory for dependencies (default: ~/.protox/deps)
• --config: Path to configuration file (default: .protox.yaml)

Example:

Create a protox.yaml file at the root of your project:

version: 1

modules:
  - path: .

depends:
  - name: googleapis
    repository: https://github.com/googleapis/googleapis

generators:
  - name: go
    out: gen
    opt:
      - paths=source_relative

The modules path tells protox where your protobuf files are. The generators indicates what to generate. Protox will automatically install the required generators for you - no manual installation needed!

Update dependencies and build the project:

# Download tools and dependencies
./protox update

# Compile protobuf files
./protox build

protox will automatically download the required dependencies, then compile the .proto files it finds, following the instructions in protox.yaml.

See the examples/ directory for sample projects and usage patterns.

Tool Management

Protox features a comprehensive tool management system that automatically handles the installation and management of protobuf-related tools:

Supported Tools

• protoc-gen-go: Go Protocol Buffer Generator (via go install)
• protoc-gen-go-grpc: Go gRPC Protocol Buffer Generator (via go install)

Tool Directory Structure

Tools are organized in version-specific directories:

~/.protox/tools/
└── protoc-gen-go/
    └── v1.31.0/bin/protoc-gen-go

Multiple Versions

You can have multiple versions of the same tool installed simultaneously. Protox will use the version specified in your protox.yaml file, or the latest available version if not specified.

Custom Tools

The tool management system is extensible. See the tool management documentation for details on adding custom tools.

Testing

Protox includes comprehensive unit and integration tests:

# Run unit tests only (fast)
task test

# Run integration tests (requires network access)
task test-integration

# Run all tests
task test-all

For detailed information about integration tests, see INTEGRATION_TESTS.md.

Contributing

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a new branch for your feature or bugfix
3. Make your changes and add tests if applicable
4. Open a pull request with a clear description of your changes

Please follow the existing code style and add documentation where appropriate.

License

This project is licensed under the MIT License. See the LICENSE file for details.