From 26ef29879636bce23fa86e090301177e1905b4bc Mon Sep 17 00:00:00 2001 From: Magnus Madsen Date: Sat, 15 Aug 2026 16:51:38 +0200 Subject: [PATCH 1/3] docs: update build commands (build, build-classes, clean, jars) The `build` command no longer writes class files; the new `build-classes` command does. The `build-jar` and `build-fatjar` commands compile the project themselves and do not touch the `build` directory. Also documents the `clean` command. Co-Authored-By: Claude Fable 5 --- src/build-and-packages.md | 6 ++++-- src/build.md | 42 ++++++++++++++++++++++++++++----------- 2 files changed, 34 insertions(+), 14 deletions(-) diff --git a/src/build-and-packages.md b/src/build-and-packages.md index dd11c6c5..ec703461 100644 --- a/src/build-and-packages.md +++ b/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. diff --git a/src/build.md b/src/build.md index ecf95d3b..9628b2f2 100644 --- a/src/build.md +++ b/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,12 @@ 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; it does not write anything +> to the `build` directory. ## Building a fat JAR-file (bundling all dependencies) @@ -68,11 +86,11 @@ 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; it does not write +> anything to the `build` directory. ## Building a Flix Project From 550298e63e526a12c372fd50f8c67e768252c317 Mon Sep 17 00:00:00 2001 From: Magnus Madsen Date: Sat, 15 Aug 2026 16:54:28 +0200 Subject: [PATCH 2/3] docs: reword jar notes Co-Authored-By: Claude Fable 5 --- src/build.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/build.md b/src/build.md index 9628b2f2..6a187d88 100644 --- a/src/build.md +++ b/src/build.md @@ -76,8 +76,8 @@ 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` compiles the project itself; it does not write anything -> to the `build` directory. +> **Note:** `build-jar` compiles the project itself and places the compiled +> JAR-file in the `artifact` directory. ## Building a fat JAR-file (bundling all dependencies) @@ -89,8 +89,8 @@ bundled into one single JAR-file. 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` compiles the project itself; it does not write -> anything to the `build` directory. +> **Note:** `build-fatjar` compiles the project itself and places the compiled +> JAR-file in the `artifact` directory. ## Building a Flix Project From ec0aedb10af1b99b58ed384398c3d44690f728f4 Mon Sep 17 00:00:00 2001 From: Magnus Madsen Date: Sat, 15 Aug 2026 16:57:50 +0200 Subject: [PATCH 3/3] docs: note that build is not needed before build-jar/build-fatjar Co-Authored-By: Claude Fable 5 --- src/build.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/build.md b/src/build.md index 6a187d88..62a01349 100644 --- a/src/build.md +++ b/src/build.md @@ -77,7 +77,8 @@ 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` compiles the project itself and places the compiled -> JAR-file in the `artifact` directory. +> 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) @@ -90,7 +91,8 @@ 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` compiles the project itself and places the compiled -> JAR-file in the `artifact` directory. +> JAR-file in the `artifact` directory. There is no need to run `build` or +> `build-classes` before running `build-fatjar`. ## Building a Flix Project