MAD Skills series: Hilt under the hood

Third episode of the Hilt MAD Skills series

This is the third episode in the MAD Skills series on Hilt! Be sure to check out Episode 1 and Episode 2. In this episode, we’ll take a deep dive into how Hilt works under the hood.

If you prefer to consume this content in a video format, check it out here:

Topics covered

• How the various Hilt annotations work together to generate code.
• How the Hilt Gradle Plugin works behind the scenes to improve the overall experience when using Hilt with Gradle.

How the various Hilt annotations work together to generate code

Hilt uses annotation processors to generate code. Annotation processing occurs within the compiler when converting your source files into java bytecode. As the name suggests, annotation processors are triggered on the annotations within your source files. An annotation processor typically inspects the annotation and types to perform various tasks, like validation or generating new sources.

In Hilt, three of the most important annotations are @AndroidEntryPoint, @InstallIn, and @HiltAndroidApp.

@AndroidEntryPoint

AndroidEntryPoint enables field injection in your Android classes such as Activities, Fragments, Views, and Services.

In the following example, simply annotating PlayActivity with AndroidEntryPoint allows us to inject the MusicPlayer into our activity.

If you’re using Gradle, you’re probably familiar with the simplified syntax shown above. However, this syntax is actually just syntactic sugar provided to you by the Hilt Gradle plugin. More about the Hilt Gradle plugin below, but for now let’s look at how this example would look without the syntactic sugar.

Now we see that the original base class, AppCompatActivity, is really an input to the AndroidEntryPoint annotation. The PlayActivity, itself, actually extends the generated class Hilt_PlayActivity. This class is generated by Hilt’s annotation processors, and contains all of the logic necessary to perform injection. Here’s a simplified example of the code in that generated base class:

In this example, the generated class extends AppCompatActivity. However, in general it will extend whichever class was passed into the AndroidEntryPoint annotation. This allows injection to work with any base class you want.

The main purpose of this generated class is to handle injection. It’s important to perform injection as early as possible to prevent accidental access to a field before it’s been injected. Thus, for activities, injection occurs during the onCreate method.

In the inject method, we first need an instance of its injector, PlayActivity_Injector. In Hilt, the injector for an activity is an entry point, and we can get an instance of the injector using the EntryPoints utility class.

As you may have guessed, PlayActivity_Injector is also generated by Hilt’s annotation processors. It will have the following format:

The generated injector is a Hilt entry point that is installed into the ActivityComponent. It contains a single method that allows us to inject an instance of the PlayActivity. If you’ve ever used Dagger in an Android application without Hilt, you’re likely familiar with writing these inject methods directly on the component.

@InstallIn

InstallIn is used to indicate which component a module or entry point should be installed into. In the following example, we’ve installed the MusicDataBaseModule into the SingletonComponent:

With InstallIn, a module or entry point can be contributed from anywhere within the transitive dependencies of your application. However, at some point we’ll need to collect all of the InstallIn contributions to get the full set of modules and entry points for each component.

Hilt generates a metadata annotation in a fixed package to make collecting and discovering these InstallIn contributions easier. Generated annotations will have the following format:

By putting the metadata into a fixed package, Hilt’s processors can easily find the metadata generated in all transitive dependencies of your application. From there, we can use the information contained in the metadata annotation to find a reference to the InstallIn contribution itself — in this case, the MusicDatabaseModule.

HiltAndroidApp

Finally, the HiltAndroidApp annotation enables injection in your Android application class. In this regard, you can think of it exactly like the AndroidEntryPoint annotation. To start, a user just needs to annotate their application class with @HiltAndroidApp.

However, HiltAndroidApp has one other important function — generating Dagger components.

When the Hilt annotation processor encounters @HiltAndroidApp, it generates a set of components inside of a wrapper class that has the same name as the application class, prefixed with HiltComponents_. If you’ve ever used Dagger before, these components are the @Component and @Subcomponent annotated classes that you normally would write by hand.

To generate these components, Hilt looks in the metadata package described above to find all of the @InstallIn-annotated classes. The @InstallIn modules are placed in the modules list of the corresponding component declaration. The @InstallIn entry points are placed as super types of the corresponding component declaration.

