Setting up a programming environment

Copyright © 2024 J. M. Spivey
Jump to navigation Jump to search

Note

If you just want to take the shortest route, "Option One," installing a virtual appliance, then simpler instructions with screenshots can be found on another page.

For the practical component of many lecture courses you will take, but particularly Digital Systems and Compilers, it will be convenient for you to have your own Linux-based programming environment to supplement the support given by the computers in the Software Labs. The instructions on this page guide you through the process of setting up a specific Linux distribution, either on a dedicated computer or within a virtual machine on a computer running Windows or Mac OS.

The Linux distribution I have chosen is Debian with the Raspberry Pi desktop. This is quite lightweight in terms of the amount of disk and memory space and processing power it needs, and therefore ideal for installing as a virtual machine inside VirtualBox, where particularly the amount of RAM from the host that can be dedicated to the guest is limited. It also works well on an older PC or laptop, should you have one on hand. We will be installing a 32-bit version of Linux, even on a 64-bit machine, because the 32-bit version works well on machines with limited amounts of RAM, and is certainly adequate for everything you will want to do.

Of course, you're welcome to make your own setup according to your own tastes, and the suggestions offered here are intended just to give you an easy route to independence. It's possible to get the software for Digital Systems, for Compilers, or for another course, working directly under Mac OS, or inside the "Windows Subsytem for Linux", and you may prefer those solutions. If you want a simple fool-proof way of getting the software you need, however, I think the VirtualBox approach is a good way to go.

You may have a Windows machine or a Mac already with some spare disk space, and if so you can very easily install VirtualBox and put a Linux installation inside it. That's preferable, I think, to a dual-boot arrangement that inevitably involves frequent switching from one operating system to the other. If you can get hold of an older laptop, then it's not unreasonable to have a separate machine dedicated to running Linux. You can buy a refurbished laptop for £150–200 that is perfectly adequate, and you may think that a worthwhile investment. I hesitate to recommend a dealer here, but am willing to be asked about it. But beware: following Option One in the instructions below will erase the entire contents of your machine's hard disk. Make a copy elsewhere of any files you would like to keep.

Alternatively, you could get a real Raspberry Pi and install the ARM-based edition of the Raspberry Pi OS on it. That setup is also adequate for all the lab exercises, but it lacks the convenience of a laptop with built in keyboard and screen. Nevertheless, tasks 5A and 5B will enable you to install the software tools needed for the Digital Systems and Compilers courses, starting from the initial disk image provided with the Raspberry Pi.

Overview

The rest of these instructions are divided into tasks, only some of which apply to each setup.

  • For a minimal version of Debian under VirtualBox (Option One), you can follow instead tasts 0, 1, 6, and 7.
  • If you want a full Debian installation under VirtualBox (Option Two), you will need to follow tasks 0, 1, 2, 3, 4, 5A, 5B, and 7.
  • If you are dedicating a machine to Linux (Option Three), then you will need to follow tasks 0, 3, 5A, 5B, and 7.

Option Three is the shortest path through the maze, and ends with an installation of Linux inside VirtualBox that contains only the software that is actually needed for the courses; more software can be added later. This is the path we will follow if we have an installation party. Here's a kind of flowchart of the tasks in each option.

Vbox-options.png

If you just want to install the virtual appliance (Option One), then another page has detailed instructions with screenshots. For that and Option Two, the other VirtualBox-based setup, these instructions and screenshots describe what to do on a Windows machine, but a Mac OS setup will be very similar. Another page lists the steps needed to prepare the virtual appliance.

A temporary page has notes towards completing this one.

Task 0: obtain software

For Option Three, you must complete this step using another already functioning computer. It may be the one on which you plan to install Linux, or another computer running Linux or Windows or Mac OS that you can use to download files from the Web. You must also have a USB drive of at least 8GB capacity whose contents you are willing to destroy.

Download the following files, and put them on your desktop.

For Options One and Two, you can use the downloaded files directly from the desktop. For Option Three, you must now write the ISO image to the USB stick. This must be done in the right way: we neither want the image written to the drive as a single ordinary file, nor the ISO image unpacked and written as multiple files, but rather the image written in a raw fashion to the drive. UNetbootin will look after the details – just use the Diskimage option and specify the DVD-ROM image you downloaded a moment ago.

If you are using VirtualBox, continue with Task 1; for a physical machine, go to Task 3.

Task 1: install VirtualBox

For Options One and Two, you now need to install VirtualBox, and then add the extension pack. (For some purposes, the extension pack is not really necessary, but it does allow USB devices like the micro:bit to be used from the guest machine.)

1.1 To install VirtualBox, double-click on the downloaded file. You can accept all defaults.

1.2 Start "Oracle VM VirtualBox" from the start menu. Pin it to the taskbar if you like. You will see the VirtualBox manager window, with (so far) no virtual machines listed.

