A development tool is a convenience and not a requirement. Every Java program that runs in production is compiled with javac and started with java from a terminal or from a build script. Learning those two commands takes the fog away, because a development tool hides exactly what they show you.
The previous lesson in this module covered "What Does Your First Java Program Look Like and How Do You Run It?", and the next lesson in this module is about "What Is the Difference Between JDK, JRE and the JVM?", which explains the three names that you keep meeting in every Java setup guide.
What are the two commands?
javac is the compiler. It reads source files that end in .java and it writes class files that end in .class. The java program is the launcher. It reads class files and it runs them.
The rule that surprises newcomers is that java never compiles source code, and javac never runs your program.
# compile every .java file in the current folder
javac *.java
# run a class by its fully qualified name
java com.example.Greeting
Look carefully at the name that you give to java. It is not the file name. It is the class name, and it carries the package prefix when the class sits inside a package. That detail becomes obvious as soon as you start to organise your files into folders.
How do you control where the class files go?
By default javac puts each class file right next to its source file, and that turns into a mess very quickly. The -d flag sends all of the output into one folder that you choose, and that folder then becomes the classpath that you hand to java.
mkdir -p out
javac -d out src/com/example/Greeting.java src/com/example/Util.java
java -cp out com.example.Greeting
There are two paths here and they have two different jobs. The flag -d out says where to write the compiled classes. The flag -cp out says where to look for them while the program runs. Keeping your source files in one folder and your class files in another is the layout that every build tool uses, so adopting it early makes the idea of a classpath much easier to see.
How do packages line up with folders?
A package declaration inside the source code has to match the folder structure below the source root. A file that declares package com.example; belongs in the folder com/example/, and the compiler refuses to build the project if the two do not agree.
# project layout
src/com/example/Greeting.java -> package com.example;
src/com/example/util/Helper.java -> package com.example.util;
# compile the whole tree
javac -d out $(find src -name '*.java')
java -cp out com.example.Greeting
You can run the program from any folder that is not the source root, and the same classpath still works. That is because the classpath is resolved against the place where you started the program. The one rule that always has to hold is that the package path and the folder path agree.
Can I run a file without compiling it first?
Yes. If you hand a source file straight to java, it compiles the file in memory and runs it. This is the fastest way to try out a small piece of code.
java Greeting.java
java --source 21 Greeting.java
This mode is made for experiments. It does not produce class files on disk, it does not support a whole project with several files, and it hides the compile step that you need to understand. Use it to check a fragment, and then go back to the two step flow.
Why do I get "ClassNotFoundException" or "Could not find or load main class"?
Both of those messages mean the same thing. The launcher could not find the class that you named. There are three usual causes, and they appear in this order of frequency. The name might be wrong, because the package prefix is missing. The classpath might not point at the folder that holds the compiled output. Or you compiled into one folder and then ran the program with the classpath set to a different folder.
# list what actually got compiled
find out -name '*.class'
# check the classpath that the runtime sees
java -XshowSettings:properties -cp out com.example.Greeting 2>&1 | grep -i class.path
Then compare the folder that you listed with the folder that you passed to -cp. If the class file sits at out/com/example/Greeting.class, then the classpath has to be out and the class name has to be com.example.Greeting. The package path is part of the class name, and the classpath is the root that the package path hangs from.
How do you ship a program as a single file?
Compiled classes are loose files, which is fine while you are learning and awkward when you want to give the program to somebody else. The standard packaging format is called a JAR. It is a zip archive that holds the class files and a small text file called a manifest, and the manifest names the class that should start first. Once you have one of these, a single command runs your program on any machine that has a compatible runtime. This is the shape that most Java applications are delivered in.
# 1. compile into a folder
javac -d out src/com/example/*.java
# 2. package the classes together with a manifest
jar --create --file app.jar --main-class com.example.Greeting -C out .
# 3. run it
java -jar app.jar
# 4. look inside the archive
jar --list --file app.jar
# what the archive contains
META-INF/
META-INF/MANIFEST.MF
com/
com/example/
com/example/Greeting.class
com/example/Util.class
The option --main-class writes the entry point into the manifest, and that is what lets java -jar know where to begin without you naming a class. Adding other libraries works in the same way. They go into the archive too, and the manifest lists them in its class path entry, or you place them next to the jar and name them yourself.
How do you read a compiler error that mentions a symbol?
The "cannot find symbol" error is the most common compiler error of all, and it has two usual causes. Either the name is spelled wrongly or the capital letters are different, or the class that declares the name has not been imported. The message tells you which symbol it wanted and where it was looking, and it usually lists the closest matches that it found. That list is often the answer sitting in plain sight.
Greeting.java:6: error: cannot find symbol
System.out.println(name.toUppercas());
^
symbol: method toUppercas()
location: variable name of type String
When the missing symbol is a type rather than a method, the fix is an import or a fully qualified name. When it is a method, the fix is usually a simple spelling mistake, and the compiler's list of suggestions usually contains the correctly spelled version.
Quick reference
- javac compiles and java runs. They never swap roles.
- The flag
-dchooses the output folder, and the flag-cpchooses where to look for classes. - A package declaration has to match the folder path below the source root.
- The command java File.java runs a single file, which is handy for quick experiments.
- You give java the package prefix and the class name, not the file name.
- A class not found error always means a wrong name or a wrong classpath root.
Try it yourself: create a small project with two classes inside a com.example package. Compile it with javac -d out, and then run it from three different folders using the classpath. Finally, rename the output folder and watch the class not found error appear, and then fix it by pointing the classpath at the right place.