Software

OCaml

We will use the OCaml programming language throughout the course. Here are some useful OCaml resources:

x86-64

Our compiler targets the x86-64 architecture. We've prepared a reference (to be updated throughout the semester) for the x86-64 features we'll be using: x86-64 reference

Git / GitHub

We'll be using GitHub Classroom to distribute stencil code for each assignment. You'll get the link when the assignment is released. If you've never used Git before, read this doc. There are also plenty of Git tutorials online for courses like cs 0150, 0200, and 0320.

Writing and running code

In order to work with OCaml and compile to x86, you'll need to be able to run your code in a standardized environment (i.e. one that is not architecture-dependent). We have 2 supported methods of running code for this class:

  1. Vagrant/Virtual Box

    • Pros: Runs code locally on your machine, fairly easy to set up and light weight
    • Cons: Does not work on Macs with Apple Silicon (M1/M2)
  2. Department machine

    • Pros: Already set up for you, can SSH through VS Code to get the experience of local development, allows you to use Apple Silicon Mac
    • Cons: Requires an internet connection, files are not accessible locally (though if you save and commit to GitHub often, you shouldn't have any issues)
  3. Docker for M1 Macs

    • Pros: Easy to set up locally, enables local development, works on Apple Silicon.
    • Cons: Docker can be finnicky to work with, experimental course feature.

VM Setup (Vagrant/VirtualBox)

Below are instructions for installing the cs1260 virtual machine on your computer in order to have a standardized development environment. In order to install the necessary software we will be referring to the wonderful guide put together by the cs131 course staff. Please refer to the following sections in the guide with any changes or updates noted.

Virtual Machine Setup

Software
Vagrant Setup

You should use our Vagrantfile instead of the one from cs131. The cs126 Vagrantfile is as follows:

Vagrant.configure("2") do |config|
    config.vm.box = "n-young/cs1260box"
    config.vm.box_version = "1.1"
    config.vm.provider "virtualbox" do |vb|
        vb.customize [ "modifyvm", :id, "--uart1", "0x3F8", "4" ]
        vb.customize [ "modifyvm", :id, "--uartmode1", "file", File.join(Dir.pwd, "ubuntu-bionic-18.04-cloudimg-console.log") ]

        vb.memory = "2048"
    end
end

Using the VM

Once you set up your VM, you will want to turn it on and access it. Since it’s essentially an entirely separate computer, you will need to use SSH to connect to it, much like you do with the department computers. Unlike regular SSH, however, you won’t be connecting over the internet, but directly through Vagrant.

Some useful commands from outside of your machine:

It is important that you issue vagrant halt if you don't want your VM running in the background

From inside the VM you can exit as you would any other ssh

Shared Folders

Once you are inside of your VM, you have access to all of the files that you normally would on your computer.

After connecting with vagrant ssh, you can issue cd /vagrant which will take you to the directory on your computer that you launched your VM from. You can then interect with these files either locally or through you VM and your changes will be saved across both.

Writing code

If you have another editor of choice (e.g. emacs or vim) you are free to use it. Note that your virtual machine already has the merlin and ocamlformat packages which may be of use should you choose to use a different text editor.

First, install VS Code by following these instructions. Once VS Code is installed, go navigate to View > Extensions and search for and install the Remote - SSH extension from Microsoft.

Now, open a terminal and go to the folder where you have your Vagrantfile (but do not enter your virtual machine). Make sure it is running by typing vagrant up. Then, type vagrant ssh-config --host csci1260. Copy the output to your clipboard.

Return to VS Code. Open the command palette by navigating to View > Command Palette and type Remote-SSH: Open Configuration File. In the now open file, paste the information that you copied earlier after running vagrant ssh-config --host csci1260.

You are now ready to connect to your Vagrant virtual machine with VS Code! open the command palette again and type Remote-SSH: Connect to Host. Pick csci1260 from the resulting options. VS Code will open a new window (there may be some first time setup which will take a moment to complete).

From here, you can open open the explorer by navigating to View > Explorer. Then, type /vagrant and press OK to see a view of the files in your virtual machine's shared folder. Double click to open any file.

The virtual machine comes with OCaml support pre-configured for VS Code, which gives you many useful features like type-hints above functions and formatting-on-save.

Department machine setup

CS department machines are setup for you, and we'll show you how to use VS Code to get the experience of local development if you're working remotely. All you need to do is add the following lines to your ~/.bashrc. You can open this file by running nano ~/.bashrc.

(If you're using a custom shell, you'll want to edit ~/.zshrc, ~/.config/fish/config.fish, or equivalent.)

source /course/cs1260/opam/opam-init/variables.sh
dune() {
  cmd=$1
  shift
  if [ -f "dune-project" ]; then
      /course/cs1260/opam/4.14.0/bin/dune $cmd --root . $@
  else
      echo "Make sure to run dune from a project root directory (i.e. one that contains a 'dune-project' file)"
  fi
}

Writing code

If you have another editor of choice (e.g. emacs or vim) you are free to use it. The department machine already has the merlin and ocamlformat packages which may be of use should you choose to use a different text editor.

First, install VS Code by following these instructions. Once VS Code is installed, go navigate to View > Extensions and search for and install the Remote - SSH extension from Microsoft.

Follow the connecting remotely using VS Code guide. Where it says to make your home folder your default directory, you can also open your folder you will be using for this class (i.e. ~/course/cs1260).

Then download the "OCaml Platform" extension through the VS Code extension marketplace.

Finally, go to settings and search for "Format on Save". You'll want to make sure that is turned on.

You should be good to go! The OCaml Platform extension should give you many useful features like type-hints above functions and formatting-on-save. You may get a popup asking to select a sandbox, but it should work if you close the popup.

Docker for M1 Macs

Note: this is an experimental development environment; please be aware that bugs may arise with this setup later on in the course; we will patch things as they come up, however.

Follow the setup instructions here; running the script will install Docker, an emulation environment called Qemu, and a runner called Lima. Ensure that you run this script in an environment where you're happy having the course folder be!

After the setup script has completed, the resulting ./start script will start the container, and the ./stop script will stop it. To enter the container, run the provided limactl command. If, once you enter the container, dune isn't available, run eval $(opam env). If dune is still not available or, for whatever reason, something doesn't work, run the commands in this script in order.

Writing Code

Similarly to all of the other environments, you should be able to use VSCode on your files locally and Docker will sync them into the container's file tree. Use the container shell to build your code.

Afterwards, download the "OCaml Platform" extension through the VS Code extension marketplace.

Finally, go to settings and search for "Format on Save". You'll want to make sure that is turned on.

You should be good to go! The OCaml Platform extension should give you many useful features like type-hints above functions and formatting-on-save. You may get a popup asking to select a sandbox, but it should work if you close the popup.

Conclusion

You are now all set up to write OCaml! If you have issues with any of this, post on Ed and course staff can help. Have fun coding!