Explicitly expose a set of build system dependencies

.github/workflows/verify-pull-request.yml

@@ -27,3 +27,14 @@ jobs:
         with:
           options: "--check --verbose"
           version: "24.8.0"
+  check-build-json:
+    name: "Check build.json"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: bazel-contrib/[email protected]
+        with:
+          bazelisk-cache: true
+          disk-cache: "verify-pr:check-build-json"
+          repository-cache: true
+      - run: python3 scripts/build_helpers/manage_build_json.py --validate

build.json

@@ -0,0 +1,68 @@
+{
+  // A list of all source files required to build the Emboss compiler.
+  "embossc_sources": [
+    "compiler/__init__.py",
+    "compiler/back_end/__init__.py",
+    "compiler/back_end/cpp/__init__.py",
+    "compiler/back_end/cpp/attributes.py",
+    "compiler/back_end/cpp/emboss_codegen_cpp.py",
+    "compiler/back_end/cpp/generated_code_templates",
+    "compiler/back_end/cpp/header_generator.py",
+    "compiler/back_end/util/__init__.py",
+    "compiler/back_end/util/code_template.py",
+    "compiler/front_end/__init__.py",
+    "compiler/front_end/attribute_checker.py",
+    "compiler/front_end/attributes.py",
+    "compiler/front_end/constraints.py",
+    "compiler/front_end/dependency_checker.py",
+    "compiler/front_end/emboss_front_end.py",
+    "compiler/front_end/error_examples",
+    "compiler/front_end/expression_bounds.py",
+    "compiler/front_end/generated/cached_parser.py",
+    "compiler/front_end/glue.py",
+    "compiler/front_end/lr1.py",
+    "compiler/front_end/make_parser.py",
+    "compiler/front_end/module_ir.py",
+    "compiler/front_end/parser.py",
+    "compiler/front_end/prelude.emb",
+    "compiler/front_end/reserved_words",
+    "compiler/front_end/symbol_resolver.py",
+    "compiler/front_end/synthetics.py",
+    "compiler/front_end/tokenizer.py",
+    "compiler/front_end/type_check.py",
+    "compiler/front_end/write_inference.py",
+    "compiler/util/__init__.py",
+    "compiler/util/attribute_util.py",
+    "compiler/util/error.py",
+    "compiler/util/expression_parser.py",
+    "compiler/util/ir_data.py",
+    "compiler/util/ir_data_fields.py",
+    "compiler/util/ir_data_utils.py",
+    "compiler/util/ir_util.py",
+    "compiler/util/name_conversion.py",
+    "compiler/util/parser_types.py",
+    "compiler/util/parser_util.py",
+    "compiler/util/resources.py",
+    "compiler/util/simple_memoizer.py",
+    "compiler/util/traverse_ir.py",
+    "embossc"
+  ],
+  // A list of all source files required for the Emboss C++ runtime.
+  "emboss_runtime_cpp_sources": [
+    "runtime/cpp/emboss_arithmetic.h",
+    "runtime/cpp/emboss_arithmetic_all_known_generated.h",
+    "runtime/cpp/emboss_arithmetic_maximum_operation_generated.h",
+    "runtime/cpp/emboss_array_view.h",
+    "runtime/cpp/emboss_bit_util.h",
+    "runtime/cpp/emboss_constant_view.h",
+    "runtime/cpp/emboss_cpp_types.h",
+    "runtime/cpp/emboss_cpp_util.h",
+    "runtime/cpp/emboss_defines.h",
+    "runtime/cpp/emboss_enum_view.h",
+    "runtime/cpp/emboss_maybe.h",
+    "runtime/cpp/emboss_memory_util.h",
+    "runtime/cpp/emboss_prelude.h",
+    "runtime/cpp/emboss_text_util.h",
+    "runtime/cpp/emboss_view_parameters.h"
+  ]
+}

doc/contributing.md

@@ -29,6 +29,41 @@ comes from a non-Google open source project needs to have an acceptable license
 and be committed to the Emboss repository in a specific location.
 
 
+### Updating Build Helper Files
+
+The Emboss project provides a set of generated files in the `gen/` directory
+that can be used by other build systems (like CMake, GN, etc.) to easily
+include the Emboss compiler and C++ runtime sources.
+
+These files are generated from a single source of truth: `build.json`.
+
+-   **`build.json`**: This file, located in the project root, contains the
+    canonical lists of source files required for the compiler and the C++
+    runtime. It is the only file in this system that should be manually
+    edited, though it is typically updated via a script.
+
+-   **`gen/`**: This directory contains the generated helper files. **Do not
+    edit these files directly**, as they will be overwritten.
+
+If you change the dependencies of the Emboss compiler or runtime in the Bazel
+build system, you will need to update `build.json` and regenerate the helper
+files.
+
+-   To update `build.json` with the latest sources from Bazel, run:
+    ```bash
+    ./scripts/build_helpers/manage_build_json.py
+    ```
+
+-   To regenerate the files in `gen/` after modifying `build.json`, run:
+    ```bash
+    ./scripts/build_helpers/generate_build_files.py
+    ```
+
+A CI check is in place to ensure that `build.json` is always in sync with the
+Bazel build. If this check fails, you will need to run the `manage_build_json.py`
+script and commit the changes.
+
+
 ### How-To Guides
 
 This document covers the process of getting a change into the main Emboss

