hermesvm Binary Size Analysis

Analyze per-commit binary size changes of the hermesvm shared library across a git commit range. Produces a markdown report with per-commit sizes and summary tables of significant increases and decreases.

When This Skill Applies

• Analyzing which commits caused hermesvm binary size growth
• Investigating size regressions in the hermesvm library
• Producing a size report for a range of commits

Pre-Run Prompt

Before starting, inform the user how size is measured and ask about verification:

1. Explain the measurement method: Tell the user that sizes are measured by summing ALLOC section sizes (via readelf -SW on Linux or otool -l on macOS), not by measuring the file size with stat. This excludes alignment padding and non-shipping sections (symbol tables, string tables, code signatures), matching what actually ships on-device after strip.

2. Ask about parent-commit verification: This verification is enabled by default. It builds each BUILD commit's parent to confirm no skipped commit changed the binary size. It catches miscategorized SKIP commits but roughly doubles the build time. If the user declines, skip all verification substeps in Step 2.

Required User Input

• Commit range: A base commit and an end commit (or HEAD). For example: b48b6cc..HEAD or v0.290.0..v0.300.0
• CMake flags (optional): Additional CMake configuration flags. Defaults are listed below.
• Parent-commit verification (optional): Enabled by default. Disable to halve build time at the risk of missing miscategorized SKIP commits.

Default Build Configuration

cmake -B cmake-build-minsizerel -GNinja \
  -DHERMESVM_GCKIND=HADES \
  -DHERMESVM_HEAP_HV_MODE=HEAP_HV_PREFER32 \
  -DCMAKE_BUILD_TYPE=MinSizeRel \
  -DHERMESVM_ALLOW_JIT=2 \
  -DHERMESVM_ALLOW_CONTIGUOUS_HEAP=ON \
  -DHERMES_IS_MOBILE_BUILD=ON

If the user provides additional flags, append them to the cmake command. If the user provides a different value to flags in default build configuration above, replace it with the user-provided value (e.g., -DHERMESVM_ALLOW_JIT=0).

Procedure

Step 0: Verify Git Repository and Tools

This skill requires a GitHub checkout of the static_h repo (commit hashes are git hashes). Before proceeding, verify the working directory is a valid git repo:

git rev-parse --is-inside-work-tree

If this fails (e.g., the repo is a Sapling/Mercurial checkout or not a repo at all), stop and inform the user that this skill only works in a git checkout of the Hermes repository.

Bloaty setup: This skill uses bloaty for detailed per-section diffs on large size increases. Download and build it:

git clone https://github.com/google/bloaty.git ~/bloaty
cd ~/bloaty && cmake -B build -GNinja && cmake --build build

If the download or build fails (e.g., no network access, missing dependencies), ask the user to provide the path to a pre-built bloaty binary.

Step 1: Categorize Commits

Generate the list of commits in the range and categorize each as BUILD or SKIP.

A commit is SKIP if it only touches files outside the directories that contribute to the hermesvm binary. The relevant source directories are:

• lib/ (VM, Parser, Sema, IR, BCGen, Support, Regex, etc.)
• API/hermes/
• public/hermes/
• include/hermes/
• external/
• CMakeLists.txt (exact match, not filtered by .txt suffix), cmake/, lib/config/

Files that never affect the binary: test/, unittests/, .github/, docs (.md, .txt, .rst), tools/, npm packages (hermes-parser, prettier-plugin, etc.), utils/, benchmarks/, website/, blog/.

Use this Python script to categorize:

#!/usr/bin/env python3
import subprocess, sys

RELEVANT_PREFIXES = [
    "lib/", "API/hermes/", "API/jsi/", "public/hermes/", "include/hermes/",
    "external/", "cmake/", "lib/config/",
]

…