Extra comments

compiler/noirc_driver/src/lib.rs

@@ -334,6 +334,8 @@ pub fn compute_function_abi(
 ///
 /// On success this returns the compiled program alongside any warnings that were found.
 /// On error this returns the non-empty list of warnings and errors.
+///
+/// See [compile_no_check] for further information about the use of `cached_program`.
 pub fn compile_main(
     context: &mut Context,
     crate_id: CrateId,
@@ -555,6 +557,12 @@ pub const DEFAULT_EXPRESSION_WIDTH: ExpressionWidth = ExpressionWidth::Bounded {
 /// Compile the current crate using `main_function` as the entrypoint.
 ///
 /// This function assumes [`check_crate`] is called beforehand.
+///
+/// The returned program is backend-agnostic and so must go through a transformation pass before usage in proof generation.
+/// These transformations are _not_ covered by the check that decides whether we can use the cached artifact.
+/// That comparison is based on on [CompiledProgram::hash] which is a persisted version of the hash of the input
+/// [`ast::Program`][noirc_frontend::monomorphization::ast::Program], whereas the output [`circuit::Program`][acir::circuit::Program]
+/// contains the final optimized ACIR opcodes, including the transformation done after this compilation.
 #[tracing::instrument(level = "trace", skip_all, fields(function_name = context.function_name(&main_function)))]
 pub fn compile_no_check(
     context: &mut Context,
@@ -571,6 +579,7 @@ pub fn compile_no_check(
 
     let hash = fxhash::hash64(&program);
     let hashes_match = cached_program.as_ref().map_or(false, |program| program.hash == hash);
+
     if options.show_monomorphized {
         println!("{program}");
     }

compiler/noirc_evaluator/src/ssa.rs

@@ -238,7 +238,7 @@ impl SsaProgramArtifact {
     }
 }
 
-/// Compiles the [`Program`] into [`ACIR``][acvm::acir::circuit::Program].
+/// Compiles the [`Program`] into [`ACIR`][acvm::acir::circuit::Program].
 ///
 /// The output ACIR is backend-agnostic and so must go through a transformation pass before usage in proof generation.
 #[tracing::instrument(level = "trace", skip_all)]

tooling/nargo/src/ops/check.rs

@@ -2,8 +2,8 @@ use acvm::compiler::CircuitSimulator;
 use noirc_driver::{CompiledProgram, ErrorsAndWarnings};
 use noirc_errors::{CustomDiagnostic, FileDiagnostic};
 
+/// Run each function through a circuit simulator to check that they are solvable.
 pub fn check_program(compiled_program: &CompiledProgram) -> Result<(), ErrorsAndWarnings> {
-    // Check if the program is solvable
     for (i, circuit) in compiled_program.program.functions.iter().enumerate() {
         let mut simulator = CircuitSimulator::default();
         if !simulator.check_circuit(circuit) {

tooling/nargo/src/ops/transform.rs

@@ -6,6 +6,7 @@ use iter_extended::vecmap;
 use noirc_driver::{CompiledContract, CompiledProgram};
 use noirc_errors::debug_info::DebugInfo;
 
+/// Apply ACVM optimizations on the circuit.
 pub fn transform_program(
     mut compiled_program: CompiledProgram,
     expression_width: ExpressionWidth,
@@ -18,14 +19,14 @@ pub fn transform_program(
     compiled_program
 }
 
+/// Apply the optimizing transformation on each function in the contract.
 pub fn transform_contract(
     contract: CompiledContract,
     expression_width: ExpressionWidth,
 ) -> CompiledContract {
     let functions = vecmap(contract.functions, |mut func| {
         func.bytecode =
             transform_program_internal(func.bytecode, &mut func.debug, expression_width);
-
         func
     });
 

tooling/nargo_cli/src/cli/compile_cmd.rs

@@ -65,6 +65,7 @@ pub(crate) fn run(args: CompileCommand, config: NargoConfig) -> Result<(), CliEr
     Ok(())
 }
 
+/// Continuously recompile the workspace on any Noir file change event.
 fn watch_workspace(workspace: &Workspace, compile_options: &CompileOptions) -> notify::Result<()> {
     let (tx, rx) = std::sync::mpsc::channel();
 
@@ -108,6 +109,8 @@ fn watch_workspace(workspace: &Workspace, compile_options: &CompileOptions) -> n
     Ok(())
 }
 
+/// Parse and compile the entire workspace, then report errors.
+/// This is the main entry point used by all other commands that need compilation.
 pub(super) fn compile_workspace_full(
     workspace: &Workspace,
     compile_options: &CompileOptions,
@@ -129,6 +132,8 @@ pub(super) fn compile_workspace_full(
     Ok(())
 }
 
+/// Compile binary and contract packages.
+/// Returns the merged warnings or errors.
 fn compile_workspace(
     file_manager: &FileManager,
     parsed_files: &ParsedFiles,
@@ -144,6 +149,7 @@ fn compile_workspace(
     // Compile all of the packages in parallel.
     let program_warnings_or_errors: CompilationResult<()> =
         compile_programs(file_manager, parsed_files, workspace, &binary_packages, compile_options);
+
     let contract_warnings_or_errors: CompilationResult<()> = compiled_contracts(
         file_manager,
         parsed_files,
@@ -164,13 +170,16 @@ fn compile_workspace(
     }
 }
 
+/// Compile the given binary packages in the workspace.
 fn compile_programs(
     file_manager: &FileManager,
     parsed_files: &ParsedFiles,
     workspace: &Workspace,
     binary_packages: &[Package],
     compile_options: &CompileOptions,
 ) -> CompilationResult<()> {
+    // Load any existing artifact for a given package, _iff_ it was compiled with the same nargo version.
+    // The loaded circuit includes backend specific transformations, which might be different from the current target.
     let load_cached_program = |package| {
         let program_artifact_path = workspace.package_build_path(package);
         read_program_from_file(program_artifact_path)
@@ -180,6 +189,7 @@ fn compile_programs(
     };
 
     let compile_package = |package| {
+        // Compile the program, or use the cached artifacts if it matches.
         let (program, warnings) = compile_program(
             file_manager,
             parsed_files,
@@ -188,11 +198,14 @@ fn compile_programs(
             compile_options,
             load_cached_program(package),
         )?;
-
+        // Choose the target width for the final, backend specific transformation.
         let target_width =
             get_target_width(package.expression_width, compile_options.expression_width);
+        // Run ACVM optimizations and set the target width.
         let program = nargo::ops::transform_program(program, target_width);
+        // Check solvability.
         nargo::ops::check_program(&program)?;
+        // Overwrite the build artifacts with the final circuit, which includes the backend specific transformations.
         save_program_to_file(&program.into(), &package.name, workspace.target_directory_path());
 
         Ok(((), warnings))
@@ -208,13 +221,15 @@ fn compile_programs(
     collect_errors(program_results).map(|(_, warnings)| ((), warnings))
 }
 
+/// Compile the given contracts in the workspace.
 fn compiled_contracts(
     file_manager: &FileManager,
     parsed_files: &ParsedFiles,
     contract_packages: &[Package],
     compile_options: &CompileOptions,
     target_dir: &Path,
 ) -> CompilationResult<()> {
+    // TODO(6669): Should we look for cached artifacts?
     let contract_results: Vec<CompilationResult<()>> = contract_packages
         .par_iter()
         .map(|package| {
@@ -223,6 +238,7 @@ fn compiled_contracts(
             let target_width =
                 get_target_width(package.expression_width, compile_options.expression_width);
             let contract = nargo::ops::transform_contract(contract, target_width);
+            // TODO(6669): Should the circuits in the contracts run through the simulator?
             save_contract(contract, package, target_dir, compile_options.show_artifact_paths);
             Ok(((), warnings))
         })

tooling/nargo_cli/tests/stdlib-props.rs

@@ -61,6 +61,7 @@ fn prepare_and_compile_snippet(
 ) -> CompilationResult<CompiledProgram> {
     let (mut context, root_crate_id) = prepare_snippet(source);
     let options = CompileOptions { force_brillig, ..Default::default() };
+    // TODO: Run nargo::ops::transform_program?
     compile_main(&mut context, root_crate_id, &options, None)
 }