{"owner":"tesseract-ocr","repo":"tesseract","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":[".github/copilot-instructions.md"],"files":{".github/copilot-instructions.md":"# Tesseract OCR - GitHub Copilot Instructions\n\n## Repository Overview\n\nTesseract is an open-source **OCR (Optical Character Recognition) engine** that recognizes text from images. This repository contains:\n\n- **libtesseract**: C++ OCR library with C API wrapper\n- **tesseract**: Command-line OCR program\n- **Training tools**: For creating custom language models\n\n**Key Facts:**\n- Primary language: **C++17** (requires C++17-compliant compiler)\n- Size: Large (~100MB+ with submodules)\n- License: Apache 2.0\n- Maintained by: Stefan Weil (lead), Zdenko Podobny (maintainer)\n\n## Build Systems\n\nTesseract supports **two build systems**. Both are actively maintained and tested in CI.\n\n### 1. Autotools (Traditional, POSIX Systems)\n\n**When to use:** Linux, macOS (command-line), MSYS2 on Windows\n\n**Build sequence:**\n```bash\n./autogen.sh                    # Generate configure script (only needed after git clone)\n./configure                      # Configure build (creates Makefiles)\nmake                            # Build library and CLI\nsudo make install               # Install to system\nsudo ldconfig                   # Update library cache (Linux only)\nmake training                   # Build training tools (optional)\nsudo make training-install      # Install training tools\n```\n\n**Important:**\n- ALWAYS run `./autogen.sh` first if building from git clone\n- Use `make -j N` for parallel builds (N = number of CPU cores)\n- Check `configure --help` for build options\n- To clean: `make clean` or `make distclean` (complete cleanup)\n\n### 2. CMake (Modern, Cross-platform)\n\n**When to use:** Windows (MSVC, MinGW), cross-platform, modern development\n\n**Build sequence:**\n```bash\nmkdir build                     # MUST use out-of-source build\ncd build\ncmake ..                        # Configure (add options here)\nmake                            # Or: cmake --build .\nsudo make install               # Install to system\n```\n\n**Important CMake options:**\n- `BUILD_TRAINING_TOOLS=ON` - Enable training tools build\n- `CMAKE_BUILD_TYPE=Release` - Release build (default is RelWithDebInfo)\n- `GRAPHICS_DISABLED=ON` - Disable ScrollView (GUI debugger)\n- `ENABLE_NATIVE=OFF` - Disable CPU-specific optimizations (for portability)\n\n**CMake enforces out-of-source builds** - you cannot build in the source directory. If you get an error about this, remove `CMakeCache.txt` and build in a separate directory.\n\n## Dependencies\n\n### Core Required Dependencies\n\n- **Leptonica 1.74.2+** (REQUIRED) - Image I/O library\n  - Without this, build will fail\n  - Usually installed via package manager: `libleptonica-dev` (Ubuntu) or `leptonica` (Homebrew)\n\n- **C++17 compiler:**\n  - GCC 7+, Clang 5+, MSVC 2017+\n  - Verified compilers: gcc-11, gcc-12, gcc-14, clang-15, clang++\n\n### Training Tools Dependencies\n\nOnly needed if building training tools (`make training` or `-DBUILD_TRAINING_TOOLS=ON`):\n\n- pango-devel / libpango1.0-dev\n- cairo-devel\n- icu-devel\n\n### Optional Dependencies\n\n- **libarchive-dev**, **libcurl4-openssl-dev** - For advanced features\n- **OpenMP** - For parallel processing (enabled by default if available)\n- **cabextract** - For testing with CAB archives\n\n### Traineddata Files\n\nTesseract requires **traineddata files** to function. Minimum required:\n- `eng.traineddata` (English)\n- `osd.traineddata` (Orientation and Script Detection)\n\n**Installation:**\n```bash\n# Download individual files (to /usr/local/share/tessdata/ or your TESSDATA_PREFIX path)\ncd /usr/local/share/tessdata/  # Or wherever you want to install\nwget https://github.com/tesseract-ocr/tessdata/raw/main/eng.traineddata\nwget https://github.com/tesseract-ocr/tessdata/raw/main/osd.traineddata\n\n# Or clone all languages (WARNING: 1.2+ GB)\ngit clone https://github.com/tesseract-ocr/tessdata.git\n```\n\n**Set environment variable:**\n```bash\nexport TESSDATA_PREFIX=/usr/local/share/tessdata/\n```\n\nVerify with: `tesseract --list-langs`\n\n## Testing\n\n### Running Unit Tests\n\n**With autotools:**\n```bash\n./autogen.sh\n./configure\nmake\nmake check                      # Runs all unit tests\n```\n\n**With CMake:**\n```bash\nmkdir build && cd build\ncmake ..\nmake\nctest                          # Or: cmake --build . --target test\n```\n\n**Important:**\n- Tests require `googletest` submodule: `git submodule update --init --recursive`\n- Tests require tessdata files (eng, osd minimum)\n- Test results in `test-suite.log` (autotools) or CTest output (CMake)\n\n### Running Tesseract CLI\n\nBasic test commands:\n```bash\n# After installation:\ntesseract --version\ntesseract --list-langs\ntesseract input.png output      # OCR image, creates output.txt\ntesseract input.png output pdf  # Create searchable PDF\n```\n\nTest files available in `test/testing/` (requires test submodule):\n- `phototest.tif` - English test image\n- `devatest.png` - Hindi/Devanagari test image (different format intentional)\n\n## Project Structure\n\n### Source Code Layout\n\n```\nsrc/\n├── api/               # Public C/C++ API (baseapi.h, capi.h)\n├── ccmain/            # Main OCR control logic\n├── lstm/              # LSTM neural network engine (Tesseract 4+)\n├── ccutil/, cutil/    # Core utilities, data structures\n├── classify/          # Character classifier\n├── dict/              # Dictionary and language model\n├── textord/           # Text line and word detection\n├── wordrec/           # Word recognition\n├── training/          # Training tools (lstmtraining, text2image, etc.)\n└── tesseract.cpp      # CLI main() entry point\n\ninclude/tesseract/     # Public header files\nunittest/              # Unit tests (requires googletest)\ntest/testing/          # Test images and data\ntessdata/              # Default location for traineddata files\ndoc/                   # Documentation\n```\n\n### Key Files\n\n- **src/api/baseapi.h** - Main C++ API class (`TessBaseAPI`)\n- **src/api/capi.h** - C wrapper API\n- **src/tesseract.cpp** - Command-line tool\n- **CMakeLists.txt**, **configure.ac**, **Makefile.am** - Build configuration\n- **VERSION** - Current version string\n\n### Configuration Files\n\n- **.clang-format** - Code formatting rules (LLVM style)\n- **tesseract.pc.in** - pkg-config template\n- **.github/workflows/** - CI/CD definitions\n\n## CI/CD Workflows\n\n### Active Workflows\n\n1. **cmake.yml** - CMake builds on Ubuntu/macOS, 6 configurations\n2. **autotools.yml** - Autotools builds, comprehensive testing\n3. **unittest.yml** - Unit tests with sanitizers (ASAN, UBSAN)\n4. **codeql-analysis.yml** - Security static analysis\n5. **vcpkg.yml**, **msys2.yml**, **cmake-win64.yml** - Windows builds\n\n### Validation Requirements\n\nAll PRs trigger:\n- **Build tests** on multiple platforms (Ubuntu 22.04, 24.04, macOS 14, 15)\n- **Compiler tests** (GCC 11-14, Clang 15)\n- **Unit tests** with sanitizers\n- **CodeQL** security scan\n\n**Expect ~10-30 minutes** for full CI validation.\n\n### Common CI Failures\n\n- **Missing dependencies:** Check workflow files for required packages\n- **Test failures:** Often due to missing tessdata files\n- **Sanitizer errors:** Memory leaks, undefined behavior\n- **CodeQL alerts:** Security vulnerabilities in code\n\n## Common Build Issues & Workarounds\n\n### Issue: \"configure: error: Leptonica not found\"\n**Solution:** Install leptonica development package\n```bash\n# Ubuntu/Debian:\nsudo apt-get install libleptonica-dev\n# macOS:\nbrew install leptonica\n```\n\n### Issue: \"CMake Error: cannot build in source directory\"\n**Solution:** CMake requires out-of-source builds\n```bash\nrm -f CMakeCache.txt\nmkdir build && cd build && cmake ..\n```\n\n### Issue: \"make check\" fails with \"cannot find tessdata\"\n**Solution:** Set TESSDATA_PREFIX or download files\n```bash\nexport TESSDATA_PREFIX=/usr/local/share/tessdata/\n# Or copy files to /usr/local/share/tessdata/\n```\n\n### Issue: Submodule errors (googletest, test)\n**Solution:** Initialize submodules\n```bash\ngit submodule update --init --recursive\n```\n\n### Issue: Old Tesseract version conflicts\n**Solution:** Remove previous installation before building\n```bash\n# Find installed files:\nwhich tesseract\npkg-config --modversion tesseract\n# Uninstall old version, then rebuild\n```\n\n### Issue: Training tools not building\n**Solution:** Install pango, cairo, icu dependencies\n```bash\nsudo apt-get install libpango1.0-dev libcairo2-dev libicu-dev\n```\n\n## Validation Steps for Code Changes\n\nWhen making code changes, follow these steps:\n\n1. **Build the project** (choose one):\n   ```bash\n   # Autotools:\n   ./autogen.sh && ./configure && make\n   # CMake:\n   mkdir build && cd build && cmake .. && make\n   ```\n\n2. **Run unit tests**:\n   ```bash\n   # Autotools:\n   make check\n   # CMake:\n   ctest\n   ```\n\n3. **Test CLI manually**:\n   ```bash\n   tesseract test/testing/phototest.tif output\n   cat output.txt  # Verify OCR output\n   ```\n\n4. **Check for memory issues** (if modifying C++ code):\n   ```bash\n   # Build with sanitizers:\n   CXXFLAGS=\"-g -O2 -fsanitize=address,undefined\" ./configure\n   make && make check\n   ```\n\n5. **Run CodeQL** (security check):\n   - Will run automatically in CI\n   - Or use GitHub Code Scanning locally\n\n6. **Verify documentation** (if API changes):\n   - Update header comments in `include/tesseract/`\n   - Update relevant docs in `doc/`\n\n## Code Style & Conventions\n\n- **Formatting:** Use clang-format with `.clang-format` config (LLVM style)\n- **Naming:** \n  - Classes: `CamelCase` (e.g., `TessBaseAPI`)\n  - Functions: `CamelCase` (e.g., `ProcessPage`)\n  - Variables: `snake_case` or `lower_case`\n- **Headers:** Use include guards, document public APIs\n- **Comments:** Focus on \"why\", not \"what\"\n- **Commits:** Use meaningful messages, reference issue numbers\n\n## Important Notes for AI Coding Agents\n\n1. **Always use out-of-source builds with CMake** - in-source builds are blocked\n2. **Check for Leptonica** before building - it's a hard requirement\n3. **Initialize git submodules** before running tests\n4. **Set TESSDATA_PREFIX** or tests will fail\n5. **Building takes time** - allow 2-5 minutes for full build\n6. **Testing takes time** - `make check` can take 5-10 minutes\n7. **Don't remove existing tests** - they're critical for preventing regressions\n8. **Check CI workflows** for platform-specific requirements\n9. **Sanitizer builds are slower** - 2-3x slower than normal builds\n10. **Training tools are optional** - only build if needed for the task\n\n## Useful Commands Reference\n\n```bash\n# Quick build and test (autotools):\n./autogen.sh && ./configure && make -j8 && make check\n\n# Quick build and test (CMake):\nmkdir build && cd build && cmake .. && make -j8 && ctest\n\n# Format code:\nfind src -name '*.cpp' -o -name '*.h' | xargs clang-format -i\n\n# Check test results:\ncat test-suite.log                    # autotools\nctest --output-on-failure             # CMake\n\n# Install only library (no training):\nmake install                          # After ./configure && make\n\n# Clean builds:\nmake clean                            # Partial clean\nmake distclean                        # Complete clean (autotools)\nrm -rf build                          # Complete clean (CMake)\n\n# Check installed version:\ntesseract --version\npkg-config --modversion tesseract\n\n# Debug OCR on specific image:\ntesseract input.png output -l eng --psm 6 -c debug_file=/dev/null\n```\n\n---\n\n**Trust these instructions.** Only search for additional information if these instructions are incomplete, outdated, or if you encounter an error not covered here. The workflows and build procedures are tested daily in CI and represent current best practices for this repository.\n"}}