fastqr 1.0.1

data/phpunit.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.5/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+         verbose="true">
+    <testsuites>
+        <testsuite name="FastQR Test Suite">
+            <directory>bindings/php/tests</directory>
+        </testsuite>
+    </testsuites>
+    <coverage>
+        <include>
+            <directory suffix=".php">bindings/php/src</directory>
+        </include>
+    </coverage>
+</phpunit>
+

data/prebuilt/README.md

@@ -0,0 +1,131 @@
+# Pre-built Binaries
+
+This directory contains pre-built binaries for FastQR on different platforms.
+
+## Supported Platforms
+
+- **macOS**
+  - arm64 (Apple Silicon M1/M2/M3)
+  - x86_64 (Intel)
+- **Linux**
+  - x86_64 (64-bit Intel/AMD)
+  - arm64 (64-bit ARM)
+
+## Directory Structure
+
+```
+prebuilt/
+├── macos-arm64/
+│   ├── lib/
+│   │   └── libfastqr.dylib
+│   ├── bin/
+│   │   └── fastqr
+│   └── include/
+│       └── fastqr.h
+├── macos-x86_64/
+│   └── ...
+├── linux-x86_64/
+│   └── ...
+└── linux-arm64/
+    └── ...
+```
+
+## Building Binaries
+
+To build binaries for your platform:
+
+```bash
+./scripts/build-binaries.sh
+```
+
+This will create a tarball in `prebuilt/fastqr-VERSION-PLATFORM.tar.gz`.
+
+## Using Pre-built Binaries
+
+### For Ruby Gem
+
+Pre-built binaries are automatically included in the gem and loaded via FFI.
+
+```bash
+gem install fastqr
+# No need to install qrencode or vips!
+```
+
+### For Node.js
+
+Pre-built binaries are automatically included in the npm package.
+
+```bash
+npm install fastqr
+# No need to install qrencode or vips!
+```
+
+### For PHP
+
+Pre-built binaries are included in the Composer package.
+
+```bash
+composer require fastqr/fastqr
+# No need to install qrencode or vips!
+```
+
+### Manual Installation
+
+Download and install pre-built binaries manually:
+
+```bash
+# Download from GitHub Releases
+wget https://github.com/tranhuucanh/fastqr/releases/download/v1.0.0/fastqr-1.0.0-macos-arm64.tar.gz
+
+# Extract
+tar xzf fastqr-1.0.0-macos-arm64.tar.gz
+
+# Install
+sudo cp -r macos-arm64/lib/* /usr/local/lib/
+sudo cp -r macos-arm64/bin/* /usr/local/bin/
+sudo cp -r macos-arm64/include/* /usr/local/include/
+
+# On Linux, update library cache
+sudo ldconfig
+```
+
+Or use the install script:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/tranhuucanh/fastqr/main/scripts/install.sh | bash
+```
+
+## Platform Detection
+
+The bindings automatically detect your platform and load the appropriate binary:
+
+- **Ruby**: `FastQR::Platform.platform`
+- **Node.js**: `require('./lib/platform').detectPlatform()`
+- **PHP**: Platform detected in `FastQR::init()`
+
+## Notes
+
+- Binaries are built with static linking of libqrencode and libvips
+- No external dependencies required at runtime
+- Binaries are built on GitHub Actions for consistency
+- All binaries are tested before release
+
+## Building for All Platforms
+
+To build binaries for all platforms, use GitHub Actions:
+
+```bash
+git tag -a v1.0.0 -m "Release 1.0.0"
+git push origin v1.0.0
+```
+
+This will trigger the `build-binaries.yml` workflow which builds for all platforms.
+
+## License
+
+The pre-built binaries include statically linked libraries:
+- libqrencode (LGPL 2.1)
+- libvips (LGPL 2.1+)
+
+As required by LGPL, users can rebuild with different versions. See BUILD.md for instructions.
+

data/scripts/README.md

@@ -0,0 +1,248 @@
+# FastQR Release Scripts
+
+This directory contains scripts for building and releasing FastQR.
+
+## Scripts
+
+### 1. `build-local.sh`
+Build fastqr locally for testing.
+
+**Usage:**
+```bash
+./scripts/build-local.sh
+```
+
+**What it does:**
+- Cleans build directory
+- Runs CMake configuration
+- Builds fastqr binary
+- Output: `build/fastqr`
+
+**Example:**
+```bash
+./scripts/build-local.sh
+./build/fastqr --version
+./build/fastqr "Hello" test.png
+```
+
+---
+
+### 2. `update-version.sh`
+Update version number across all project files.
+
+**Usage:**
+```bash
+./scripts/update-version.sh <version>
+```
+
+**What it updates:**
+- `VERSION` file
+- `CMakeLists.txt`
+- `fastqr.gemspec`
+- `bindings/ruby/lib/fastqr/version.rb`
+- `bindings/nodejs/package.json`
+- `composer.json`
+- All `*.md` files (URLs and version references)
+
+**Example:**
+```bash
+./scripts/update-version.sh 1.0.1
+```
+
+**Note:** This is automatically called by `release.sh`, you rarely need to run it manually.
+
+---
+
+### 3. `release.sh`
+Release a new version to GitHub.
+
+**Usage:**
+```bash
+./scripts/release.sh <version>           # Normal release
+./scripts/release.sh <version> --force   # Force overwrite existing tag
+```
+
+**What it does:**
+1. Checks if tag already exists
+2. Checks for uncommitted changes
+3. Updates version in all files
+4. Commits changes
+5. Creates git tag
+6. Pushes to GitHub
+7. Triggers GitHub Actions
+
+**Normal Release Example:**
+```bash
+# Make your changes
+git add .
+git commit -m "feat: add new feature"
+
+# Release new version
+./scripts/release.sh 1.0.1
+```
+
+**Force Release Example:**
+```bash
+# If you need to re-release the same version:
+# 1. Manually delete tag and release on GitHub
+# 2. Run with --force flag
+./scripts/release.sh 1.0.1 --force
+```
+
+---
+
+## Release Workflow
+
+### For New Version
+
+```bash
+# 1. Make your changes and commit
+git add .
+git commit -m "feat: your changes"
+
+# 2. Build and test locally
+./scripts/build-local.sh
+./build/fastqr --version  # Should show old version
+./build/fastqr "Test" test.png
+
+# 3. Release new version
+./scripts/release.sh 1.0.1
+```
+
+GitHub Actions will automatically:
+- Build binaries for all platforms
+- Create GitHub Release
+- Update Homebrew formula
+- Publish to package registries
+
+### For Overwriting Version
+
+```bash
+# 1. Delete tag and release on GitHub manually
+# Go to: https://github.com/tranhuucanh/fastqr/releases
+# - Delete the release
+# - Delete the tag (Settings → Tags)
+
+# 2. Force release locally
+./scripts/release.sh 1.0.0 --force
+```
+
+---
+
+## Version Management
+
+FastQR uses a single-source-of-truth approach for versioning:
+
+- **Source:** `VERSION` file
+- **Updated by:** `update-version.sh`
+- **Used in:** All build scripts and CI/CD
+
+### Version Format
+
+Semantic Versioning: `MAJOR.MINOR.PATCH`
+
+Examples:
+- `1.0.0` - Initial release
+- `1.0.1` - Bug fixes
+- `1.1.0` - New features (backward compatible)
+- `2.0.0` - Breaking changes
+
+---
+
+## Troubleshooting
+
+### "Tag already exists" error
+```bash
+./scripts/release.sh 1.0.1
+# Error: Tag v1.0.1 already exists!
+```
+
+**Solution:**
+1. If you want a new version, use a different number: `1.0.2`
+2. If you want to overwrite, delete on GitHub first, then use `--force`:
+   ```bash
+   ./scripts/release.sh 1.0.1 --force
+   ```
+
+### "Uncommitted changes" error
+```bash
+./scripts/release.sh 1.0.1
+# Error: You have uncommitted changes!
+```
+
+**Solution:**
+```bash
+git status  # Check what's changed
+git add .
+git commit -m "your message"
+./scripts/release.sh 1.0.1
+```
+
+### GitHub Actions not triggering
+- Check: https://github.com/tranhuucanh/fastqr/actions
+- Ensure tag was pushed: `git push origin v1.0.1`
+- Check workflow permissions in repo settings
+
+### Homebrew formula not updating
+- Check Actions log: https://github.com/tranhuucanh/fastqr/actions
+- Ensure `HOMEBREW_TAP_TOKEN` secret is set in repo settings
+- Check formula repo: https://github.com/tranhuucanh/homebrew-fastqr
+
+---
+
+## CI/CD Pipeline
+
+```
+Push tag v1.0.1
+    ↓
+GitHub Actions triggered
+    ↓
+┌─────────────────────────────┐
+│ 1. Build binaries           │
+│    - macOS (arm64, x86_64)  │
+│    - Linux (x86_64, arm64)  │
+└─────────────┬───────────────┘
+              ↓
+┌─────────────────────────────┐
+│ 2. Create GitHub Release    │
+│    - Upload binaries        │
+│    - Generate changelog     │
+└─────────────┬───────────────┘
+              ↓
+┌─────────────────────────────┐
+│ 3. Update Homebrew formula  │
+│    - Download source tarball│
+│    - Calculate SHA256       │
+│    - Update Formula/fastqr.rb│
+│    - Push to homebrew-fastqr│
+└─────────────────────────────┘
+```
+
+---
+
+## Files Modified by Release
+
+When you run `./scripts/release.sh 1.0.1`:
+
+```
+VERSION                                 → 1.0.1
+CMakeLists.txt                          → project(fastqr VERSION 1.0.1 ...)
+fastqr.gemspec                          → spec.version = '1.0.1'
+bindings/ruby/lib/fastqr/version.rb     → VERSION = '1.0.1'
+bindings/nodejs/package.json            → "version": "1.0.1"
+composer.json                           → "version": "1.0.1"
+README.md                               → /v1.0.1/fastqr-1.0.1-...
+INSTALL.md                              → /v1.0.1/fastqr-1.0.1-...
+docs/*.md                               → /v1.0.1/fastqr-1.0.1-...
+```
+
+All changes are committed with message: `chore: bump version to v1.0.1`
+
+---
+
+## See Also
+
+- [BUILD.md](../BUILD.md) - Building from source
+- [CONTRIBUTING.md](../CONTRIBUTING.md) - Contributing guidelines
+- [DISTRIBUTION.md](../DISTRIBUTION.md) - Distribution details
+

data/scripts/build-binaries.sh

@@ -0,0 +1,98 @@
+#!/bin/bash
+
+# FastQR - Build Pre-compiled Binaries
+# This script builds binaries for multiple platforms
+
+set -e
+
+echo "🔨 FastQR Binary Builder"
+echo "========================"
+echo ""
+
+# Get version from CMakeLists.txt
+VERSION=$(grep "project(fastqr VERSION" CMakeLists.txt | sed 's/.*VERSION \([0-9.]*\).*/\1/')
+echo "Version: $VERSION"
+
+# Detect platform
+OS="unknown"
+ARCH=$(uname -m)
+if [[ "$OSTYPE" == "darwin"* ]]; then
+    OS="macos"
+elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
+    OS="linux"
+fi
+
+echo "Platform: $OS-$ARCH"
+echo ""
+
+# Output directory
+OUTPUT_DIR="prebuilt/$OS-$ARCH"
+mkdir -p "$OUTPUT_DIR/lib"
+mkdir -p "$OUTPUT_DIR/bin"
+
+echo "🔧 Building for $OS-$ARCH..."
+
+# Clean and build
+rm -rf build
+mkdir build
+cd build
+
+# Configure with static linking
+cmake .. \
+    -DCMAKE_BUILD_TYPE=Release \
+    -DBUILD_SHARED_LIBS=ON \
+    -DCMAKE_INSTALL_PREFIX="$PWD/install" \
+    -DFASTQR_BUILD_EXAMPLES=OFF
+
+# Build
+if [[ "$OS" == "macos" ]]; then
+    make -j$(sysctl -n hw.ncpu)
+else
+    make -j$(nproc)
+fi
+
+# Install to temporary location
+make install DESTDIR="$PWD/staging"
+
+cd ..
+
+# Copy binaries
+if [[ "$OS" == "macos" ]]; then
+    cp build/staging/usr/local/lib/libfastqr.*.dylib "$OUTPUT_DIR/lib/libfastqr.dylib" 2>/dev/null || \
+    cp build/libfastqr.*.dylib "$OUTPUT_DIR/lib/libfastqr.dylib" 2>/dev/null || \
+    cp build/libfastqr.dylib "$OUTPUT_DIR/lib/libfastqr.dylib"
+
+    cp build/staging/usr/local/bin/fastqr "$OUTPUT_DIR/bin/fastqr" 2>/dev/null || \
+    cp build/fastqr "$OUTPUT_DIR/bin/fastqr"
+else
+    # Copy all .so files to lib directory
+    if [ -f build/staging/usr/local/lib/libfastqr.so ]; then
+        cp build/staging/usr/local/lib/libfastqr.so* "$OUTPUT_DIR/lib/"
+    else
+        cp build/libfastqr.so* "$OUTPUT_DIR/lib/"
+    fi
+
+    # Copy binary
+    if [ -f build/staging/usr/local/bin/fastqr ]; then
+        cp build/staging/usr/local/bin/fastqr "$OUTPUT_DIR/bin/fastqr"
+    else
+        cp build/fastqr "$OUTPUT_DIR/bin/fastqr"
+    fi
+fi
+
+# Copy headers
+cp -r include "$OUTPUT_DIR/"
+
+# Create tarball
+cd prebuilt
+tar czf "fastqr-$VERSION-$OS-$ARCH.tar.gz" "$OS-$ARCH"
+cd ..
+
+echo ""
+echo "✅ Binary built successfully!"
+echo "📦 Output: prebuilt/fastqr-$VERSION-$OS-$ARCH.tar.gz"
+echo ""
+echo "Contents:"
+ls -lh "$OUTPUT_DIR/lib/"
+ls -lh "$OUTPUT_DIR/bin/"
+

