start.md

Getting Started

Welcome to Venice!

Venice can run on any operating system for which a Java VM is available, like Linux, MacOSX, or Windows.

Setup Venice on a local machine or use a Venice Gitpod workspace without requiring any local installation.

Venice Local Setup

1. Install Java

Venice requires Java 8 or newer.

Java can be downloaded from:

• Eclipse Temurin
• Zulu

The Venice JAR published to Maven is compiled with Java 8. Nevertheless Venice is regulary compiled and unit tested with Java 8, 11, and 17.

2. Get the Venice JAR file

Manually download the JAR from Maven: Venice JAR

or download it with curl:

curl "https://repo1.maven.org/maven2/com/github/jlangch/venice/1.12.34/venice-1.12.34.jar" --output ./venice-1.12.34.jar

3. Setup the Venice REPL

This automated setup will create a REPL launcher script with the Java classpath correctly setup, will download the Jansi library from Maven, and add some example Venice scripts. The setups works on MacOS, Linux, and Windows.

Open a terminal, move to the directory the Venice JAR is located, and start the REPL in setup mode:

foo> java -jar venice-1.12.34.jar -setup -colors

For a REPL run in a darkmode terminal use the option -colors-dark instead of -colors. This can also be changed later on by modifying the generated REPL launcher shell script repl.bat or repl.sh respectively.

The -setup option will cause the Venice setup to:

• create a libs, tmp, tools, and scripts directory in the current working dir
• download the Jansi library from the Maven repository to the libs dir
• install Maven locally to the REPL in the tools dir
• extract some example Venice scripts to the scripts dir
• create a launcher shell script repl.bat for Windows and repl.sh for all other OS

Now the Venice REPL can be started simply by executing the REPL launcher.

on MacOSX and Linux:

foo> ./repl.sh

on Windows:

foo> repl.bat

The REPL is started and prompts for input:

Venice REPL: 1.12.30
Home: /Users/juerg/Desktop/test
Java: 1.8.0_392
Loading configuration from classpath custom 'repl.json'
Using Ansi terminal (light color mode turned on)
Use the commands !lightmode or !darkmode to adapt to the terminal's colors
Type '!' for help.
venice>

REPL setup directory structure (on MacOS / Linux)

REPL_HOME
├── libs
│   ├── venice-1.12.34.jar
│   ├── jansi-2.4.1.jar
│   └── repl.json
├── tools
│   └── apache-maven-3.9.6
│       └── ...
├── tmp
│   └── ...
├── scripts
│   └── ... (example scripts)
├── repl.env
├── repl.sh
└── run-script.sh

REPL setup directory structure (on Windows)

REPL_HOME
├── libs
│   ├── venice-1.12.34.jar
│   ├── jansi-2.4.1.jar
│   └── repl.json
├── tools
│   └── apache-maven-3.9.6
│       └── ...
├── tmp
│   └── ...
├── scripts
│   └── ... (example scripts)
├── repl.env.bat
└── repl.bat

4. Run expressions in the REPL

Type an expression like (+ 1 1) followed by a <CR>

venice> (+ 1 1)
=> 2
venice>

Venice Gitpod workspace

Start a REPL from a Venice Gitpod workspace

A Venice REPL can be run without local installation in a Gitpod workspace. If you don't have a GitHub login yet, please sign up for GitHub.

Just fire up a Venice Gitpod workspace in your browser by opening the URL https://gitpod.io/#https://github.com/jlangch/venice. Gitpod will ask you to login to GitHub and will launch a Venice workspace container for you in the cloud, containing a full Linux environment. It will also clone the Venice repository and build it.

Wait until the workspace has been built ...

The workspace will start a fresh REPL in a terminal.

If you see the Venice REPL prompt venice> type an expression like (+ 1 100) followed by a <CR>

Manually start a new REPL terminal in the workspace

Start a new terminal (menu Terminal -> New Terminal) ...

launch the REPL within the terminal:

$ cd /workspace/repl
$ ./repl.sh

Useful VSCode extensions

VSCode settings.json

{
    "files.associations": {
        "*.venice": "clojure"
    },
    
    "workbench.colorTheme": "Tomorrow Night Blue",
    "redhat.telemetry.enabled": false    
}

Where to head next

• browse through the readme
• see the cheatsheet and use it as a quick reference