From here, the Dagger processor takes over and generates the component implementation from the @Component and @Subcomponent annotations. If you’ve ever used Dagger without Hilt, you’ve likely interacted with these classes directly. However, Hilt hides this complexity from the user.

As this blog post is about Hilt, we won’t go into further details about the Dagger generated code. However, if you’re interested, you can check out this presentation by Ron Shapiro and David Baker and they’ll walk you through the details. In addition, you can check out the cheat sheet for Dagger codegen 101.

Hilt Gradle plugin

Now that you’ve seen how code generation works in Hilt, let’s now take a look at the Hilt Gradle plugin. The Hilt Gradle plugin performs a lot of useful tasks, including bytecode rewriting and classpath aggregation.

Bytecode rewriting

As the name suggests, bytecode rewriting is the process of rewriting bytecode. Unlike annotation processing, which can only generate new code, bytecode rewriting can rewrite existing code. When used sparingly, this feature can be very powerful.

To see why we use bytecode rewriting in Hilt, let’s return to @AndroidEntryPoint.

While extending the Hilt_PlayActivity base class works in practice, it can cause issues with your IDE. Since the generated class does not exist until after you’ve successfully compiled your code, you’ll often see red squiggles in your IDE. In addition, you won’t have access to auto-complete for things like overriding methods, and you won’t be able to access methods from the base class.

Not only can the loss of these features slow down your coding velocity, but all of these red squiggles can also make it extremely difficult to focus.

The Hilt Android plugin comes to the rescue by enabling bytecode rewriting on your AndroidEntryPoint classes. With the Hilt Android plugin enabled, all that’s required is to annotate your class with @AndroidEntryPoint and you can extend your normal base class.

Since this syntax no longer references the generated base class, there are no issues with the IDE. During bytecode rewriting, the Hilt Gradle plugin will swap your base class with the generated Hilt_PlayActivity. Since this process happens directly in the bytecode, it’s not visible to the user.

However, there are some disadvantages to bytecode rewriting.

• The plugin must modify low-level bytecode, rather than source code. This is somewhat error prone.
• Because the bytecode has already been compiled by the time rewriting occurs, any issues generally show up at runtime rather than compile time.
• Rewriting complicates debugging, since when something does go wrong the source files may not represent the bytecode that’s being executed.

For these reasons, Hilt tries to rely on bytecode rewriting as little as possible.

Classpath aggregation

Finally, let’s look at another useful feature of the Hilt Gradle plugin: classpath aggregation. To understand what classpath aggregation is and why it’s needed, let’s look at another example.

In this example, :app depends on a single Gradle module, :database, where both :app and :database contribute InstallIn modules.

As we’ve already seen, Hilt will generate metadata into the fixed hilt_metadata package which will be used to find all @InstallIn-annotated modules when generating the component.

While this works fine for a single level of dependencies, let’s see what happens when we add another Gradle module, :cache, as a dependency of :database.

When :cache is compiled, although it will generate metadata, that metadata will not be available when compiling :app because it is a transitive dependency. Thus, Hilt has no way of knowing about the CacheModule and it will be accidentally excluded from the generated component.

While you could technically fix this issue by declaring the :cache dependency as api rather than implementation, it’s not recommended. Not only is using api worse for incremental builds, it’s a nightmare to maintain.

This is where the Hilt Gradle plugin comes to the rescue.

The Hilt Gradle plugin automatically aggregates all classes from the transitive dependencies of :app, even if implementation is used.

In addition, the Hilt Gradle plugin also has a number of benefits over using api directly.

First, classpath aggregation is less error-prone and requires no maintenance compared to manually using api for dependencies throughout your app. You can simply use implementation as you normally would, and the Hilt Gradle plugin will take care of the rest.

Second, the Hilt Gradle plugin only aggregates classes at the application level, so unlike when using api, compilation of the libraries in your project are not affected.

Finally, classpath aggregation provides better encapsulation of your dependencies because it’s impossible to accidentally reference these classes in your source files, and they won’t show up as suggestions in code-completion.

Conclusion

In this episode, we’ve uncovered how the various Hilt annotations work together to generate code. We also looked at the Hilt Gradle plugin and saw how it works behind the scenes using bytecode rewriting and classpath aggregation to make using Hilt safer and easier.

Thanks for reading, and keep an eye out for more MAD skills episodes to come!