docs: update build commands (build, build-classes, clean, jars)

src/build-and-packages.md

@@ -10,17 +10,19 @@ The Flix build system supports the following commands:
 
 - `init`: creates a new Flix project in the current directory.
 - `check`: checks the current project for compiler errors.
-- `build`: builds the current project (i.e. emits Java bytecode).
+- `build`: builds (i.e. compiles) the current project.
+- `build-classes`: builds the current project and writes the class files to the `build` directory.
 - `build-jar`: builds a jar-file from the current project. 
 - `build-fatjar`: builds a jar-file with all dependencies bundled.
 - `build-pkg`: builds a fpkg-file from the current project. 
+- `clean`: removes the `build` directory.
 - `run`: runs main in current project.  
 - `test`: runs all tests in the current project.
 
 All commands can be executed from the command line, from the REPL, and from
 VSCode.
 
-All commands, except `build-pkg` work without a manifest file. To build,
+All commands, except `build-pkg` and `clean`, work without a manifest file. To build,
 package, and publish a Flix project, a `flix.toml` manifest is required. The
 `init` command will create an empty skeleton `flix.toml` manifest, if not
 already present. 

src/build.md

@@ -39,11 +39,28 @@ skips code generation (and hence is significantly faster).
 ## Building a Project
 
 We can compile a project with the `build` command. Running the `build` command
-will compile the entire project and emit bytecode, i.e. compiled Java classes,
-to the `build` directory.
+will compile the entire project, including code generation, but nothing is
+written to disk. The `build` command is useful to check that the whole project
+compiles.
 
-Flix has no `clean` command. Deleting the `build` directory serves the same
-purpose.
+## Building Class Files
+
+We can compile a project to Java class files with the `build-classes` command.
+Running the `build-classes` command will compile the entire project and emit
+bytecode, i.e. compiled Java classes, to the `build/class` directory. If there
+is a `main` function, we can run it:
+
+```bash
+$ java -cp build/class Main
+```
+
+If the project, or one of its dependencies, depends on JAR-files then these must
+also be added to the class path.
+
+## Cleaning a Project
+
+We can remove the `build` directory with the `clean` command. This deletes all
+class files emitted by `build-classes` and all documentation generated by `doc`.
 
 ## Building a JAR-file
 
@@ -55,11 +72,13 @@ function, we can run it:
 $ java -jar artifact/project.jar
 ```
 
-The JAR-file contains all class files from the `build` directory. The built JAR
-may depend on external JARs, if the project, or one of its dependencies, depends
-on JAR-files.
+The JAR-file contains all class files of the project together with any files in
+the `resources` directory. The built JAR may depend on external JARs, if the
+project, or one of its dependencies, depends on JAR-files.
 
-> **Note:** `build-jar` automatically invokes the `build` command.
+> **Note:** `build-jar` compiles the project itself and places the compiled
+> JAR-file in the `artifact` directory. There is no need to run `build` or
+> `build-classes` before running `build-jar`.
 
 ## Building a fat JAR-file (bundling all dependencies)
 
@@ -68,11 +87,12 @@ We can compile a project to a single standalone fat JAR-file with the
 `artifact/project.jar` file where _all_ dependencies — both Flix and Maven — are
 bundled into one single JAR-file. 
 
-The JAR-file contains all class files from the `build` directory together with
-all class files extract from all Maven dependencies found in the `lib`
-directory. 
+The JAR-file contains all class files of the project together with the contents
+of all JAR dependencies found in the `lib` directory. 
 
-> **Note:** `build-fatjar` automatically invokes the `build` command.
+> **Note:** `build-fatjar` compiles the project itself and places the compiled
+> JAR-file in the `artifact` directory. There is no need to run `build` or
+> `build-classes` before running `build-fatjar`.
 
 ## Building a Flix Project