Packaging, Compilation, and Just

Author: bowbahdoe

src/SUMMARY.md

@@ -841,7 +841,7 @@ Make them do one. -->
   - [java.base](./modules/java.base.md)
   - [The Unnamed Module](./modules/the_unnamed_module.md)
   - [Module Imports](./modules/module_imports.md)
-  - [Multi-Module Directory Layout]()
+  - [Multi-Module Directory Layout](./modules/multi_module_directory_layout.md)
 - [Lambdas](./lambdas.md)
   - [Functional Interfaces](./lambdas/functional_interfaces.md)
   - [@FunctionalInterface](./lambdas/functional_interface_annotation.md)
@@ -861,20 +861,46 @@ Make them do one. -->
 # Sharing Code
 
 - [Compilation](./compilation.md)
-  - [javac]()
-  - [--release]()
-- [Packaging]()
-  - [jar]()
-  - [--main-class]()
-- [Documentation]()
-  - [javadoc]()
+  - [javac](./compilation/javac.md)
+  - [Class Files](./compilation/class_files.md)
+  - [Modules](./compilation/modules.md)
+  - [Compile Multiple Files](./compilation/multiple_files.md)
+  - [Clean](./compilation/clean.md)
+  - [-g](./compilation/g.md)
+  - [Running Compiled Code](./compilation/running_compiled_code.md)
+  - [Challenges](./compilation/challenges.md)
+- [Packaging](./packaging.md)
+  - [jar](./packaging/jar.md)
+  - [Jar Files](./packaging/jar_files.md)
+  - [--module-path](./packaging/module_path.md)
+  - [--main-class](./packaging/main_class.md)
+  - [Libraries](./packaging/libraries.md)
+  - [Challenges](./packaging/challenges.md)
+
+# Tools
+
+- [just](./just.md)
+  - [Installation](./just/installation.md)
+  - [Justfile](./just/justfile.md)
+  - [Recipes](./just/recipes.md)
+  - [Dependencies](./just/dependencies.md)
+  - [Documentation Comments](./just/documentation_comments.md)
+  - [Further Reading](./just/further_reading.md)
+  - [Challenges](./just/challenges.md)
+
+# Sharing Code II
+
+- [Distribution](./distribution.md)
+  - [jars](./distribution/jars.md)
+  - [jlink]()
+- [Documentation](./documentation.md)
   - [Documentation Comments](./documentation/documentation_comments.md)
+  - [javadoc]()
   - [@param]()
   - [@return]()
   - [@throws]()
   - [Markdown]()
-- [Distribution]()
-  - [jlink]()
+
 
 <!--- 
 PROJECT IDEAS:

src/compilation.md

@@ -3,3 +3,13 @@
 The first step to sharing code you've written with other people is to
 compile it.
 
+Compilation in the context of programming languages means that a program
+reads all your code, ensures it abides by the rules of the language,
+and translates your code to some other form. Usually this other form 
+is in some manner more directly "runnable" than the code you started with.
+
+We call programs that do this reading, ensuring, and translation "compilers."
+
+This happens behind the scenes when you run `java src/Main.java`
+but for sharing code you will need to do it yourself as a separate
+step.

src/compilation/challenges.md

@@ -0,0 +1,30 @@
+# Challenges
+
+Remember the rules for this are
+
+- Try to use only the information given up to this point in this book.
+- Try not to give up until you've given it a solid attempt
+
+## Challenge 1.
+
+Take your code from one of the previous projects and compile all of it
+to class files.
+
+Make sure you can then run it using those class files.
+
+## Challenge 2.
+
+Take the code for one of the previous projects and put it in
+the multi-module directory layout.
+
+Compile it using the `--module-source-path` and `--module`
+options instead of listing the files out explicitly.
+
+Make sure you can then run it using the `--module-path` and `--add-modules ALL-MODULE-PATH`
+flags.
+
+
+## Challenge 3.
+
+Run the command from the previous command again, this time making sure to pass `-g`.
+Be sure to also clean whatever directory you used for output. 

