Skip to content
SoutherSoutherSouther

Installation

This page installs the souther command on your machine and checks that it runs. It is for anyone who wants to compile or run a Souther model from the command line.

Requirements

Section titled “Requirements”

Souther runs on JDK 25. The compiler, the classes it generates and souther-runtime are all Java 25 class files, so an older JDK cannot load them. Check which Java you have:

Terminal window
java -version

The first line of the output must name version 25 or later. If it does not, install a JDK 25 from your usual source before you continue. A JDK is needed rather than a JRE, because souther japi reads javadoc through the Java compiler.

The Homebrew formula and the Scoop manifest below bring a Java runtime with them. The manual download and the -Nojdk Windows archive do not.

Install Souther

Section titled “Install Souther”

Pick the tab for your platform. Each one installs the same command line.

Install from the Souther Homebrew tap:

Terminal window
brew install souther-lang/souther/souther

The formula depends on the Homebrew openjdk package, so Homebrew installs a JDK when the machine has none. When JAVA_HOME is already set to a JDK 25 or later, the launcher uses that one instead.

To tap first and install by bare name:

Terminal window
brew tap souther-lang/souther
brew install souther

Verify the installation

Section titled “Verify the installation”

Open a new terminal and ask the command which version it is:

Terminal window
souther version
souther 0.4.0

souther help lists every command with one line saying what it does:

Terminal window
souther help
usage: souther <command> [options] [args]


commands:
  init      start a project, or add Souther to one
  compile   compile to .class files, or for an installed target
  run       run one behavior and print its output
  fmt       format source, to stdout or in place
  examples  how well the `example`s cover the model
  doc       read the language specification
  api       the stdlib surface and its signatures
  japi      a dependency jar's public API, with javadoc
  mcp       serve doc, api and japi over MCP stdio
  lsp       serve the language server over LSP stdio
  tooling   what an editor needs to start and configure the server, as JSON
  help      what a command takes, and what its options mean
  version   which Souther this is


`souther help <command>` writes what one command takes, and `souther doc cli/commands` writes the whole of it.

If the shell reports that souther is not found, the directory it was installed into is not on PATH yet. Open a new terminal, or add the directory to PATH as the tab for your platform describes.

Editor support

Section titled “Editor support”

The VS Code extension gives diagnostics, completion, go-to-definition, rename and formatting. It bundles the language server and downloads a Java 25 runtime when the machine has none, so it works without the souther command. Other editors and coding agents start the same server with souther lsp. See Editors and agents for the setup of each one.

Compile targets

Section titled “Compile targets”

The JVM target is built into souther, so souther compile writes .class files with nothing else installed. The WebAssembly and Native backends are separate jars. Installing one puts it where souther compile --target wasm or souther compile --target native finds it, and each target page says how.

Next steps

Section titled “Next steps”
  • Quick start: write a one-file model, run it, read its coverage report and start a project, in ten minutes.
  • Tutorial: build a business-trip approval model step by step.