Documentation

Driver.Pipeline

One compile, end to end, as a function: source text in, a PipelineResult out. No process exit, no printing, no progress animation — those belong to whoever is driving.

Driver/Modules.lean's compileModule only takes a module as far as type checking, and caches that; every pass after it (well-formedness, Typed2Computable, Computable2Guarded, Guarded2Network) runs once, here, against the checked main module rather than per EXTENDS dependency. It is separate from the CLI because two consumers need it: the CLI itself, and tests/regression's runner.

inductive PipelineError :

Any way a compile can fail, from any stage. One type so a caller handles one thing; PipelineError.stage recovers where it came from.

Instances For

    This error's diagnostic code, from whichever pass produced it. The same identity CompilerDiagnostic.pretty prints in error[E0042]:, available without going through the rendered text — which is what a regression fixture asserts on.

    Equations
    Instances For

      Where this error points, from whichever pass produced it: the same span CompilerDiagnostic.pretty underlines. What a regression fixture asserts on when the position is the thing under test, which code and stage cannot express — an error relocated to the start of its enclosing production still carries the right code and stage.

      Equations
      Instances For

        This error's notesOf, from whichever pass produced it — the extra, independently-positioned source snippets CompilerDiagnostic.pretty renders after the hints. What a regression fixture asserts on (Tests/Expectation.lean's notePositions) when a diagnostic's identity isn't enough and where its notes point matters too (e.g. a duplicate-declaration error's note at the first declaration).

        Equations
        Instances For
          def PipelineError.render (sources : SourceRegistry) (mainLines : List String.Slice) (colored : Bool) :

          Rendered form of err, against the source lines it belongs to: a driver error renders against its own module's lines (an error inside an EXTENDS-ed dependency is not about the main module), looked up in sources; everything past the driver only ever concerns the main module, so it renders against mainLines. Pure — rendering a diagnostic needs no IO.

          Equations
          Instances For

            A compile's non-fatal diagnostics, from any stage. Mirrors PipelineError, one constructor per group of stages that can produce one: everything up to type checking reports through DriverWarning, and well-formedness through its own. The passes after it still report at MonadDiagnostic Empty ε and so cannot warn at all; each grows a constructor here on the day it can.

            Instances For

              The -W<name>/-Wno-<name> name a given warning is filtered under — forwards to whichever wrapped warning's own.

              Equations
              Instances For

                The source lines this warning should render against, or none to fall back to the main module's. Only a driver warning can belong to another module — everything past the driver runs on the main module alone, the same way PipelineError.render treats those errors.

                Equations
                Instances For
                  @[implicit_reducible]
                  Equations
                  • One or more equations did not get rendered due to their size.
                  structure PipelineResult :

                  Everything one compile produced: its diagnostics, how far it got, the sources it read (needed to render those diagnostics), and each stage's output for whoever wants to inspect or dump it. An artifact is none when its stage never ran — either because the compile failed earlier, or because the module has no PlusCal algorithm, in which case there is nothing for Computable2Guarded onward to do and reached stops at .computable.

                  Instances For

                    Did the compile succeed?

                    Equations
                    Instances For

                      The warnings this compile actually reports, in the order they were raised: everything a pass raised, minus what -Wno-<name> turns off.

                      Separate from renderWarnings because "which warnings survive -W" and "what they look like" are different questions, and more than one caller wants the first without the second — PipelineResult .warnings is deliberately the unfiltered record of what the passes raised, so anything asking whether a warning is suppressed has to apply the filter, and should not have to re-implement it.

                      Equations
                      Instances For
                        structure PipelineHooks :

                        What the driver reports as it goes. Plain IO actions: a caller drives a spinner, a test runner collects them into a list, and neither needs to know the driver's monad.

                        • onModuleEvent : String → ModuleOutcome → IO Unit

                          A module finished (or failed).

                        • onModuleProgress : String → IO Unit

                          Work started, or resumed, on a module.

                        • logLine : String → IO Unit

                          A line the driver wants shown now, ahead of the final result.

                        Instances For
                          def runPipeline (source : String) (containingDir : Option System.FilePath) (moduleId : String) (expectedName : Option String := none) (hooks : PipelineHooks := { }) :

                          Compile source all the way through, reporting progress through hooks.

                          containingDir is where EXTENDS resolution starts looking (none when the source came from stdin, which has no directory of its own); moduleId is the key this module's source is registered under, and the one DriverErrors from it are tagged with; expectedName is what the module must call itself, i.e. its file's stem — none for stdin, which has no filename to agree with.

                          Never throws and never exits: every failure comes back as PipelineResult.error, tagged with the stage it came from.

                          Equations
                          • One or more equations did not get rendered due to their size.
                          Instances For
                            def runPipelineIO (flags : FlagsEnv) (source : String) (containingDir : Option System.FilePath) (moduleId : String) (expectedName : Option String := none) (hooks : PipelineHooks := { }) :

                            runPipeline with its flags and its state supplied: one compile, self-contained, from IO. Each call starts from a fresh DriverState, so nothing — module cache, fresh-name counter, source registry — carries over between two compiles in the same process. Common/Position.lean's span map is the one piece of per-compile state that is not in DriverState, and needs none: it is process-global and grows rather than resets, which is safe for the reason its own module doc gives.

                            Equations
                            Instances For

                              This compile's reported warnings, rendered, in the order they were raised. Each renders against its own module's source lines, falling back to mainLines. Pure: the caller decides where the lines go (Fugue.lean routes them through its spinner, the regression runner asserts on them).

                              Equations
                              • One or more equations did not get rendered due to their size.
                              Instances For

                                This compile's fatal error, rendered, if it failed.

                                Equations
                                Instances For

                                  Every diagnostic line this result should print, in report order: warnings first, then the error if there was one.

                                  Equations
                                  Instances For

                                    The one-line account of what a successful compile produced, or none if it failed before producing a checked module.

                                    Equations
                                    • One or more equations did not get rendered due to their size.
                                    Instances For