src/compilation/class_files.md

@@ -0,0 +1,27 @@
+# Class Files
+
+The format that the Java compiler outputs is called a "class file."
+
+These class files are what is loaded into the "Java Virtual Machine" to actually run your program. This is
+in part because the Java Virtual Machine was conceived as a general tool not technicially specific to Java.
+
+There are other languages besides Java - such as [Clojure](https://clojure.org/) and [Kotlin](https://kotlinlang.org/) - which
+also can be compiled into class files. 
+
+```text
+
+Java Source Code --> javac -------------\
+                                         ----> Class Files --> Java Virtual Machine
+Kotlin Source Code --> kotlinc ---------/  |
+                                          /
+Lombok Source Code --> lombokc ----------/
+
+... and more
+```
+
+This lets those languages make use of the Java Virtual Machine and all the millions
+of dollars and decades of work put into making it run code fast.[^bringup]
+
+[^bringup]: I bring this up because if you are only thinking about Java it might seem like a
+pointless extra step. It somewhat is, but at the same time it lets other languages "compete"
+on more or less even ground. The JVM is a labor of fill-in-the-blank, that is for sure.

src/compilation/clean.md

@@ -0,0 +1,22 @@
+# Clean
+
+If you compile code multiple times you should "clean"
+your working directory before each compilation.
+
+This is because when you run `javac -d output ...` the compiler
+will simply dump class files into the destination folder.
+It will not remove any "stale" class files from earlier compiler runs.
+
+This can lead you to be in a state where you think your code is working
+but if you ever compiled it again, from scratch, you would get errors.
+
+The simplest way to handle this in bash is to use the `rm` tool. `rm` **r**e**m**oves
+files. Before you run the compiler clear out any old output with `rm -rf output`.
+`-rf` stands for "**r**ecursive" and "**f**orce." This is what you need to delete whole
+folders.[^simple]
+
+[^simple]: This technique - just deleting folders and doing the work from scratch again - can be slow.
+The upside of this approach is that it is simple to understand.
+It also probably doesn't matter since your computer is fast. When you need to really efficiently compile
+huge codebases you turn to a special kind of program called a build tool. These are complex beasts but can
+avoid unneccesary work.

src/compilation/g.md

@@ -0,0 +1,39 @@
+# -g
+
+There are a lot of options you can pass to `javac` to alter its behavior.
+One of the ones that I find useful is `-g`. The `g` stands for "**g**enerate debug info."[^obvious]
+
+This makes sure the generated class files have information about things like what variables were named
+what. This, in turn, helps Java give better error messages
+
+For example, if you have a program like the following:
+
+```java
+class Main {
+    void main() {
+        String nocturne = null;
+        IO.println(nocturne.length());
+    }
+}
+```
+
+While in all situations it will ultimately crash with a `NullPointerException`, if
+you did not compile with `-g` you might get a stack trace like the following. 
+You will probably need to scroll to the right to see the relevant bit.
+
+```text,no_run
+Exception in thread "main" java.lang.NullPointerException: Cannot invoke "String.length()" because "<local1>" is null
+	at Main.main(Main.java:4)
+```
+
+Whereas using `-g` will get you an exception that includes the variable name of what was `null`.
+
+```text,no_run
+Exception in thread "main" java.lang.NullPointerException: Cannot invoke "String.length()" because "nocturne" is null
+	at Main.main(Main.java:4)
+```
+
+So, with rare exceptions, you should always use `-g`.  
+
+
+[^obvious]: Obviously.

src/compilation/javac.md

@@ -0,0 +1,41 @@
+# javac
+
+The compiler used for compiling Java code is called `javac`.
+This stands for "**Java** **C**ompiler".
+
+Its job is to take a list of `.java` files and compile
+them into `.class` files.
+
+For a single file Java program you can do this by running
+a command similar to the following.
+
+```bash
+javac -d output src/Main.java
+```
+
+The `-d output` in that example means "put the compiled class files in a folder called `output`."
+After running the command above you would expect to see something like the following.
+
+```text
+src/
+    Main.java
+output/
+    Main.class
+```
+
+You aren't guarenteed that any given `.java` file will produce only one `.class` file
+as output. Inner classes are one reason for this, but there are others.
+
+```text
+src/
+    Main.java
+output/
+    Main.class
+    Main$1.class
+    Main$Thing.class
+```
+
+To compile multiple files you need to list every `.java` file
+one after another.
+
+```

src/compilation/modules.md

@@ -0,0 +1,11 @@
+# Modules
+
+For reasons that will become apparent as we proceed,
+it is best if all all the code you intend to share
+is contained within a named module.
+
+This means at minimum your classes would need to be in packages
+and would need to provide a `module-info.java`.
+
+Many things will work even without that but some important ones
+will not.

src/compilation/multiple_files.md

@@ -0,0 +1,43 @@
+# Compile Multiple Files
+
+To have `javac` compile multiple files you have a few options.
+
+The first is to simply list every file you want to compile one after
+the other when calling `javac`.
+
+```bash
+javac -d output src/Main.java src/Other.java src/Another.java
+```
+
+This has the obvious downside of needing you to add new files to what can
+become a large list over time.
+
+If you get far enough in learning bash you can paper over this
+with commonly available tools like `find`.
+
+```bash
+javac -d output $(find ./src -name "*.java" -type f)
+```
+
+Where the `$()` is bash syntax that runs the command in the parentheses and uses its
+output as arguments to the command being run. `find` is a tool that lists all files that
+match some criteria. In this case all files (as opposed to folders) that have a name that
+ends with `.java`.
+
+The other option is to structure your project using the multi-module directory layout.
+
+```
+your.project/
+  src/
+    code/
+      Main.java
+      Other.java
+    module-info.java
+```
+
+If you do this then you can compile all the code in a module by using the `--module-source-path` and `--module` options.
+
+```bash
+javac -d output --module-source-path "./*/src" --module your.project
+```
+

src/compilation/running_compiled_code.md

@@ -0,0 +1,44 @@
+# Running Compiled Code
+
+The way you ultimately run your compiled code depends on 
+whether or not all your code is in packages.
+
+If you have any classes in the unnamed package - which
+will only be the case when said code is also not in a named
+module - you should run your code like so:
+
+```bash,no_run
+java --class-path output Main
+```
+
+Where you can substitute `Main` for whatever the class you want to run is.
+So if you want to run a class named `Impromptu` in the `chopin` package
+you would run `java --class-path output chopin.Impromptu`.
+
+`--class-path` should be self-explanatory. It is the path where `java`
+will look for class files.
+
+But if you do not have any classes in the unnamed package - which will
+be hopefully be the case when you share code with others[^conflicts] -
+you instead want to run your code like this.
+
+```
+java \
+    --module-path output \
+    --add-modules ALL-MODULE-PATH
+    composers.Main
+```
+
+The `--module-path` option is very similar to the `--class-path` option. The difference
+is that all the code on the `--module-path` will be loaded with more strict rules.[^before]
+
+The `--add-modules ALL-MODULE-PATH` bit just means "load all the code on the module path."[^auth]
+
+[^conflicts]: Remember the social convention of reverse domain name notation (`com.google`, etc)
+
+[^before]: You can think of `--class-path` as sort of a "compatibility mode" for libraries 
+and code written before Java had a concept of modules. The difference isn't super important
+other than the very specific case of wanting to compile and run classes in the unnamed package.
+Well that and "troublesome" libraries, but we will get to that later.
+
+[^auth]: Chances are Java will make this the default in the future. For now you must write it though.