DEV Community: Sifiso Fakude

Building a Plug-and-Play JVM Compiler for Android and Desktop with Bytesmith

Sifiso Fakude — Mon, 24 Aug 2026 03:41:37 +0000

What if adding Kotlin and Java compilation to your application didn't mean building an entire compilation pipeline yourself?

What if you could add Bytesmith, configure the filesystem once, provide your source files and output destination, and simply compile?

That's the idea behind Bytesmith.

Bytesmith is a Kotlin and Java compiler toolkit designed for JVM and Android applications. It provides a unified API for Kotlin, Java, and mixed-language compilation, while also supporting filesystem abstraction, custom classpaths, boot classpaths, compiler plugins, packaging, and diagnostics.

Configure the environment, provide the source, specify the output, and compile.

The problem

Compiler tooling can become surprisingly difficult when it is tightly coupled to the environment in which it was originally designed to run.

You might need to deal with:

Kotlin compiler versions
Kotlin standard libraries
Java compilation
Bootclasspath configuration
Dependency classpaths
Source discovery
Output handling
Android storage
Storage Access Framework URIs
Packaging
Compiler diagnostics

And then there is the question of where those files actually live.

On a desktop JVM, you might have traditional filesystem paths:

/home/user/project/src/Main.kt

On Android, you might be working with application storage or files selected through the Storage Access Framework:

content://...

If your compiler API directly depends on java.io.File, your compilation code becomes coupled to one filesystem model.

Bytesmith takes a different approach.

Adding Bytesmith

The goal is to make compilation something you can plug into an application.

With Gradle:

implementation("io.github.sifisofakude.bytesmith:bytesmith-common:1.0.0")

After adding Bytesmith, configure the filesystem your application wants to use.

For a JVM application:

FileSystems.current = JvmFileSystem()

For Android:

FileSystems.current = AndroidSafFileSystem(context)

Once the filesystem is configured, the rest of the compilation layer can operate through the filesystem abstraction.

The basic compilation example

Bytesmith provides a high-level compilation entry point.

For example:

val result = Main().compile(
    JvmFileSystem(),
    listOf(
        "-d", "build/classes",
        "src/main/java",
        "src/main/kotlin"
    )
)

println(result)

The important part is that you provide the filesystem and compilation arguments.

Bytesmith handles the compiler orchestration.

You don't need to build an entire compilation pipeline yourself.

Compiling Kotlin

Bytesmith also exposes the Kotlin compiler directly when you need more control.

For example:

val result = KotlinCompiler(JvmFileSystem()).compile(
    Options(
        outputDir = "build/classes",
        kotlinSources = kotlinSources,
        javaSources = emptyList(),
        classpath = emptyList(),
        bootClasspath = emptyList(),
        warningsAsErrors = false
    )
)

This gives your application control over the compilation environment while still allowing Bytesmith to handle the underlying compiler integration.

Compiling Java

Bytesmith isn't just a Kotlin compiler wrapper.

Java compilation is supported through ECJ.

For example:

val result = JavaCompiler(JvmFileSystem()).compile(
    Options(
        outputDir = "build/classes",
        javaSources = javaSources,
        classpath = emptyList(),
        bootClasspath = emptyList(),
        warningsAsErrors = false
    )
)

This means an application can use Bytesmith for Java compilation without implementing its own ECJ integration.

Mixed Kotlin and Java projects

Bytesmith can also compile projects containing both Kotlin and Java source files.

For example:

src/
└── main/
    ├── kotlin/
    │   └── Example.kt
    └── java/
        └── JavaExample.java

You can provide both types of source files to the compilation process:

val sources = listOf(
    "src/main/kotlin/Example.kt",
    "src/main/java/JavaExample.java"
)

The Kotlin compiler and Java compiler are orchestrated as part of the compilation process.

This is useful for applications that generate source code, developer tools, code editors, custom build systems, or other environments where compilation itself is an application feature.

The filesystem abstraction

This is one of the most important parts of Bytesmith.

A compiler shouldn't necessarily care where a source file physically comes from.

A desktop application might use:

/home/user/project/Main.kt

An Android application might use application storage.

Or the source might come from a user-selected SAF document:

content://...

These are fundamentally different storage mechanisms.

But the compilation operation doesn't need to be.

The application chooses the filesystem implementation:

FileSystems.current = JvmFileSystem()

or:

FileSystems.current = AndroidSafFileSystem(context)

Bytesmith then works through the filesystem abstraction.

