Mezzanine

KO | EN

gitlite — search

#javascript #react #llm #golang #go #android #deep-learning #docker #windows #kubernetes #vue #security #ios #open-source

(★ 62)

A Gradle plugin and Kotlin Symbol Processor that reads files at compile time

Mezzanine Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Mezzanine
A Gradle plugin and Kotlin symbol processor that allows you to read static UTF-8 files synchronously.

## What does this do?
Android apps often need to read in a default configuration file on startup and change functionality based on the contents of the configuration file. A convenient, frequently used way to store this configuration file is in assets, and then to read out of this file on startup. This can mean doing expensive disk I/O on the main thread, which increases startup times. You can get around the additional I/O by pasting the contents of the file into a `String` constant, but this can make code review difficult.

Mezzanine solves this problem by generating a class at compile time which stores the file contents in a `String` constant. This is loaded by the class loader, along with your code, when the application is started, rather than requiring additional disk I/O after startup. It acts as an intermediary between files and your running Kotlin code. Instead of needing to paste the contents of the file into the constant yourself, you can store it in its own file and maintain proper separation. For instance, if you are executing JavaScript using a `WebView` or some library like `duktape`, you can store the files in `.js` files without the additional annoyance of needing to perform disk I/O.

Note: There is a hard limit set by the javac compiler where `String` constants cannot exceed `65535` bytes in size.

## Usage

To your application's `build.gradle.kts`, you must apply the Kotlin plugin, the KSP plugin, and the Mezzanine plugin.

```kotlin
plugins {
    kotlin("jvm") version "LATEST_VERSION"
    id("com.google.devtools.ksp") version "LATEST_VERSION"
    id("com.anthonycr.plugins.mezzanine") version "2.3.0"
}
```

Then add the build dependencies to the `dependencies` block.

```kotlin
dependencies {
    implementation("com.anthonycr.mezzanine:core:2.3.0")
    ksp("com.anthonycr.mezzanine:processor:2.3.0")
}
```

Then setup the `mezzanine` extension to pass the file you want to be processed. You can pass as many files as comma separated paths as you need. The path should be relative to the project root.

Additionally, you will need to specify whether Mezzanine should generate the mezzanine function in this module or not, using the `generateMezzanine` property.
Only one module can generate the mezzanine function. Usually, you would set this to `true` in your top level or application module and `false` in your other modules. Defaults to `true`.

```kotlin
mezzanine {
    files = files(
        "src/main/assets/test.json"
    )
    generateMezzanine = true
}
```

After the above has been added to the `build.gradle.kts`, a Kotlin interface must be created in the project.

The interface must
- Have one function with no parameters and a return type of `String`.
- Be annotated with `@FileStream(path)` where `path` is one of the values passed in the extension setup in the `build.gradle.kts`.

```kotlin
@FileStream("src/main/assets/test.json")
interface TestJson {
    fun produce(): String
}
```

Then where you need to consume the file, obtain an instance of the file stream using the `mezzanine` function.

```kotlin
import com.anthonycr.mezzanine.mezzanine

val testJson = mezzanine<TestJson>() // Alternatively, call the generated constructor _Mezzanine_TestJson()
val fileContents = testJson.produce()
```

## Building Cross-Platform

By default, Git checks out files in a repo using the platform default EOL character. This can result
in Mezzanine seeing different file contents when building on Unix based systems or Windows systems.
While this might not affect the functionality of the project, if you have assertions based around 
the output or require that the files being read have a specific formatting, it is recommended that
you set the EOL character explicitly in `.gitattributes` for the files you have Mezzanine read. For 
example, in this project, the files we are reading are all JSON files, so the contents of our
`.gitattributes` are as follows (so that we can support building on both Unix and Windows based 
systems).

```
*.json text eol=lf
```

## Additional Considerations
- Files are assumed to be encoded as `UTF-8`.
- Files must be less than `65kB`, otherwise compilation will fail.

Licensed under the Apache License, Version 2.0 (the "License"); you may 
not use this file except in compliance with the License. You may obtain 
a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software 
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 
License for the specific language governing permissions and limitations 
under the License.
````

Mezzanine

Mezzanine Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Mezzanine

Mezzanine Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README