Skip to content

KaLibraryModule

@SubclassOptInRequired(markerClass = [KaPlatformInterface::class])
interface KaLibraryModule : KaModule

A module which represents a binary library, such as a JAR or KLIB.

Dependencies

KaLibraryModules can have their own dependencies (e.g. directRegularDependencies). These dependencies are only relevant when the library is analyzed as a use-site module (e.g. its decompiled sources are viewed in the IDE). When the library module is used as a dependency of another module, its own dependencies are irrelevant.

The library module should either have the exact dependencies it was compiled with or, if unknown, a single KaLibraryFallbackDependenciesModule.

Platform-specific content scope restriction

The contentScope of the library module excludes file types that are harmful for the targetPlatform. For example, a JVM library module filters out .kotlin_metadata and .knm files, which excludes Kotlin declarations from non-JVM platforms. It also filters out source files.

While most proper library module setups don't need such filtering, there are both pathological as well as legitimate use cases in the wild. For example, certain Kotlin stdlib setups required both the kotlin-stdlib and kotlin-stdlib-common JARs to be part of the same KaLibraryModule (this has been fixed with 2.x stdlibs). Such a library module has the JVM target platform, and we need to exclude .kotlin_metadata files from the content scope.

As another example, a JVM library module might accidentally include source JARs in its binary roots. These sources must be excluded. Otherwise, the Analysis API might accidentally try to load library declarations from them.

Properties

baseContentScope

abstract val baseContentScope: GlobalSearchScope

A base content scope of the module, which is not yet refined by extension and restriction scopes provided by KotlinContentScopeRefiner.

Note that baseContentScope doesn't represent the actual content scope of the current module. To get a content scope of the module, contentScope should be used instead.

baseContextModuleOrSelf

The KaModule's baseContextModule, or the module itself if it's not a KaDanglingFileModule.

binaryRoots

abstract val binaryRoots: Collection<Path>

A list of binary roots which constitute the library. The list can contain JARs, KLIBs, folders with .class files, and so on.

The paths should be consistent with the contentScope, so the following equivalence should hold:

library.contentScope.contains(file) <=> library.binaryRoots.listRecursively().contains(file)

binaryVirtualFiles

abstract val binaryVirtualFiles: Collection<VirtualFile>

A list of binary roots which constitute the library, in VirtualFile form. Like binaryRoots, the list can contain JARs, KLIBs, folders with .class files, and so on.

Originally, this property was only intended to cover libraries in an in-memory file system, whose roots cannot be represented as paths in binaryRoots. However, not every disk-based binary root can be represented as a path either (e.g. roots in a JAR file system), so the Analysis API is moving towards virtual files as the canonical representation of binary roots (see KT-72676): binaryVirtualFiles is to cover all binary roots, and binaryRoots will eventually change its return type to a collection of VirtualFiles (after a deprecation cycle), at which point this property will be removed. The IntelliJ platform implementation already exposes all binary roots through this property, while the Standalone platform currently exposes only in-memory roots, keeping disk-based roots in binaryRoots.

compilerPluginGeneratedDeclarations

Declarations generated by compiler plugins for this module, not including the generated declarations for dependencies of this module.

contentScope

abstract val contentScope: GlobalSearchScope

Represents the content scope of a current module, i.e., a GlobalSearchScope which determines all the files that are contained in the module.

This scope should be lazily built from baseContentScope using KotlinContentScopeRefiner extension points.

directDependsOnDependencies

The module's dependsOn dependencies.

A dependsOn dependency expresses that the current module can provide actual declarations for expect declarations from the dependency module, as well as see internal symbols of the dependency module. As such, dependsOn dependencies are a Kotlin Multiplatform concept.

dependsOn dependencies in general are transitive, but the resulting list is not a transitive closure. To get all transitive dependsOn dependencies, transitiveDependsOnDependencies should be used. The list also does not include the current module.

directFriendDependencies

The module's friend dependencies. Friend dependencies allow the current module to use internal symbols from the dependency module.

The resulting list is not transitive and does not include the current module.

directRegularDependencies

The module's regular dependencies. Regular dependencies allow the current module to use symbols from the dependency module.

The resulting list is not transitive and does not include the current module.

isResolvable

Whether the given KaModule can be the use-site module of an analyze call. A module which is not resolvable will be rejected by analyze with an exception.

All modules returned by KaModuleProvider.getModule are guaranteed to be resolvable. By extension, all possible use-site PsiElements are also part of resolvable modules. As such, module resolvability is normally not a concern of an Analysis API user.

isSdk

abstract val isSdk: Boolean

Whether the module represents an SDK, such as the JDK.

libraryName

abstract val libraryName: String

The name of the library.

In practice, the specific format of the libraryName depends on the Analysis API platform which provides the KaLibraryModule implementation.

librarySources

The library sources for the binary library, if any.

For example, if this module is a binary JAR, then librarySources corresponds to the sources JAR.

moduleDescription

open override val moduleDescription: String

A human-readable description of the module, such as "main sources of module 'analysis-api'".

project

abstract val project: Project

The Project to which the module belongs.

All the module's dependencies should belong to the same Project as the module itself.

stableModuleName

A stable binary name of module from the Kotlin point of view. Having a correct module name is critical for internal-visibility mangling.

NOTE: stableModuleName will be removed in the future and replaced with a platform interface service.

targetPlatform

abstract val targetPlatform: TargetPlatform

A platform which the module represents (e.g, JVM, JS, Native).

See also

  • TargetPlatform

transitiveDependsOnDependencies

A list of directDependsOnDependencies and all of their own dependsOn dependencies (directly and indirectly), sorted topologically with the nearest dependencies first in the list. The list does not include the current module.

Functions

allDirectDependencies

A list of all modules that the given module directly depends on.

See also

allDirectDependenciesOfType

A list of all modules of type M that the given module directly depends on.

See also

directDependsOnDependenciesOfType

A list of all modules of type M that the given module directly depends on with a depends-on dependency.

See also

directFriendDependenciesOfType

A list of all modules of type M that the given module directly depends on with a friend dependency.

See also

directRegularDependenciesOfType

A list of all modules of type M that the given module directly depends on with a regular dependency.

See also