1.3. Install the extension pack by clicking on Preferences, then choosing the Extensions tab.

  • Click on the blue square with the green plus sign at the far right, then find the file Oracle_VM_VirtualBox_Extension_Pack-<version> on your Desktop or the USB drive (where <version> stands for a version number such as 6.1.32), select it, and click Open.
  • In the next dialog box, click Install. You will be shown a licence agreement; scroll down to the bottom then click I Agree.
  • Now the screen will go black and you will be asked to give permission for changes; click Yes.
  • Next you should see a message that the installation was successful; click OK, and click OK again in the Preferences window.

You should now be back at the VirtualBox manager window: stay there for the next step, which is Task 6 for Option One and Task 2 for Option Two.

Task 2: Create a virtual machine

2.1 Click on New to create a new virtual machine. You will be presented with a sequence of choices

2.2 Give a name for the machine ("Labs" will do), accept the default location, and select Linux and 32-bit Debian.

2.3 Accept the default of 1GB of RAM.

2.4 Choose to create a virtual hard disk: use VDI format, dynamically allocated, in the default location, but increase the size to 20GB.

2.5 After making these choices, clicking Create will take you back to the main window, but now with a virtual machine listed in the left-hand column. Continue with Task 3.

Task 3: Install Debian with the RPi Desktop

The next task is to boot the machine (real or virtual) from the Debian installation medium, which will be either the USB stick you prepared earlier or the same data as an ISO file on your desktop.

For Option Two: select the virtual machine you just created and press Start. On this first boot, VirtualBox will ask you to choose a disk image to boot from. Navigate to the Desktop and choose the ISO file downloaded earlier; click on Start.

For Option Three: plug the USB key in, switch on the machine, and perform whatever actions are needed to boot off the USB key. Typically, you need to press Enter or F12 while the BIOS is showing its splash screen, then select the USB key from a list that may also include the machine's hard disk.

3.1 When the boot menu appears, quickly press Down-Arrow to stop the countdown and give yourself time to think. If you miss it, just reset the machine and try again. We are going to install the operating system on the hard disk drive of the (virtual or physical) machine, so choose either Graphical Install or Install according to taste (I always use Install for simplicity) and press Enter. Both installation processes ask precisely the same questions.

3.2 Choose 'British English'.

3.3 When it comes to disk partitioning, choose 'Guided – use entire disk'. If you are in VirtualBox, this means the entire disk of your new virtual machine, not the entire disk of the host.

3.4 Choose the first hard disk (probably there will be just one).

3.5 Choose 'All files in one partition'.

3.6 Choose 'Finish partitioning'.

3.7 After a pause for thought, select 'Yes' explicitly. On a real machine, this is the point at which the entire previous contents of the hard disk will be erased.

3.8 Now the machine will grind away, copying the operating system files to the hard disk. Leave it to stew for a while. On other variants of Debian, there are choices to be made about what software to install, but this edition just installs a standard set.

3.9 The final question is whether to install the Grub bootloader on the primary drive. You can safely say Yes. (If this step fails, it's because you didn't make the virtual hard disk big enough.)

3.10 Now everything is done, and you will be invited to reboot the machine (real or virtual) and start the new operating system.

3.11 After the operating system has booted, you will see the first-boot wizard, which invites you to choose a keyboard layout and timezone, then a username and password. It checks for any software updates since the installation media were created, then invites you to restart the machine with updated settings.

3.12 On reboot, you will be logged in automatically with the username you just chose.

If you are using VirtualBox, continue with Task 4; otherwise, skip it and go to Task 5.

Task 4: Install guest additions

Guest Additions for VirtualBox is a set of device drivers that can be installed into the guest operating system; they provide a shared clipboard between host and guest, the possibility of sharing folders in the filesystem of the host with the guest, and an integration where resizing the machine's window on the host automatically changes the size of guest's display. To install them,

4.1 Use the VirtualBox command 'Devices/Insert Guest Additions CD Image' to put the CD in the virtual drive.

4.2 Open the File Manager and browse to the CD to mount it.

4.3 Open a terminal window, change to the directory /media/cdrom and invoke the shell command 

$ sudo sh VBoxLinuxAdditions.run

and type your password when prompted.

4.4 Finally, reboot the virtual machine to activate the new drivers.

Continue with Task 5.

Task 5: Set up common software

At this point, you have a working Linux environment with a lot of software installed, but not the specific compilers and other tools that are needed for the Digital Systems and Compilers course. You can install these next; skip either or both tasks if you don't want to have the software for that course. If you download the virtual appliance, it contains both sets of software, but you may wish to add some of the other software listed below.

Mercurial and Geany are used for both courses, and you can install them by opening a terminal window and typing the command, 

