Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
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
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.
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 install git golang build-essential bison qemu-system curl
these aren't tested development platforms
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
(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
(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.
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-
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.
You'll need to bootstrap everything the first time:
This will set up the git repo for code review and build the
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
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
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
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 (
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.