Classpath howto

Both kotlinc and java commands recognize the short form -cp and the long form --CLASSPATH flag. This howto guide describes what this flag means and how you can avoid giving it every time you invoke kotlinc or java.

CAVEAT: In this guide, I need to be concrete and specific when giving examples. In such cases I choose names I like, or real pathname as existing on my computer. So when you implement the ideas in this guide, you have to make appropriate changes like using your real login name and using the real pathname of your kotlin runtime library, etc.

Compiling Kotlin programs that use the Processing core library

Many MCS-178 projects use the processing library to draw graphics and perhaps also perform simulation. The core processing library is available here as core.jar. I suggest you keep all the jar files related to MCS-178 in one place, say in the directory ~/java. After downloading core.jar, you should create the java directory in your home directory, and move core.jar into it by typing these two commands

$ mkdir ~/java
$ mv ~/Downloads/core.jar ~/java

at the shell prompt $. Now you can compile your Kotlin program as follows. Suppose your Kotlin source file is named File.kt and your current directory is where the file File.kt is at. You can type the following at the prompt $

$ kotlinc -cp .:~/java/core.jar File.kt

This command tells the kotlin compiler kotlinc to compile the source file File.kt, and also tells it that all class files the program needs can be found either in the current directory . or in the jar file core.jar in the java directory of my home directory.

If the compilation is successful, it should produce, amongst other files, the class file FileKt.class which can be run using the java command to be described next.

Running Kotlin programs that use the Processing core library

You can use the java command to run your class file as long as you tell it where the files containing the classes that it uses reside. Let’s say that you have a class file named FileKt.class that was compiled from the Kotlin source file File.kt that uses the processing core library. Assume further that your shell’s current directory is in the same directory as the file File.kt. You need to tell java about these 3 things:

1. where the Kotlin runtime classes are,
   
2. where the file core.jar is, and
3. where the file FileKt.class is.

In case of the Mac machines in the lab these files are at (1) /opt/local/share/java/kotlin/lib/kotlin-runner.jar (2) $HOME/java/core.jar (3) .

Therefore, I can put these paths together, separating them by :, and give the whole thing to java in a --CLASSPATH or -cp flag. So the full command I have to type in order to run FileKt.class is

$ java -cp "/opt/local/share/java/kotlin/lib/kotlin-runner.jar:$HOME/java/core.jar:." FileKt

Saving keystrokes via an environment variable

If you have to give the same long classpath flag often—whenever you execute kotlinc or java—you may want to save some typing.

As luck would have it, the java command also inspects the CLASSPATH environment variable and uses it as default if you did not give the -cp flag on the command line. So you should assign the long combined paths to the CLASSPATH shell environment variable by typing

$ CLASSPATH="/opt/local/share/java/kotlin/lib/kotlin-runner.jar:$HOME/java/core.jar:.

at the shell prompt $. From now on whenever you need to run a Kotlin class file that uses the processing core library, you can omit the -cp flag altogether, that is, you can simply type

$ java FileKt

to run FileKt.class.

However, your definition of CLASSPATH will be gone once you exit the terminal program. To make the definition available every time you use the terminal, add the line

$ export CLASSPATH="/opt/local/share/java/kotlin/lib/kotlin-runner.jar:$HOME/java/core.jar:."

to your ~/.bash_profile file.

Unfortunately, the writer of kotlinc did not make it look into the environment for an existence of the CLASSPATH variable. So this method solves only half of our problem. You still have to find some other way to save keystrokes when giving long class paths to kotlinc.

Saving keystrokes via the alias mechanism

A better way to save keystrokes solves the problem fully. In bash, you can give any command (or partial command) an alias. When you type an alias of a long string to bash, it will replace the alias with the string it is aliasing. For example, if you type

$ alias pktc="kotlinc -cp $HOME/java/core.jar:."

and later type

$ pktc Bears.kt

bash will think that you have just typed

$ kotlinc -cp $HOME/java/core.jar:. Bears.kt

and respond accordingly.

Your first step should be to put two aliasing lines

alias pktc="kotlinc -cp $HOME/java/core.jar:."
alias pkt="java -cp /opt/local/share/java/kotlin/lib/kotlin-runner.jar:$HOME/java/core.jar:."

in your ~/.bashrc file and make sure your ~/.bash_profile has this line

source ~/.bashrc

at the end. This sets up the system so that you can have the aliases pktc and pkt for use as commands at all time.

After putting the two alias definitions in ~/.bashrc, the definitions won’t take effect immediately. They will take effect the next time you open the terminal app. If you want them to take effect right after you have saved the definitions, type

$ source ~/.bashrc

and continue working from that terminal with the alias definitions in memory.

With the pktc and pkt aliases in bash’s memory, you can compile your program Bears.kt by typing

$ pktc Bears.kt

and then execute the file BearsKt.class by typing

$ pkt BearsKt