$ sudo apt-get install mercurial geany geany-plugin-projectorganiser geany-plugin-vc

This includes a couple of Geany plugins that are useful, one that helps with editing projects that consist of multiple files, the other providing an interface to version control systems such as Mercurial and Git.

Task 5A: Set up lab software (Digital Systems)

For Digital Systems, in the same terminal window, type the command, 

$ sudo apt-get install gcc-arm-none-eabi gdb-multiarch minicom python3-pip

and then 

$ sudo pip3 install pyocd

These commands install suitable compiling and debugging tools that target bare-metal ARM chips.

The package libnewlib-arm-none-eabi is implicitly installed with the C compiler: it provides an implementation of the standard C libraries libc and libm on about 10 different ARM variants, such as ARMv6m and ARMv7m with and without floating point. Because we are interested in only one variant, the ARMv6m architecture that is provided by the micro:bit, the other variants are forcibly removed as part of the process of building a virtual appliance, and this saves about 1GB of disk space and (more importantly) the bandwidth needed to download that data. They can be restored by reinstalling the package manually. If you are making your own installation, then all variants will be installed automatically, and will remain unless you remove them yourself.

Task 5B: Set up lab software (Compilers)

For Compilers, in the terminal window type the commands, 

$ sudo apt-get install gcc tcl ocaml-nox qemu-user gcc-arm-linux-gnueabihf

These install:

  • GCC to compile the Keiko assembler and runtime system.
  • TCL, needed to generate the Kieko interpreter from an abstract description.
  • OCaml, needed to compile the compilers written in the course. (The -nox variant does not include the libraries needed for writing X Window applications in OCaml, which are irrelevant to the course.)
  • The user-mode parts of QEMU, needed to run ARM code output by the Lab 4 compiler.
  • The ARM version of GCC, needed to compile the startup and library code that goes with our compiler output. This brings with it the ARM assembler and linker. Note that the version installed here, gcc-arm-linux-gnueabihf, is different from the version, gcc-arm-none-eabi that is used in the Digital Systems course; it's OK to have both of them installed at the same time.

Other courses

  • For Functional Programming, the Glasgow Haskell compiler GHC is easily installed on Debian as the package ghc.
  • For Imperative Programming, programs in all three parts of the course are written in the Scala language. The compiler is available on Debian as the package scala.
  • I've not installed in the pre-packaged appliance some other software that you might like: for example, you can install Git, if you prefer it to Mercurial, as the package git. You may also prefer other editors that are not installed by default.

When you have installed the software you want at the moment (you can add more later), continue with Task 7.

Task 6: Install virtual appliance

For Option One: use the VirtualBox Import function to import the virtual appliance contained in the file oxenv.ova. It's OK to accept the default settings for everything about the newly-created machine. Start the machine by choosing it from the list of installed machines and pressing Start. The machine is set for autologin of user guest with password guest.

Task 7: Make minor adjustments

Tidying up

Once VirtualBox is installed, and Linux within it, you can throw away the files you downloaded at the start. If you used Option Three, the contents of oxenv.ova have been installed as part of the virtual hard disk, so that file can be thrown away too.

Appearance

  • I find desktop backgrounds distracting if they are not a plain, dull colour. If you agree, right-click on the desktop and choose 'Desktop Preferences', where you can select a different image or none.
  • On my screen, various elements would look better with relative sizes adjusted. The same dialog allows you adjust the sizes of icons and type on the screen.
  • Prefer a black-on-white theme for the terminal application, but it comes as grey-on-black and I haven't changed it in the appliance. Use Edit/Preferences in the application to change the colours and, if you like, to adjust the font size to suit your screen.

Shared folders

Create a folder in the host to share, or just share your desktop folder.

  • In the VirtualBox management window, use Settings/Shared Folders. Check automount. Save settings and boot the guest.
  • In the guest, add yourself to the vboxsf group with the command sudo addgroup <name> vboxsf (where <name> is your username). Log out and in again.
  • You will find the shared folder under /media/sf_<folder>.

Remote access

  • You can use the ssh command from the virtual machine to log in to the Software Lab computers with
ssh u99abc@ecs.ox.ac.uk
where u99abc represents your username in the Software Lab. To make things go more smoothly, you can generate a local authentication key with ssh-keygen and install it on the remote machine with ssh-copy-id.
  • It's a good idea to make backups of your work, and you can do it with the command
rsync -av ~ u99abc@ecslab.ox.ac.uk:oxenv-backup
which uses the rsync command to copy everything under your home directory to a directory named oxenv-backup on the Software Lab machines. The rsync program skips copying files that have not changed since last time they were copied. This command will prompt for your password on the remote machine, unless you have installed an authentication key.
Retrieved from "https://spivey.oriel.ox.ac.uk/wiki/index.php?title=Setting_up_a_programming_environment&oldid=3807"