fastqr 1.0.1

data/INSTALL.md

@@ -0,0 +1,171 @@
+# Installation Guide
+
+FastQR can be installed in multiple ways depending on your needs and platform.
+
+## 📦 Quick Install
+
+### macOS (Homebrew)
+
+```bash
+brew tap tranhuucanh/fastqr
+brew install fastqr
+```
+
+This installs the CLI tool and libraries system-wide.
+
+### Language-Specific Packages
+
+**Ruby (Gem):**
+```bash
+gem install fastqr
+```
+
+**Node.js (npm):**
+```bash
+npm install fastqr
+```
+
+**PHP (Composer):**
+```bash
+composer require fastqr/fastqr
+```
+
+**All language packages include pre-built binaries - no system dependencies required!**
+
+## 🔨 Build from Source
+
+### Prerequisites
+
+- C++14 compatible compiler
+- CMake 3.15+
+- libqrencode 4.0+
+- libvips 8.10+
+
+### macOS
+
+```bash
+# Install dependencies
+brew install cmake qrencode vips
+
+# Clone and build
+git clone https://github.com/tranhuucanh/fastqr.git
+cd fastqr
+./build.sh
+
+# Install
+cd build
+sudo make install
+```
+
+### Ubuntu/Debian
+
+```bash
+# Install dependencies
+sudo apt-get update
+sudo apt-get install -y cmake libqrencode-dev libvips-dev build-essential
+
+# Clone and build
+git clone https://github.com/tranhuucanh/fastqr.git
+cd fastqr
+./build.sh
+
+# Install
+cd build
+sudo make install
+```
+
+## 📥 Pre-built Binaries
+
+Download pre-built binaries from [GitHub Releases](https://github.com/tranhuucanh/fastqr/releases):
+
+```bash
+# Download and install
+curl -fsSL https://raw.githubusercontent.com/tranhuucanh/fastqr/main/scripts/install.sh | bash
+```
+
+Or manually:
+
+```bash
+# Download for your platform
+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
+```
+
+## 🧪 Verify Installation
+
+### CLI Tool
+
+```bash
+fastqr --version
+fastqr "Hello World" test.png
+```
+
+### Ruby
+
+```ruby
+require 'fastqr'
+puts FastQR.version
+FastQR.generate("Hello", "test.png")
+```
+
+### Node.js
+
+```javascript
+const fastqr = require('fastqr');
+console.log(fastqr.version());
+fastqr.generate('Hello', 'test.png');
+```
+
+### PHP
+
+```php
+<?php
+use FastQR\FastQR;
+echo FastQR::version();
+FastQR::generate('Hello', 'test.png');
+```
+
+## 📚 Next Steps
+
+- Read the [README](README.md) for usage examples
+- See [BUILD.md](BUILD.md) for detailed build instructions
+- Check [DISTRIBUTION.md](DISTRIBUTION.md) for publishing guides
+
+## ❓ Troubleshooting
+
+**"Command not found" after installation:**
+```bash
+# Make sure /usr/local/bin is in your PATH
+echo $PATH
+export PATH="/usr/local/bin:$PATH"
+```
+
+**"Library not found" error:**
+```bash
+# macOS
+export DYLD_LIBRARY_PATH=/usr/local/lib:$DYLD_LIBRARY_PATH
+
+# Linux
+export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
+sudo ldconfig
+```
+
+**Gem/npm/composer packages not finding binaries:**
+
+This should not happen as binaries are pre-built and bundled. If it does:
+1. Check your platform is supported
+2. Try building from source
+3. Open an issue on GitHub
+
+For more help, see [BUILD.md](BUILD.md) or open an [issue](https://github.com/tranhuucanh/fastqr/issues).
+

data/LICENSE

@@ -0,0 +1,39 @@
+GNU LESSER GENERAL PUBLIC LICENSE
+Version 2.1, February 1999
+
+Copyright (C) 1991, 1999 Free Software Foundation, Inc.
+51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+[This is the first released version of the Lesser GPL.  It also counts
+ as the successor of the GNU Library Public License, version 2, hence
+ the version number 2.1.]
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+
+---
+
+FastQR - Fast QR Code Generator Library
+Copyright (C) 2025 FastQR Project
+
+This project statically links with:
+- libqrencode (LGPL v2.1) - Copyright (C) 2006-2017 Kentaro Fukuchi
+- libvips (LGPL v2.1+) - Copyright (C) 1989-2021 Imperial College, London
+
+As required by the LGPL, you can obtain the source code and rebuild this
+library with modified versions of libqrencode and libvips. See BUILD.md
+for instructions.
+

data/PREBUILT.md

@@ -0,0 +1,171 @@
+# Pre-built Binaries Release Process
+
+This document describes how pre-built binaries are generated and distributed for FastQR.
+
+## Overview
+
+Starting from v1.0.0, FastQR includes pre-built binaries in all language packages (Ruby, Node.js, PHP). This means users can install packages without needing to install system dependencies (libqrencode, libvips).
+
+## Supported Platforms
+
+- **macOS**
+  - arm64 (Apple Silicon M1/M2/M3)
+  - x86_64 (Intel)
+- **Linux**
+  - x86_64 (64-bit Intel/AMD)
+  - arm64 (64-bit ARM)
+
+## How It Works
+
+### 1. Building Binaries
+
+When a new tag is pushed, the GitHub Actions workflow `.github/workflows/build-binaries.yml` automatically:
+
+1. Builds binaries for all 4 platforms
+2. Creates tarballs for each platform
+3. Extracts and organizes binaries into binding directories
+4. Commits binaries to the repository
+5. Creates GitHub Release with all assets
+
+### 2. Platform Detection & Loading
+
+Each language binding automatically detects the platform and loads the appropriate binary:
+
+**Ruby:**
+```ruby
+# bindings/ruby/lib/fastqr/platform.rb
+FastQR::Platform.platform  # => "macos-arm64"
+FastQR::Platform.lib_path  # => Path to pre-built binary
+```
+
+**Node.js:**
+```javascript
+// bindings/nodejs/lib/platform.js
+platform.detectPlatform()  // => "macos-arm64"
+platform.getPrebuiltPath() // => Path to pre-built binary
+```
+
+**PHP:**
+```php
+// bindings/php/src/FastQR.php
+// Auto-detects platform and loads binary via FFI
+```
+
+### 3. Distribution
+
+**Ruby Gem:**
+- Pre-built binaries are included in `bindings/ruby/prebuilt/`
+- Gem is published to RubyGems.org
+- Users: `gem install fastqr` (no dependencies needed!)
+
+**npm Package:**
+- Pre-built binaries are included in `bindings/nodejs/prebuilt/`
+- Package is published to npm
+- Users: `npm install fastqr` (no dependencies needed!)
+
+**Composer Package:**
+- Pre-built binaries are committed to repository in `bindings/php/prebuilt/`
+- Package is published to Packagist
+- Users: `composer require fastqr/fastqr` (no dependencies needed!)
+
+## Release Checklist
+
+When releasing a new version:
+
+1. **Update version** in all files:
+   ```bash
+   # CMakeLists.txt, package.json, gemspec, etc.
+   ```
+
+2. **Tag and push**:
+   ```bash
+   git tag -a v1.0.1 -m "Release 1.0.1"
+   git push origin v1.0.1
+   ```
+
+3. **GitHub Actions will**:
+   - Build binaries for all platforms
+   - Create GitHub Release
+   - Commit binaries to repository
+
+4. **Publish packages**:
+   ```bash
+   # Ruby
+   gem build fastqr.gemspec
+   gem push fastqr-1.0.1.gem
+
+   # Node.js
+   cd bindings/nodejs
+   npm publish
+
+   # PHP (auto via webhook)
+   ```
+
+## Manual Build
+
+To build binaries manually:
+
+```bash
+# Build for current platform
+./scripts/build-binaries.sh
+
+# Output: prebuilt/fastqr-VERSION-PLATFORM.tar.gz
+```
+
+## Binary Structure
+
+Each platform binary tarball contains:
+
+```
+platform/
+├── lib/
+│   └── libfastqr.{dylib|so}  # Shared library
+├── bin/
+│   └── fastqr                 # CLI tool
+└── include/
+    └── fastqr.h               # Header file
+```
+
+## Troubleshooting
+
+**Problem**: Binary not found for platform
+
+**Solution**: Check if platform is supported. If not, user must build from source.
+
+**Problem**: Binary fails to load
+
+**Solution**: Check file permissions and paths. On macOS, may need to allow in System Preferences → Security.
+
+**Problem**: GitHub Actions build fails
+
+**Solution**: Check build logs. Common issues:
+- Missing dependencies
+- Platform-specific build errors
+- Network issues downloading dependencies
+
+## Future Improvements
+
+- [ ] Add Windows support
+- [ ] Add more Linux distributions (Alpine, CentOS)
+- [ ] Optimize binary size
+- [ ] Add binary verification/signing
+- [ ] Cache dependencies in CI for faster builds
+
+## License Compliance
+
+Pre-built binaries statically link libqrencode and libvips (both LGPL 2.1).
+
+To comply with LGPL:
+1. LICENSE file is included in all packages
+2. BUILD.md provides instructions for rebuilding with custom libraries
+3. Source code is available on GitHub
+4. Attribution is included in README
+
+## Resources
+
+- [GitHub Actions Workflow](.github/workflows/build-binaries.yml)
+- [Build Script](scripts/build-binaries.sh)
+- [Platform Detection (Ruby)](bindings/ruby/lib/fastqr/platform.rb)
+- [Platform Detection (Node.js)](bindings/nodejs/lib/platform.js)
+- [Pre-built Binaries Directory](prebuilt/)
+

data/README.md

@@ -0,0 +1,312 @@
+# FastQR
+
+[![License](https://img.shields.io/badge/License-LGPL%202.1-blue.svg)](LICENSE)
+[![C++](https://img.shields.io/badge/C++-14-blue.svg)](https://isocpp.org/)
+[![Ruby](https://img.shields.io/badge/Ruby-Gem-red.svg)](https://rubygems.org/gems/fastqr)
+[![Node.js](https://img.shields.io/badge/Node.js-npm-green.svg)](https://www.npmjs.com/package/fastqr)
+[![PHP](https://img.shields.io/badge/PHP-Composer-blue.svg)](https://packagist.org/packages/fastqr/fastqr)
+
+FastQR is a fast, powerful QR code generator with full UTF-8 support, custom colors, logo embedding, and precise size control. **Pre-built binaries included**!
+
+## ✨ Features
+
+- 🚀 **High Performance**: No process forking
+- ⚡ **Batch Mode**: Generate 1000 QR codes in ~0.4s (7x faster than single mode!)
+- 🌐 **Full UTF-8 Support**: Vietnamese, Japanese (Kanji, Hiragana, Katakana), Chinese, emoji, etc.
+- 🎨 **Custom Colors**: Choose colors for QR code and background
+- 📐 **Exact Size**: Generate QR codes with precise pixel dimensions (e.g., 2000x2000px)
+- 🖼️ **Logo Embedding**: Add company logos to the center of QR codes
+- 📦 **Multiple Languages**: Bindings for Ruby, Node.js, PHP
+- 🛡️ **Error Correction**: Supports 4 levels (L, M, Q, H)
+- 💾 **Multiple Formats**: PNG, JPG, WebP
+- ✅ **Pre-built Binaries**: No dependencies needed for gem/npm/composer packages!
+
+## 🎯 Comparison with qrencode
+
+| Feature | FastQR | qrencode |
+|---------|--------|----------|
+| **Speed** | ✅ The same | ✅ The same |
+| **Exact Size** | ✅ 2000x2000px exact | ❌ Scale-based (hard to be exact) |
+| **UTF-8 Support** | ✅ Full | ⚠️ Limited |
+| **Colors** | ✅ RGB customizable | ❌ Black only |
+| **Logo** | ✅ Yes | ❌ No |
+| **Bindings** | ✅ Ruby, Node.js, PHP | ❌ CLI only |
+| **Installation** | ✅ Pre-built binaries | ❌ Requires system deps |
+
+## 🏗️ Architecture
+
+FastQR is built on:
+
+- **[libqrencode](https://fukuchi.org/works/qrencode/)** (LGPL v2.1) - QR code generation
+- **[libpng](http://www.libpng.org/pub/png/libpng.html)** - Fast PNG encoding
+- **[stb_image](https://github.com/nothings/stb)** (Public Domain) - Logo image loading
+
+## 📦 Installation
+
+### macOS (Homebrew)
+
+```bash
+brew tap tranhuucanh/fastqr
+brew install fastqr
+```
+
+### Ubuntu/Debian
+
+```bash
+# Download from GitHub Releases
+wget https://github.com/tranhuucanh/fastqr/releases/download/v1.0.0/fastqr-1.0.0-linux-x64.deb
+sudo dpkg -i fastqr-1.0.0-linux-x64.deb
+```
+
+### Language Packages (Pre-built Binaries Included!)
+
+**Ruby:**
+```bash
+gem install fastqr
+# No system dependencies needed! 🎉
+```
+
+**Node.js:**
+```bash
+npm install fastqr
+# No system dependencies needed! 🎉
+```
+
+**PHP:**
+```bash
+composer require fastqr/fastqr
+# No system dependencies needed! 🎉
+```
+
+**Important**: Starting from v1.0.0, all language packages include pre-built binaries for:
+- macOS (Intel & Apple Silicon)
+- Linux (x86_64 & arm64)
+
+You don't need to install `libqrencode` or `libpng` separately! The binaries are automatically bundled and loaded.
+
+### Build from Source
+
+```bash
+# Install dependencies
+# macOS:
+brew install qrencode libpng cmake
+
+# Ubuntu/Debian:
+sudo apt-get install libqrencode-dev libpng-dev cmake build-essential
+
+# Build
+git clone https://github.com/tranhuucanh/fastqr.git
+cd fastqr
+mkdir build && cd build
+cmake ..
+make
+sudo make install
+```
+
+See [INSTALL.md](INSTALL.md) for more installation options.
+
+## 🚀 Quick Start
+
+### CLI
+```bash
+fastqr "Hello World" output.png
+fastqr -s 500 -f 255,0,0 "Red QR" red.png
+fastqr -F batch.txt output_dir/  # Batch mode - 7x faster!
+```
+
+### Ruby
+```bash
+gem install fastqr  # Pre-built binaries included!
+```
+```ruby
+require 'fastqr'
+FastQR.generate("Hello", "qr.png", size: 500)
+FastQR.generate_batch(["QR 1", "QR 2"], "output/")  # Batch mode
+```
+
+### Node.js
+```bash
+npm install fastqr  # Pre-built binaries included!
+```
+```javascript
+const fastqr = require('fastqr');
+fastqr.generate('Hello', 'qr.png', { size: 500 });
+fastqr.generateBatch(['QR 1', 'QR 2'], 'output/');  // Batch mode
+```
+
+### PHP
+```bash
+composer require fastqr/fastqr  # Pre-built binaries included!
+```
+```php
+use FastQR\FastQR;
+FastQR::generate('Hello', 'qr.png', ['size' => 500]);
+FastQR::generateBatch(['QR 1', 'QR 2'], 'output/');  // Batch mode
+```
+
+### C++
+```cpp
+#include <fastqr.h>
+fastqr::QROptions options;
+options.size = 500;
+fastqr::generate("Hello", "qr.png", options);
+```
+
+## 📚 Documentation
+
+Complete usage guides for each platform:
+
+- **[CLI Usage Guide](docs/CLI_USAGE.md)** - Complete command-line reference with all options and examples
+- **[Ruby/Rails Usage Guide](docs/RUBY_USAGE.md)** - Ruby and Rails integration with examples
+- **[Node.js Usage Guide](docs/NODEJS_USAGE.md)** - Node.js, Express, and TypeScript guide
+- **[PHP Usage Guide](docs/PHP_USAGE.md)** - PHP, Laravel, and WordPress integration
+- **[Documentation Index](docs/README.md)** - Full documentation portal
+
+## 📖 API Reference
+
+### QROptions
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `size` | int | 300 | Output size in pixels (QR codes are square) |
+| `optimizeSize` | bool | false | Auto round-up to nearest integer multiple for best performance |
+| `foreground` | RGB array | [0,0,0] | QR code color |
+| `background` | RGB array | [255,255,255] | Background color |
+| `errorLevel` | string | 'M' | Error correction: L (~7%), M (~15%), Q (~25%), H (~30%) |
+| `logo` | string | "" | Path to logo image |
+| `logoSize` | int | 20 | Logo size as percentage (1-50) |
+| `quality` | int | 95 | Image quality for lossy formats (1-100) |
+| `format` | string | 'png' | Output format: png, jpg, webp |
+
+### Error Correction Levels
+
+- **L (Low)**: ~7% of codewords can be restored
+- **M (Medium)**: ~15% of codewords can be restored
+- **Q (Quartile)**: ~25% of codewords can be restored
+- **H (High)**: ~30% of codewords can be restored
+
+Higher levels allow QR codes to remain readable when damaged or have logos embedded.
+
+## 🔧 Development
+
+### Build from Source
+
+```bash
+git clone https://github.com/tranhuucanh/fastqr.git
+cd fastqr
+
+# Install dependencies
+brew install qrencode libpng cmake
+
+# Build
+mkdir build && cd build
+cmake ..
+make
+
+# Run examples
+./example_basic
+
+# Run tests
+make test
+```
+
+### Project Structure
+
+```
+fastqr/
+├── include/           # C++ headers
+│   ├── fastqr.h
+│   ├── stb_image.h
+│   └── stb_image_write.h
+├── src/              # C++ source
+│   ├── fastqr.cpp
+│   └── cli.cpp
+├── bindings/         # Language bindings
+│   ├── ruby/
+│   ├── nodejs/
+│   └── php/
+├── prebuilt/         # Pre-compiled binaries
+│   ├── macos-arm64/
+│   ├── macos-x86_64/
+│   ├── linux-x86_64/
+│   └── linux-arm64/
+├── scripts/          # Build and install scripts
+├── examples/         # Examples
+├── cmake/           # CMake configs
+└── LICENSE          # LGPL 2.1
+```
+
+## 📄 License
+
+FastQR is licensed under the **GNU Lesser General Public License v2.1 (LGPL-2.1)**.
+
+This project uses:
+- **libqrencode** (LGPL v2.1) - Copyright (C) 2006-2017 Kentaro Fukuchi
+- **libpng** - PNG image encoding
+- **stb_image** (Public Domain) - Sean Barrett's single-header image library
+
+As required by the LGPL, you can obtain the source code and rebuild this library with modified versions of libqrencode. See [BUILD.md](BUILD.md) for instructions.
+
+### LGPL Requirements
+
+When using FastQR in your projects:
+
+1. **Open Source Projects**: You can freely use FastQR
+2. **Closed Source/Commercial Projects**: You can use FastQR as a library, but:
+   - You must include a copy of the LGPL license
+   - You must state that your software uses FastQR
+   - Users must be able to replace the FastQR library with a modified version
+
+See [LICENSE](LICENSE) for full details.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
+
+## 🐛 Bug Reports
+
+If you find a bug, please open an issue with:
+- Your OS and version
+- FastQR version
+- Steps to reproduce
+- Expected vs actual behavior
+
+## 📮 Contact
+
+- GitHub: [@tranhuucanh](https://github.com/tranhuucanh)
+- Issues: [GitHub Issues](https://github.com/tranhuucanh/fastqr/issues)
+
+## 🙏 Acknowledgments
+
+- [libqrencode](https://fukuchi.org/works/qrencode/) by Kentaro Fukuchi
+- [libpng](http://www.libpng.org/pub/png/libpng.html) by PNG Development Group
+- [stb libraries](https://github.com/nothings/stb) by Sean Barrett
+
+## 📊 Benchmarks
+
+```
+Generating 100 QR codes (500x500px):  ~0.3 seconds
+Generating 1000 QR codes (500x500px): ~3 seconds
+
+Performance tested on modern hardware 🚀
+```
+
+## 🗺️ Roadmap
+
+- [ ] Windows support
+- [ ] SVG output
+- [ ] Python bindings
+- [ ] Batch processing API
+- [ ] QR code scanning/decoding
+
+---
+
+Made with ❤️ by FastQR Project

data/VERSION

@@ -0,0 +1 @@
+1.0.1