Getting Started

Álvaro Jurado edited this page Jan 31, 2017 · 64 revisions

Getting started

Harvey is a distributed operating system. It can be built with clang, gcc or icc (Intel Compiler). It can run on amd64 (x86_64), main line of the project, RISC-V and aarch64 (ARM 64).

This file is a quick list of instructions to get you started quickly.

Before you start

How to get Prerequisites

To build Harvey and play with it, you need to have git, golang, qemu, gcc, clang, icc, binutils and bison installed.

Official support

we test with Linux on every commit


On a Debian, Ubuntu or other .deb system, you should be able to get going with:

sudo apt-get install git golang build-essential bison qemu-system curl


these aren't tested development platforms


(tested on 10.3-RELEASE-p5 and 11.0-RELEASE-p1)

If you are in a FreeBSD, you should do:

pkg install git go gcc6 clang38 bison
export PATH=/usr/local/bin:$PATH

In case you want to use gcc, this trick will be needed ensuring you use right flags for gcc 6:

ln -s /usr/local/bin/gcc6 /usr/bin/gcc


(tested on 5.9 GENERIC#1761)

In case you were in an OpenBSD box, you should do:

pkg_add git go gcc bison

But you will need to build your own recent binutils package, because actual one shipped with OBSD won't be compatible.


(tested on OS X "El Capitan" and macOS "Sierra", see homebrew-gcc_cross_compilers)

If you are on a Mac, you should install macports and do

port install x86_64-elf-gcc
port install x86_64-elf-binutils
port install qemu
export TOOLPREFIX=x86_64-elf-

or if you use homebrew

brew tap sevki/gcc_cross_compilers
brew install sevki/gcc_cross_compilers/x86_64-elf-gcc
brew install qemu go
export TOOLPREFIX=x86_64-elf-


You'll need to bootstrap everything the first time:


This will set up the git repo for code review and build the build tool. You should now be able to build everything by running

ARCH=amd64 util/build

In case you want to build it with clang:

CC=clang ARCH=amd64 util/build

For FreeBSD users who want to use gcc6:

CC=/usr/bin/gcc ARCH=amd64 util/build

Getting ninep to serve your files

Usually script will do this for you, but if you love some craft you can get ninep in the following way

git submodule init
git submodule update
export GOPATH=$(pwd)/util
export GOBIN=$(pwd)/util
go install

In case last would give you some problem, try installing libs first:

go install
go install

After these, you have util/ufs and you must add "harvey" and "none" users to your Linux/Mac/BSD system. "harvey" because you will need that hostowner could be the appropriate owner of your file server. And "none" if you boot a cpu server and want to have all the available services running. Harvey inherited this from Plan 9, so it would be better if you would understand well this. Please read this doc and learn why "none" user is important and very useful, and any other things about 9P services.

However, we're working to hack ninep in order to not having to add users to host system which is running the file server. But it would be just a hack at the begining, because you will want to have your users available across your network in case you would use ldap servers, or something like that, so this is not arbitrary and has its own reason and logic for being so.

Well, after this parenthesis, you can run ninep manually in another shell session just executing this:

util/ufs -root=/$HARVEY-REPO_PATH -debug=3

Running Harvey

Once ninep is running, move to Harvey's repo directory and just boot Harvey as cpu server with this:

export HARVEY=$(pwd)

  • You could test Harvey with Virtio capabilities of QEMU, just follow this guide for it.

Once Harvey is up, you can telnet onto it with

util/telnet localhost:5555

Where 5555 is forwarded to the Harvey instance. This gives you a prompt without any security, so be careful if you want to open that to internet.

Now let's go to see how to have some GUI working.

Getting rio GUI on Harvey

As many other things across the system, Harvey inherited a GUI program from its ancestors. This is rio, an small program that allows you to move inside Harvey through menus and windows. But the story doesn't ends here, please read carefully how to use rio and some history about it. Draw is something in what you could be interested.

After booting Harvey as a cpu server (previous paragraph), you can use drawterm to have rio working. You could find useful a drawterm info page about how to use it and what is it. To make this work with qemu, you must add the user 'none' to your host system or the listen command which serves the connection will fail to start.

Also you can start Harvey as a terminal, instead of a cpu server, using vesa driver and running rio with this:

    export HARVEY=$(pwd)

Look inside GO9PTERM script how we pass the needed params that will be catched by /rc/bin/termrc booting script, for starting your rio environment through profile set up of user harvey (/usr/harvey/rc/lib/profile).

You can run rio in a cpu server too (Harvey's kernel is the same) with this series of commands:

cpu% aux/mouse ps2
cpu% ms&
cpu% aux/realemu
cpu% aux/vga -m vesa -l 1024x768x24

It's just in cpu server mode we disabled GUI by default.

Come to our list to see and learn more things. Don't forget looking at "Virtual disk with Fossil and Venti on Harvey" section for how to setup your disk.