handbrake-builder

An configurable, production-grade macOS build script for building, signing, notarizing and packing HandBrake from source.

This script is intended for advanced users who want full control over the HandBrake build process while remaining compatible with Apple’s modern security requirements.

Features

• Automated end-to-end build of HandBrake from upstream GitHub sources
• Repository cloning, updating, and clean rebuilds
• Automatic dependency installation and validation via Homebrew
• Environment preflight checks (Xcode, Command Line Tools, SDKs, codesigning identities)
• Deterministic build configuration with sensible defaults and overrideable settings
• Structured logging of all build phases (configure, compile, link, package)
• Robust extraction of primary compiler and build-system warnings / errors
• Generation of a concise, human-readable warning / error log suitable for CI and local development
• macOS code signing using Developer ID Application
• Optional notarization via notarytool, including submission and status handling
• Safe handling of interrupted or failed builds
• CI-friendly, non-interactive operation
• Fully compatible with macOS default tooling (BSD awk, zsh)
• Designed for easy integration into existing shell-based build pipelines

Requirements

• macOS 12 or newer
• Xcode Command Line Tools
• Homebrew
• Apple Developer ID (for signing / notarization)

Installation

git clone https://github.com/Nomis101/handbrake-builder.git
cd handbrake-builder
The script can be copied into /usr/local/bin

Configuration

The script will create a file buildconfig.conf in $HOME/Library/Application Support/HandBrakeBuilder that can be used to control the behavior of the script.

• DEV_DIR=
  Absolute path to your development directory.
  Examples:
  DEV_DIR="$HOME/Developer"
  DEV_DIR="/Volumes/Developer"
  DEV_DIR="$HOME/Documents"
  

• HB_GIT_REF=
  Git reference to build
  Valid values:
  

  • master (default)
    
  • release tags, e.g. 1.10.2
    
  • latest (highest semantic version tag)
    Examples: HB_GIT_REF="master"
    HB_GIT_REF="1.10.2"
    

• ENABLE_LOG=
  Log generation, enable (1) or disable (0) collection of compiler log into a log file

• ERROR_LOG=
  Error log generation, enable (1) or disable (0) collection of build errors into a separate errors log file.

• WARN_LEVEL=
  Compiler warning verbosity (set from 0 to 2). Higher levels can generate many warnings.

• WARN_LOG=
  Warning log generation, enable (1) or disable (0) collection of compiler warnings into a separate warnings log file.

• UPDATE_DEPS=
  Dependency handling (Homebrew). Automatically update and upgrade Homebrew dependencies before starting the build if set to 1 (disable set to 0).

• AUTO_GIT_PULL=
  Git repository auto-update. If set to 1, automatically pull new commits from the HandBrake Git repository if the local branch is behind the upstream.

• APPLY_PATCHES=
  Auto apply patches located in the patch folder.

• ADD_CONFIG_OPTS=
  Additional options appended to ./configure.
  Example: ADD_CONFIG_OPTS="--df-jobs=3 --lto=thin"

• NOTARY_ENABLE=
  macOS notarization Enable (1) or disable (0) notarization of the built application.

• NOTARY_USERNAME=
  Apple ID used for notarization

• NOTARY_TEAMID=
  Apple Developer Team ID used for notarization

• MAKE_INSTALLER=
  Create an installer file at the end of the build

• Custom compiler flags
  Additional compiler flags to append to the build.
  These are optional and advanced usage:
  CFLAGS=""
  CXXFLAGS=""
  OBJCFLAGS=""
  OBJCXXFLAGS=""
  

Folders

The project folder is located at $HOME/Library/Application Support/HandBrakeBuilder
This folder contains subfolders:
git-backups: Backup folder for changes on the sourcode if the branch is changed
logs: Contains build logs, warning logs and error logs (if enabled)
patches: If this folder contains patches (*.patch), this patches will be applied on the sourcecode (if enabled)

Note

This project includes original code and code generated with the assistance of OpenAI’s ChatGPT. The author reviewed, integrated, and tested all components to ensure correctness and reliability.