All programming assignments in this course require that you have access to a x86 platform that runs Linux, with some specific software installed. This “assignment” guides you through the steps to set thus up on your own machine.
Note that having some experience with Linux is crucial for your professional prospects. Almost every backend system out there runs Linux. So if you’re not familiar with Linux, don’t think of this “Linux for ICS312” as just something you have to do, but as a valuable experience. Each semester I get e-mails from alumni saying either “I wish I had been better at the command-line before getting my first job” or “I am so glad I was good with the command-line before hitting the job market”.
If you’re already running Linux in one way or another that you like and are comfortable with, you can skip to the Installing NASM section below.
Otherwise, here are some options:
uhunix.hawaii.edu [WARNING: Some assignment may require superuser privileges, which you won’t have on this machine]Some of these options are easier/harder and have different advantages. When in doubt ask your instructor/TAs.
The instructor STRONGLY recommends and uses Option #1. Information for the other options may be slightly out of date.
Install Docker if it’s not already on your host. Then the idea is that you keep your source files on your host in whatever directory. In that same directory, you then simply type the following command to start a Linux container (it can take a while the first time):
On Linux or MacOS:
docker run -it --rm --name mycontainer -v "`pwd`":/home/ics312user henricasanova/ics312 /bin/bash
or on Windows using the CMD prompt:
docker run -it --rm --name mycontainer -v "%cd%:/home/ics312user" henricasanova/ics312 /bin/bash
or on Windows using PowerShell:
docker run -it --rm --name mycontainer -v "${pwd}:/home/ics312user" henricasanova/ics312 /bin/bash
The -v pwd/cd option above is to say: “make the current working directory visible inside the Linux container at /home/ics312user/”.
Note that if you’re on a non-Intel MacOS host (M1, M2, etc.), you will get a warning WARNING: The requested image's platform (linux/amd64) does not match the detected host platform.... This is just a warning and is fine, but if it annoys you just add --platform linux/amd64 to the command-line arguments (anywhere before henricasanova/ics312).
Once this command returns, you will have a command-line interface (aka a shell) inside the Linux container, and in the working directory on the container you will have access to the content of your working directory on your host. When you log out of the shell, the container will terminate.
In a second (or third, or fourth, …) terminal on your host in that same working directory, you can type:
docker exec -it mycontainer /bin/bash
This command will also open a command-line interface inside the Linux container.
Bottom-line: you can develop your code on your host (using whatever text editor / IDE you like) and compile/run it on the container.
Skip Section II (Installing NASM) and Section IV (Installing Java) below and do only Section III
WSL2 supports 32-bit binaries. See these two links.
So, as long as you have the latest Windows and WSL2, you should be all good, and proceed to Step II below.
Plenty of information on-line on how to do this!
You all have an account on uhunix.hawaii.edu (using your UH username and password), which runs Linux. I have installed NASM in my home area. You should update your .bashrc file (in your home directory) to include the following line:
export PATH=$PATH:/home/15/henric/local/bin
once you’ve done this, simply type
source ~/.bashrc
And type:
nasm
which should say: “nasm: fatal: no input file specified. Type nasm -h for help.”.
You should be all set, and you can skip Section II (Installing NASM) below and directly go to Section III
WARNING: People have encountered problems on M1/M2 Apple processors with this option. Try at your own risk!
Vagrant is a great tool that sits on top of virtualization frameworks and allows for super quick installation and usage. I use it on top of Virtual Box, which is free. The Getting Started page on the Vagrant Web site is really good, but just in cases here are a few easy steps:
my_vagrant, and cd to that directoryvagrant init ubuntu/bionic64
vagrant up
vagrant ssh, and voila, welcome to your Linux VMvagrant haltTry out the above to make sure everything works. This is the most basic use
of Vagrant. Your notice that once you’ve done all the above, you’ll have a file called
Vagrantfile, which you can customize later if you want. The Vagrant site has tons of good information about additional
capabilities and features. Remember that you must always be in your my_vagrant directory.
A very useful feature
is that your my_vagrant directory on your host is mounted as
/vagrant/ on your VM! So the files you keep there (i.e., your
programming assignments) are visible both on your host (e.g., for editing)
and on your VM (e.g., for compiling/running). In addition, if your VM may
become compromised, you can always re-install from scratch but you haven’t
lost your files since they’re always on your host! Note that this is
/vagrant on the VM, that is a directory at the root (not, for
instance, /home/vagrant, which is your home directory on your VM.
So, for instance, say you have your homework assignment on your VM in your home directory,
and that it is in a directory called my_homework. This is how you would create
a .tar archive and copy it to your host (i.e., your own computer):
% ls
my_homework/
% zip -r my_homework.zip my_homework
% cp my_homework.zip /vagrant
And now, on your computer, in the same directory in which you typed vagrant ssh you’ll
see that file my_homework.tar has magically appeared.
WARNING: People have encountered problems on M1/M2 Apple processors with this option. Try at your own risk!
Vagrant above gives you very basic Terminal access, which is fast. However,
perhaps you want a full-features Ubuntu GUI, at the risk of it running
slowly on your system. In this case, you want to use Virtual Box (or
whatever Virtualization framework you want/have installed), and create and
start your VM that way. There are plenty of on-line documentation/tutorials on how to install
Ubuntu on VirtualBox.
You should get the 17.04 Ubuntu
desktop distribution, which you can get from the UH mirror
(e.g., download the file named ubuntu-16.04-desktop-i386.iso.)
You absolutely want to set up a Shared
Folder (which works as the /vagrant/ directory in Option #3). This
way, the files you keep there (i.e., your programming assignments) are
visible both on your host (e.g., for editing) and on your VM (e.g., for
compiling/running). In addition, if your VM may become compromised, you
can always re-install from scratch but you haven’t lost your files since
they’re always on your host!
This is of course the slam dunk. Many of you are already running Linux and can likely stop reading now. Running Linux on your own machine is of course the ultimate way to gain experience, and most people get started with the ever so popular Ubuntu desktop distribution.
If you’re not quite ready to replace your current OS with Linux, you can go dual boot by installing a Linux partition on your machine. This is pretty standard, and there are many step-by-step guides on-line. A decent one for setting up a dual-boot Windows/Linux machine is on the Ubuntu Web site. Ubuntu also provides a Windows installer, which I’ve never tried myself but has been used successfully by many people. See this page for MacOS/Ubuntu dual boot. These links are active but may be stale. Web search engines are your friends for figuring this out.
If you are using the Docker image (Option #1 above) you can skip this step as NASM is already installed on that image!
Now that you have access to a Linux machine, you need to install NASM. Assuming you’re running Ubuntu, you can use the Ubuntu package manager tool with a GUI. However, I typically use only the command-line (you’ll find that’s a theme throughout the semester) to install packages.
First, make sure you are connected to the network. Then on your Linux system type the following command in the Shell:
sudo apt update
The sudo command runs commands as the super user, and when you
installed Ubuntu you were placed by default in the list of users who can
use sudo. The apt command is used to deal with
everything related to package management, and in the invocation above, to
update your package list so that you will not have errors installing new
packages. This could take a while.
Once the package list has been updated, then install NASM by typing the following command:
sudo apt install gcc make nasm gcc-multilib
This last package is to make sure that you can generate 32-bit executables with the gcc C compiler.
That’s it!
I’ve built a small test case, which is in fact the basic framework we’ll be using throughout the semester, so that you can check that everything’s working. Download the nasm_check.tar archive to your account on your Linux box, e.g., in your home directory. This can be done in many ways, for instance from a Web browser that you’re running in your Ubuntu installation. The easiest way may be to type in a terminal the command (on one line):
wget http://courses.ics.hawaii.edu/ics312_spring2025/morea/GettingStarted/nasm_check.tar
(If you get a “wget: command not found” error, simply install wget by typing the command “sudo apt install wget”)
Once the archive is in your working directory, you can unarchive it by typing the command:
tar -xvf nasm_check.tar
This will create a directory named nasm_check.
Go to that directory:
cd nasm_check
and type the command:
make
You should get some output, and the last line should be: “It works!”. If not, then you should send me an e-mail with the whole output. If you get the correct output, you now have everything that you need for all NASM assignments.
If you see some “Command not found” message,you can likely install the required software with sudo apt install xxxxx as explained in the error message.
If you see some errors like “skipping incompatible …”, you may have to install two new packages:
sudo apt install lib32gcc-9-dev libx32gcc-9-dev
If this fails, contact your TA/instructor.
If you are using the Docker image (Option #1 above) you can skip this step as Java is already installed on that image, and you are done!
Now that you have access to a Linux machine, you need to install Java. But perhaps Java is already installed! Try to invoke the Java compiler from the command-line as follows:
javac -version
If you get some output like “javac XX…” where XX is 8 or above, you’re all set can skip everything below. (If you get this output but where XX is below 8, then you need to upgrade Java to at least OpenJDK 8 - unlikely.)
If you get some “command not found” error message, then follow the steps below to install Java.
Assuming you’re running Ubuntu, you can use the Ubuntu package manager tool with a GUI. However, I typically use only the command-line (you’ll find that’s a theme throughout the semester) to install packages.
First, make sure you are connected to the network. Then on your Linux system type the following command in the Shell:
sudo apt update
The sudo command runs commands as the super user, and when you
installed Ubuntu you were placed by default in the list of users who can
use sudo. The apt command is used to deal with
everything related to package management, and in the invocation above, to
update your package list so that you will not have errors installing new
packages. This could take a while.
Once the package list has been updated, then install Java (OpenJDK) by typing the following command:
sudo apt install default-jdk
Once this is done, you should be able to invoke javac -version from the command-line and get the expected output.