gen/sources.bzl

@@ -0,0 +1,83 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+# Automatically generated by generate_build_files.py.
+# Do not edit this file directly.
+
+EMBOSSC_SOURCES = [
+    "compiler/__init__.py",
+    "compiler/back_end/__init__.py",
+    "compiler/back_end/cpp/__init__.py",
+    "compiler/back_end/cpp/attributes.py",
+    "compiler/back_end/cpp/emboss_codegen_cpp.py",
+    "compiler/back_end/cpp/generated_code_templates",
+    "compiler/back_end/cpp/header_generator.py",
+    "compiler/back_end/util/__init__.py",
+    "compiler/back_end/util/code_template.py",
+    "compiler/front_end/__init__.py",
+    "compiler/front_end/attribute_checker.py",
+    "compiler/front_end/attributes.py",
+    "compiler/front_end/constraints.py",
+    "compiler/front_end/dependency_checker.py",
+    "compiler/front_end/emboss_front_end.py",
+    "compiler/front_end/error_examples",
+    "compiler/front_end/expression_bounds.py",
+    "compiler/front_end/generated/cached_parser.py",
+    "compiler/front_end/glue.py",
+    "compiler/front_end/lr1.py",
+    "compiler/front_end/make_parser.py",
+    "compiler/front_end/module_ir.py",
+    "compiler/front_end/parser.py",
+    "compiler/front_end/prelude.emb",
+    "compiler/front_end/reserved_words",
+    "compiler/front_end/symbol_resolver.py",
+    "compiler/front_end/synthetics.py",
+    "compiler/front_end/tokenizer.py",
+    "compiler/front_end/type_check.py",
+    "compiler/front_end/write_inference.py",
+    "compiler/util/__init__.py",
+    "compiler/util/attribute_util.py",
+    "compiler/util/error.py",
+    "compiler/util/expression_parser.py",
+    "compiler/util/ir_data.py",
+    "compiler/util/ir_data_fields.py",
+    "compiler/util/ir_data_utils.py",
+    "compiler/util/ir_util.py",
+    "compiler/util/name_conversion.py",
+    "compiler/util/parser_types.py",
+    "compiler/util/parser_util.py",
+    "compiler/util/resources.py",
+    "compiler/util/simple_memoizer.py",
+    "compiler/util/traverse_ir.py",
+    "embossc",
+]
+
+EMBOSS_RUNTIME_CPP_SOURCES = [
+    "runtime/cpp/emboss_arithmetic.h",
+    "runtime/cpp/emboss_arithmetic_all_known_generated.h",
+    "runtime/cpp/emboss_arithmetic_maximum_operation_generated.h",
+    "runtime/cpp/emboss_array_view.h",
+    "runtime/cpp/emboss_bit_util.h",
+    "runtime/cpp/emboss_constant_view.h",
+    "runtime/cpp/emboss_cpp_types.h",
+    "runtime/cpp/emboss_cpp_util.h",
+    "runtime/cpp/emboss_defines.h",
+    "runtime/cpp/emboss_enum_view.h",
+    "runtime/cpp/emboss_maybe.h",
+    "runtime/cpp/emboss_memory_util.h",
+    "runtime/cpp/emboss_prelude.h",
+    "runtime/cpp/emboss_text_util.h",
+    "runtime/cpp/emboss_view_parameters.h",
+]

gen/sources.cmake

