Arbor

Timber like logging implementation for Kotlin Multiplatform.

Purpose

This library was built as a practical experiment with Kotlin Multiplatform and specifically the new single module approach. Despite Kotlin's excellent documentation it was unclear how to properly publish all artifacts to Maven such as sources and documentation. Hopefully this project provides a more complete template for others to use.

API

Arbor follows a very similar usage pattern to Timber. Key differences exist in feature support and terminology which was done purely because I had a thesaurus laying around.

Sow Your Seedling

Seedlings are platform specific logging implementations such as using Logcat in Android and println in JavaScript.

Android

Arbor.sow(LogCatSeedling())

JavaScript

Arbor.sow(Seedling())

JVM

Arbor.sow(Seedling())

Custom seedlings can be created from the com.toxicbakery.logging.ISeedling interface.

Logging

All logging is triggered from the Arbor static methods which supports debug, info, verbose, warning, error, and wtf. Logging calls are passed to the underlying branch implementation and finally to the sown seedling instances.

Arbor.d("Hello World!")

Log tagging is automatic on Android but can be easily overridden.

Arbor.tag("Custom Tag").i("My Log with a tag.")

Kotlin Extensions

While Arbor supports writing string concatenations, leveraging Kotlin concatenations leads to strings being evaluated regardless of if they will be logged. In release that means CPU cycles may be wasted towards logging that is ultimately never printed. The arbor Kotlin extension leverages functions to work around this.

Debug message

arbor { "Debug" }

Changing the log level

arbor(LogLevel.E) { "Error" }

Levering custom tags via Arbor branches

val tag = Arbor.tag("MyTag")
arbor(branch = tag) { "Custom Tag" }

Install

Arbor is a Kotlin Multiplatform project supporting JavaScript, JVM, and Android platforms.

Android

implementation "com.ToxicBakery.logging:arbor-android:1.+"

JavaScript

implementation "com.ToxicBakery.logging:arbor-js:1.+"

JVM

implementation "com.ToxicBakery.logging:arbor-jvm:1.+"

Migrating from Timber

Library migrations can be difficult. I've written a drop in kotlin file that can be placed anywhere in your application for a generally 1:1 mapping of Timber to Arbor. Notably missing is extension functions for string formatting.

https://gist.github.com/ToxicBakery/e55f55ec73450257901431c06eb1e969

Alternately, Kotlin can be leveraged more directly if you prefer.

package timber.log

typealias Timber = com.toxicbakery.logging.Arbor

This has a drawback in that Timber.tag(...) calls will not work.