Metadata-Version: 2.1
Name: fromager
Version: 0.0.1
Summary: Wheel maker
Author-email: Mark McLoughlin <markmc@redhat.com>, Doug Hellmann <dhellmann@redhat.com>
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: html5lib
Requires-Dist: packaging
Requires-Dist: pkginfo
Requires-Dist: PyYAML
Requires-Dist: pyproject-hooks !=1.1.0,>=1.0.0
Requires-Dist: python-gitlab
Requires-Dist: python-pypi-mirror
Requires-Dist: requests
Requires-Dist: resolvelib
Requires-Dist: stevedore
Requires-Dist: tomli
Provides-Extra: build
Requires-Dist: build ; extra == 'build'
Requires-Dist: twine ; extra == 'build'
Provides-Extra: test
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: pytest-cov ; extra == 'test'
Requires-Dist: coverage !=4.4,>=4.0 ; extra == 'test'

# fromager

Fromager is a tool for completely re-building a dependency tree of
Python wheels from source.

1. The [binary
   package](https://packaging.python.org/en/latest/glossary/#term-Built-Distribution)
   they are installing was built from source in a known build
   environment compatible with their own environment
1. All of the package’s dependencies were also built from source -- any
   binary package installed will have been built from source
1. All of the build tools used to build these binary packages will
   also have been built from source.

## Modes

Fromager has different modes for bootstrapping and production builds.
The bootstrap mode recursively processes all dependencies starting
from the requirements specifications given to determine what needs to
be built and what order to build it. The production build commands
separate these steps and avoid recursive processing so each step can
be performed in isolation.

## Bootstrapping

The `bootstrap` command

* Creates an empty package repository for
  [wheels](https://packaging.python.org/en/latest/specifications/binary-distribution-format/)
* Downloads the [source
  distributions](https://packaging.python.org/en/latest/glossary/#term-Source-Distribution-or-sdist)
  for the input packages and places them under
  `sdists-repo/downloads/`.
* Recurses through the dependencies
  * Firstly, any build system dependency specified in the
    pyproject.toml build-system.requires section as per
    [PEP517](https://peps.python.org/pep-0517)
  * Secondly, any build backend dependency returned from the
    get_requires_for_build_wheel() build backend hook (PEP517 again)
  * Lastly, any install-time dependencies of the project as per the
    wheel’s [core
    metadata](https://packaging.python.org/en/latest/specifications/core-metadata/)
    `Requires-Dist` list.
* As each wheel is built, it is placed in a [PEP503 "simple" package
  repository](https://peps.python.org/pep-0503/) under
  `wheels-repo/simple` generated by
  [pypi-mirror](https://pypi.org/project/python-pypi-mirror/).
* The order the dependencies need to be built bottom-up is written to
  `build-order.json`.

Wheels are built by running `pip wheel` configured so it will only
download dependencies from the local wheel repository. This ensures
that all dependencies are being built in the correct order.

## Additional docs

* [Package build customization instructions](docs/customization.md)
* [Developer instructions](docs/develop.md)

## What's with the name?

Python's name comes from Monty Python, the group of comedians. One of
their skits is about a cheese shop that has no cheese in stock. The
original Python Package Index (pypi.org) was called The Cheeseshop, in
part because it hosted metadata about packages but no actual
packages. The wheel file format was selected because cheese is
packaged in wheels. A
"[fromager](https://en.wiktionary.org/wiki/fromager)" is the French
word for someone who makes or sells cheese.
