|
| 1 | +This release introduces the Lean module system, which allows files to |
| 2 | +control the visibility of their contents for other files. In previous |
| 3 | +releases, this feature was available as a preview when the option |
| 4 | +`experimental.module` was set to `true`; it is now a fully supported |
| 5 | +feature of Lean. |
| 6 | + |
| 7 | +# Benefits |
| 8 | + |
| 9 | +Because modules reduce the amount of information exposed to other |
| 10 | +code, they speed up rebuilds because irrelevant changes can be |
| 11 | +ignored, they make it possible to be deliberate about API evolution by |
| 12 | +hiding details that may change from clients, they help proofs be |
| 13 | +checked faster by avoiding accidentally unfolding definitions, and |
| 14 | +they lead to smaller executable files through improved dead code |
| 15 | +elimination. |
| 16 | + |
| 17 | +# Visibility |
| 18 | + |
| 19 | +A source file is a module if it begins with the `module` keyword. By |
| 20 | +default, declarations in a module are private; the `public` modifier |
| 21 | +exports them. Proofs of theorems and bodies of definitions are private |
| 22 | +by default even when their signatures are public; the bodies of |
| 23 | +definitions can be made public by adding the `@[expose]` |
| 24 | +attribute. Theorems and opaque constants never expose their bodies. |
| 25 | + |
| 26 | +`public section` and `@[expose] section` change the default visibility |
| 27 | +of declarations in the section. |
| 28 | + |
| 29 | +# Imports |
| 30 | + |
| 31 | +Modules may only import other modules. By default, `import` adds the |
| 32 | +public information of the imported module to the private scope of the |
| 33 | +current module. Adding the `public` modifier to an import places the |
| 34 | +imported modules's public information in the public scope of the |
| 35 | +current module, exposing it in turn to the current module's clients. |
| 36 | + |
| 37 | +Within a package, `import all` can be used to import another module's |
| 38 | +private scope into the current module; this can be used to separate |
| 39 | +lemmas or tests from definition modules without exposing details to |
| 40 | +downstream clients. |
| 41 | + |
| 42 | +# Meta Code |
| 43 | + |
| 44 | +Code used in metaprograms must be marked `meta`. This ensures that the |
| 45 | +code is compiled and available for execution when it is needed during |
| 46 | +elaboration. Meta code may only reference other meta code. A whole |
| 47 | +module can be made available in the meta phase using `meta import`; |
| 48 | +this allows code to be shared across phases by importing the module in |
| 49 | +each phase. Code that is reachable from public metaprograms must be |
| 50 | +imported via `public meta import`, while local metaprograms can use |
| 51 | +plain `meta import` for their dependencies. |
| 52 | + |
| 53 | + |
| 54 | +The module system is described in detail in [the Lean language reference](https://lean-reference-manual-review.netlify.app/find/?domain=Verso.Genre.Manual.section&name=files). |
0 commit comments