2. Software Prerequisites¶
In this course, we will be using OCaml as the main
programming language. We will be working with multi-file projects, which will
make use of various external libraries, and involve automated building and
testing. The default OCaml version for this class is 4.12.0
, but later
4.x
versions should work fine too. If you don’t have a working OCaml
framework (or your OCaml version is different from the one used below), please
allocate at least 2 hours for going through this setup document, as some of
the software packages listed required for our class will take quite a while to
install.
Even if you already have OCaml installed, please, make sure check the intructions below on installing LLVM and Clang in your operating system.
2.1. Updating your OCaml¶
First, we need to install all the software necessary for fully fledged OCaml development. If you have used OCaml before you should already have this set up, so you are almost good to go: you will still need LLVM and Clang, so see the instructions below.
Assuming you already have some version of opam installed in your system, but
your OCaml version is older than 4.12.0
(you can check it by executing
ocamlc --version
), please, update your set up and install the necessary
packages as follows:
opam update; opam upgrade
opam switch create 4.12.0
eval $(opam env)
opam install -y dune core batteries utop num menhir merlin ocamlformat ocaml-lsp-server
opam user-setup install
Alternatively, if you don’t have a working opam
and OCaml, please,
follow the instructions below.
2.2. Installing OCaml from scratch on MS Windows 10/11¶
Unfortunately, the OCaml infrastructure is not supported well on Windows (natively), therefore developing large multi-file projects in it is problematic. To circumvent this issue, we will be running OCaml and the related software using Windows Subsystem for Linux (WSL2), a utility that allows to run a distribution of Linux within your Windows 10 or Windows 11 system. This setup takes a large number of steps, but once you’re done with it, you’ll have a premium support for OCaml, and also a fully functional Linux distribution installed on your machine.
First, let us enable WSL2 and install a Linux distribution. The detailed steps are given in the following tutorials:
Don’t forget the password for the Linux account you’ve just created: you will need it to install some software.
In case if you’re experience errors when starting Linus under WSL2, please, check the Troubleshooting section below.
At the end of this step, you should be able to run a “bare-bone” Ubuntu Linux terminal as an application within your Windows system. In my case, it looks as follows.
![_images/ubuntu.png](_images/ubuntu.png)
You can access your Windows home folder from WSL Linux via tha path
/mnt/c/Users/YOURNAME/
whereYOURNAME
is your Windows user name. It is convenient to make a symbolic link for it, so you could access it quickly, for instance, calling ithome
. This is how you create such a link:cd ~ ln -s /mnt/c/Users/YOURNAME/ home
Now you can navigate to you Windows home folder via
cd ~/home
and to your Linux home folder viacd ~
.So far so good, now we have a running Linux, so it’s time to install OCaml libraries. First, we need to install a number of Linux packages that OCaml needs. Run the following lines from Linux terminal (it can be done both from within graphical shell, or from within a separate Ubuntu terminal run as a Windows applications):
sudo apt install make m4 gcc pkg-config libx11-dev
Don’t forget to enter the password you’ve created for your Linux account, it might be different from your Windows one. Be patient: installing those packages will take quite some time.
Next, we will install the
opam
package manager for working with different OCaml libraries. Execute the following lines from Linux terminal:sudo apt install opam opam init -y --compiler=4.12.0 --disable-sandboxing eval $(opam env) opam install -y dune core batteries utop num menhir merlin ocamlformat ocaml-lsp-server opam user-setup install
Once done, add the following line to the
~/.bashrc
file in the home folder of WSL2 Linux:eval $(opam env)
After that, close your terminal window and start a new one.
To check that your OCaml is correctly installed, run
ocamlc --version
from the terminal. You should get the output4.12.0
, which is the version of the OCaml compiler we have just installed.We recommend you to use VSCode for your OCaml your development, assuming you’ve done steps 1-4.
Start by installing the
Remote-WSL
plugin. It is the one suggested the first time you run VSCode. Alternatively, you can install it by pressingCtrl-Shift-P
, typinginstall extensions
, and choosingInstall Extensions
item from the dropdown menu, and then finding and installing theRemote-WSL
extension.After installing that extension, press
Ctrl-Shift-P
and chooseRemote-WSL: New Window
. This will take a few seconds and will start a new window of VSCode that runs inside your WSL Linux (you can even start a Linux terminal there).Next, in this remote window, install the extension “OCaml Platform” in the same way as described above.
Now, you can open an OCaml file (
Ctrl-Shift-P
, followed by “File: Open File”) and enjoy the advanced features: highlighting, code completion, and type information, as well as many others. An example of the UI is shown below. Notice the indicators at the bottom of the screen, showing that VSCode runs in WSL (Ubuntu), with OCaml/merlin support enabled:
![_images/vscode-wsl.png](_images/vscode-wsl.png)
2.3. Installing OCaml from scratch on Linux¶
If you’re using Linux, the setup is similar to the one for Windows 10/11 WSL2
described previously. Just follow the points above starting from the step 3 in
the previous section. If you’re using a distribution different from Ubuntu, make
sure to use the corresponding package manager (instead of apt
) to get the
system packages in the step 3.
2.4. Installing OCaml from scratch on macOS¶
OCaml is well-supported in macOS, so the installation process is fairly straightforward.
Install the Homebrew package manager for macOS.
Install the following system packages using Homebrew:
brew install make m4 gcc pkg-config
Next, we will install the
opam
package manager for installing and maintaining different OCaml libraries. Execute the following lines from the terminal:brew install opam opam init -y --compiler=4.12.0 eval $(opam env) opam install -y dune core batteries utop num menhir merlin ocamlformat ocaml-lsp-server opam user-setup install
Once done, add the following line to your
~/.zshrc
,~/.bashrc
, or~/.profile
files (if they exist):eval $(opam env)
After that, close your terminal window and start a new one.
To check that your OCaml is correctly installed, run
ocamlc --version
from the terminal. You should get the output4.12.0
, which is the version of the OCaml compiler we have just installed.We suggest you use VSCode for OCaml development. To do so, after downloading and installing the VSCode IDE, you you will need to install the OCaml Platform extension, which enables OCaml support in VSCode (assuming you have installed all libraries above via
opam
in the step 3). You can install the extension by pressingCommand-Shift-P
, typingInstall Extensions
, and choosing that item from the dropdown menu.Now, if you open an OCaml file, it will look like that:
![_images/vscode-mac.png](_images/vscode-mac.png)
2.5. Installing LLVM and Clang¶
For some projectsin this class, we will be using the LLVM framework, which you can install as follows:
Ubuntu or MS Windows 10/11 with WSL2: run
sudo apt-get update && apt-get install clang
macOS: Install XCode (via the AppStore), run it, go to
Preferences
, and install the command line tools.macOS (alternative): If you use Homebrew, run
brew install llvm
.
2.6. Running native applications using Rosetta (For M1/M2 Macs)¶
If you’re using a new MacBook with an M1/M2 chip, in many cases you will have to run the examples from the classes using the Rosetta translator. Make sure you install Rosetta following these instructions.
In case if running a Makescript in a project results in a number of errors involving X86 Assembly commands, simply re-rung the command as:
arch -x86_64 make
You can also make an alias for this specific command with a flag, e.g., calling
it rosetta
by adding to your shell file (e.g., ~/.zshrc
):
alias rosetta="arch -x86_64"
And then run make scripts as rosetta make
.
2.7. Checking your Setup¶
In order to check your set up, please, make sure to email your GitHub name to the instructor—this is necessary to grant you GitHub access for course-related repositories.
Once you are done installing/updating OCaml and LLVM, please clone this project from GitHub—it is private, but you should have access to it if you have provided your GitHub name.
Once cloned, run make
from the project root. You should see the
output, meaning that your configuration is complete for the class:
DEFINING O0
DEFINING O1
DEFINING O2
DEFINING O3
clang -fno-stack-protector -fno-asynchronous-unwind-tables -O0 -emit-llvm -S -o factorial-O0.ll factorial.c
clang -fno-stack-protector -fno-asynchronous-unwind-tables -O0 -S -o factorial-O0.s factorial-O0.ll
clang -c -o factorial-O0.o factorial-O0.s
clang -o factorial-O0 factorial-O0.o
clang -fno-stack-protector -fno-asynchronous-unwind-tables -O1 -emit-llvm -S -o factorial-O1.ll factorial.c
clang -fno-stack-protector -fno-asynchronous-unwind-tables -O1 -S -o factorial-O1.s factorial-O1.ll
clang -c -o factorial-O1.o factorial-O1.s
clang -o factorial-O1 factorial-O1.o
clang -fno-stack-protector -fno-asynchronous-unwind-tables -O2 -emit-llvm -S -o factorial-O2.ll factorial.c
clang -fno-stack-protector -fno-asynchronous-unwind-tables -O2 -S -o factorial-O2.s factorial-O2.ll
clang -c -o factorial-O2.o factorial-O2.s
clang -o factorial-O2 factorial-O2.o
clang -fno-stack-protector -fno-asynchronous-unwind-tables -O3 -emit-llvm -S -o factorial-O3.ll factorial.c
clang -fno-stack-protector -fno-asynchronous-unwind-tables -O3 -S -o factorial-O3.s factorial-O3.ll
clang -c -o factorial-O3.o factorial-O3.s
clang -o factorial-O3 factorial-O3.o
dune build --profile release @install
2.8. Troubleshooting and FAQ¶
Problem: When startgin Linux under WSL2, I get the error
WslRegisterDistribution failed with error: 0x80370102
.Solution: Enable the Virtual Machine Platform Windows feature and make virtualization is enabled in the BIOS of your machine. Some useful links:
Question: May I use Emacs for programming in OCaml?
Answer: Of course, you can! This tutorial used to have notes on how to configure Emacs/Aquamacs for OCaml, but the experience of the last few years has confincingly demonstrated that VSCode is a much simpler and more convenient to use alternative, so why don’t you give it a try?
Problem: Merlin is not detected by VSCode, which gives an error “
ocamlmerlin
is not found”.Solution: This is the case if you didn’t add
eval $(opam env)
to the configuration files (e.g.,~/.bashrc
,~/.zshrc
, or~/.profile
). Adding it and restarting VSCode should fix it.Problem: In VSCode, a Git icon in the vertical panel on the left keeps blinking with the “watch” symbol when being updated.
Solution: Add the following line to your
settings.json
file:"git.showProgress": false
2.9. Installing Graphical Shell for WSL2¶
You might want to install a graphical shell for the Linux distribution running in WSL. This article provides detailed instructions on how to do so for Windows 10, and here you can find instrucitons for Windows 11. Here are some comments:
You don’t have to install Firefox in WSL Linux, as you can use your Windows browser instead.
The required graphical XServer shell (run separately from Windows) can be downloaded from this resource.
To run Linux with the graphical mode, you will always have to first run the XServer, and then the Ubuntu shell, in which you will have to type
xfce4-session
. The Ubuntu window will have to stay running as long as you use Linux.
If the Linux image appears to be somewhat “blurred”, here’s how to fix it:
First, add the following lines at the end of the file
~/.bashrc
in your Linux home folder:export GDK_SCALE=0.5 export GDK_DPI_SCALE=2This can be done using the
nano
editor, similarly to how it is done in this tutorial.Next, close any running instance of that X server (VcxSrv). Open the folder where you have installed it (e.g.,
C:\Program Files\VcXsrv
), right click onvcxsrv.exe
. Choose Properties > Compatibility tab > Change high DPI settings > Enable Override high DPI scaling and change it toApplication
option. Here is the screenshot looks like after changing the settings:
![_images/blur.png](_images/blur.png)
Once you have done all of this, you can run Linux terminal within the graphical XFCE shell and execute all commands from it, rather than from a Windows-started Ubuntu terminal. In my case, it looks as follows:
![_images/xfce.png](_images/xfce.png)