ContextQMD
Back to Compose Multiplatform

Low-Level API FIR

analysis/low-level-api-fir/README.md

2.3.205.3 KB
Original Source

Low-Level API FIR

Low-level API FIR (LL API or LL FIR for short) is an interlayer between Analysis API FIR Implementation and FIR compiler. Low-level API FIR is responsible but not limited for:

  • Finding corresponding FirElement by KtElement
  • Lazy resolution of declarations (FirElementWithResolveState)
  • Collecting diagnostics for FirDeclaration
  • Incremental code analysis
  • Implementing FIR providers using the Analysis API implementor's declaration/package/etc. providers (e.g., IntelliJ indexes in the IDE)

You can read about how FIR compiler works here.

The entry point for LL API is LLResolutionFacade. LLResolutionFacade represents a project view from a use-site KaModule. The lifetime of LLResolutionFacade is limited by modification events.

LowLevelFirApiFacade file contains a useful API surface to interact with Low Level API FIR from Analysis API FIR.

Documentation

There are a bunch of different areas. Docs for each area are sorted by context depth – from the basic overview to the deepest implementation details.

  • Mapping from KtElement to FirElement (KT → FIR) & Incremental Analysis & Collecting diagnostics
    1. FirElementBuilder is responsible for mapping from KtElement to FirElement.
    2. FileStructure is a tree like-structure of FileStructureElement which is associated with some KtFile. Aggregates information about KT → FIR mapping and diagnostics for an associated file.
    3. FileStructureElement is a representation of specific KtElement. Is responsible for KT → FIR mapping and diagnostics for the specific KtElement.
    4. FileStructureElementDiagnosticRetriever is responsible to collect diagnostics for FileStructureElement.
    5. LLFirDeclarationModificationService is a service that is responsible for FileStructure invalidation in the case of associated PSI modification.
  • Lazy resolution
    1. FirResolvePhase to understand what the compiler phases are and what is the basic difference between the CLI and the Analysis API modes.
    2. LLFirModuleLazyDeclarationResolver is the entry point for lazy resolution. Receives some FirElementWithResolveState element and a desired phase and resolve this element to this phase.
    3. LLFirResolveDesignationCollector is a designation collector. Collects LLFirResolveTarget for the specific FirElementWithResolveState. Decides which element can be resolved lazily and which cannot.
    4. LLFirResolveTarget is an instruction on how to resolve specific FirElementWithResolveState.
    5. LLFirLazyResolverRunner is responsible for running LLFirLazyResolver for the specific phase and making sure that it worked correctly.
    6. LLFirTargetResolver is the core part of lazy resolution. We have a separate implementation of LLFirTargetResolver for each compiler phase, each of which is responsible for all the resolution logic for the associated phase.
    7. LLFirLockProvider is responsible for locking logic which is widely used by LLFirTargetResolver during resolution.
  • ContextCollector represents the resolution context of a specific place in code (a context)

Project Module Structure

The LLResolutionFacade represents a view from a specific module (root module) to the dependent modules. A module is represented by:

  • LLFirSession – the implementation of FirSession (FIR compiler representation of a module)
  • ModuleFileCache – the KtFile -> FirFile cache & also caches for FIR providers