More information about --yul-optimizations option in READMEs and docs

docs/yul.rst

@@ -1047,6 +1047,9 @@ You can override this sequence and supply your own using the ``--yul-optimizatio
 
     solc --optimize --ir-optimized --yul-optimizations 'dhfoD[xarrscLMcCTU]uljmul'
 
+The order of steps is significant and affects the quality of the output.
+Moreover, applying a step may uncover new optimization opportunities for others that were already
+applied so repeating steps is often beneficial.
 By enclosing part of the sequence in square brackets (``[]``) you tell the optimizer to repeatedly
 apply that part until it no longer improves the size of the resulting assembly.
 You can use brackets multiple times in a single sequence but they cannot be nested.

libyul/optimiser/README.md

@@ -4,6 +4,7 @@ planned state of the optimiser.
 
 Table of Contents:
 
+- [Selecting optimisations](#selecting-optimisations)
 - [Preprocessing](#preprocessing)
 - [Pseudo-SSA Transformation](#pseudo-ssa-transformation)
 - [Tools](#tools)
@@ -33,6 +34,17 @@ the following transformation steps are the main components:
  - [Redundant Assign Eliminator](#redundant-assign-eliminator)
  - [Full Function Inliner](#full-function-inliner)
 
+## Selecting optimisations
+
+By default the optimiser applies its predefined sequence of optimisation steps to the generated assembly.
+You can override this sequence and supply your own using the `--yul-optimizations` option:
+
+``` bash
+solc --optimize --ir-optimized --yul-optimizations 'dhfoD[xarrscLMcCTU]uljmul'
+```
+
+There's a [table listing available abbreviations in the optimiser docs](/docs/yul.rst#optimization-step-sequence).
+
 ## Preprocessing
 
 The preprocessing components perform transformations to get the program

tools/yulPhaser/README.md

@@ -9,7 +9,7 @@ The input is a set of one or more [Yul](/docs/yul.rst) programs and each sequenc
 Optimised programs are given numeric scores according to the selected metric.
 
 Optimisation step sequences are presented in an abbreviated form - as strings of letters where each character represents one step.
-The abbreviations are defined in [`OptimiserSuite::stepNameToAbbreviationMap()`](/libyul/optimiser/Suite.cpp#L388-L423).
+There's a [table listing available abbreviations in the optimiser docs](/docs/yul.rst#optimization-step-sequence).
 
 ### How to use it
 The application has sensible defaults for most parameters.
@@ -72,6 +72,13 @@ solc/solc <sol file> --ir --output-dir <output directory>
 After running this command you'll find one or more .yul files in the output directory.
 These files contain whole Yul objects rather than just raw Yul programs but `yul-phaser` is prepared to handle them too.
 
+#### Using optimisation step sequences with the compiler
+You can tell Yul optimiser to use a specific sequence for your code by passing `--yul-optimizations` option to `solc`:
+
+``` bash
+solc/solc <sol file> --optimize --ir-optimized --yul-optimizations <sequence>
+```
+
 ### How to choose good parameters
 Choosing good parameters for a genetic algorithm is not a trivial task but phaser's defaults are generally enough to find a sequence that gives results comparable or better than one hand-crafted by an experienced developer for a given set of programs.
 The difficult part is providing a fairly representative set of input files.