porters

Core Functionality

• 🚀 Zero-Config Project Init - Automatically detects existing C/C++ projects
• ⚡ Direct File Execution - porters execute file.c compiles and runs instantly with automatic dependency resolution
• 📦 Unified Dependency Management - Git (SSH/HTTPS), path, global/local support, and registry
• 🔨 14 Build System Support - Auto-detect and seamlessly integrate with CMake, XMake, Meson, Make, Ninja, Autotools, SCons, Bazel, Buck2, Premake, QMake, Conan, vcpkg, or custom builds
• 🎯 Smart Project Scaffolding - Interactive project creation with license selection
• 🤖 Smart Auto-Configuration - Everything works automatically with optional manual overrides
• 🔄 Automatic Dependency Resolution - Platform-aware with constraint checking
• 📊 Dependency Graph Visualization - Understand your project dependencies
• 🔒 Lockfile Support - Reproducible builds with porters.lock
• 📤 GitHub Publishing - Automated package releases with artifacts
• 📚 Package Registry - Search and install packages from the Porters registry

Advanced Features

• 🔌 Extension System - Create and publish custom extensions to crates.io
• 🌍 Global Package Installation - Centralized dependency management in ~/.porters/
• 💾 Global Dependency Cache - Shared cache across all projects in ~/.porters/cache/
• 📂 Isolated Virtual Environments - Project-specific dependencies in ports/ folder
• 🔄 Smart Sync - porters sync with --dev and --optional flags
• 🛠️ Compiler Detection - Auto-detect GCC, Clang, MSVC, LLVM, MinGW, Emscripten
• 📝 Build Scripts - Pre/post build hooks for custom workflows
• 🎛️ Enhanced Configuration - Build flags, include paths, linking options
• 🆙 Self-Updating - Built-in update mechanism via GitHub releases
• ✅ Tool Version Requirements - Specify minimum versions for compilers and build tools (like Python's requirements.txt)
• 🔐 Hash Verification - SHA-256 checksums for all dependencies
• 🔗 Transitive Dependencies - Automatic resolution of dependencies-of-dependencies
• 🎨 Custom Commands - Define project-specific CLI commands in config
• 📜 Named Scripts - Quick shortcuts for common tasks
• 🌐 Remote Registry Sync - Automatically fetch package index from GitHub
• ✈️ Offline Mode - Work without internet using cached dependencies

Extension Ecosystem

• 📦 Auto-Install Extensions - Automatically install extensions from porters.toml
• 🌐 crates.io Marketplace - Publish and discover extensions on crates.io
• 🔧 6 Lifecycle Hooks - pre_build, post_build, pre_install, post_install, pre_sync, post_sync
• 🎯 User-Made Extensions - Anyone can create and publish Porters extensions
• 💡 Template Generator - porters extension create scaffolds extension projects

Production-Ready Features

• 🌍 Cross-Platform - Windows, macOS, Linux support
• 🔧 Platform-Specific Dependencies - Conditional dependency resolution
• 📚 Library & Application Projects - Proper configuration for both types
• ⚡ Parallel Operations - Async dependency downloads
• 🎨 Beautiful CLI - Colored output with emoji indicators
• 🔍 Build Tool Detection - Automatic checking and installation guidance
• ⚠️ Enhanced Error Handling - Helpful messages with GitHub issue links
• 🚨 Version Validation - Pre-build checks for tool version requirements
• 📦 Registry System - Search, discover, and install curated C/C++ packages
• 💻 Global Configuration - Centralized settings in ~/.porters/config.toml

Before installing Porters, ensure you have the following tools installed:

Core Requirements

• Rust & Cargo - Required for Porters itself (installation and core functionality)
• Git - Required for dependency management and cloning repositories

Build System Support (Install as needed)

Porters auto-detects and supports 14+ build systems. Install the ones you plan to use:

Modern Build Systems

• CMake - Cross-platform build generator
• XMake - Lua-based modern build system
• Meson - Fast, user-friendly build system
• Bazel - Google's scalable build system
• Buck2 - Meta's fast build system

Traditional Build Systems

• Make - Makefile-based builds
• Ninja - Fast, lightweight build system
• Autotools - configure/make (GNU Build System)
• SCons - Python-based build tool

Meta Build Systems

• Premake - Project file generator (Visual Studio, Makefiles, Xcode)
• QMake - Qt's build system

Package Managers with Build Integration

• Conan - C/C++ package manager with CMake integration
• vcpkg - Microsoft's C++ library manager

Compilers

• GCC/G++ - GNU Compiler Collection
• Clang/Clang++ - LLVM compiler
• MSVC - Microsoft Visual C++ (Windows)
• MinGW - Minimalist GNU for Windows

Note: You don't need to install all build systems - Porters will auto-detect and use what's available for your projects.

[project]
name = "my-project"
version = "1.0.0"
description = "My awesome C++ project"
license = "Apache-2.0"
authors = ["Your Name <you@example.com>"]
repository = "https://github.com/username/my-project"
project-type = "application"  # or "library"
entry_point = "src/main"
platforms = ["windows", "macos", "linux"]
keywords = ["application", "c", "cpp"]
readme = "README.md"

# Tool version requirements (like Python's requirements.txt)
[requires]
cpp = ">=17"           # C++ standard version
cmake = ">=3.20"       # CMake version
gcc = ">=9.0"          # GCC version
clang = ">=12.0"       # Clang version (alternative to gcc)
ninja = ">=1.10"       # Ninja build tool version
make = ">=4.0"         # Make version
meson = ">=0.60"       # Meson version
bazel = ">=5.0"        # Bazel version
conan = ">=1.50"       # Conan version
vcpkg = "*"            # Any version of vcpkg

# Extensions to auto-install from crates.io
extensions = [
    "porters-format",    # Code formatter extension
    "porters-lint",      # Linting extension
    "porters-doc"        # Documentation generator
]

[dependencies]
fmt = { git = "https://github.com/fmtlib/fmt", tag = "10.1.1" }
spdlog = { git = "https://github.com/gabime/spdlog", branch = "v1.x" }
mylib = { path = "../mylib" }

[dev-dependencies]
catch2 = { git = "https://github.com/catchorg/Catch2" }
benchmark = { git = "https://github.com/google/benchmark" }

[optional-dependencies]
zlib = { git = "https://github.com/madler/zlib" }

[build]
system = "cmake"
options = ["-DBUILD_SHARED_LIBS=ON"]

[build.env]
CC = "clang"
CXX = "clang++"

# Build lifecycle scripts
[build.scripts]
pre-build = "echo Building..."
post-build = "strip build/myapp"
pre-install = "echo Installing..."
post-install = "echo Done!"

# Custom CLI commands
[[commands]]
name = "format"
description = "Format source code"
script = "clang-format -i src/**/*.cpp"

[[commands]]
name = "docs"
description = "Generate documentation"
script = "doxygen Doxyfile"
[commands.env]
DOXYGEN_OUTPUT = "docs/html"

# Named script shortcuts
[scripts]
test-all = "cargo build && cargo test"
deploy = "./deploy.sh production"

# Direct file execution configuration (OPTIONAL - works automatically)
[run]
# Extra include directories (beyond automatic dependency includes)
include-dirs = ["./include", "./extra/include"]

# Compiler flags (only if you want warnings, optimizations, etc.)
compiler-flags = ["-Wall", "-O2", "-std=c17"]

# Linker flags (only if you need extra libraries)
linker-flags = ["-lm", "-lpthread"]

# Override compiler (only if you need a specific one)
c-compiler = "clang"    # Default: auto-detect
cpp-compiler = "clang++"  # Default: auto-detect

# extension.toml
name = "porters-format"
version = "0.1.0"
description = "Code formatting extension"

[hooks]
post-build = "hooks/format.sh"

[[commands]]
name = "format"
description = "Format code"
script = "scripts/format.sh"

Porters natively supports and executes the following build systems with auto-detection:

Traditional Build Systems

• Make - Makefile-based builds
• Ninja - Fast, lightweight build system
• Autotools - configure/make (GNU Build System)
• Meson - Fast, user-friendly build system
• SCons - Python-based build tool
• Jam - Boost.Build system

CMake Ecosystem

• CMake - Cross-platform build generator
• Conan - C/C++ package manager with CMake integration
• vcpkg - Microsoft's C++ library manager
• Hunter - CMake-based package manager

Modern Build Systems

• XMake - Lua-based modern build system
• Bazel - Google's scalable build system
• Buck2 - Meta's fast build system
• Premake - Project file generator (Visual Studio, Makefiles, Xcode)
• QMake - Qt's build system
• Gradle C++ - Gradle build system for C++

Custom Build

• Custom Scripts - Define your own build commands in porters.toml

Auto-Detection Priority

1. Package managers (Conan, vcpkg, Hunter)
2. Modern systems (Bazel, Buck2, CMake, XMake, Meson, Gradle C++)
3. Meta build (Premake, QMake)
4. Traditional (Ninja, Autotools, SCons, Jam, Make)
5. Explicit configuration via build.system in porters.toml