@@ -0,0 +1,83 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+# Automatically generated by generate_build_files.py.
+# Do not edit this file directly.
+
+set(EMBOSSC_SOURCES
+  "compiler/__init__.py"
+  "compiler/back_end/__init__.py"
+  "compiler/back_end/cpp/__init__.py"
+  "compiler/back_end/cpp/attributes.py"
+  "compiler/back_end/cpp/emboss_codegen_cpp.py"
+  "compiler/back_end/cpp/generated_code_templates"
+  "compiler/back_end/cpp/header_generator.py"
+  "compiler/back_end/util/__init__.py"
+  "compiler/back_end/util/code_template.py"
+  "compiler/front_end/__init__.py"
+  "compiler/front_end/attribute_checker.py"
+  "compiler/front_end/attributes.py"
+  "compiler/front_end/constraints.py"
+  "compiler/front_end/dependency_checker.py"
+  "compiler/front_end/emboss_front_end.py"
+  "compiler/front_end/error_examples"
+  "compiler/front_end/expression_bounds.py"
+  "compiler/front_end/generated/cached_parser.py"
+  "compiler/front_end/glue.py"
+  "compiler/front_end/lr1.py"
+  "compiler/front_end/make_parser.py"
+  "compiler/front_end/module_ir.py"
+  "compiler/front_end/parser.py"
+  "compiler/front_end/prelude.emb"
+  "compiler/front_end/reserved_words"
+  "compiler/front_end/symbol_resolver.py"
+  "compiler/front_end/synthetics.py"
+  "compiler/front_end/tokenizer.py"
+  "compiler/front_end/type_check.py"
+  "compiler/front_end/write_inference.py"
+  "compiler/util/__init__.py"
+  "compiler/util/attribute_util.py"
+  "compiler/util/error.py"
+  "compiler/util/expression_parser.py"
+  "compiler/util/ir_data.py"
+  "compiler/util/ir_data_fields.py"
+  "compiler/util/ir_data_utils.py"
+  "compiler/util/ir_util.py"
+  "compiler/util/name_conversion.py"
+  "compiler/util/parser_types.py"
+  "compiler/util/parser_util.py"
+  "compiler/util/resources.py"
+  "compiler/util/simple_memoizer.py"
+  "compiler/util/traverse_ir.py"
+  "embossc"
+)
+
+set(EMBOSS_RUNTIME_CPP_SOURCES
+  "runtime/cpp/emboss_arithmetic.h"
+  "runtime/cpp/emboss_arithmetic_all_known_generated.h"
+  "runtime/cpp/emboss_arithmetic_maximum_operation_generated.h"
+  "runtime/cpp/emboss_array_view.h"
+  "runtime/cpp/emboss_bit_util.h"
+  "runtime/cpp/emboss_constant_view.h"
+  "runtime/cpp/emboss_cpp_types.h"
+  "runtime/cpp/emboss_cpp_util.h"
+  "runtime/cpp/emboss_defines.h"
+  "runtime/cpp/emboss_enum_view.h"
+  "runtime/cpp/emboss_maybe.h"
+  "runtime/cpp/emboss_memory_util.h"
+  "runtime/cpp/emboss_prelude.h"
+  "runtime/cpp/emboss_text_util.h"
+  "runtime/cpp/emboss_view_parameters.h"
+)

gen/sources.gni

@@ -0,0 +1,83 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+# Automatically generated by generate_build_files.py.
+# Do not edit this file directly.
+
+embossc_sources = [
+  "compiler/__init__.py",
+  "compiler/back_end/__init__.py",
+  "compiler/back_end/cpp/__init__.py",
+  "compiler/back_end/cpp/attributes.py",
+  "compiler/back_end/cpp/emboss_codegen_cpp.py",
+  "compiler/back_end/cpp/generated_code_templates",
+  "compiler/back_end/cpp/header_generator.py",
+  "compiler/back_end/util/__init__.py",
+  "compiler/back_end/util/code_template.py",
+  "compiler/front_end/__init__.py",
+  "compiler/front_end/attribute_checker.py",
+  "compiler/front_end/attributes.py",
+  "compiler/front_end/constraints.py",
+  "compiler/front_end/dependency_checker.py",
+  "compiler/front_end/emboss_front_end.py",
+  "compiler/front_end/error_examples",
+  "compiler/front_end/expression_bounds.py",
+  "compiler/front_end/generated/cached_parser.py",
+  "compiler/front_end/glue.py",
+  "compiler/front_end/lr1.py",
+  "compiler/front_end/make_parser.py",
+  "compiler/front_end/module_ir.py",
+  "compiler/front_end/parser.py",
+  "compiler/front_end/prelude.emb",
+  "compiler/front_end/reserved_words",
+  "compiler/front_end/symbol_resolver.py",
+  "compiler/front_end/synthetics.py",
+  "compiler/front_end/tokenizer.py",
+  "compiler/front_end/type_check.py",
+  "compiler/front_end/write_inference.py",
+  "compiler/util/__init__.py",
+  "compiler/util/attribute_util.py",
+  "compiler/util/error.py",
+  "compiler/util/expression_parser.py",
+  "compiler/util/ir_data.py",
+  "compiler/util/ir_data_fields.py",
+  "compiler/util/ir_data_utils.py",
+  "compiler/util/ir_util.py",
+  "compiler/util/name_conversion.py",
+  "compiler/util/parser_types.py",
+  "compiler/util/parser_util.py",
+  "compiler/util/resources.py",
+  "compiler/util/simple_memoizer.py",
+  "compiler/util/traverse_ir.py",
+  "embossc",
+]
+
+emboss_runtime_cpp_sources = [
+  "runtime/cpp/emboss_arithmetic.h",
+  "runtime/cpp/emboss_arithmetic_all_known_generated.h",
+  "runtime/cpp/emboss_arithmetic_maximum_operation_generated.h",
+  "runtime/cpp/emboss_array_view.h",
+  "runtime/cpp/emboss_bit_util.h",
+  "runtime/cpp/emboss_constant_view.h",
+  "runtime/cpp/emboss_cpp_types.h",
+  "runtime/cpp/emboss_cpp_util.h",
+  "runtime/cpp/emboss_defines.h",
+  "runtime/cpp/emboss_enum_view.h",
+  "runtime/cpp/emboss_maybe.h",
+  "runtime/cpp/emboss_memory_util.h",
+  "runtime/cpp/emboss_prelude.h",
+  "runtime/cpp/emboss_text_util.h",
+  "runtime/cpp/emboss_view_parameters.h",
+]