The architecture looks roughly like this:

             Application
                  |
                  v
          FileSystems.current
                  |
        +---------+---------+
        |                   |
        v                   v
 JvmFileSystem       AndroidSafFileSystem
        |                   |
        +---------+---------+
                  |
                  v
              Bytesmith
                  |
          +-------+-------+
          |               |
          v               v
     Kotlin compiler     ECJ
          |               |
          +-------+-------+
                  |
                  v
              Output

The compiler doesn't have to know whether the underlying storage is a JVM filesystem or SAF.

Android and SAF

This becomes particularly useful on Android.

The Storage Access Framework doesn't behave like a traditional filesystem.

Instead of receiving a normal filesystem path, your application may receive a URI:

content://...

You may then need to work with:

ContentResolver
Document providers
Document tree URIs
Persisted permissions
DocumentFile
DocumentsContract

Bytesmith's filesystem abstraction allows those details to stay inside the filesystem implementation.

The compilation code doesn't need to become filled with Android-specific storage logic.

You configure the filesystem once.

Then Bytesmith can work through it.

Scoped Storage, SAF, or JVM paths?

From the perspective of the compilation API, it shouldn't fundamentally matter whether your application is using:

JVM filesystem
    |
    +-- /home/user/project/Main.kt

or:

Android application storage
    |
    +-- /data/user/0/...

or:

Storage Access Framework
    |
    +-- content://...

Those are different storage mechanisms.

They don't have to result in completely different compiler implementations.

The filesystem implementation handles the difference.

That's one of the reasons I built the filesystem abstraction separately from the compilation logic.

Android usage

An Android application can configure the appropriate filesystem implementation:

FileSystems.current = AndroidSafFileSystem(context)

After that, the same Bytesmith compilation layer can operate against the configured filesystem.

If SAF resources need to be materialized for a particular compilation operation, the filesystem implementation can handle that as well.

For example:

val local = fs.materialize(uri, "Sources")

and later:

fs.clearMaterialized("Sources")

The important thing is that the compilation layer doesn't need to implement its own SAF handling.

Classpaths

Real compilation usually requires dependencies.

Bytesmith allows you to provide a custom classpath.

For example:

val options = Options(
    outputDir = "build/classes",
    kotlinSources = kotlinSources,
    javaSources = javaSources,
    classpath = listOf(
        "libs/library.jar",
        "libs/another-library.jar"
    ),
    bootClasspath = emptyList(),
    warningsAsErrors = false
)

The application decides what libraries should be visible to the compiler.

Bytesmith handles passing those dependencies into the appropriate compiler.

Kotlin standard library versions

This separation is also useful when working with Kotlin's standard library.

The Kotlin compiler and Kotlin standard library are related, but they aren't exactly the same thing.

If your generated source needs APIs from a newer Kotlin standard library, you can provide the appropriate:

kotlin-stdlib.jar

through the compilation classpath.

For example:

val classpath = listOf(
    "libs/kotlin-stdlib.jar",
    "libs/my-library.jar"
)

This means an update to the standard library doesn't automatically mean Bytesmith itself needs to be updated simply because the library JAR changed.

There is an important limitation.

Providing a newer kotlin-stdlib.jar does not make an older Kotlin compiler understand new Kotlin language features.

If a newer Kotlin release introduces new syntax, compiler functionality, or lowering requirements, the compiler itself needs to support those features.

The goal is not to pretend compiler versions don't matter.

The goal is to avoid coupling things that can evolve independently.

Bootclasspath

Compilation environments sometimes require a bootclasspath.

Bytesmith can detect the appropriate bootclasspath where possible.

If you need explicit control, you can provide one yourself.

This gives you two options.

Simple case

Let Bytesmith determine the environment.

Advanced case

The application supplies the bootclasspath.

You get convenience without losing control.

Compiler plugins

Bytesmith also supports Kotlin compiler plugins.

You can provide plugin JARs and plugin options as part of the compilation environment.

For example:

val options = Options(
    pluginClasspath = listOf(
        "plugins/my-plugin.jar"
    ),
    pluginOptions = listOf(
        "plugin:my.plugin:key=value"
    )
)

This makes Bytesmith useful for more than straightforward source compilation.

An application can construct a compilation environment specifically for the code it needs to compile.

Packaging the output

Compilation doesn't necessarily have to end with a directory containing .class files.

Bytesmith can also package compiled output into JAR or ZIP archives.

For example:

build/classes

can be used as a directory output, while an application can also produce:

app.jar

or:

app.zip

This is useful when the compiled result needs to be consumed as an artifact rather than simply left in a classes directory.

Diagnostics

Compilation errors are only useful if your application can actually report them.

Bytesmith exposes compilation results and listener callbacks.

For example:

