Converting a project

//tools/convert turns an autoconf project into a Bazel module built on these rules. It reads the project's configure.ac (expanded by the real autom4te) and the file lists of its build (Makefile.am, or a hand-written Makefile.in), and writes BUILD.bazel, MODULE.bazel and a report. What it cannot translate on its own it asks about in one file, decisions.bzl, which a person answers and keeps.

The result is a module in the shape of the hand-written BCR overlays: an autoconf target per configure body with checks.* calls, config.h and the other configured headers, the gnulib library with its conditional sources and wrapper headers, a cc_library per library and a cc_binary per program of the automake tree, bool_flags for the configure options, and select()s where configure branched on the platform.

Which projects

What sits next to configure.ac decides how much of a module comes out. The first note of the report names the shape it found.

A Makefile.am that switches compilers (CC = $(TARGET_CC), grub's firmware side) builds nothing for the host: its programs and libraries are left out and reported, whatever the shape of the rest.

Running it

From a clone of this repository:

bazel run //tools/convert -- convert --src https://ftp.gnu.org/gnu/gzip/gzip-1.15.tar.xz --out /path/to/output --dev

--src takes a release archive URL, a local archive or a source tree. --out receives BUILD.bazel, MODULE.bazel, REPO.bazel (the module's defaults: license metadata, the standard as a future toolchain feature), CONVERSION_REPORT.md and decisions.bzl. The banner of each generated file repeats the command, which is what regenerates the conversion. Options:

--help lists the rest. --profile FILE belongs to the tool rather than to the convert subcommand, so it goes before the subcommand: bazel run //tools/convert -- --profile run.prof convert .... It writes a cProfile of the run to FILE and a text summary to FILE.txt.

What to do with the output depends on where the module is going, see Using the output.

Decisions

The first run usually exits with status 3 and lists the constructs it could not translate under "Decisions required" in the report. Each is an entry of decisions.bzl with decision.UNDECIDED as its value: replace the value and run the same command again. The outputs are written even while decisions are missing, so the project can be looked at, but a conversion is complete only when the file answers every question.

The file is read with a parser, never evaluated; its header names the rules_cc_autoconf that wrote it. New entries are added in key order with a comment block showing the construct: the upstream text in a fenced block tagged with its language, where it was found, and why it is asked. Entries the converter stops asking for are reported as unused. A checks.X(...) value reads as in a BUILD file: add load("@rules_cc_autoconf//autoconf:checks.bzl", "checks") at the top.

A DEFAULTS table answers every undecided key of a kind at once, for a construct that never matters for the module (a firmware compiler's probes, a toolchain's warning flags); the report lists what a default answered:

DEFAULTS = {
    "probe": decision.IGNORE,
}

The kinds the converter asks for:

The kinds it never asks for, added by hand when wanted:

The migration guide says how each autoconf construct maps to a check, a rule or a select, which is what a replacement is written in.

Bundled decisions

The questions every gnulib project raises the same way, the gettext probes and substitutions of a project that builds no message catalogs, gnulib's own witness variables, are answered once, in gnulib/m4/decisions.bzl beside the ports. The converter reads it beneath the project's decisions file: a key the project's file answers wins, a key it leaves out or UNDECIDED takes the bundled answer, and only then does DEFAULTS apply. The report lists every answer taken from it under "Decisions inherited", so nothing applies silently; the bundled file's own keys never count as unused. --bundled-decisions FILE reads another file, none reads none; by default the converter finds the checkout's, or the copy in its runfiles when it runs from elsewhere.

BUILD.bazel and autoconf.bzl

In project mode every package the conversion writes to has two files. autoconf.bzl is generated: the package's targets are the body of one macro, configure(), named as the script it stands for, the constants several rules share stand at the top level, and visibility("private") keeps the file loadable from its own package alone. A BUILD.bazel that still calls the macro by its former name, autoconf_targets(), keeps working: the generated file aliases it and the report asks for the switch. The converter writes it whole on every run, formatted twice, as a BUILD file first (where buildifier expands every rule call and sorts the lists it sorts) and then as the .bzl file the statements move into, so it reads like a BUILD file. BUILD.bazel is hand-written: the converter writes it once, as a stub that loads the macro and calls it, and never touches it again. In a registry entry both sit in overlay/, extension/BUILD.bazel and extension/autoconf.bzl beside a sub-configure package's. A package the conversion does not write (a tests/ package of hand-written tests) is a hand-written BUILD.bazel in the same place, which the converter leaves alone.

BUILD.bazel does three things:

• Adds targets. Tests, tools, aliases, anything the conversion does not produce. A rule it loads from another module makes that module a bazel_dep of the generated MODULE.bazel. A constant autoconf.bzl defines at the top level (NO_WARNINGS, the option table) can be loaded from it; one defined inside the macro (a glob(), or a list built from one) cannot.
• Replaces generated targets. A rule with the same name as a generated one replaces it: at the next conversion the generated rule is left out of autoconf.bzl, whose macro docstring names it with a "Targets replaced" section of the report, and consumers are unchanged.
• Provides generated files. A generated:<path> decision of the form ":<target>" names a rule of BUILD.bazel that writes the file; the converter lists the file among the consumer's sources and emits no rule. This is the home for a tool shared by several outputs or a .bzl macro of its own; a one-line genrule fits inline in the decisions file.

For a shape 3 project BUILD.bazel holds the libraries and programs outright: there is no generated output to replace.

Visibility. Every generated target carries an explicit visibility, so a package(default_visibility = ...) in BUILD.bazel never publishes them. Public is deliberate and small: what make install ships, the libraries, programs and headers and their aliases, and the option flags, which are the module's configure options. Everything else, the autoconf targets, the config headers, autoconf_linkopts, the option settings, the gnulib and private header libraries and the generated-file rules, is private, or //:__subpackages__ when the module has other packages (a sub-configure, a hand-written tests/), which then see them. A tree rendered into a subdirectory of a larger workspace is confined to that directory instead, //third_party/foo:__subpackages__, and vendored ports are confined the same way.

A tree or entry converted before this layout, with a generated BUILD.bazel and a hand-written BUILD.additions.bazel beside it, is migrated by the next run: the additive file's contents become the new BUILD.bazel, its loads merged with the autoconf.bzl load (which names the top-level constants the text reads), and the additive file is removed; the report says so. A constant it read that autoconf.bzl now defines inside the macro has to be declared in BUILD.bazel by hand, and the report names those too.

How it translates

One bullet per construct; the table after them holds the details a reviewer of the output may want.

• Expansion. autom4te expands configure.ac with a prelude that marks every AC_DEFUN body and check macro call. The converter never parses m4; an m4_fatal becomes a warning so the expansion completes.
• Targets and deps. Each AC_DEFUN body is an autoconf target. AC_REQUIRE and calls of ported macros become deps on the ports under //gnulib/m4 and //autoconf/macros, the headers' :defaults targets default_deps. A local check a port already produces is left out and reported.
• Checks. Check macros become checks.* and macros.* calls, their action arguments read as configure runs them. Runtime probes are never executed. The language standard configure switches the compiler into is pinned on the package, and recorded by a check.
• Shell. The shell between calls is evaluated symbolically: the condition a call runs under becomes its requires, platform cases become select()s, options become flags with config settings, assignments to substituted variables become AC_SUBST checks. What the analysis cannot follow becomes a decision, never a guess.
• Registry libraries. A library the registry provides, that configure probes for or pkg-config asks about, becomes a bazel_dep and a dep of what links it. The checks that compile or link against it move to an autoconf target of their own with the library as its one cc_deps entry, which the main target depends on; every other check stays toolchain-only, so its result does not depend on the dependency graph. A library configure only probes under one of its options (gawk's -lmpfr -lgmp under --enable-mpfr) is a dep in that option's select() arm, so turning the flag off drops it from the graph. configure's own probes stay probes; PKG_CHECK_MODULES has none to run and is decided at conversion time from the registry's versions.
• The gnulib tree. gnulib-comp.m4 and gnulib.mk give the module deps, the wrapper headers, the recipe-written headers and the conditional sources of one gnulib library.
• The automake tree. Every Makefile.am gives a cc_library per library and a cc_binary per program, with LDADD, LIBADD and the flag variables resolved into deps, defines, includes and copts.
• Generated files. Recipes the converter can read become write_file, substitution or template rules; AC_CONFIG_FILES templates are rendered; everything else is a generated: decision.
• Sub-configures. Each AC_CONFIG_SUBDIRS directory is a package of the same module, converted from its own tree, sharing the decisions file. One configure enters only sometimes builds where configure enters it: a host-OS condition or a decided automake conditional becomes the package's target_compatible_with; a probe-dependent one (gawk's extension/ needs dlfcn.h) is a subdir: decision, and its targets are tagged manual until it is made. An option the sub-configure's script declares under the same name as the root's (gawk's extension/ runs the root's MPFR macro) is the root's flag: the package keys on //:<name>_enabled and declares no flag of its own, so one --//:<name> switches the whole module.
• Licensing. The license files the release ships are exported, with the registry's package metadata over them: the SPDX identifier is read from the text and the source headers, and asked for as a license: decision when they do not settle it.

Details by construct

Vendoring the ports

By default the module depends on the gnulib ports of this repository (@rules_cc_autoconf//gnulib/m4/...), which change as the repository tracks gnulib. --vendor-ports copies every port the conversion resolved, and every port those depend on, into third_party/rules_cc_autoconf/<package>/BUILD.bazel of the module, with labels rewritten and the in-repository rule replaced by the public autoconf rule. The module is then pinned to the snapshot it was converted against; regenerating against a newer checkout refreshes the copies and the diff shows what gnulib changed. The rules themselves, and the two ports that are rule implementations (AC_C_INLINE, AC_C_RESTRICT), still come from rules_cc_autoconf; the report names them. The converter needs the checkout the ports come from: run it there with bazel run, or pass --index <checkout>.

Inlining the checks

A dependency's checks run in the dependency's configuration. A project that pins a language standard (C_STD_OPTS, from a macro, a -std= in its flags or a standard: decision) pins its own checks and targets, not the ports it depends on: gnulib's gl_C_BOOL then answers for the toolchain's default mode, C23 on gcc 15 and later, and config.h leaves <stdbool.h> out of a compile that runs in gnu11. --inline-checks declares every gnulib port the conversion resolved, and every port those reach, as a target of the project's package: the same rule graph with the same names flattened (:gnulib/m4/c-bool/c-bool), each attribute the text of the port's BUILD file with the labels rewritten, the ports' :defaults and config settings mirrored alongside. GNULIB_M4_DEPS and GNULIB_M4_DEFAULT_DEPS then name the mirrors, which take the package's C_STD_OPTS like its own targets. The //autoconf/... ports stay dependencies. Each check's JSON is the port's, so the content cache still matches the toolchain's results wherever the flags agree; only a pinned project reruns.

The text is lifted from the port BUILD files with a parser at every run, from the checkout bazel run started in or the one --index <checkout> names; there is no snapshot, and an entry carries the ports of the tree its rules version names. //autoconf/tests/ports_mirror declares every port again through the same emitter (bazel run //tools/convert:update_index writes its BUILD file beside index.toml) and compares the evaluated attributes with the port's, so a port the lift cannot reproduce, or a mirror that fell behind its port, fails there before it reaches an entry.

Converting single m4 files

To port one m4 file the way the hand ports under //gnulib/m4 are written, name the file and give a configure.ac that invokes its macros:

bazel run //tools/convert -- convert --src /path/to/project --out /tmp/port --only foo.m4 --in-repo

Every other macro resolves to the existing ports. The output is one package per m4 file with an aggregator target named after the file, in the layout of //gnulib/m4/<name>.

Checking against GNU autoconf

The check subcommand runs the project's real configure with the pinned autotools and the compiler, flags and environment of the current Bazel C++ toolchain, as the conformance tests of this repository do, and diffs the resulting config header against one Bazel built from the converted BUILD.bazel:

bazel run //tools/convert -- check --src /path/to/project --out /tmp/check \
    --bazel-config-h lib/config.h=/path/to/output/bazel-bin/lib/config.h

The GNU results stay in /tmp/check/gnu/. This validates the host platform only; the conformance tests under //gnulib/tests are the reference for the rest.

Using the output

There are three ways to take a conversion into a build, from the most to the least packaged. In each, the files a person edits are decisions.bzl and the BUILD.bazel files; everything else is regenerated.

In all three the output directory holds hand-written files beside the generated ones, and the converter owns only its own. Every file it writes starts with a banner that says @generated and names rules_cc_autoconf; that mark is what it goes by:

• A file in the way that lacks the mark and differs from what would be written stops the run, before anything is written, with the paths listed. Hand-written files are kept where they are: move the file aside, or delete it. A hand-written BUILD.bazel is never in the way, since the conversion writes autoconf.bzl beside it.
• After writing, the converter's files that this run did not produce are removed, and nothing else: a package that left the automake tree leaves no stale autoconf.bzl behind, while a hand-written file is never touched. The report lists what was removed.

A project's own generated files (a parser that says @generated) are not the converter's, since the mark needs both words. MODULE.bazel is the one exception to the first rule: it is always regenerated, and the module() attributes of the file that was there, bazel_compatibility and compatibility_level among them, are kept in the new one.

A registry entry

--bcr-entry names the entry in a Bazel Central Registry checkout and takes everything else from it:

# the first time: the archive and its integrity
bazel run //tools/convert -- convert --bcr-entry bcr/modules/foo/1.2.bcr.1 \
    --src https://ftp.gnu.org/gnu/foo/foo-1.2.tar.gz --integrity sha256-...
# every time after
bazel run //tools/convert -- convert --bcr-entry bcr/modules/foo/1.2.bcr.1

The path gives the module name and version. In the entry directory:

An entry converted before this layout, with a generated BUILD.bazel and a BUILD.additions.bazel beside it, is migrated by the next run, see BUILD.bazel and autoconf.bzl.

The report and the scratch output go to --out, by default a temporary directory whose path the run prints, so nothing but the entry lands in the checkout. The banner of the generated files repeats the --bcr-entry command. Without a checkout, --bcr with --out, --source-url, --integrity and optionally --bcr-version writes the same entry under <out>/modules/.

An http_archive

For a project whose conversion is one BUILD file, a consumer can keep the generated file in its own repository and inject it with http_archive. --http-archive-entry names the directory, conventionally 3rdparty/<name>/, and reads decisions.bzl and source.json from it as --bcr-entry does:

bazel run //tools/convert -- convert --http-archive-entry 3rdparty/foo \
    --src https://ftp.gnu.org/gnu/foo/foo-1.2.tar.gz --integrity sha256-...

It writes the generated BUILD file there as BUILD.foo.bazel, the name http_archive users expect for an injected build file (a hand-written file of that name is not overwritten), records the archive in source.json, and prints the lines the consumer's MODULE.bazel needs: the bazel_deps the generated module declared and the http_archive call with build_file = "//3rdparty/foo:BUILD.foo.bazel". The report carries the same lines. The consumer also depends on rules_cc_autoconf. The injected file is all generated: there is no hand-written BUILD.bazel beside it, so a project that needs targets of its own takes one of the other two ways.

http_archive injects one file. A conversion that writes more, a sub-configure package, a config.h.in the release lacks, vendored ports, stops with a message naming the extra files: that project is rendered into its tree instead.

Rendering into the project

For anything larger than one BUILD file, or when the sources are a checkout rather than a release archive, point --out at the source tree, or copy the output over it:

bazel run //tools/convert -- convert --src /path/to/foo --out /path/to/foo \
    --decisions /path/to/foo/decisions.bzl

The tree is then a Bazel module: MODULE.bazel, the autoconf.bzl and BUILD.bazel files and decisions.bzl live in it, and a consumer reaches it with local_path_override, git_override or archive_override, or by vendoring the tree. Packaging and redistribution are the project's own concern from there; the converter's part is the same regeneration command, with the tree as both input and output. A source tree that ships its own BUILD.bazel files keeps them: the converter writes autoconf.bzl beside each, and the report names the BUILD files that do not call configure() yet.

Keeping the converter current

• tools/convert/index.toml is a snapshot of the hand ports: which macro lives in which target and what each provides. Regenerate it after adding or renaming ports with bazel run //tools/convert:update_index; CI fails when the committed snapshot differs from the ports.
• tools/convert/libraries.toml maps -l names to registry modules, with the version an entry depends on. bazel run //tools/convert:update_libraries refreshes it from the public registry (--registry <clone> reads a clone's origin/main instead): a module keeps the upstream release the table holds and takes its newest .bcr.N; moving to another upstream release is per module, --allow-upstream <module>. A registry entry's regeneration pins its dependencies the same way, from the checkout, with convert --allow-upstream <module> for the exceptions; the newer releases left alone are listed as notes. A library the entry already pins, in its MODULE.bazel or its previous version's for a fresh .bcr.N, keeps that upstream release rather than the table's; the table serves the libraries the entry never pinned.
• The golden tests under //tools/convert fix the output for a few gnulib modules and for gzip, each with its decisions file next to the expected output, and run buildifier with all warnings on it. After an intentional change, refresh a golden with bazel run //tools/convert:<name>_golden_test -- --update.
• The Python is type-checked by mypy in strict mode (.mypy.ini) and linted and format-checked by ruff (.ruff.toml) on every build: the .bazelrc applies rules_venv's py_mypy_aspect and py_ruff_aspect, with the toolchains in tools/convert/3rdparty, so bazel build //... fails on a type error, a lint finding or an unformatted file. bazel run @rules_venv//python/ruff:format and :fix apply what ruff can fix; a target tagged no_mypy or no_ruff is skipped.
• The prelude mirrors autoconf 2.73 internals. Updating the pinned autoconf means revisiting tools/convert/instrument.m4 and the shape regexes next to it.