argotorg / argotorg/solidity

Document output selection

Open
#15,744 0 comments 0 reactions 0 assignees View on GitHub
documentation :book: low effort medium impact must have eventually
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.