From 8de85a18eeed4f52d061197eaf43213fe1d3cb11 Mon Sep 17 00:00:00 2001 From: Chip Hogg Date: Thu, 13 Aug 2026 16:00:18 -0400 Subject: [PATCH] Finish documenting UDLs and making them available We landed UDLs that make `Constant` (which is amazing!), but we didn't fully propagate them everywhere that makes sense. This PR adds the UDL include files to the installation instructions, and explains how to get them, linking to the UDL docs. We also add `--literals` and `--all-literals` command line parameters to the single file script in the obvious way. And since the "all units" files are pretty clearly playing the role of "just give me everything; I don't care about compilation speed", I enabled `--all-literals` in the all-units files, rather than adding a "yes/no literals" variant of each, which would explode us from 4 to 8 published headers. This will make literals available in godbolt now, which is great. (As an aside, for calibration purposes: even though this is the "don't care about compilation speed" option, we should still be dramatically faster than mp-units.) --- BUILD.bazel | 10 +++++++++- docs/install.md | 9 +++++++-- tools/bin/make-single-file | 28 ++++++++++++++++++++++++++-- 3 files changed, 42 insertions(+), 5 deletions(-) diff --git a/BUILD.bazel b/BUILD.bazel index 48b0998f..7216e1dd 100644 --- a/BUILD.bazel +++ b/BUILD.bazel @@ -90,7 +90,7 @@ BASE_UNIT_STRING = " ".join(BASE_UNITS) GIT_ID_CMD = "cat bazel-out/stable-status.txt | grep STABLE_GIT_ID | sed 's/STABLE_GIT_ID \\(.*\\)/\\1/' | tr -d '\\n'" -CMD_ROOT = "$(location tools/bin/make-single-file) {extra_opts} {units} {all_constants} --version-id $$({id_cmd}) > $(OUTS)" +CMD_ROOT = "$(location tools/bin/make-single-file) {extra_opts} {units} {all_literals} {all_constants} --version-id $$({id_cmd}) > $(OUTS)" ################################################################################ # Release single-file package `au.hh` @@ -101,6 +101,7 @@ genrule( outs = ["docs/au.hh"], cmd = CMD_ROOT.format( all_constants = "", + all_literals = "", extra_opts = "", id_cmd = GIT_ID_CMD, units = "--units " + BASE_UNIT_STRING, @@ -125,6 +126,7 @@ genrule( outs = ["docs/au_noio.hh"], cmd = CMD_ROOT.format( all_constants = "", + all_literals = "", extra_opts = "--noio", id_cmd = GIT_ID_CMD, units = "--units " + BASE_UNIT_STRING, @@ -149,6 +151,7 @@ genrule( outs = ["docs/au_all_units.hh"], cmd = CMD_ROOT.format( all_constants = "--all-constants", + all_literals = "--all-literals", extra_opts = "", id_cmd = GIT_ID_CMD, units = "--all-units", @@ -173,6 +176,7 @@ genrule( outs = ["docs/au_all_units_noio.hh"], cmd = CMD_ROOT.format( all_constants = "--all-constants", + all_literals = "--all-literals", extra_opts = "--noio", id_cmd = GIT_ID_CMD, units = "--all-units", @@ -197,6 +201,7 @@ genrule( outs = ["docs/au_stdformat.hh"], cmd = CMD_ROOT.format( all_constants = "", + all_literals = "", extra_opts = "--std-format", id_cmd = GIT_ID_CMD, units = "--units " + BASE_UNIT_STRING, @@ -217,6 +222,7 @@ genrule( outs = ["docs/au_stdformat_noio.hh"], cmd = CMD_ROOT.format( all_constants = "", + all_literals = "", extra_opts = "--std-format --noio", id_cmd = GIT_ID_CMD, units = "--units " + BASE_UNIT_STRING, @@ -237,6 +243,7 @@ genrule( outs = ["docs/au_all_units_stdformat.hh"], cmd = CMD_ROOT.format( all_constants = "--all-constants", + all_literals = "--all-literals", extra_opts = "--std-format", id_cmd = GIT_ID_CMD, units = "--all-units", @@ -257,6 +264,7 @@ genrule( outs = ["docs/au_all_units_stdformat_noio.hh"], cmd = CMD_ROOT.format( all_constants = "--all-constants", + all_literals = "--all-literals", extra_opts = "--std-format --noio", id_cmd = GIT_ID_CMD, units = "--all-units", diff --git a/docs/install.md b/docs/install.md index 2d68ba3a..d746c19e 100644 --- a/docs/install.md +++ b/docs/install.md @@ -96,7 +96,7 @@ to your `deps` attribute, and include the appropriate files. | Dependency | Headers provided | Notes | |------------|------------------|-------| -| `@au//au` | `"au/au.hh"`
`"au/fwd.hh"`
`"au/units/*.hh"`
`"au/units/*_fwd.hh"`
`"au/constants/*.hh"` | Core library functionality. See [all available units](https://github.com/aurora-opensource/au/tree/main/au/units) and [constants](./reference/constant.md#built-in) | +| `@au//au` | `"au/au.hh"`
`"au/fwd.hh"`
`"au/units/*.hh"`
`"au/units/*_fwd.hh"`
`"au/units/literals/*.hh"`
`"au/constants/*.hh"` | Core library functionality. See [all available units](https://github.com/aurora-opensource/au/tree/main/au/units), [unit literals](./reference/constant.md#unit-literals), and [constants](./reference/constant.md#built-in) | | `@au//au:io` | `"au/io.hh"` | `operator<<` support | | `@au//au:std_format` | `"au/std_format.hh"` | `std::format` support[^1] | | `@au//au:testing` | `"au/testing.hh"` | Utilities for writing googletest tests
_Note:_ `testonly = True` | @@ -176,7 +176,7 @@ In either case, here are the main targets and include files provided by the Au l | Target | Headers provided | Notes | |--------|------------------|-------| -| `Au::au` | `"au/au.hh"`
`"au/fwd.hh"`
`"au/io.hh"`
`"au/std_format.hh"`[^1]
`"au/units/*.hh"`
`"au/units/*_fwd.hh"`
`"au/constants/*.hh"` | Core library functionality. See [all available units](https://github.com/aurora-opensource/au/tree/main/au/units) | +| `Au::au` | `"au/au.hh"`
`"au/fwd.hh"`
`"au/io.hh"`
`"au/std_format.hh"`[^1]
`"au/units/*.hh"`
`"au/units/*_fwd.hh"`
`"au/units/literals/*.hh"`
`"au/constants/*.hh"` | Core library functionality. See [all available units](https://github.com/aurora-opensource/au/tree/main/au/units) and [unit literals](./reference/constant.md#unit-literals) | | `Au::testing` | `"au/testing.hh"` | Utilities for writing googletest tests | [^1]: Do not include `"au/std_format.hh"` unless you know that both your compiler and your build @@ -426,6 +426,11 @@ Here's how: - Similarly, to see the full list of available constants, search the `.hh` files in the `au/constants/` folder. For example, `speed_of_light` will include the contents of `"au/constants/speed_of_light.hh"`, which provides the constant `au::SPEED_OF_LIGHT`. + - To include [unit literals](./reference/constant.md#unit-literals), pass the `--literals` flag + with the units whose literals you want: for example,
+ `tools/bin/make-single-file --units meters seconds --literals meters`.
+ Each entry named here also pulls in the unit itself, so `--literals meters` works even if + `meters` isn't in the `--units` list. - Provide the `--noio` flag if you prefer to avoid the expense of the `` library. Now you have a file, `~/au.hh`, which you can add to your `third_party` folder. diff --git a/tools/bin/make-single-file b/tools/bin/make-single-file index f2fa32a1..2ff30856 100755 --- a/tools/bin/make-single-file +++ b/tools/bin/make-single-file @@ -51,6 +51,7 @@ def main(argv=None): filenames=filenames( main_files=args.main_files, units=args.units, + literals=args.literals, constants=args.constants, include_io=args.include_io, include_std_format=args.std_format, @@ -61,7 +62,7 @@ def main(argv=None): return 0 -def filenames(main_files, units, constants, include_io, include_std_format): +def filenames(main_files, units, literals, constants, include_io, include_std_format): """Construct the list of project filenames to include. The script will be sure to include all of these, and will also include any @@ -70,6 +71,7 @@ def filenames(main_files, units, constants, include_io, include_std_format): names = ( ["au/au.hh"] + [f"au/units/{u}.hh" for u in units] + + [f"au/units/literals/{u}.hh" for u in literals] + [f"au/constants/{c.lower()}.hh" for c in constants] + main_files ) @@ -96,6 +98,19 @@ def parse_command_line_args(argv): help="Include all units (may slow compilation!)", ) + literal_group = parser.add_mutually_exclusive_group(required=False) + literal_group.add_argument( + "--literals", + nargs="*", + default=[], + help="The units whose unit literals to include (implies the unit itself)", + ) + literal_group.add_argument( + "--all-literals", + action="store_true", + help="Include all unit literals (may slow compilation!)", + ) + constant_group = parser.add_mutually_exclusive_group(required=False) constant_group.add_argument( "--constants", nargs="*", default=[], help="The constants to include" @@ -134,7 +149,8 @@ def enumerate_units_and_constants(args): Massage args object so that it's "as if" user had specified all units/constants manually. This means that if `--all-units` is specified, we populate the `units` list with every existing - entry, and then delete `--all-units`, and similarly for `--all-constants`. + entry, and then delete `--all-units`, and similarly for `--all-literals` and + `--all-constants`. """ def looks_like_header(f): return f.endswith(".hh") and not f.endswith("_fwd.hh") @@ -145,6 +161,12 @@ def enumerate_units_and_constants(args): ] del args.all_units + if args.all_literals: + args.literals = [ + f[:-3] for f in os.listdir("au/units/literals/") if looks_like_header(f) + ] + del args.all_literals + if args.all_constants: args.constants = [ f[:-3].upper() @@ -296,6 +318,8 @@ def manifest(args): "List of included units:", ] + [f" {u}" for u in sorted(args.units)] + + ["List of included unit literals:"] + + [f" {u}" for u in sorted(args.literals)] + ["List of included constants:"] + [f" {c}" for c in sorted(args.constants)] )