Skip to content

setup.adoc

Latest commit

 

History

History
518 lines (430 loc) · 12.7 KB

setup.adoc

File metadata and controls

518 lines (430 loc) · 12.7 KB
Raw
title <code>ops-class.org</code> Setup
description Overview of how to download the OS/161 source code and install a ops-class.org toolchain.
omitTop true
priority 0.8
changefreq monthly
spelling_exceptions
LTS
Trusty Tahr
Xenial Xerus
Bento
Vagrantfile
EC2
VMware

{ops-class} assignments start with the {os161} instructional operating system and require a special toolchain to compile, run, debug, and test. This page describes how to get the sources and install the toolchain.

1. Toolchain

Your options for installing the toolchain depend on the operating system running on the computer that you are going to develop on:

  1. Windows:

  2. Mac OS:

  3. Ubuntu (or other Linux distributions that support Debian packaging):

  4. Other UNIX systems:

You’ll note that most of these options boil down to getting Ubuntu installed somehow—​either with or without a GUI—​and then using our packages. The only exceptions are Windows installations that can use the packages natively, or those that want to install from source for some reason.

We review the main options below.

1.1. Virtual Machine with GUI

Consider this option if:

  • your computer is beefy enough to run a full GUI-based virtual machine (many are), and

  • you prefer editing source code using a graphical editor like Atom, Sublime, Eclipse, etc.

There are many tutorials on how to install Ubuntu using VirtualBox [1]—here’s one—so we aren’t going to maintain one here. We would suggest choosing Ubuntu 16.04 LTS "Xenial Xerus", the latest LTS (Long Term Support) version. We have packages ready for it as well as Ubuntu 14.04 LTS "Trusty Tahr".

One you have Ubuntu installed and running to your satisfaction, continue by installing the toolchain using the ops-class.org PPA.

1.2. Headless Virtual Machine (No GUI)

Consider this option if:

  • you’d prefer a more lightweight virtual machine, and

  • if you are using Windows, you are comfortable editing files in a text-based editor like Vim or Emacs.

We maintain an {ops-class} Vagrant configuration. It loads a pre-built headless (no GUI) VirtualBox virtual machine [2] based on the minimal Bento Ubuntu Vagrant boxes. The current version is based on Ubuntu 16.04 LTS "Xenial Xerus". It contains the rest of the toolchain, including sys161, the OS/161 cross-compilers, and test161.

1.2.1. Current version

1.2 is the current version.

1.2.2. Installation

Install Vagrant and Git. Note that Ubuntu packages very old versions of Vagrant for apt-get. You’ll have better luck following the instructions on the Vagrant website. (This is also true for Git. You may want to add the Git maintainers PPA.)

Then:

git clone https://github.com/ops-class/vagrant
cd vagrant && vagrant up

The vagrant up may take a few minutes. Once it completes, you should be able to log in to the virtual machine and run the OS/161 tools:

$ vagrant ssh
trinity@zion:~$ sys161
sys161: System/161 release ...
sys161: Usage: sys161 [sys161 options] kernel [kernel args...]
...

1.2.3. Installation troubleshooting

First examine the vagrant up logs for errors. Some messages that appear to be errors are in fact usually benign. These include:

