How to use external annotation on command line?

1

Hi there,

Is there any instruction on how to setup and use external annotation on command line?

Thanks,
Zemian

2

It's simple: just use -annotations option, which works similar to -classpath.          

3

Evgeny,

Please forgive my nooby questions, but I am at lost as what to do. The helppage says:

  -annotations [String] paths to external annotations

So what value to pass to -annotations option? You said value should be like "-classpath"? So I add directories paths separated by path separator? What content should these directory contain? Jar file?

I asked similar question in here: http://blog.jetbrains.com/kotlin/using-external-annotations, but Andrey seems to indicate that we need an XML file for command line usage? So how do I generate this XML file? And where would I put this file to be used by compiler?

Thanks,
Zemian

4

Yes, after "-annotations" option you pass list of annotations roots separated by path separator. Each root may be either directory or jar file.

The easiest way to generated XML files with annotations is using GUI in Kotlin plugin to IntelliJ IDEA which was described in linked blog post. It’s not that easy to write these XMLs manually. But if you are persistent enough for it (or you have some reasons not to use IDEA) you can still do it. Check lib/alt/kotlin-jdk-annotations.jar and see the format.

5

Evgeny,

I don’t want to get into touchy subject of how great IDEA is. Matter of fact, I think it’s a pretty good IDE (http://saltnlight5.blogspot.com/2012/12/intellij-idea-is-pretty-awesome.html). However, the Kotlin is a programming language, and itself should not force users to use any IDE. What you described does not make me feel good that I can’t use certain Kotlin feature without the IDE. At least it’s very hard to use. This is a turn off instead of incentive for me to learn Kotlin.

So having said that. I still not understanding how this “external annotation” works in term of command line usage with compiler. Perhaps I am not asking the right question, so let me try again.

Let’s say I want to assume/treat all JDK library to be null safe (I don’t want to use (!!) or (?) when using built-in JDK lib). So how do I do this without using any IDE, but using command line only?

Thanks,
Zemian

6

Could you offer some idea how this could be implemented?

Current format supports only annotating concrete Java methods with nullability/mutability information. You cannot say that all methods of certain lib are null-safe.

We are working on KAnnotator: a tool which will infer external annotations automatically by analyzing bytecode. It will be possible to provide various options for it (like null-safety by default). After that you’ll have XML files which you’ll be able to edit, if you want to tweak something.

7

> Could you offer some idea how this could be implemented?

Hum… I not am sure yet. I will share if I come across with idea.

> We are working on KAnnotator:  a tool which will infer external annotations automatically by analyzing  bytecode. It will be possible to provide various options for it (like  null-safety by default). After that you’ll have XML files which you’ll  be able to edit, if you want to tweak something.

But I thought M4 release is saying KAnnotator is ready for use no?. Thus my original question is how do I use it now that it’s ready?

8

Sorry for confusing, but technically we haven't released KAnnotator as a standalone tool. In M4 we released only automatically generated annotations for JDK built by KAnnotator. But we are planning to release the tool itself soon.

9

> In M4 we released only automatically generated annotations for JDK built by KAnnotator.

From a user/developer perspective, what does this mean? Again, how do I use it?

I don’t mean to push the issue. I think Kotlin is pretty good language on all the features I’ve seen so far. But this (!!) enforcement is littele troublesome for me to get over with. I mean I do understand the benefit of it. But perhaps I am not used to it enough, but I feel it’s hindering the readability of the code and hassle to work with when the entire built-in JDK library could return possible null values, and I have to constantly prevent it with (!!) operator. With this in mind, I am much interested in seeing this new feature of KAnnotator you guys have. However, I am lost as how to use it without the IDE.

10

>From a user/developer perspective, what does this mean? Again, how do I use it? Annotations for JDK are attached in standalone compiler automatically. The same happens with JDK runtime and Kotlin runtime: they appear in classpath automatically.

Of course we understand the troubles which are caused with null-checks in Kotlin, and we are working on making it easier to use. That’s why we are making KAnnotator.

11

Evgeny,

Can you please provide an example how to use “external annotation” through command line?

For example, here I have a simple program:

``

fun main(args : Array<String>) {

     val props = System.getProperties()

     //val keys = props!!.keySet()

     val keys = props.keySet()

     println(keys)

}

So in command line I get this error, which I expected so far.

``

bash> bin/kotlinc-jvm -output . -src Test.kt

ERROR: /Users/zemian/apps/kotlinc/Test.kt: (4, 18) Only safe (?.) or non-null asserted (!!.) calls are allowed on a nullable receiver of type java.util.Properties?

exec() finished with COMPILATION_ERROR return code

So I assume that this “external annotation” feature will eliminate that error. I attempted to use -annotations option as you suggested, but still got the same error:

``

bash> bin/kotlinc-jvm -annotations lib/kotlin-jdk-annotations.jar -output . -src Test.kt

ERROR: /Users/zemian/apps/kotlinc/Test.kt: (4, 18) Only safe (?.) or non-null asserted (!!.) calls are allowed on a nullable receiver of type java.util.Properties?

exec() finished with COMPILATION_ERROR return code

So how do I use it?

Zemian

12

As I said in previous post, our external annotatons for JDK are attached automatically. Unfortunately, we do not have automatically inferred annotation for System.getProperties() method (because KAnnotator couldn't infer it, and we didn't add it manually).

If you use it often, you can add your custom annotations for JDK (which will be merged with ours). To do it, create folder for holding annotations, add java/lang/annotations.xml with content (see our annotations for format example), and add “-annotations <path-to-your-annotations-folder>” to compiler’s command line arguments.

If you are willing to contrubute, feel free send us pull requests with adding this, and maybe some other annotations for JDK methods.