The documentation for Kotlin is now located on the new site. This page is kept for historical reasons

Skip to end of metadata
Go to start of metadata

The documentation for Kotlin is now located on the new site. This page is kept for historical reasons


Modules are being redesigned

A module is a unit of compilation in Kotlin. Physically, modules are described by build scripts. Such scripts programmatically assemble module descriptors that carry information about source files that constitute the module, dependencies, and compiler options used to build the module.

Being a unit of compilation means that all the analyses and optimizations may be performed module-wise, and that binary compatibility issues arise only on module boundaries.

Module identifiers and root namespaces

Each module must have a unique identifier. This becomes and identifiers for the module's root namespace – the one all other namespaces in that module reside in.

Default imports

A build script for a module may specify a set of default imports for its source files. It is convenient to import ubiquitously used libraries (like collections, UI, etc) by default.

Filesystem layout

Kotlin does not require any particular layout of source files in the file system: a namespace may not correspond to a directory, and a class may not occupy its own file. I.e. one can put all the source code for a module into a single source file.


Modules can depend on other modules, and specify version requirements for their dependencies.

While exact API is not settled yet, the module script file may look like this:

val homeDir = "..." 
module("org.jetbrains.test") { 

What's next

  • No labels


  1. Anonymous

    Please use proper dependency versions. 4.8.2 in Maven means 4.8.2 if you have it otherwise anything will do. [4.8.2] means I want 4.8.2 and only 4.8.2. If anything from 4.8.2 onwards is ok but nothing after 4 as I have no idea what that might entail, use [4.8.2,5)

  2. Is it intended that this build language be the sole/primary way of compiling Kotlin code, or will there be the possibility of writing Ant/Maven plugins to integrate with existing build infrastructures?  Having written several maven plugins I'd be keen helping out with a kotlin-maven-plugin.

    1. Build language is not there yet but there are two things that we'd like about building:

      1. The unit of compilation mustn't be just a file or list of files

      2. Build script is a code (written in Kotlin, naturally)

      There surely will be the bridges in all Ant/Maven/whatever directions or it will hurt Kotlin adoption badly.

  3. i hope with that module concept the java dependency hell can be left behind.

    loading different versions of the same library (if possible bound to different namespace) would finally allow to solve tasks which are actually not possible in pure java.

    i.e. apache wink uses slf4j if it gets mixed with other library that also use slf4j but in different version then exceptions require you to decide to kill the project or choose different frameworks with different dependencies.

  4. Anonymous

    Mark asked about build-time interoperability with Maven/Ant etc, I'm curious about your plans for the runtime. Will your modules have any runtime representation, and if so will it be compatible with OSGi?  -- Neil Bartlett

    1. Well, modules will definitely be introspectable at runtime. No definite decision on OSGI yet.

      1. +1 on OSGi support.  Without it Kotlin would be a total non-starter for me (currently).  Definitely liking what I'm reading tho.

  5. Anonymous

    +1 on modularity support but not necessarily OSGI. Huge projects, with millions of lines of code and hundreds of developers, need some thing like OSGi, Ivy or Maven. I imagine that the upcoming OSGi/Jigsaw debacle could be an opportunity for your new language. 

  6. Anonymous

    Please don't use the word 'module' to mean compilation unit.  Yes, yes, I know that the word 'module' is standard usage to mean compilation unit. 

    However, in the Java environment, 'module' has come to mean an OSGi-like module: that is, a deployment unit: a runtime 'component' ... a modularized jar file.  Notice how even in this thread, the mention of the word 'module' has evoked OSGi questions.  The confusion has already begun, even though the two are completely unrelated.

    Since the word 'module' is already in use in the OSGi context, please choose another work for 'compilation unit'.  How about, well, 'compilation unit'.  That works just fine.  I don't think you need to add a new word for that. 

    Now, with respect to OSGI:  The biggest problem with OSGi right now is not having "native" support with a consistent and easy-to-use set of tools.  This is a huge opportunity for you.  You could solve the OSGi problem and provide a set of tooling that would make everybody happy.  If there were a natural and native way to represent runtime OSGi modules in Kotlin, I think you would attract a whole class of developers that have been looking for this solution.  And this would make the Java runtime environment that much more robust.

    +1 for OSGi support

    1. Could you expand on what you call "native" support for OSGi? Thanks

      1. Building modular applications is hard.  But if I am going to start from scratch, with a new language, I would want to make sure that my applications are modular from the beginning.  This is what industrial strength should mean.

        A post in the blog entry I linked to above says this:

        Dependencies should be defined in some kind of source file. Like, say, Java source, which already has import statements after all. I can even put annotations in my Java source that define which packages are to be exported, what the version of each package is, etc.

        OSGi adds a layer of information hiding at the level of the run-time module.  One module can only call those elements of another module that are exported by that module.  It also says that one module is only interested in certain versions of another module.  OSGi implements this at the level of the jar file by adding a customized manifest which is implemented through specialized class loaders.

        Languages currently don't encapsulate the runtime module, only the 'compilation unit', and the 'package'.

        A run-time module provides limited visibility into one or more packages.  Think of the packages that might go into a jar file.  Just because something is public to a package in a jar file does not mean it should be public to the run-time module that contains that package.

        I'm not sure exactly what type of language construct are needed to support run-time modules.  This pushes to the edges of the language definition, because it is more of a deployment concept than a programming concept. 

        I guess what I am trying to say is that it should be a pleasure to develop modular, industrial-strength, applications.  I'm not sure exactly what this means in terms of a language support.  But I want it.  :)

        1. Got your point. Thanks

          1. Not to belabor this, but here are some links you might be interested in:

            Developing Modules for Development

            Project Jigsaw

            Also, JBoss has recently released the JBoss OSGi Framework.  WebSphere is supporting OSGi.

            OSGI technology is mature and is reaching critical mass.

            One poster said: I guess we’ll have to wait for whatever comes after Java.

            I think that's your cue. :)

  7. I'm going to add a couple of more thoughts in favor of supporting some form of runtime components ("modules") which are basically jar files + information hiding (controlled classpath).

    My first though has to do with project comprehension.  When you join an existing project, there is often some architectural documentation which gives you a birds eye view of project.  This may come as a block diagram, or perhaps something a little more granular -- perhaps including major "sub-systems".  Then you're pointed to the JavaDocs, which has package, class and method documentation, but at this point, you are way down in the weeds.  What you need is something at a higher level than JavaDocs but lower than architectural documentation.

    There is a middle level which is what the experienced developers on a project carry around in their brains.  But this is often never documented.  And if it is documented, the documentation is probably way out of date because it was created at the beginning of the project but hasn't been updated since.  The challenge for a new developer is to get this middle-level model of the software into his own brain. 

    This middle level is approximately the level of runtime components.  It is above the class level but below the architectural level.  It shows the interaction between the "components" of the system, but is finer that the system or sub-system level.  It is certainly above the package and class level.  Knowledge of this level is what differentiates the experienced developer from a new developer (who struggles to learn this level).

    Having this middle level formalized somehow in the language (or perhaps somewhere in language metadata) would allow tooling that could extract information about this middle level and present it as current, up-to-date mid-level design documentation.  This would greatly facilitate project comprehension for new developers but would also fill a needed gap in project documentation.  Something like JavaDocs on steroids.  It would provide meaningful descriptive information about this middle level and could be generated on demand.

    Having some type of formal support for runtime components, in addition to being intrinsically useful, would foster this type of mid-level documentation, that in my opinion, is desperately needed.

    My second thought has to do with the 'dynamic' part of OSGi.  OSGI really has two different levels:  the 'module' level and the 'service' level.  The service level is dynamic and the module level is not.  If you were to build 'Kotlin Modules' on top of OSGi (or even if not), you could have a successful implementation without necessarily having to support the dynamic service layer.  This would simplify things greatly and would be one way to limit the scope of an initial implementation but still be able to provide something useful.

    Anyway, just 2 more cents from me ... :)

      1. Anonymous

        By the way. Can I put comments in Russian? 

        1. If you want to provide feedback in Russian, please, send it directly to andrey (dot) breslav (at) jetbrains (dot) com

  8. We use OSGi in a project at work and I don't see how we could get along with OSGi without the two consultants we have that have a lot of experience with OSGi. All the internal knowledge you need to have about OSGi when something doesn't work to figure out what the problem is is a pain. When you have changed your code and want to test it you need to recreate the respective OSGi bundle which means you have to rebuild your Java project. Say good bye to incremental compilation and developer productivity. When you are done with developing your component you turn it into an OSGi bundle. Nope, doesn't work. With OSGi the Maven dependencies become much different and your code brakes. I can't say I find this very developer friendly nor productive. Some lightweight alternative like JBoss Modules with good developer productivity and good tool support would be an OSGi killer.

    Then the only way to create an OSGi bundle seems to define some OSGi plugin in maven that does the work for you. You have to pass on some settings that seem to be magic and not documented anywhere. You have to hire some freelancer who knows OSGi to tell you. So good tool support is also important to prevent developer productivity from plumeting. IMHO, it is better to leave the module system out for the time being till you have a better solution than OSGi or a smoother integration.

    1. Just a note: Runtime modules != compile-time modules