ccextractor/docs/Building_macos_system_libs.md

Building CCExtractor on macOS using System Libraries (-system-libs)

Overview

This document explains how to build CCExtractor on macOS using system-installed libraries instead of bundled third-party libraries.

This build mode is required for Homebrew compatibility and is enabled via the -system-libs flag introduced in PR #1862.

Why is -system-libs needed?

Background

CCExtractor was removed from Homebrew (homebrew-core) because:

• Homebrew does not allow bundling third-party libraries
• The default CCExtractor build compiles libraries from src/thirdparty/
• This violates Homebrew packaging policies

What -system-libs fixes

The -system-libs flag allows CCExtractor to:

• Use system-installed libraries via Homebrew
• Resolve headers and linker flags using pkg-config
• Skip compiling bundled copies of common libraries

This makes CCExtractor acceptable for Homebrew packaging.

Build Modes Explained

1️⃣ Default Build (Bundled Libraries)

Command:

./mac/build.command

Behavior:

• Compiles bundled libraries:
  • freetype
  • libpng
  • zlib
  • utf8proc
• Self-contained binary
• Larger size
• Suitable for standalone builds

2️⃣ System Libraries Build (Homebrew-compatible)

Command:

./mac/build.command -system-libs

Behavior:

• Uses system libraries via pkg-config
• Does not compile bundled libraries
• Smaller binary
• Faster build
• Required for Homebrew

Required Homebrew Dependencies

Install required dependencies:

brew install pkg-config autoconf automake libtool \
  gpac freetype libpng protobuf-c utf8proc zlib

Optional (OCR / HARDSUBX support):

brew install tesseract leptonica ffmpeg

How to Build

cd mac
./build.command -system-libs

Verify:

./ccextractor --version

What Changes Internally with -system-libs

Libraries NOT compiled (system-provided)

• FreeType
• libpng
• zlib
• utf8proc

Libraries STILL bundled

• lib_hash (Custom SHA-256 implementation, no system equivalent)

CI Coverage

A new CI job was added:

• build_shell_system_libs

What it does:

• Installs Homebrew dependencies
• Runs ./build.command -system-libs
• Verifies the binary runs correctly

This ensures Homebrew-compatible builds stay working.

Verification (Local)

You can confirm system libraries are used:

otool -L mac/ccextractor

Expected output includes paths like:

/opt/homebrew/opt/gpac/lib/libgpac.dylib

Homebrew Formula Usage (Future)

Example formula snippet:

def install
  system "./mac/build.command", "-system-libs"
  bin.install "mac/ccextractor"
end

Summary

• -system-libs is opt-in
• Default build remains unchanged
• Enables CCExtractor to return to Homebrew
• Fully tested in CI and locally

Related

• PR #1862 — Add -system-libs flag
• Issue #1580 — Homebrew compatibility
• Issue #1534 — System library support