Skip to content

developers.md

Latest commit

 

History

History
339 lines (257 loc) · 7.72 KB

developers.md

File metadata and controls

339 lines (257 loc) · 7.72 KB
Raw

Installer Development Guide

Information for VT Code maintainers and contributors.

Overview

VT Code provides native installers for three platforms:

  • Shell script (macOS, Linux) - scripts/install.sh
  • PowerShell script (Windows) - scripts/install.ps1
  • Homebrew formula - homebrew/vtcode.rb

Platform Detection

Shell Script

  • Uses uname -s for OS (Darwin, Linux, etc.)
  • Uses uname -m for arch (x86_64, arm64, aarch64, armv7l)
  • Maps to release binary: ARCH-PLATFORM (e.g., x86_64-apple-darwin)

PowerShell Script

  • Uses [Environment]::Is64BitProcess for 64-bit detection
  • Uses WMI Get-WmiObject Win32_Processor for ARM64 detection
  • Maps to: x86_64-pc-windows-msvc

Release Binaries

Required for installation. Must be generated for all platforms:

vtcode-v{VERSION}-{PLATFORM}.tar.gz  (macOS, Linux, etc.)
vtcode-v{VERSION}-{PLATFORM}.zip     (Windows)

Supported Platforms

  • aarch64-apple-darwin (macOS ARM64/M1/M2)
  • x86_64-apple-darwin (macOS Intel)
  • aarch64-unknown-linux-gnu (Linux ARM64)
  • x86_64-unknown-linux-gnu (Linux x86_64)
  • armv7-unknown-linux-gnueabihf (Linux ARMv7)
  • x86_64-pc-windows-msvc (Windows)

GitHub Releases Setup

Installers expect binaries at:

https://github.com/vinhnx/vtcode/releases/download/v{VERSION}/{BINARY}

GitHub Actions Workflow

Example CI/CD for cross-platform builds:

name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    strategy:
      matrix:
        include:
          - os: macos-latest
            target: x86_64-apple-darwin
          - os: macos-latest
            target: aarch64-apple-darwin
          - os: ubuntu-latest
            target: x86_64-unknown-linux-gnu
          - os: ubuntu-latest
            target: aarch64-unknown-linux-gnu
          - os: windows-latest
            target: x86_64-pc-windows-msvc
    
    runs-on: ${{ matrix.os }}
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Build
        run: cargo build --release --target ${{ matrix.target }}
      
      - name: Package
        run: |
          if [ "$RUNNER_OS" = "Windows" ]; then
            7z a vtcode-v${{ github.ref_name }}-${{ matrix.target }}.zip \
              target/${{ matrix.target }}/release/vtcode.exe
          else
            tar -czf vtcode-v${{ github.ref_name }}-${{ matrix.target }}.tar.gz \
              -C target/${{ matrix.target }}/release vtcode
          fi
      
      - name: Upload
        uses: softprops/action-gh-release@v1
        with:
          files: vtcode-v*

Testing Installers

Shell Script

On macOS

bash scripts/install.sh
# Verify
vtcode --version

On Linux (local)

bash scripts/install.sh
vtcode --version

In Docker

# Test on Linux
docker run -it --rm ubuntu:latest bash -c \
  'apt-get update && apt-get install -y curl && \
   bash <(curl -fsSL file:///path/to/install.sh)'

PowerShell Script

On Windows 10/11

.\scripts\install.ps1
vtcode --version

Via PowerShell Core (cross-platform)

pwsh -File scripts/install.ps1
vtcode --version

Homebrew Formula

# Test locally
brew install --verbose --formula ./homebrew/vtcode.rb
vtcode --version

# Uninstall
brew uninstall vtcode

Updating for New Releases

1. Create GitHub Release

  1. Create release on GitHub with tag v{VERSION}
  2. Upload binary artifacts for all platforms
  3. Note the SHA256 hashes

2. Update Homebrew Formula

Edit homebrew/vtcode.rb:

class Vtcode < Formula
  version "X.Y.Z"
  
  on_macos do
    if Hardware::CPU.arm?
      url "https://github.com/vinhnx/vtcode/releases/download/v#{version}/vtcode-v#{version}-aarch64-apple-darwin.tar.gz"
      sha256 "HASH_HERE"
    else
      url "https://github.com/vinhnx/vtcode/releases/download/v#{version}/vtcode-v#{version}-x86_64-apple-darwin.tar.gz"
      sha256 "HASH_HERE"
    end
  end
  
  on_linux do
    if Hardware::CPU.arm? && Hardware::CPU.is_64_bit?
      url "https://github.com/vinhnx/vtcode/releases/download/v#{version}/vtcode-v#{version}-aarch64-unknown-linux-gnu.tar.gz"
      sha256 "HASH_HERE"
    else
      url "https://github.com/vinhnx/vtcode/releases/download/v#{version}/vtcode-v#{version}-x86_64-unknown-linux-gnu.tar.gz"
      sha256 "HASH_HERE"
    end
  end
end

Get SHA256:

shasum -a 256 vtcode-v*.tar.gz
shasum -a 256 vtcode-v*.zip

3. Update Homebrew Tap (if applicable)

If using a personal tap (github.com/vinhnx/homebrew-vtcode):

cd ~/homebrew-vtcode
cp ../vtcode/homebrew/vtcode.rb Formula/
git add Formula/vtcode.rb
git commit -m "Update VT Code to v{VERSION}"
git push

4. Verify Installation

Test on each platform:

# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/vinhnx/vtcode/main/scripts/install.sh | bash
vtcode --version

# Windows
irm https://raw.githubusercontent.com/vinhnx/vtcode/main/scripts/install.ps1 | iex
vtcode --version

# Homebrew
brew install vtcode
vtcode --version

Installer Scripts Structure

Shell Script (scripts/install.sh)

Key functions:

  • detect_platform() - Determine OS and architecture
  • check_existing() - Check if already installed
  • get_latest_version() - Query GitHub API
  • download_binary() - Download and extract
  • determine_install_path() - Find best installation location
  • install_binary() - Copy binary and make executable
  • verify_installation() - Run vtcode --version
  • print_next_steps() - Show post-install guidance

Error handling: set -e (exit on error)

PowerShell Script (scripts/install.ps1)

Key functions:

  • Get-PlatformInfo - Detect architecture
  • Test-ExistingInstallation - Check if already installed
  • Get-LatestVersion - Query GitHub API
  • Get-Binary - Download binary
  • Expand-Binary - Extract binary
  • Get-InstallDirectory - Find best location
  • Install-Binary - Copy and verify
  • Add-ToPATH - Configure PATH
  • Test-Installation - Verify installation
  • Cleanup-TempFiles - Remove temp files

Error handling: $ErrorActionPreference = "Stop"

Troubleshooting Installer Issues

Download failures

Check if GitHub API is accessible:

curl https://api.github.com/repos/vinhnx/vtcode/releases/latest

Platform detection issues

Test detection logic:

# Shell
uname -s
uname -m

# PowerShell
[Environment]::Is64BitProcess
Get-WmiObject Win32_Processor | Select Architecture

Path configuration

Verify PATH after installation:

# Shell
echo $PATH

# PowerShell
$env:PATH

Documentation

User-facing docs:

  • docs/installation/README.md - Main installation guide
  • docs/installation/QUICK_REFERENCE.md - Quick commands
  • docs/installation/NATIVE_INSTALLERS.md - Technical details

This file:

  • docs/installation/DEVELOPERS.md - Maintainer guide

Common Issues

Binary not found in release

Ensure binaries are uploaded to GitHub Releases for all platforms. Check:

curl https://api.github.com/repos/vinhnx/vtcode/releases/latest | jq '.assets'

SHA256 mismatch

Regenerate SHA256:

shasum -a 256 vtcode-v*.tar.gz

Update formula with new hashes.

Installer script permissions

Make sure installers are executable:

chmod +x scripts/install.sh scripts/install.ps1

PowerShell execution policy

Users might need to set execution policy:

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process

The script handles this in comments.

Future Improvements

  1. Auto-generated SHA256 - Update formula automatically on release
  2. Signature verification - Sign binaries and verify in installers
  3. Rollback support - Install/downgrade specific versions
  4. Delta updates - Only download changed binary segments
  5. Cached downloads - Distribute via CDN or mirrors