ionspin / kotlin-spec

Kotlin Language Specification:

Kotlin Language Specification

This repository contains the specification of the Kotlin programming language, which describes how parts of the language should function in more detail, as compared to a more traditional user documentation on the Kotlin Website.

It would be most useful to those who are interested in how Kotlin works on a finer level and how its features interoperate, e.g., language enthusiasts, compiler writers and Kotlin power-users. However, if you are simply wondering, why some code you wrote works the way it does, this specification might help you get an answer to that.

Currently, the specification covers only what we call Kotlin/Core: fundamental parts of Kotlin which should function the same way irregardless of the underlying platform. In the future, we plan to extend it with additional platform-specific sections covering Kotlin/JVM, Kotlin/JS and Kotlin/Native.

Compatibility

Kotlin Language Specification is still in progress and has experimental stability level, meaning no compatibility should be expected between even incremental releases, any functionality can be added, removed or changed without warning.

Artifacts

HTML version of the specification is available on the Kotlin Website.

PDF version can be downloaded using the links in the HTML version or using the direct link.

Kotlin grammar

The grammar is a part of the specification and is also contained in this repository.

The reference grammar files in ANTLR4 format are located in the grammar folder. The human-friendly version is available on the Kotlin Website, in the HTML or PDF version of the specification.

Building the specification

The specification is built using Gradle. Therefore, most dependencies are downloaded by the build system.

However, there are several external dependencies which should be installed separately. For instructions on how to do this, please refer to your operating system documentation.

• Pandoc (tested with version 2.9.1)
• npm (tested with version 6.14.6)
• gpp (tested with version 2.25)
• bash (tested with version 5.0.17)

After installing these dependencies, building the specification is as easy as running:

./gradlew buildWeb buildPdf

which creates both HTML and PDF versions of the specification in ./build/spec.

When doing the build for the very first time, you will see Gradle downloading ideaIC-LATEST-EAP-SNAPSHOT.zip, which may take quite a long time. This IDEA snapshot is used for specification and grammar tests, and will be cached (until a new version is available), so this lengthy download should happen only once (in a while).

The PDF version is available in two flavours: single-file PDF, containing the complete specification, and a set of section-based PDFs, containing their respective sections.

The HTML version consists of a set of section-based pages linked together via an interactive table of contents.

Contributing

If you want to contribute to the specification, that's great! You can help us make the Kotlin specification better by one of the following ways.

1. Create an issue and describe what you think can be improved
2. Make a pull request and extends the specification
3. Discuss the specification on the Kotlin forums
4. Drop an email to Marat Akhin or Mikhail Belyaev with your suggestions

Note: if doing a pull request, it should be based on the develop branch.

We welcome any and all feedback to the specification, but may tweak, change or iterate with you on the contribution before including it in the specification.

Further details on how to contribute to the specification are available in CONTRIBUTING.md.

Reference

If one needs to reference this specification, they may use the following:

Marat Akhin, Mikhail Belyaev et al. "Kotlin language specification: Kotlin/Core", JetBrains / JetBrains Research, 2020