From d3cf11776283b33b7373cf6b6bf26edd3717ffc0 Mon Sep 17 00:00:00 2001 From: Ziyang Liu Date: Thu, 1 Aug 2024 17:38:37 -0700 Subject: [PATCH] Restore auto generation of compiler option table (#6373) --- .gitignore | 4 +- .../reference/plutus-tx-compiler-options.md | 64 ++++++++++--------- .../app/GeneratePluginOptionsDoc.hs | 40 +++++++----- plutus-tx-plugin/src/PlutusTx/Options.hs | 12 ++-- 4 files changed, 67 insertions(+), 53 deletions(-) diff --git a/.gitignore b/.gitignore index d287326cc68..e51e4d9b553 100644 --- a/.gitignore +++ b/.gitignore @@ -75,6 +75,9 @@ pkgs/.stack *.code-workspace .*.sw* +# Doc site +yarn.lock + # Misc act-event.json .history/ @@ -109,4 +112,3 @@ plutus-pab/test-node/alonzo-purple/db *.timelog *.stacks .nvimrc - diff --git a/doc/docusaurus/docs/reference/plutus-tx-compiler-options.md b/doc/docusaurus/docs/reference/plutus-tx-compiler-options.md index 4fe6ff08b34..c000ef385e5 100644 --- a/doc/docusaurus/docs/reference/plutus-tx-compiler-options.md +++ b/doc/docusaurus/docs/reference/plutus-tx-compiler-options.md @@ -2,6 +2,11 @@ sidebar_position: 5 --- + + # Plutus Tx compiler options These options can be passed to the compiler via the `OPTIONS_GHC` pragma, for instance @@ -13,33 +18,34 @@ These options can be passed to the compiler via the `OPTIONS_GHC` pragma, for in For each boolean option, you can add a `no-` prefix to switch it off, such as `no-typecheck`, `no-simplifier-beta`. -| Option | Value Type | Default | Description | -|----------------------------------|---------------|---------|-------------| -| `conservative-optimisation` | Bool | False | When conservative optimisation is used, only the optimisations that never make the program worse (in terms of cost or size) are employed. Implies `no-relaxed-float-in`. | -| `context-level` | Int | 1 | Set context level for error messages. | -| `coverage-all` | Bool | False | Add all available coverage annotations in the trace output | -| `coverage-boolean` | Bool | False | Add boolean coverage annotations in the trace output | -| `coverage-location` | Bool | False | Add location coverage annotations in the trace output | -| `defer-errors` | Bool | False | If a compilation error happens and this option is turned on, the compilation error is suppressed and the original Haskell expression is replaced with a runtime-error expression. | -| `dump-compilation-trace` | Bool | False | Dump compilation trace for debugging | -| `dump-pir` | Bool | False | Dump Plutus IR | -| `dump-plc` | Bool | False | Dump Typed Plutus Core | -| `dump-uplc` | Bool | False | Dump Untyped Plutus Core | -| `max-cse-iterations` | Int | 4 | Set the max iterations for CSE | -| `max-simplifier-iterations-pir` | Int | 12 | Set the max iterations for the PIR simplifier | -| `max-simplifier-iterations-uplc` | Int | 12 | Set the max iterations for the UPLC simplifier | -| `optimize` | Bool | True | Run optimization passes such as simplification and floating let-bindings. | -| `pedantic` | Bool | False | Run type checker after each compilation pass | -| `profile-all` | ProfileOpts | None | Set profiling options to All, which adds tracing when entering and exiting a term. | -| `relaxed-float-in` | Bool | True | Use a more aggressive float-in pass, which often leads to reduced costs but may occasionally lead to slightly increased costs. | -| `remove-trace` | Bool | False | Eliminate calls to `trace` from Plutus Core | -| `simplifier-beta` | Bool | True | Run a simplification pass that performs beta transformations | -| `simplifier-inline` | Bool | True | Run a simplification pass that performs inlining | -| `simplifier-remove-dead-bindings`| Bool | True | Run a simplification pass that removes dead bindings | -| `simplifier-unwrap-cancel` | Bool | True | Run a simplification pass that cancels unwrap/wrap pairs | -| `strictify-bindings` | Bool | True | Run a simplification pass that makes bindings stricter | -| `target-version` | Version | 1.1.0 | The target Plutus Core language version | -| `typecheck` | Bool | True | Perform type checking during compilation. | -| `verbosity` | Verbosity | Quiet | Set logging verbosity level (0=Quiet, 1=Verbose, 2=Debug) | - +|Option|Value Type|Default|Description| +|-|-|-|-| +|`conservative-optimisation`|Bool|False|When conservative optimisation is used, only the optimisations that never make the program worse (in terms of cost or size) are employed. Implies `no-relaxed-float-in`, `no-inline-constants`, and `preserve-logging`.| +|`context-level`|Int|1|Set context level for error messages.| +|`coverage-all`|Bool|False|Add all available coverage annotations in the trace output| +|`coverage-boolean`|Bool|False|Add boolean coverage annotations in the trace output| +|`coverage-location`|Bool|False|Add location coverage annotations in the trace output| +|`defer-errors`|Bool|False|If a compilation error happens and this option is turned on, the compilation error is suppressed and the original Haskell expression is replaced with a runtime-error expression.| +|`dump-compilation-trace`|Bool|False|Dump compilation trace for debugging| +|`dump-pir`|Bool|False|Dump Plutus IR| +|`dump-tplc`|Bool|False|Dump Typed Plutus Core| +|`dump-uplc`|Bool|False|Dump Untyped Plutus Core| +|`inline-constants`|Bool|True|Always inline constants. Inlining constants always reduces script costs slightly, but may increase script sizes if a large constant is used more than once. Implied by `no-conservative-optimisation`.| +|`max-cse-iterations`|Int|4|Set the max iterations for CSE| +|`max-simplifier-iterations-pir`|Int|12|Set the max iterations for the PIR simplifier| +|`max-simplifier-iterations-uplc`|Int|12|Set the max iterations for the UPLC simplifier| +|`optimize`|Bool|True|Run optimization passes such as simplification and floating let-bindings.| +|`pedantic`|Bool|False|Run type checker after each compilation pass| +|`preserve-logging`|Bool|False|Turn off optimisations that may alter (i.e., add, remove or change the order of) trace messages. Implied by `conservative-optimisation`.| +|`profile-all`|ProfileOpts|None|Set profiling options to All, which adds tracing when entering and exiting a term.| +|`relaxed-float-in`|Bool|True|Use a more aggressive float-in pass, which often leads to reduced costs but may occasionally lead to slightly increased costs. Implied by `no-conservative-optimisation`.| +|`remove-trace`|Bool|False|Eliminate calls to `trace` from Plutus Core| +|`simplifier-beta`|Bool|True|Run a simplification pass that performs beta transformations| +|`simplifier-inline`|Bool|True|Run a simplification pass that performs inlining| +|`simplifier-remove-dead-bindings`|Bool|True|Run a simplification pass that removes dead bindings| +|`simplifier-unwrap-cancel`|Bool|True|Run a simplification pass that cancels unwrap/wrap pairs| +|`strictify-bindings`|Bool|True|Run a simplification pass that makes bindings stricter| +|`target-version`|Version|1.1.0|The target Plutus Core language version| +|`typecheck`|Bool|True|Perform type checking during compilation.| +|`verbosity`|Verbosity|Quiet|Set logging verbosity level (0=Quiet, 1=Verbose, 2=Debug)| diff --git a/plutus-tx-plugin/app/GeneratePluginOptionsDoc.hs b/plutus-tx-plugin/app/GeneratePluginOptionsDoc.hs index bad7ddb085d..27547633864 100644 --- a/plutus-tx-plugin/app/GeneratePluginOptionsDoc.hs +++ b/plutus-tx-plugin/app/GeneratePluginOptionsDoc.hs @@ -1,3 +1,4 @@ +-- editorconfig-checker-disable-file {-# LANGUAGE ApplicativeDo #-} {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE QuasiQuotes #-} @@ -40,29 +41,34 @@ main = do Text.writeFile (Text.unpack $ paramOutputFile params) optionsTable optionsTable :: Text -optionsTable = [fmt| -.. - This file is generated by running plutus-tx-plugin:gen-plugin-opts-doc. - Do not modify by hand. +optionsTable = Text.stripStart $ [fmt| +--- +sidebar_position: 5 +--- -.. list-table:: - :header-rows: 1 - :widths: 35 15 15 50 + - * - Option - - Value Type - - Default - - Description +# Plutus Tx compiler options +These options can be passed to the compiler via the `OPTIONS_GHC` pragma, for instance + +``` haskell +{{-# OPTIONS_GHC -fplugin-opt PlutusTx.Plugin:dump-uplc #-}} +{{-# OPTIONS_GHC -fplugin-opt PlutusTx.Plugin:max-simplifier-iterations-uplc=3 #-}} +``` + +For each boolean option, you can add a `no-` prefix to switch it off, such as `no-typecheck`, `no-simplifier-beta`. + +|Option|Value Type|Default|Description| +|-|-|-|-| {Text.unlines $ uncurry genRow <$> Map.toList O.pluginOptions} |] genRow :: O.OptionKey -> O.PluginOption -> Text -genRow k (O.PluginOption tr _ field desc _) = [fmt| - * - ``{k}`` - - {show tr} - - {show (pretty defaultValue)} - - {desc} -|] +genRow k (O.PluginOption tr _ field desc _) = + [fmt||`{k}`|{show tr}|{show (pretty defaultValue)}|{desc}||] where defaultValue = O.defaultPluginOptions ^. field diff --git a/plutus-tx-plugin/src/PlutusTx/Options.hs b/plutus-tx-plugin/src/PlutusTx/Options.hs index aa7c4967371..203dd15d980 100644 --- a/plutus-tx-plugin/src/PlutusTx/Options.hs +++ b/plutus-tx-plugin/src/PlutusTx/Options.hs @@ -152,8 +152,8 @@ pluginOptions = desc = "When conservative optimisation is used, only the optimisations that \ \never make the program worse (in terms of cost or size) are employed. \ - \Implies ``no-relaxed-float-in``, ``no-inline-constants``, and \ - \``preserve-logging``." + \Implies `no-relaxed-float-in`, `no-inline-constants`, and \ + \`preserve-logging`." in ( k , PluginOption typeRep @@ -188,7 +188,7 @@ pluginOptions = desc = "Always inline constants. Inlining constants always reduces script \ \costs slightly, but may increase script sizes if a large constant \ - \is used more than once. Implied by ``no-conservative-optimisation``." + \is used more than once. Implied by `no-conservative-optimisation`." in (k, PluginOption typeRep (setTrue k) posInlineConstants desc []) , let k = "optimize" desc = "Run optimization passes such as simplification and floating let-bindings." @@ -250,15 +250,15 @@ pluginOptions = desc = "Use a more aggressive float-in pass, which often leads to reduced costs \ \but may occasionally lead to slightly increased costs. Implied by \ - \``no-conservative-optimisation``." + \`no-conservative-optimisation`." in (k, PluginOption typeRep (setTrue k) posRelaxedFloatin desc []) , let k = "preserve-logging" desc = "Turn off optimisations that may alter (i.e., add, remove or change the \ - \order of) trace messages. Implied by ``conservative-optimisation``." + \order of) trace messages. Implied by `conservative-optimisation`." in (k, PluginOption typeRep (setTrue k) posPreserveLogging desc []) , let k = "remove-trace" - desc = "Eliminate calls to ``trace`` from Plutus Core" + desc = "Eliminate calls to `trace` from Plutus Core" in (k, PluginOption typeRep (setTrue k) posRemoveTrace desc []) , let k = "dump-compilation-trace" desc = "Dump compilation trace for debugging"