Debug Reports
Since 0.4.3
Debug reports are available from AspectK 0.4.3. Earlier versions do not have them.
Advice is woven into the compiled code, not into your sources, so the source never shows what runs. Debug reports show which advice applies to each target annotation and which functions it was woven into. They also include a Kotlin-like dump of every woven file.
1. Enabling reports
Every compilation of the module then writes its reports to its own directory under
build/aspectk/reports/:
build/aspectk/reports/<target>/<compilation>/
aspects.txt advice per target annotation, and hints that no longer resolve
woven/app/Main.kt Kotlin-like dump of a woven file
woven/app/Main.aspects.txt functions in that file and the advice woven into each
<target> and <compilation> are the Kotlin target and compilation, for example jvm/main.
On Android modules that use the built-in Kotlin of AGP the target segment is empty, so the
path looks like reports/debugUnitTest/.
Writing the reports adds work to every compilation of the module, so enable them while investigating and leave them off otherwise.
2. Example project
The reports below come from this project. :app declares its own aspect and depends on
:lib. :gone had an aspect for the same annotation, but it has since been deleted while
:app still has its record.
// :lib (depends on :shared)
package lib
@Aspect
object LibAspect {
@Before(target = [shared.Logged::class])
fun advice(jp: JoinPoint) {}
}
// :app (depends on :lib), Main.kt
package app
@Aspect
object AppAspect {
@Before(target = [shared.Logged::class])
fun advice(jp: JoinPoint) {}
}
class Woven {
@shared.Logged
fun run() {}
}
@shared.Logged
fun topLevel() {}
3. aspects.txt
:app gets this aspects.txt:
## Applied
shared.Logged
BEFORE app.AppAspect.advice [local]
BEFORE lib.LibAspect.advice [external]
## Dropped
gone.GoneAspect.advice -> shared.Logged [external]
Applied lists every target annotation the module knows about by its fully qualified name,
here shared.Logged. Under each one is a line for every advice that applies to it:
BEFORE app.AppAspect.advice [local]
──┬─── ──────┬───── ──┬─── ──┬──
kind aspect object advice where it came from
(qualified) function
So app.AppAspect.advice is the advice function of the app.AppAspect object, and it is a
@Before advice. The tag says where the advice came from:
| Tag | Source |
|---|---|
local |
An @Aspect in this module, compiled in this build |
external |
An @Aspect in another module, received through the compile classpath (see Cross-Module Injection) |
carried-forward |
An @Aspect in this module recorded by the previous build. Its file was not recompiled in this incremental round, so the advice is read back from that record |
Dropped lists advice that was recorded earlier but no longer exists, for example because
the aspect was deleted. Here GoneAspect no longer exists, so nothing is woven for it. Each
line has the form <aspect>.<advice> -> <target annotations> [<tag>]. A carried-forward
entry only appears in an incremental round: a full rebuild starts without the previous record.
4. woven/
Each file that received advice gets two entries, laid out by package. In the example,
Main.kt is woven and Plain.kt is not, so only Main.kt has entries:
<File>.aspects.txt
This file lists the woven functions in the file by their fully qualified names. Under each
function are the advice woven into it, in weaving order, in the same format as aspects.txt:
app.Woven.run
BEFORE app.AppAspect.advice [local]
BEFORE lib.LibAspect.advice [external]
app.topLevel
BEFORE app.AppAspect.advice [local]
BEFORE lib.LibAspect.advice [external]
<File>.kt
This file is the whole source file after weaving, printed as Kotlin-like code by the
compiler's dumpKotlinLike(). It shows the code AspectK inserted, which the source file does
not. This is Woven from woven/app/Main.kt, with the constructor and the inherited
equals/hashCode/toString stubs left out:
class Woven {
@Logged
fun run() {
AppAspect.advice(jp = DefaultJoinPoint(target = <this>, signature = $MethodSignatures.<get-ajc$tjp_0>(), args = listOf<Any?>(elements = [<this>])))
LibAspect.advice(jp = DefaultJoinPoint(target = <this>, signature = $MethodSignatures.<get-ajc$tjp_0>(), args = listOf<Any?>(elements = [<this>])))
}
object $MethodSignatures {
val ajc$tjp_0: MethodSignature
field = MethodSignature(methodName = "run", annotations = listOf<AnnotationInfo>(elements = [AnnotationInfo(type = Logged::class, typeName = "shared.Logged", args = listOf<Any?>(elements = []), parameterNames = listOf<String>(elements = []))]), parameter = listOf<MethodParameter>(elements = [MethodParameter(name = "<this>", type = Woven::class, typeName = "app.Woven", annotations = listOf<AnnotationInfo>(elements = []), isNullable = false)]), returnType = Unit::class, returnTypeName = "kotlin.Unit")
get
}
}
The dump shows the following:
- Advice calls: the empty body of
run()now starts with a call to each@Beforeadvice, in the order listed inMain.aspects.txt. JoinPointconstruction: each call builds aDefaultJoinPointfrom the receiver (<this>), the method signature and the argument list. A top-level function hastarget = null.- Method signatures: AspectK generates a
$MethodSignaturesobject that holds oneMethodSignatureper woven function. It is created once and shared by every call. @Afterand@Around: these wrap the original body. In the dump, the body appears inside atry/finallyblock or a proceed lambda.
The dump is generated from the compiler's internal representation, so it is not always valid
Kotlin. <this>, <get-...> and /* fake */ are notation of the dump format.
A file with no woven function has neither entry. If an advice is listed under Applied but
no <File>.aspects.txt mentions it, it was not woven into this module. Check whether its
target annotation is used here, on a function with a body.
5. Incremental builds
An incremental round only compiles the files that changed, so the reports are kept per file:
aspects.txtis rewritten every round and stays complete. Advice from files that were not recompiled is listed ascarried-forward.- A recompiled file has its old dump and
<File>.aspects.txtreplaced. If it is no longer woven, both are removed. - Files that were not recompiled keep the reports of the round that last compiled them.
Note
Deleting a source file leaves its reports in place, because the file is never part of a later round. Run a clean build to remove them.