fastqr 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3cfb16eee23a1070b11b2013601477652c38b61eb11e202fd14de3864de6dc16
+  data.tar.gz: 4b9b60fb37a427f9921a4bb80bf32cddb7167fd7ea6e07f1938080885305f8a8
+SHA512:
+  metadata.gz: 2a032ae6df4927909e110905199b26fd970abd8e59dd7d34eb3e718152f096da724fd153db2c570f8e31bea34769c98a696b982e00552ce1dec395ebf5fc0d3a
+  data.tar.gz: 96a2b4db93bef4d77105b6439143bd52570a64fa4d3db13a7760284d126d46c8b534d068a32f0109c17a9b0daf159a4c55c8d1b2db31e3d26015db9ddede7d7f

data/BUILD.md

@@ -0,0 +1,482 @@
+# Building FastQR from Source
+
+This guide explains how to build FastQR from source, including building with custom versions of libqrencode and libvips (as required by LGPL).
+
+## 📋 Requirements
+
+### All Platforms
+
+- C++14 compatible compiler (GCC 5+, Clang 3.4+, MSVC 2017+)
+- CMake 3.15 or higher
+- Git
+
+### Dependencies
+
+- **libqrencode** (version 4.0+)
+- **libvips** (version 8.10+)
+
+## 🍎 macOS
+
+### Install Dependencies
+
+```bash
+# Using Homebrew
+brew install cmake qrencode vips pkg-config
+
+# Or build from source (see below)
+```
+
+### Build FastQR
+
+```bash
+# Clone repository
+git clone https://github.com/tranhuucanh/fastqr.git
+cd fastqr
+
+# Create build directory
+mkdir build
+cd build
+
+# Configure
+cmake .. \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DCMAKE_INSTALL_PREFIX=/usr/local
+
+# Build
+make -j$(sysctl -n hw.ncpu)
+
+# Test
+make test
+
+# Install
+sudo make install
+```
+
+### Build with Custom libqrencode
+
+```bash
+# Build libqrencode from source
+cd /tmp
+git clone https://github.com/fukuchi/libqrencode.git
+cd libqrencode
+./autogen.sh
+./configure --prefix=/usr/local
+make
+sudo make install
+
+# Build FastQR
+cd /path/to/fastqr
+mkdir build && cd build
+cmake .. -DCMAKE_PREFIX_PATH=/usr/local
+make
+sudo make install
+```
+
+### Build with Custom libvips
+
+```bash
+# Install libvips dependencies
+brew install glib libpng libjpeg libexif
+
+# Build libvips from source
+cd /tmp
+git clone https://github.com/libvips/libvips.git
+cd libvips
+./autogen.sh
+./configure --prefix=/usr/local
+make
+sudo make install
+
+# Build FastQR
+cd /path/to/fastqr
+mkdir build && cd build
+cmake .. -DCMAKE_PREFIX_PATH=/usr/local
+make
+sudo make install
+```
+
+## 🐧 Ubuntu/Debian
+
+### Install Dependencies
+
+```bash
+# Ubuntu 20.04+, Debian 11+
+sudo apt-get update
+sudo apt-get install -y \
+  build-essential \
+  cmake \
+  pkg-config \
+  libqrencode-dev \
+  libvips-dev \
+  git
+```
+
+### Build FastQR
+
+```bash
+# Clone repository
+git clone https://github.com/tranhuucanh/fastqr.git
+cd fastqr
+
+# Create build directory
+mkdir build
+cd build
+
+# Configure
+cmake .. \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DCMAKE_INSTALL_PREFIX=/usr/local
+
+# Build
+make -j$(nproc)
+
+# Test
+make test
+
+# Install
+sudo make install
+```
+
+### Build with Custom libqrencode
+
+```bash
+# Install build dependencies
+sudo apt-get install -y autoconf automake libtool libpng-dev
+
+# Build libqrencode
+cd /tmp
+git clone https://github.com/fukuchi/libqrencode.git
+cd libqrencode
+./autogen.sh
+./configure --prefix=/usr/local
+make
+sudo make install
+sudo ldconfig
+
+# Build FastQR
+cd /path/to/fastqr
+mkdir build && cd build
+cmake .. -DCMAKE_PREFIX_PATH=/usr/local
+make
+sudo make install
+```
+
+### Build with Custom libvips
+
+```bash
+# Install libvips dependencies
+sudo apt-get install -y \
+  libglib2.0-dev \
+  libexpat1-dev \
+  libjpeg-dev \
+  libpng-dev \
+  libwebp-dev \
+  libtiff-dev \
+  libexif-dev
+
+# Build libvips
+cd /tmp
+git clone https://github.com/libvips/libvips.git
+cd libvips
+./autogen.sh
+./configure --prefix=/usr/local
+make
+sudo make install
+sudo ldconfig
+
+# Build FastQR
+cd /path/to/fastqr
+mkdir build && cd build
+cmake .. -DCMAKE_PREFIX_PATH=/usr/local
+make
+sudo make install
+```
+
+## 🪟 Windows (MSVC)
+
+### Install Dependencies
+
+1. Install Visual Studio 2019 or later with C++ support
+2. Install CMake from https://cmake.org/download/
+3. Install vcpkg:
+
+```powershell
+cd C:\
+git clone https://github.com/Microsoft/vcpkg.git
+cd vcpkg
+.\bootstrap-vcpkg.bat
+.\vcpkg integrate install
+```
+
+4. Install dependencies:
+
+```powershell
+.\vcpkg install qrencode:x64-windows
+.\vcpkg install vips:x64-windows
+```
+
+### Build FastQR
+
+```powershell
+# Clone repository
+git clone https://github.com/tranhuucanh/fastqr.git
+cd fastqr
+
+# Create build directory
+mkdir build
+cd build
+
+# Configure
+cmake .. `
+  -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake `
+  -DCMAKE_BUILD_TYPE=Release
+
+# Build
+cmake --build . --config Release
+
+# Install
+cmake --install . --prefix C:\fastqr
+```
+
+## 🔧 CMake Build Options
+
+```bash
+# Build shared library (default: static)
+cmake .. -DBUILD_SHARED_LIBS=ON
+
+# Disable examples
+cmake .. -DFASTQR_BUILD_EXAMPLES=OFF
+
+# Disable bindings
+cmake .. -DFASTQR_BUILD_BINDINGS=OFF
+
+# Custom install prefix
+cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/local
+
+# Debug build
+cmake .. -DCMAKE_BUILD_TYPE=Debug
+
+# Specify C++ compiler
+cmake .. -DCMAKE_CXX_COMPILER=clang++
+```
+
+## 🧪 Running Tests
+
+```bash
+cd build
+
+# Run all tests
+make test
+
+# Or use ctest
+ctest --output-on-failure
+
+# Run specific test
+ctest -R basic_test
+```
+
+## 💎 Building Ruby Gem
+
+```bash
+cd /path/to/fastqr
+
+# Install dependencies
+gem install rake rake-compiler
+
+# Build gem
+gem build fastqr.gemspec
+
+# Install locally
+gem install fastqr-1.0.0.gem
+
+# Test
+ruby -rfastqr -e "puts FastQR.version"
+```
+
+### Building Ruby Gem with Custom Libraries
+
+```bash
+# Set library paths
+export LIBRARY_PATH=/usr/local/lib:$LIBRARY_PATH
+export C_INCLUDE_PATH=/usr/local/include:$C_INCLUDE_PATH
+export CPLUS_INCLUDE_PATH=/usr/local/include:$CPLUS_INCLUDE_PATH
+
+# Build gem
+gem build fastqr.gemspec
+```
+
+## 📦 Building Node.js Module
+
+```bash
+cd /path/to/fastqr/bindings/nodejs
+
+# Install dependencies
+npm install
+
+# Build native addon
+npm run install
+
+# Test
+npm test
+
+# Create tarball
+npm pack
+```
+
+### Building Node.js Module with Custom Libraries
+
+```bash
+cd bindings/nodejs
+
+# Set PKG_CONFIG_PATH
+export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH
+
+# Build
+npm run install
+```
+
+## 🐘 Building PHP Extension
+
+PHP uses FFI, so no compilation needed. Just ensure libfastqr is installed:
+
+```bash
+# Build and install libfastqr
+cd /path/to/fastqr
+mkdir build && cd build
+cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local
+make
+sudo make install
+
+# Test PHP binding
+cd ../bindings/php
+composer install
+vendor/bin/phpunit
+```
+
+## 🔍 Troubleshooting
+
+### "qrencode.h not found"
+
+```bash
+# Make sure qrencode is installed
+pkg-config --modversion libqrencode
+
+# If not found, install or add to PKG_CONFIG_PATH
+export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH
+```
+
+### "vips.h not found"
+
+```bash
+# Make sure vips is installed
+pkg-config --modversion vips
+
+# If not found, install or add to PKG_CONFIG_PATH
+export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH
+```
+
+### "Library not found" at runtime
+
+```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
+
+# Or add to system library path
+# macOS: Add to /etc/ld.so.conf
+# Linux: sudo ldconfig /usr/local/lib
+```
+
+### CMake can't find libraries
+
+```bash
+# Specify library locations explicitly
+cmake .. \
+  -DQRENCODE_INCLUDE_DIR=/usr/local/include \
+  -DQRENCODE_LIBRARY=/usr/local/lib/libqrencode.a \
+  -DVIPS_INCLUDE_DIR=/usr/local/include \
+  -DVIPS_LIBRARY=/usr/local/lib/libvips.a
+```
+
+### Ruby gem fails to build
+
+```bash
+# Install development headers
+# Ubuntu/Debian:
+sudo apt-get install ruby-dev
+
+# macOS: Already included with Homebrew Ruby
+
+# Check Ruby configuration
+ruby -rrbconfig -e 'puts RbConfig::CONFIG["CC"]'
+```
+
+### Node.js module fails to build
+
+```bash
+# Install node-gyp globally
+npm install -g node-gyp
+
+# Rebuild
+node-gyp rebuild
+
+# Clean and rebuild
+node-gyp clean
+node-gyp configure
+node-gyp build
+```
+
+## 📝 LGPL Compliance Notes
+
+FastQR uses **LGPL 2.1** license and statically links with:
+- libqrencode (LGPL 2.1)
+- libvips (LGPL 2.1+)
+
+As required by LGPL, you can:
+
+1. **Replace the library**: Build FastQR with different versions of libqrencode/libvips using the instructions above
+2. **Modify the library**: Fork and modify libqrencode/libvips, then build FastQR against your modified versions
+3. **Link dynamically**: Use `-DBUILD_SHARED_LIBS=ON` to build shared library instead of static
+
+### Example: Using Modified libqrencode
+
+```bash
+# 1. Fork and modify libqrencode
+git clone https://github.com/yourfork/libqrencode.git
+cd libqrencode
+# Make your changes
+./autogen.sh
+./configure --prefix=$HOME/custom
+make install
+
+# 2. Build FastQR with your modified libqrencode
+cd /path/to/fastqr
+mkdir build && cd build
+cmake .. -DCMAKE_PREFIX_PATH=$HOME/custom
+make
+```
+
+This satisfies LGPL requirement that users must be able to replace/modify the LGPL libraries.
+
+## 🆘 Getting Help
+
+If you encounter issues:
+
+1. Check this BUILD.md
+2. Check GitHub Issues: https://github.com/tranhuucanh/fastqr/issues
+3. Open a new issue with:
+   - Your OS and version
+   - Compiler version
+   - CMake output
+   - Error messages
+
+## 📚 Resources
+
+- [CMake Documentation](https://cmake.org/documentation/)
+- [libqrencode](https://github.com/fukuchi/libqrencode)
+- [libvips](https://github.com/libvips/libvips)
+- [LGPL v2.1 License](https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html)
+

data/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-10-18
+
+### Added
+- Initial release of FastQR
+- Core C++ library with libqrencode and libvips integration
+- Full UTF-8 support (Vietnamese, Japanese, Chinese, emoji, etc.)
+- Custom color support for QR code and background
+- Precise size control (exact pixel dimensions)
+- Logo embedding capability
+- Error correction levels (L, M, Q, H)
+- Multiple output formats (PNG, JPG, WebP)
+- CLI tool with comprehensive options
+- Ruby binding (Gem)
+- Node.js binding (npm) with TypeScript definitions
+- PHP binding (Composer) using FFI
+- CMake build system
+- Comprehensive documentation (README, BUILD, DISTRIBUTION)
+- Example code
+- Unit tests for all bindings
+- LGPL 2.1 license compliance
+- macOS and Linux support
+
+### Features
+- Generate QR codes with exact dimensions (e.g., 2000x2000px)
+- Support for all UTF-8 characters
+- RGB color customization for foreground and background
+- Logo overlay with size percentage control
+- 4 error correction levels
+- Quality control for lossy formats
+- Fast performance (no process forking)
+
+### Bindings
+- **Ruby**: Full-featured gem with native extension
+- **Node.js**: Native addon with N-API
+- **PHP**: FFI-based binding (no compilation needed)
+
+### Documentation
+- Comprehensive README with examples
+- BUILD.md with detailed compilation instructions
+- DISTRIBUTION.md with publishing guides for all package managers
+- API documentation for all languages
+
+[1.0.0]: https://github.com/tranhuucanh/fastqr/releases/tag/v1.0.0
+

data/CMakeLists.txt

@@ -0,0 +1,126 @@
+cmake_minimum_required(VERSION 3.15)
+project(fastqr VERSION 1.0.0 LANGUAGES CXX C)
+
+set(CMAKE_CXX_STANDARD 14)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+# Optimization flags for maximum performance
+if(NOT CMAKE_BUILD_TYPE)
+    set(CMAKE_BUILD_TYPE Release)
+endif()
+
+set(CMAKE_CXX_FLAGS_RELEASE "-Ofast -DNDEBUG -march=native -flto")
+set(CMAKE_C_FLAGS_RELEASE "-Ofast -DNDEBUG -march=native -flto")
+
+# Options
+option(BUILD_SHARED_LIBS "Build shared libraries" OFF)
+option(FASTQR_BUILD_EXAMPLES "Build examples" ON)
+option(FASTQR_BUILD_BINDINGS "Build language bindings" ON)
+
+# Find dependencies
+find_package(PkgConfig REQUIRED)
+find_package(PNG REQUIRED)
+
+# Find libqrencode
+pkg_check_modules(QRENCODE REQUIRED libqrencode)
+
+# Add library directories
+link_directories(${QRENCODE_LIBRARY_DIRS})
+
+# Main library
+add_library(fastqr
+    src/fastqr.cpp
+)
+
+target_include_directories(fastqr
+    PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+        $<INSTALL_INTERFACE:include>
+    PRIVATE
+        ${QRENCODE_INCLUDE_DIRS}
+        ${PNG_INCLUDE_DIRS}
+)
+
+target_link_directories(fastqr
+    PRIVATE
+        ${QRENCODE_LIBRARY_DIRS}
+)
+
+target_link_libraries(fastqr
+    PRIVATE
+        ${QRENCODE_LIBRARIES}
+        PNG::PNG
+)
+
+target_compile_options(fastqr
+    PRIVATE
+        ${QRENCODE_CFLAGS_OTHER}
+)
+
+# Set library output name
+set_target_properties(fastqr PROPERTIES
+    VERSION ${PROJECT_VERSION}
+    SOVERSION 1
+    OUTPUT_NAME fastqr
+)
+
+# CLI tool
+add_executable(fastqr-cli
+    src/cli.cpp
+)
+
+target_link_libraries(fastqr-cli
+    PRIVATE fastqr
+)
+
+set_target_properties(fastqr-cli PROPERTIES
+    OUTPUT_NAME fastqr
+)
+
+# Examples
+if(FASTQR_BUILD_EXAMPLES)
+    add_subdirectory(examples)
+endif()
+
+# Install
+include(GNUInstallDirs)
+
+install(TARGETS fastqr fastqr-cli
+    EXPORT fastqrTargets
+    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+)
+
+install(FILES include/fastqr.h
+    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+)
+
+install(EXPORT fastqrTargets
+    FILE fastqrTargets.cmake
+    NAMESPACE fastqr::
+    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/fastqr
+)
+
+# Create config file
+include(CMakePackageConfigHelpers)
+
+configure_package_config_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/cmake/fastqrConfig.cmake.in
+    ${CMAKE_CURRENT_BINARY_DIR}/fastqrConfig.cmake
+    INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/fastqr
+)
+
+write_basic_package_version_file(
+    ${CMAKE_CURRENT_BINARY_DIR}/fastqrConfigVersion.cmake
+    VERSION ${PROJECT_VERSION}
+    COMPATIBILITY SameMajorVersion
+)
+
+install(FILES
+    ${CMAKE_CURRENT_BINARY_DIR}/fastqrConfig.cmake
+    ${CMAKE_CURRENT_BINARY_DIR}/fastqrConfigVersion.cmake
+    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/fastqr
+)
+

data/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing to FastQR
+
+Thank you for your interest in contributing to FastQR! This document provides guidelines and instructions for contributing.
+
+## 🤝 How to Contribute
+
+### Reporting Bugs
+
+1. Check if the bug has already been reported in [Issues](https://github.com/tranhuucanh/fastqr/issues)
+2. If not, create a new issue with:
+   - Clear title and description
+   - Steps to reproduce
+   - Expected vs actual behavior
+   - Your environment (OS, compiler, library versions)
+   - Code samples or test cases
+
+### Suggesting Features
+
+1. Check [Issues](https://github.com/tranhuucanh/fastqr/issues) for similar requests
+2. Create a new issue tagged with "enhancement"
+3. Describe the feature and its use case
+4. Explain why it would be useful
+
+### Pull Requests
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Make your changes
+4. Add tests for new functionality
+5. Ensure all tests pass: `make test`
+6. Commit with clear messages: `git commit -m 'Add amazing feature'`
+7. Push to your fork: `git push origin feature/amazing-feature`
+8. Open a Pull Request
+
+## 📝 Development Guidelines
+
+### Code Style
+
+- **C++**: Follow Google C++ Style Guide
+- **Ruby**: Follow Ruby Style Guide
+- **JavaScript**: Follow Airbnb JavaScript Style Guide
+- **PHP**: Follow PSR-12
+
+### Commit Messages
+
+- Use present tense: "Add feature" not "Added feature"
+- Be descriptive but concise
+- Reference issues: "Fix #123: Description"
+
+### Testing
+
+- Add tests for all new features
+- Ensure existing tests pass
+- Test on multiple platforms if possible
+
+## 🏗️ Development Setup
+
+See [BUILD.md](BUILD.md) for detailed build instructions.
+
+## 📄 License
+
+By contributing, you agree that your contributions will be licensed under LGPL 2.1.
+