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

• Sending a patch

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.

This programs could have different versions across the platforms in what Harvey can be built. As a reference, we're now working with this toolchain versions:

GCC: gcc 4.8, 6.x, 7.x and 8.x

Clang: 3.9, 4.0 and 6.0

Binutils: 2.26 and higher.

Errors derived from other versions, please report to our List.

Official support

we test with Linux on every commit

Linux

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

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

Experimental

these aren't tested development platforms

Docker

If you are familiarized with Docker, Harvey has available an updated repo in Docker Hub for you:

docker run harveyos/harvey

to build harvey in your own machine

docker run -v `pwd`:/harvey --entrypoint=/harvey/util/build harveyos/harvey

and run it

docker run -v `pwd`:/harvey harveyos/harvey

FreeBSD

(Regulary tested with latest release version)

If you are in a FreeBSD, you should do:

pkg install git go gcc7 clang4 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 7:

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

OpenBSD

(tested on 5.9 GENERIC#1761)

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

pkg_add git go gcc bison

But, as it was warned in Prerequisites section above, you will need to build your own recent binutils package, because actual one shipped with OBSD (2.17) won't be compatible.

OSX

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

If you try to clone the git repo on Mac, you'll have problems due to files in some folders having names that differ only in case (e.g. HB and Hb). This is due to the Mac filesystem (HFS+) being case-insensitive by default.

The way to work around it is to create a case-sensitive disk image and clone the repo into that. You can then do all your work there:

• Download the workspace.sh script from here.
• Use it to create a new disk image (5g in this case, way more than necessary):
  • CASE_SAFE_VOLUME_SIZE=5g workspace.sh create
  • workspace.sh mount
• Now you can clone the repo and continue with the build steps below.

After this, 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-

Windows 10

You can use the Windows Linux Subsystem to compile and run Harvey. First you need to install it, you can follow the steps in the official Windows documentation.

Once you have a bash terminal on your Windows, just follows the steps for Linux, and when you have Harvey compiled, use the script util/GO9PCPUDOCKER to run it.

Now you need drawtermto connect to your Harvey. To do this, you can download the 9front version.

BUILD

You'll need to bootstrap everything the first time:

./bootstrap.sh

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

CC=gcc 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 gcc7:

CC=gcc-7 ARCH=amd64 util/build

Getting ninep to serve your files

Usually bootstrap.sh 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/third_party:$(pwd)/util
export GOBIN=$(pwd)/util
go install github.com/Harvey-OS/ninep/cmd/ufs

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

go install github.com/Harvey-OS/ninep/protocol
go install github.com/Harvey-OS/ninep/filesystem

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)
    util/GO9PCPU

This will start harvey and it will use DHCP to get an IP. On some systems (VMWare Fusion on OSX) the DHCP may not work well. You can extend the arguments in the scripts, with, e.g.:

bootargs='tcp -g 192.168.0.2 ether /net/ether0 192.168.0.15 255.255.255.0'

In this case, our gateway is 192.168.0.2, and our IP is 192.168.0.15.

---

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

---

Once Harvey is up, 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)
    util/GO9PTERM

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.