Contracts at Work
Appendix B

Building and Packaging Each Project

Everything in this book runs directly with nex. This appendix covers the one step further: turning a project into a standalone artifact someone can run without a Nex install at all.

Running Directly

nex <file>.nex compiles to the JVM and runs the result in one step — the default for every project in this book, and the mode every check suite here was verified against:

nex checks.nex

--interpret runs the same file on Nex's tree-walking interpreter instead of compiling it:

nex checks.nex --interpret

Every project in this book gives identical results run either way, with one natural exception: Chapter 8's dashboard and Chapter 9's dashboard client are long-lived, stateful GUI programs, and the default JVM backend — the same backend nex compile jvm targets — is simply the right tool for that job, the same way it would be for any real desktop program. --interpret is a REPL-adjacent mode best suited to exploring smaller pieces of code, not the natural way to run either dashboard regardless.

Compiling a Standalone Jar

nex compile jvm produces a runnable jar that needs nothing but a JVM to execute — no Nex installation, no nex launcher, no source tree alongside it:

nex compile jvm nexwc.nex build/
# Compiled nexwc.nex -> build/nexwc.jar

java -jar build/nexwc.jar sample.txt --top 3

One thing this book's own relative-path workaround (Chapter 1, and every project that reads a file by a bare relative path) depends on is worth knowing before packaging anything this way: NEX_USER_DIR is set by the nex launcher script itself, before it starts the JVM. Run a compiled jar directly with java -jar, bypassing the launcher entirely, and that variable is simply unset — confirmed directly, packaging nexwc.jar and running it against a relative path with no NEX_USER_DIR in the environment, which fails exactly the way a missing file would. Two ways around it, both confirmed working: pass an absolute path instead of a relative one, or set the variable yourself before invoking the jar —

NEX_USER_DIR="$(pwd)" java -jar build/nexwc.jar sample.txt --top 3

Any project in this book that reads a file by relative path (Chapters 1, 2, 5, and 9) is worth packaging with this in mind, rather than assuming a compiled jar inherits the same working-directory behavior the nex launcher gives it for free.

Two-Process Projects

Chapters 6, 7, and 9 each run as more than one program talking over a socket or an HTTP connection. Compiling each side separately produces two independent jars, which is arguably the right packaging for a project whose whole design is two separate processes in the first place — Chapter 9's service and dashboard, in particular, were built as two processes for reasons that chapter argues are good ones on their own, and packaging them as two artifacts reflects that rather than papering over it.