class Listener : ICompilationListener {

    override fun hasErrors() = false

    override fun onProblem(problem: CompilationProblem) {
        problem.printMessage()
    }

    override fun onClassCompiled(compiledClass: CompiledClass) {
        println(compiledClass.fileName)
    }
}

The compilation result can also provide information such as:

println(result.success)
println(result.errorCount)
println(result.warningCount)
println(result.compiledClassCount)
println(result.elapseTimeMillis)

This becomes particularly useful when Bytesmith is embedded inside a UI.

An Android code editor, for example, could take compiler diagnostics and display them directly to the user rather than dumping compiler output to a terminal.

Command-line usage

Bytesmith isn't limited to an embedded API.

It also provides a command-line interface.

A compilation can look like:

bytesmith   -cp libs/*   -bc jmods   -d build/classes   src/main/java   src/main/kotlin

The CLI exposes options for classpaths, boot classpaths, module paths, source paths, compiler plugins, plugin options, output destinations, and warnings-as-errors.

This means the same compilation capabilities can be used programmatically or from the command line.

Why not just use Gradle?

Gradle is excellent when you're building a conventional project.

But that's not necessarily the problem Bytesmith is trying to solve.

Imagine an application where the application itself needs to compile source code.

For example:

An Android IDE
A code editor
A developer tool
A code generator
A scripting environment
A custom build tool
An educational programming environment
An application that generates Kotlin or Java code dynamically

In these situations, starting a complete Gradle build just to compile a set of source files can be excessive.

You may simply want:

Source files
     |
     v
  Compile
     |
     v
Classes / JAR

Bytesmith provides that compilation layer.

The architecture

The architecture can be summarized as four responsibilities.

1. Your application

Decides what it wants to compile and where the result should go.

2. The filesystem abstraction

Decides how files are actually accessed.

JvmFileSystem
AndroidSafFileSystem

3. Bytesmith

Orchestrates compilation, classpaths, compiler configuration, diagnostics, and packaging.

4. Language compilers

Kotlin is compiled through the Kotlin compiler.

Java is compiled through ECJ.

This separation is what makes the whole thing composable.

The result

For a simple use case, the workflow is essentially:

Configure filesystem
        |
        v
Provide sources
        |
        v
Compile
        |
        v
Get result

For advanced applications, you can progressively add:

Classpath
Bootclasspath
Compiler plugins
Plugin options
Diagnostics
Packaging

without having to replace the underlying compilation architecture.

That's the balance Bytesmith is aiming for:

Simple when you need simple. Configurable when you need control.

Final thoughts

I built Bytesmith around a fairly simple idea:

Compilation should be a capability an application can plug in, not an entire infrastructure the application has to reinvent.

It can compile Kotlin.

It can compile Java.

It can handle mixed Kotlin/Java projects.

It can work with custom classpaths and boot classpaths.

It supports compiler plugins and packaging.

And, perhaps most importantly for Android, it doesn't assume that every file is a traditional JVM filesystem path.

The application chooses the filesystem implementation.

Bytesmith works through that abstraction.

So whether you're compiling files from a desktop filesystem, Android application storage, or resources exposed through the Storage Access Framework, the compilation layer can remain the same.

Configure the filesystem.

Give Bytesmith the source.

Configure dependencies when necessary.

Choose the output.

Compile.

That's Bytesmith.

Android Storage in 2026: Scoped Storage, SAF, and Why Filesystem Abstractions Still Matter

Sifiso Fakude — Sun, 23 Aug 2026 22:21:32 +0000

Android storage has changed dramatically.

For a long time, Android developers could think about storage in familiar terms:

val file = File("/some/path/file.txt")

You had a path. You opened a stream. You copied a file. You created a directory.

Simple.

Modern Android is different.

Today, an application may interact with application-private storage, shared media through MediaStore, user-selected documents through the Storage Access Framework (SAF), cloud-backed document providers, and traditional JVM filesystem APIs.

The difficult part isn't learning any one of these APIs.

The difficult part is building software that can work with different kinds of storage without forcing the entire application to understand the differences.

That is the problem that led me to build a filesystem abstraction for Android and the JVM.

The filesystem isn't always a filesystem anymore

On the JVM, this is straightforward:

val file = File("/home/user/documents/example.txt")

file.inputStream().use {
    // read
}

The application has a path that refers to something on the filesystem.

Android's Storage Access Framework changes that model.

Instead of receiving a normal filesystem path, an application can receive something like:

content://com.android.externalstorage.documents/tree/primary%3ADocuments

That isn't a filesystem path.

It is a URI representing a document-provider resource.

You don't meaningfully resolve it with:

File(uri.path)

The operating system expects you to interact with it through APIs such as ContentResolver and DocumentsContract.

This creates an important architectural distinction:

Traditional filesystem

Path
  ↓
File
  ↓
InputStream / OutputStream

versus:

Storage Access Framework

URI
  ↓
ContentResolver / DocumentsContract
  ↓
Provider
  ↓
InputStream / OutputStream

The final result may still be a stream, but everything before that stream is fundamentally different.

Scoped Storage solved one problem, but not every storage problem

Scoped Storage was an important change in Android's storage model.

For many applications, it makes storage much simpler.

An application can use its own private directories and appropriate platform APIs without needing unrestricted access to the user's entire shared filesystem.

For applications working with photos, videos, audio and other supported media, MediaStore can also provide an appropriate abstraction.

And this is where an important point gets overlooked:

Not every Android application needs SAF.

If an application only needs its own application data, use application-private storage.

If it needs to work with supported shared media, MediaStore may be the right solution.

But there are applications where the requirement is different:

"Let the user choose a directory and allow the application to work with files inside that directory."

That's where SAF becomes particularly interesting.

SAF isn't just a file picker

One of the things that surprised me while working deeply with SAF is how easy it is to think of it as merely a mechanism for selecting a file.

It is much more than that.

With the appropriate user-granted permissions, an application can work with a selected document tree.

That tree can represent storage managed by different document providers.

And those providers don't necessarily have to represent the device's local storage.

The underlying provider could potentially represent remote or cloud-backed storage.

That means the application isn't necessarily interacting with:

Android device → physical filesystem

It can be closer to:

Application
    ↓
ContentResolver
    ↓
Document Provider
    ↓
Storage implementation

The application doesn't need to know whether the provider ultimately represents local storage or another storage service.

That's one of the most powerful ideas behind SAF.

But this creates a problem for filesystem-oriented code

Imagine a library with an API like:

FileOperation("documents/example.txt")

On the JVM, that's easy.

But what does "documents/example.txt" mean on Android if the actual storage root is a SAF URI?

Suppose the user selected:

content://.../tree/primary%3ADocuments

Now the library needs to interpret:

documents/example.txt

relative to that selected document tree.

It cannot simply construct:

content://.../documents/example.txt

because SAF URIs aren't ordinary paths.

The library has to resolve the path through the document provider.

For example:

Selected SAF root
        ↓
Documents
        ↓
projects
        ↓
example.txt

Each step represents a document-provider operation rather than a normal filesystem traversal.

This is where filesystem abstraction becomes useful.

Abstract the storage, not the application

The goal isn't to pretend that SAF and the JVM filesystem are identical.

They aren't.

Trying to hide every difference can actually make an abstraction worse.

Instead, the abstraction should hide the mechanics of accessing the storage while exposing operations that make sense to the application.

For example:

interface FileSystemUtil {

    fun read(path: String): Source

    fun write(path: String): Sink

    fun createFile(path: String)

    fun createDirectory(path: String)

    fun delete(path: String)

    fun copy(source: String, destination: String)
}

The JVM implementation can use:

java.io.File

while an Android SAF implementation can use:

Uri
ContentResolver
DocumentsContract
DocumentFile

The application doesn't need to know which implementation is currently providing the storage.

The interesting part: cross-filesystem operations

This is where things become considerably more interesting.

Consider:

JVM filesystem
      ↓
      ↓ copy
      ↓
SAF

The source might be:

/home/user/file.zip

while the destination might be:

content://.../tree/...

There is no useful way to make both sides behave like java.io.File.

Instead, the operation has to understand both storage systems.

Conceptually:

JVM source
   ↓
InputStream
   ↓
buffer
   ↓
OutputStream
   ↓
SAF destination

And the reverse is equally important:

SAF source
   ↓
InputStream
   ↓
buffer
   ↓
OutputStream
   ↓
JVM destination

This is why I eventually became less interested in simply wrapping File.

The abstraction needs to represent storage operations, not just filesystem paths.

Relative paths become interesting with SAF

Another problem appears when working with a selected SAF tree.

Suppose an application asks the user to select a root directory.

The application can then operate relative to that root:

selected root/
    projects/
        demo/
            example.txt

The application might want to say:

createFile("projects/demo/example.txt")

rather than repeatedly passing the root URI around.

This creates a useful model:

Selected root
     +
Relative path
     ↓
Resolved document

The implementation can traverse the document tree and create missing directories where appropriate.

That gives application code a filesystem-like experience without pretending the underlying storage is actually a filesystem.

Why not just use DocumentFile everywhere?

DocumentFile is extremely useful.

It provides a convenient object-oriented API for working with document trees and makes traversal considerably easier.

But abstraction layers also have to consider performance and API boundaries.

There are situations where direct use of:

DocumentsContract

and:

ContentResolver

is more appropriate.

In my implementation, I ended up using both approaches depending on the operation.

DocumentFile is useful for traversal and convenient document operations.

DocumentsContract provides lower-level access to document-provider operations.

The important lesson is that a good abstraction doesn't necessarily mean choosing one Android API and hiding everything else behind it.

It means choosing the appropriate mechanism for each operation.

SAF also changes what a "path" means

This is probably the biggest conceptual difference.

On a traditional filesystem:

/home/user/project/file.txt

is a path.

With SAF:

content://provider/tree/...

is an identifier for a resource managed by a provider.

That distinction matters.

A URI can contain information that looks path-like, but it shouldn't be treated as if it were a normal filesystem path.

This is why APIs such as:

File(uri.path)

are fundamentally the wrong abstraction for SAF.

A robust storage abstraction has to understand that there are different resource addressing models.

What about cloud storage?

This is another reason SAF is interesting.

A document provider can abstract storage that isn't necessarily represented as a normal local filesystem.

From the application's perspective, the interaction can still look like:

open document
read stream
write stream
create directory
delete document

The provider handles the underlying storage.

This is one of the reasons I don't think of SAF simply as "Android's annoying file picker."

It is closer to a provider-based storage interface.

The application requests operations against documents.

The provider determines how those documents are actually represented.

So where does MediaStore fit?

MediaStore and SAF solve different problems.

If you're building an application that primarily works with shared photos, videos, audio or other supported media, MediaStore is often the appropriate API.

SAF becomes more relevant when the application needs the user to choose arbitrary documents or directory trees and then work with them through the document-provider model.

A modern Android storage architecture therefore isn't necessarily:

File

or:

SAF

or:

MediaStore

It is often:

                 Application
                      |
          +-----------+-----------+
          |           |           |
     App storage   MediaStore    SAF
          |           |           |
       private      shared      documents
                                 |
                         Document Provider

The right choice depends on the application's requirements.

Why I built a filesystem abstraction

After working with these differences, I wanted application-level code to be able to perform filesystem-like operations without constantly knowing which storage mechanism was underneath.

That led to my filesystem library.

The idea is simple:

FileSystems.current = JvmFileSystem()

or:

FileSystems.current = AndroidSafFileSystem(...)

Then higher-level operations can work through the abstraction.

The JVM implementation deals with traditional filesystem paths.

The Android implementation understands SAF URIs, document trees, ContentResolver, DocumentsContract, and document traversal.

The application gets a consistent API while the implementation deals with the storage-specific complexity.

This doesn't make Android storage "simple"

And that's important.

A filesystem abstraction doesn't magically turn SAF into java.io.File.

There are still differences.

For example:

SAF resources don't behave like normal filesystem paths.
Some operations depend on what the document provider supports.
Permissions are granted by the user.
A provider may have different capabilities from a local filesystem.
A URI may represent storage outside the traditional local filesystem.
Operations such as renaming, creating documents and traversing directories have provider-specific semantics.

A good abstraction should expose those realities rather than hide them until they become bugs.

The real problem is storage integration

The difficult question isn't:

"How do I read a file on Android?"

That's easy.

The difficult questions are:

"How do I design an application that can work with multiple storage models?"

"How do I copy between a traditional JVM filesystem and a document provider?"

"How do I expose relative paths when the underlying storage is a URI?"

"How do I keep storage-specific code from leaking throughout the application?"

"How do I build a filesystem-like API without pretending every storage backend is actually a filesystem?"

Those are architecture problems.

And that's where filesystem abstraction becomes useful.

The future isn't necessarily one filesystem API

Modern applications increasingly interact with storage through abstractions.

A local filesystem is one abstraction.

MediaStore is another.

SAF is another.

Cloud document providers introduce another layer.

The important skill isn't memorizing every API.

It's understanding what storage model you're actually working with and designing your application around that model.

That's what my work on filesystem integration has taught me.

Android storage isn't just about files anymore.

It's about resources, providers, permissions, URIs, streams, and abstractions.

And sometimes, the best solution is to build an abstraction that lets the rest of the application stop worrying about which one it's dealing with.

About the author

I'm Sifiso Fakude, a software developer focused on Android storage, filesystem integration, and developer tooling.

My work includes building filesystem abstractions that bridge traditional JVM filesystems with Android's Storage Access Framework and exploring the architectural challenges created by modern Android storage.