data/scripts/build-local.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+# Build FastQR locally for testing
+
+set -e
+
+echo "🔨 Building FastQR locally..."
+
+# Clean previous build
+rm -rf build/
+mkdir -p build
+
+# Build
+cd build
+cmake -DCMAKE_BUILD_TYPE=Release ..
+make -j$(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo 4)
+
+echo "✅ Build complete! Binary: build/fastqr"
+echo "Test it: ./build/fastqr 'Hello World' test.png"

data/scripts/install.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+
+# FastQR - Install pre-built binaries script
+# This script downloads and installs pre-built binaries for your platform
+
+set -e
+
+echo "📦 FastQR Binary Installer"
+echo "=========================="
+echo ""
+
+# Detect platform
+OS="unknown"
+ARCH=$(uname -m)
+if [[ "$OSTYPE" == "darwin"* ]]; then
+    OS="macos"
+elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
+    OS="linux"
+else
+    echo "❌ Unsupported OS: $OSTYPE"
+    exit 1
+fi
+
+# Normalize arch
+case "$ARCH" in
+    x86_64|amd64)
+        ARCH="x86_64"
+        ;;
+    aarch64|arm64)
+        ARCH="arm64"
+        ;;
+esac
+
+PLATFORM="$OS-$ARCH"
+echo "Platform: $PLATFORM"
+
+# Get version
+VERSION="${1:-1.0.0}"
+echo "Version: $VERSION"
+echo ""
+
+# Download URL
+TARBALL="fastqr-$VERSION-$PLATFORM.tar.gz"
+URL="https://github.com/tranhuucanh/fastqr/releases/download/v$VERSION/$TARBALL"
+
+echo "📥 Downloading $TARBALL..."
+if command -v curl &> /dev/null; then
+    curl -L -o "/tmp/$TARBALL" "$URL"
+elif command -v wget &> /dev/null; then
+    wget -O "/tmp/$TARBALL" "$URL"
+else
+    echo "❌ Neither curl nor wget found. Please install one of them."
+    exit 1
+fi
+
+echo "📦 Extracting..."
+cd /tmp
+tar xzf "$TARBALL"
+
+echo "🔧 Installing..."
+INSTALL_DIR="${INSTALL_DIR:-/usr/local}"
+
+if [[ -w "$INSTALL_DIR" ]]; then
+    cp -r "$PLATFORM/lib/"* "$INSTALL_DIR/lib/"
+    cp -r "$PLATFORM/bin/"* "$INSTALL_DIR/bin/"
+    cp -r "$PLATFORM/include/"* "$INSTALL_DIR/include/"
+else
+    sudo cp -r "$PLATFORM/lib/"* "$INSTALL_DIR/lib/"
+    sudo cp -r "$PLATFORM/bin/"* "$INSTALL_DIR/bin/"
+    sudo cp -r "$PLATFORM/include/"* "$INSTALL_DIR/include/"
+fi
+
+# Update library cache on Linux
+if [[ "$OS" == "linux" ]]; then
+    sudo ldconfig
+fi
+
+# Cleanup
+rm -rf "/tmp/$TARBALL" "/tmp/$PLATFORM"
+
+echo ""
+echo "✅ FastQR installed successfully!"
+echo ""
+echo "Test it:"
+echo "  fastqr --version"
+echo "  fastqr \"Hello World\" test.png"
+