W: mdadm: /etc/mdadm/mdadm.conf defines no arrays.`
==> default: mesg:
==> default: ttyname failed
==> default: :
==> default: Inappropriate ioctl for device
==> default: dpkg-preconfigure: unable to re-open stdin: No such file or directory

Also make sure that all Vagrant commands (vagrant up, vagrant ssh, etc.) are run from the same directory as your Vagrantfile. That’s just how Vagrant works.

1.2.4. Notes for Windows users

The Vagrantfile README describes some potential pitfalls for Windows users. Some concern initialization.

Another known problem is that some Windows hosts will not allow guests to create symbolic links in shared folders. If you try to build your OS/161 sources from a shared folder, the build will fail when it tries to create symbolic links in the compilation directory.

There are two workarounds.

  1. Run all of your vagrant commands as a Windows administrator: vagrant up, vagrant ssh, etc. This provides provide the guest with the required permissions to create symbolic links.

  2. Don’t share your source folder and edit your code inside the virtual machine using a terminal-based editor.

1.2.5. Upgrading the toolchain

trinity@zion:~$ sudo apt-get update ; sudo apt-get upgrade

1.2.6. Upgrading the virtual machine

This can be done by first updating the Vagrantfile via git pull and then forcing Vagrant to reprovision the VM:

vagrant halt
git pull
vagrant up --provision

But it may be easier to simply destroy the old VM and create a new one. Be sure to preserve your OS/161 sources!

1.3. {ops-class} PPA

The {ops-class} {ppa} includes all toolchain components packaged for Ubuntu 16.04 LTS "Xenial Xerus". and Ubuntu 14.04 LTS "Trusty Tahr". If you have 16.04 or 14.04 installed, you can install these packages directly. If you are using a slightly earlier or later Ubuntu release, the Xenial packages will probably work: This help page should get you started. If you are using a much earlier Ubuntu release, you should upgrade.

As of early 2017 we have evidence that the Xenial packages also seem to work on Windows 10 under the Windows Subsystem for Linux. So this is another option for Windows users. This is a new option for us, and we’ll update this document as we know more.

1.3.1. Installation

sudo add-apt-repository ppa:ops-class/os161-toolchain
sudo apt-get update
sudo apt-get install os161-toolchain

1.3.2. Upgrading

sudo apt-get update
sudo apt-get install os161-toolchain

1.4. Install from Source

We don’t support this option, but if you’d like to try instructions are available at the {os161-link}[OS/161 website]. You will need to download, configure, compile and install the OS/161 toolchain using the modified sources. Follow the online directions. However, rather that using David’s tarballs we would suggest that you use the official ops-class.org sources which are available on GitHub for test161, sys161, and the cross compilers.

Linux and other UNIX variants are likely to work. OSX may require patches. Keep reading for more instructions.

2. Source

{os161} is maintained by David Holland at Harvard University. We maintain a OS/161 fork on GitHub that includes {ops-class}-specific changes. Most of our changes are to enable automated testing using {test161}.

2.1. Current Version

2.0.2 based on upstream version 2.0.2. Our fork is currently up-to-date with the latest {os161} version.

2.2. Installation

Clone our GitHub repository. Note that this sets the Git remote name to staff so that you can use origin for your own private repository where you store your changes.

git clone https://github.com/ops-class/os161 -o staff

2.3. Upgrading

Pull and merge upstream changes from our GitHub repository. Note that this depends on having our OS/161 GitHub repository named staff rather than origin, as described above. You will also need to inspect the output of git pull (or git status) and fix any merge conflicts.

git pull staff master

3. Toolchain Components

Below we describe the individual components of the toolchain. But note that the correct way to install the toolchain is either using Vagrant or our PPA as described above.

3.1. test161

{test161} is our OS/161 distributed automated grading and testing tool. It is maintained by Scott Haseley. Sources are available on GitHub and pull requests containing bug fixes or enhancements are welcome.

3.1.1. Current version

1.2.5 is the current version.

3.1.2. Installation

If you are using our PPA, then you already have test161. If you are installing from source, once you have Go installed, the following command will install {test161} into your $GOPATH:

go get -u github.com/ops-class/test161/test161

3.1.3. Upgrading

If you are using our PPA, then follow the upgrade instructions above. If you installed from source:

go get -u github.com/ops-class/test161/test161

3.2. System/161

{system161} is maintained by David Holland at Harvard University. We maintain our own GitHub sys161 repository for the purpose of packaging sys161 for our {ppa}. We have also made some contributions to sys161 related to {test161} automation and statistics control.

3.2.1. Current version

{ppa-link}[2.0.8] which is identical to upstream version 2.0.8.

3.2.2. Installation

If you are using our PPA, then you already have sys161. You can also try installing from source [3].

3.2.3. Upgrading

If you are using our PPA, then follow the upgrade instructions above. If you installed from source, reinstall from source.

3.3. OS/161 Cross Compilers

{os161} requires a set of patched cross compilers which are maintained by David Holland at Harvard University [4]. We have packaged these for our PPA, and maintain packaging repositories for GCC, GDB, bmake, and the binary utilities.

3.3.1. Current version

Identical to the latest versions shown here.

3.3.2. Installation

If you are using our PPA, then you already have the OS/161 toolchain. You can also try installing from source.

3.3.3. Upgrading

If you are using our PPA, then follow the upgrade instructions above. If you installed from source, reinstall from source.

1. Or VMware, or Parallels, etc…​
2. We’ll talk a lot more about virtualization in class, but here’s one example of how useful it can be.
3. Good luck!
4. Surprise, surprise!