Installation

This guide will help you install Porters on your system.

Prerequisites

Before installing Porters, ensure you have the following:

Required

Rust Toolchain (for building from source or installing via Cargo)
- Install from rustup.rs
- Minimum version: Rust 1.70+

C/C++ Compiler (At least one required)

Porters will check for these automatically on first run.

Windows:
- MSVC (Visual Studio Build Tools)
- MinGW-w64
- Clang/LLVM
macOS:
- Xcode Command Line Tools: xcode-select --install
- Clang (included with Xcode)
Linux:
- GCC: sudo apt install gcc g++ (Debian/Ubuntu)
- Clang: sudo apt install clang (Debian/Ubuntu)

Build Tools (Optional but recommended)

At least one build system is recommended for project management:

CMake (Recommended)
- Download from cmake.org
- Minimum version: 3.15+
- Install:
  - Windows: choco install cmake
  - Linux: sudo apt install cmake
  - macOS: brew install cmake
XMake
- Install from xmake.io
- Cross-platform build utility
Meson
- Install via pip: pip install meson ninja
- Fast and user-friendly build system
Make
- Usually pre-installed on Linux/macOS
- Windows: Install via MinGW or Cygwin

Note: Build tools are only required for project-based workflows (porters build, porters create). The porters execute command works without any build system!

Installing Porters

Via Cargo (Recommended)

The easiest way to install Porters is through Cargo:

cargo install porters

This will download, compile, and install the latest version of Porters.

First Run System Check

After installation, when you run Porters for the first time, it will automatically:

Check for C/C++ compilers (gcc, g++, clang, MSVC, MinGW)
Check for build systems (CMake, Make, XMake, Meson, Ninja)
Display what's found with version numbers
Show installation instructions for missing tools
Save detected tools to ~/.porters/config.toml
Block execution if no C/C++ compiler is found

Example First Run:

$ porters --version

╭──────────────────────────────────────────────────╮
│  System Requirements Check                       │
╰──────────────────────────────────────────────────╯

Compilers
─────────
✅ g++ (version 11.4.0)
✅ gcc (version 11.4.0)
❌ clang++ (not found)

Build Systems
─────────────
✅ cmake (version 3.22.1)
✅ make (version 4.3)
❌ xmake (not found)

Status: ✅ System ready!

Installation Instructions:
──────────────────────────

To install missing tools on Linux:
  sudo apt-get install clang xmake

Porters version 0.1.0

Manual System Check:

You can re-run the system check anytime:

porters --check-system

This is useful after installing new compilers or build tools to update the global configuration.

Automatic PATH Setup

Porters can automatically add the Cargo bin directory to your system PATH.

Using the built-in command:

# Automatically add ~/.cargo/bin to PATH
porters add-to-path

This command:

Windows: Modifies User PATH via registry (requires admin privileges)
Linux/macOS: Appends to your shell profile (~/.bashrc, ~/.zshrc, etc.)
Detects your shell automatically
Creates backup before modifying

To remove from PATH:

porters remove-from-path

Manual PATH Setup:

If you prefer to do it manually:

Windows PowerShell (Run as Administrator):

[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\.cargo\bin",
  "User"
)

Linux/macOS (add to ~/.bashrc or ~/.zshrc):

export PATH="$HOME/.cargo/bin:$PATH"

Then restart your terminal or run:

source ~/.bashrc  # or source ~/.zshrc

Quick Setup (Current Session Only):

# Windows PowerShell
$env:Path += ";$env:USERPROFILE\.cargo\bin"

# Linux/macOS
export PATH="$HOME/.cargo/bin:$PATH"

Using Installation Script (Windows)

For Windows users, we provide an automated installation script:

# Download and run the installer
cd path\to\Porters
.\install.ps1

This script will:

Check Rust installation
Install Porters via cargo
Automatically add to PATH (with your permission)
Verify the installation

From GitHub Releases

Download pre-built binaries from the GitHub Releases page:

Download the appropriate binary for your platform
Extract the archive
Move the porters binary to a directory in your PATH

For Linux/macOS:

sudo mv porters /usr/local/bin/
chmod +x /usr/local/bin/porters

For Windows: Move porters.exe to a directory in your PATH (e.g., C:\Program Files\Porters\)

Building from Source

If you want to build Porters from source (for development or custom builds):

Step 1: Clone the Repository

# Clone the repository
git clone https://github.com/muhammad-fiaz/Porters.git
cd Porters

Step 2: Build the Project

# Build in release mode for optimal performance
cargo build --release

Step 3: Install the Binary

After building, you need to install the binary to your system PATH:

Linux/macOS:

# Copy to system PATH
sudo cp target/release/porters /usr/local/bin/

# Make it executable
sudo chmod +x /usr/local/bin/porters

Windows (PowerShell as Administrator):

# Copy to a directory in PATH (e.g., Program Files)
cp target\release\porters.exe "C:\Program Files\Porters\porters.exe"

# Or add to user PATH
$portersPath = "$env:USERPROFILE\.porters\bin"
New-Item -ItemType Directory -Force -Path $portersPath
cp target\release\porters.exe "$portersPath\porters.exe"

# Add to PATH permanently
[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path", "User") + ";$portersPath",
  "User"
)