Skip to content

bootstrap-vs-build.rst

Latest commit

 

History

History
109 lines (82 loc) · 3.24 KB

bootstrap-vs-build.rst

File metadata and controls

109 lines (82 loc) · 3.24 KB
Raw

Bootstrap vs Build

Fromager has two distinct modes of operation: bootstrap and build. Understanding the difference is key to using fromager effectively.

.. seealso::

   :doc:`/using` covers practical command usage and examples.

Quick Comparison

Aspect Bootstrap Build
Scope Entire dependency tree Single package
Purpose Discover and resolve all dependencies Compile source into wheel
Recursion Yes (processes dependencies) No (one package only)
Input Requirements file or package specs Package name + version + source URL
Output Dependency graph, build order, all wheels One wheel file

Bootstrap Mode

The bootstrap command recursively discovers and builds all dependencies:

fromager bootstrap numpy
  ├── Resolve version → numpy==1.26.0
  ├── Download source
  ├── Extract build dependencies from pyproject.toml
  ├── bootstrap(setuptools)  ← Process build dependencies first
  ├── Build wheel (with build deps available)
  ├── Extract install dependencies from wheel metadata
  └── bootstrap(cython)  ← Process each install dependency
        └── Resolve version → cython==3.0.0, then repeat...

Key operations:

  1. Version resolution for all packages
  2. Dependency graph construction
  3. Build order determination
  4. Wheel building (for each discovered package)

When to use: Initial discovery of what needs to be built, creating a complete wheel collection from scratch.

Build Mode

The build command compiles a single package without recursion:

fromager build numpy 1.26.0 https://pypi.org/simple/
  ├── Download sdist
  ├── Apply patches
  ├── Create build environment
  ├── Run pip wheel
  └── Output: numpy-1.26.0-cp311-linux_x86_64.whl

Key operations:

  1. Source download and preparation
  2. Build environment setup
  3. Wheel compilation
  4. No dependency discovery or recursion

When to use: Production builds where the build order is already known (from a previous bootstrap), CI/CD pipelines, rebuilding individual packages.

Relationship

While bootstrap and build share some common steps (downloading sources, applying patches, running pip wheel), they are separate implementations optimized for different use cases. Bootstrap maintains state across the entire dependency tree, while build operates statelessly on a single package.

The build-sequence and build-parallel commands bridge these modes by reading a build-order.json file (produced by bootstrap) and invoking the build logic for each package in the specified order.

Typical Workflow

  1. Development: Use bootstrap to discover all dependencies and create initial wheel collection
  2. Production: Use build-sequence or build-parallel with the build-order.json from bootstrap to rebuild deterministically
  3. Fixes: Use build to rebuild individual packages after applying patches