Document output selection
- Dominant language
- C++
- Stars
- 25.7k
- Forks
- 6.2k
- Avg merge
- 2d 19h
- Merged PRs (30d)
- 29
Description
Due to performance issues of IR compilation, recently there's been increased interest by frameworks in using `outputSelection` to select only the actually necessary contracts and outputs. However, this feature and its quirks were never extensively documented, so it's often used inefficiently, with no easy way for users to find out how it was intended to be used.
We really need some docs on:
- Syntax:
- The special `"*"` and `""` values and where they can be used.
- Valid outputs in all input modes (Solidity, Yul, evmasm import).
- Semantics:
- Behavior of wildcards, e.g.:
- Inconsistencies between `"*"` and `""`.
- The fact that `"*"` does not match experimental outputs ([#14363](https://github.com/ethereum/solidity/issues/14363)) and a list of such outputs.
- The fact that patterns like `"*.sol"` are interpreted literally and only specifically `"*"` is a wildcard.
- Behavior of overlapping selections (e.g. `"*"/"contract"` vs `"file.sol"/"*"`).
- Other: invalid output names, duplicates, etc.
- Lazy compilation
- Which outputs trigger which compilation stages (parsing, analysis, code generation, bytecode generation).
- Implicit compilation due to bytecode dependencies.
- How this functionality changed across compiler versions (it's not straightforward to check because an inefficient selection won't usually produce an error).
Contributor guide
Research direction
Start by locating the existing outputSelection documentation and the compiler entry points that handle Solidity, Yul, and evmasm inputs. Research wildcard and overlapping-selection behavior, lazy compilation triggers, bytecode dependencies, and version differences. Done means documenting the requested syntax, semantics, experimental outputs, invalid cases, and version-specific behavior with enough examples for users to choose outputs efficiently.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- solidity
- Domain
- compilers, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100