data/scripts/release.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+# Create and push a new release
+
+set -e
+
+if [ -z "$1" ]; then
+    echo "Usage: $0 <version> [--force]"
+    echo "Example: $0 1.0.1"
+    echo ""
+    echo "Options:"
+    echo "  --force    Force re-tag if tag already exists (use with caution!)"
+    exit 1
+fi
+
+VERSION="$1"
+FORCE_FLAG=""
+
+if [ "$2" = "--force" ]; then
+    FORCE_FLAG="--force"
+    echo "⚠️  Force mode enabled - will overwrite existing tag if present"
+fi
+
+echo "🚀 Releasing FastQR v$VERSION..."
+echo ""
+
+# Check if we're on a clean working tree
+if [ -n "$(git status --porcelain)" ]; then
+    echo "❌ Working directory not clean. Please commit or stash changes first."
+    git status --short
+    exit 1
+fi
+
+# Update version in all files
+echo "📝 Updating version strings..."
+./scripts/update-version.sh "$VERSION"
+
+# Show what changed
+echo ""
+echo "📋 Changed files:"
+git diff --name-only
+echo ""
+
+# Commit version changes
+echo "💾 Committing version update..."
+git add -A
+git commit -m "chore: bump version to $VERSION" || echo "Nothing to commit"
+
+# Create tag
+echo "🏷️  Creating tag v$VERSION..."
+if git rev-parse "v$VERSION" >/dev/null 2>&1; then
+    if [ -z "$FORCE_FLAG" ]; then
+        echo "❌ Tag v$VERSION already exists!"
+        echo "   Use --force to overwrite (not recommended for published versions)"
+        exit 1
+    else
+        echo "⚠️  Deleting existing tag v$VERSION..."
+        git tag -d "v$VERSION"
+    fi
+fi
+
+git tag -a "v$VERSION" -m "Release v$VERSION"
+
+# Push
+echo "📤 Pushing to GitHub..."
+# Detect current branch
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+git push origin "$CURRENT_BRANCH" $FORCE_FLAG
+git push origin "v$VERSION" $FORCE_FLAG
+
+echo ""
+echo "✅ Release v$VERSION created successfully!"
+echo ""
+echo "📊 Next steps:"
+echo "1. Monitor GitHub Actions: https://github.com/tranhuucanh/fastqr/actions"
+echo "2. Check npm: https://www.npmjs.com/package/fastqr"
+echo "3. Check RubyGems: https://rubygems.org/gems/fastqr"
+echo "4. Check Packagist: https://packagist.org/packages/fastqr/fastqr"
+echo "5. Check Homebrew: brew upgrade fastqr"