Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Restore auto generation of compiler option table #6373

Merged
merged 2 commits into from
Aug 2, 2024
Merged

Restore auto generation of compiler option table #6373

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a9dd644
Restore auto generation of compiler option table
zliu41 Aug 1, 2024
501e3f9
Update plutus-tx-plugin/app/GeneratePluginOptionsDoc.hs
zliu41 Aug 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,9 @@ pkgs/.stack
*.code-workspace
.*.sw*

# Doc site
yarn.lock

# Misc
act-event.json
.history/
Expand Down Expand Up @@ -109,4 +112,3 @@ plutus-pab/test-node/alonzo-purple/db
*.timelog
*.stacks
.nvimrc

64 changes: 35 additions & 29 deletions doc/docusaurus/docs/reference/plutus-tx-compiler-options.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@
sidebar_position: 5
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This appears if you look at the rendered markdown on GhiHub. Is it needed to produce the fancy documentation?

Sidebar

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes

---

<!---
This file is generated by running plutus-tx-plugin:gen-plugin-opts-doc.
Do NOT modify by hand.
--->

# Plutus Tx compiler options

These options can be passed to the compiler via the `OPTIONS_GHC` pragma, for instance
Expand All @@ -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|
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a pity that the nice alignment's gone in the raw markdown now, but that looks as if it'd be quite hard to fix.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah but the raw markdown has always been unreliable.

|-|-|-|-|
|`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)|

40 changes: 23 additions & 17 deletions plutus-tx-plugin/app/GeneratePluginOptionsDoc.hs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
-- editorconfig-checker-disable-file
{-# LANGUAGE ApplicativeDo #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE QuasiQuotes #-}
Expand Down Expand Up @@ -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
<!---
This file is generated by running plutus-tx-plugin:gen-plugin-opts-doc.
Do NOT modify by hand.
--->

* - 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
12 changes: 6 additions & 6 deletions plutus-tx-plugin/src/PlutusTx/Options.hs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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."
Expand Down Expand Up @@ -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"
Expand Down