= yaml = title: Step-by-step Installation toc: true = yaml =
This document provides step-by-step instructions for installing Vanadium.
The instructions below assume you are using the Bash shell.
set | grep BASH > /dev/null || echo "Vanadium installation requires Bash."
In addition, they assume the following software packages are installed and available in your PATH
:
On OS X, you'll also need:
For OS-specific setup details, consult these instructions:
The Vanadium code is spread out across multiple git repositories. Though it's possible to fetch the Vanadium Go code using standard go get
commands, the recommended approach is to use the jiri
tool, which helps manage multiple repositories.
Soon, we'll run a bootstrap.sh
script that uses jiri
to fetch the Vanadium repositories. As such, we must first set the JIRI_ROOT
environment variable. Use an absolute path to a non-existent directory on the local filesystem. The bootstrap.sh
script will create this directory. (Remote filesystems such as NFS are discouraged for performance reasons and to avoid git ENOKEY errors.)
# Uses existing $JIRI_ROOT environment variable, defaults to ${HOME}/vanadium if # $JIRI_ROOT is not set. export JIRI_ROOT=${JIRI_ROOT:=${HOME}/vanadium}
Recommended for contributors: Add the line above to your ~/.bashrc
or similar.
The tutorials on this website use Go code from a particular subdirectory of JIRI_ROOT
. Tutorial users should set the VANADIUM_RELEASE
environment variable to this directory, as follows:
# Needed for tutorials only. export VANADIUM_RELEASE=${JIRI_ROOT}/release/go
The bootstrap.sh
script checks that the JIRI_ROOT
directory does not yet exist, then creates it. If it exists, warn the user with a clear message about trying to install over an existing path and provide instructions on how to correct.
# Check that the JIRI_ROOT path does not exist. if [[ -e "${JIRI_ROOT}" ]]; then echo "" echo "ERROR: The JIRI_ROOT path already exists: ${JIRI_ROOT}" echo "To proceed with a fresh install remove the directory and re-run:" echo "" echo " rm -rf ${JIRI_ROOT}" echo "" echo "Or set JIRI_ROOT to a different path." exit 1 fi
Run the bootstrap.sh
script. This script will (1) install the jiri
tool in your JIRI_ROOT
directory, (2) git clone
a Vanadium-specific manifest repository that configures jiri
for the Vanadium project, and (3) use the jiri
tool to fetch all of the Vanadium repositories. Notably, this script will not write to any files outside of the JIRI_ROOT
directory.
# This can take several minutes. curl -f https://vanadium.github.io/bootstrap.sh | bash
Add $JIRI_ROOT/.jiri_root/scripts
to your PATH
, for jiri
:
export PATH=$JIRI_ROOT/.jiri_root/scripts:$PATH
Recommended for contributors: Add the line above to your ~/.bashrc
or similar.
Some components of Vanadium (e.g. Syncbase) have additional prerequisites, including Snappy, LevelDB, and Node.js.
We recommend using the jiri profile
command to install all such prerequisites. This command uses apt-get
on Linux and brew
on OS X. Note, the jiri
tool and its various plugins are located in $JIRI_ROOT/.jiri_root/scripts
.
jiri profile install v23:base
The jiri profile install
command only writes to files under JIRI_ROOT
, i.e. it will not write to system folders such as those under /usr
.
For simplicity, we use jiri go
to install tools. The jiri go
command simply augments the GOPATH
environment variable with the various paths to Vanadium Go code under the JIRI_ROOT
directory, and then runs the standard go
tool.
# Install specific tools needed for the tutorials. jiri go install v.io/x/ref/cmd/... v.io/x/ref/services/agent/... v.io/x/ref/services/mounttable/...
Compile all Go code:
jiri go build v.io/...
Run all Go tests:
jiri go test v.io/...
Install all Go binaries:
jiri go install v.io/...
You should now have the following binaries available, among others:
$JIRI_ROOT/release/go/bin/mounttabled
$JIRI_ROOT/release/go/bin/syncbased
$JIRI_ROOT/release/go/bin/vrpc
To sync to the latest version of the Vanadium source code:
jiri update