General Notes
-
Because support for development environments is inconsistent
across operating system platforms, we will make use of Dev Contatiners in Visual Studio Code. This
makes use of lightweight virtualization to provide a uniform
environment across systems.
-
You are encouraged to commit your code to a private GitHub
repository. Note that this repo must be private. Keeping
a public repo with code from this course is an honor code
violation. You can decide if you would like to split
your code between multiple repositories (recommended) or keep
everything in one repository. If you split up your code, you
will need to follow the instructions below for each project.
Download and Install Docker
-
Docker provides lightweight virtualization that we will use as
the backend for our development container.
-
Follow the download and installation instructions for your operating system:
-
Launch the Docker Desktop appliction.
-
Verify that you can run the following command from your operating systems standard command line:
docker run --rm --platform linux/arm64 hello-world
(out)
(out)
(out)Expected output:
(out)
(out)Unable to find image 'hello-world:latest' locally
(out)latest: Pulling from library/hello-world
(out)478afc919002: Pull complete
(out)Digest: sha256:53cc4d415d839c98be39331c948609b659ed725170ad2ca8eb36951288f81b75
(out)Status: Downloaded newer image for hello-world:latest
(out)
(out)Hello from Docker!
(out)This message shows that your installation appears to be working correctly.
(out)
(out)To generate this message, Docker took the following steps:
(out) 1. The Docker client contacted the Docker daemon.
(out) 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
(out) (arm64v8)
(out) 3. The Docker daemon created a new container from that image which runs the
(out) executable that produces the output you are currently reading.
(out) 4. The Docker daemon streamed that output to the Docker client, which sent it
(out) to your terminal.
(out)
(out)To try something more ambitious, you can run an Ubuntu container with:
(out) $ docker run -it ubuntu bash
(out)
(out)Share images, automate workflows, and more with a free Docker ID:
(out) https://hub.docker.com/
(out)
(out)For more examples and ideas, visit:
(out) https://docs.docker.com/get-started/
This tests two things. First, it verifies that you have
successfully installed Docker and that your command line can
execute the Docker program. Second, it verifies that you can run
a container that executes Arm assembly, which we will use later
in the course.
Visual Studio Code Setup
-
Create a folder for all of your course work. This might be a
directory on OneDrive or on your local machine (if you are going
to use git to manage your code).
-
Install Visual Studio Code.
-
Launch Visual Studio Code
-
Platform-specific notes:
-
MacOS:
-
Type command + shift + p to bring up the command pallette. Start typing
shell and sleection "Install 'code' command in PATH". This will
let you launch a copy of VSCode opened to a specific directory.
-
Windows:
-
Check any box that indicates "install code command in
PATH" or similar.
-
Install the
ms-vscode-remote.remote-containers
extension. You can find extensions under the "Extensions" icon
on the left sidebar (It looks like four boxes with one box
flying away).
-
Choose
File > Open Folder, and select the folder you created before.
Configure Project and Dev Container
-
In VSCode, create a file named
.devcontainer.json
(note the leading dot...this makes it hidden on unix systems).
Add the following to this file and save it. This describes the
container image to download and the extensions to install into
VSCode.
{
"image": "docker.io/kevinaangstadt/cs364:fall24-latest",
"customizations": {
"vscode": {
"extensions": [
"ms-python.python",
"ocamllabs.ocaml-platform",
"vscjava.vscode-java-pack"
]
}
}
}
-
Create an empty file named
cs-364.opam. This is
used by Visual Studio Code to detect your Reason "sandbox" (the
software we are about to install).
-
Create a file named
.gitignore and paste the following
contents in it. If you save this project with git, it will ignore
certain files that are generated by the compiler.
.DS_Store
/node_modules*
finalOutput/*.js
.merlin
.install
/lib/bs/
/lib/js/
/lib/ocaml/
*.log
.bsb.lock
/src/*.js
_esy
_build
*.install
*.bs.js
# Editor
/.idea/
/.vscode/
-
Reload the VSCode window. You can do this by typing
control/command + shift + p and searching for
reload to find "Developer: Reload Window". When
the window reloads, look down in the bottom left corner. You
will likely see something that says Dev Container: Reopen in
Container. Click this and choose the option that has the
same name as your project folder. This tells the Dev Container
how to interface with your project.
-
You should see a notification that the container is being built.
This will take a while the first time you do it. Once it is set
up you will see some new icons show up on the left sidebar
(including one with a camel).
-
Open the built-in terminal in VSCode. This will open to the
directory of your project. You can open the terminal using the
View > Terminal menu or typing
ctrl + `.
-
You can test that everything is working by running
rtop. You should see a big prompt for Reason. You
can exit this by typing ctrl +
d. The output should be similar to the example
below.
rtop
(out)
(out)─────────────────────────────┬──────────────────────────────────────────────────────────────┬─────────────────────────────
(out) │ Welcome to utop version 2.14.0 (using OCaml version 4.14.2)! │
(out) └──────────────────────────────────────────────────────────────┘
(out)
(out) ___ _______ ________ _ __
(out) / _ \/ __/ _ | / __/ __ \/ |/ /
(out) / , _/ _// __ |_\ \/ /_/ / /
(out) /_/|_/___/_/ |_/___/\____/_/|_/
(out)
(out) Execute statements/let bindings. Hit after the semicolon. Ctrl-d to quit.
(out)
(out) > let myVar = "Hello Reason!";
(out) > let myList: list(string) = ["first", "second"];
(out) > #use "./src/myFile.re"; /* loads the file into here */
(out)
(out)Type #utop_help for help about using utop.
(out)
(out)Reason #
(out)┌──────────────┬──────────────┬───────────────┬─────┬────┬───┬──────────┬─────┬───────────┬──────┬────────────┬───────┬──┐
(out)│Afl_instrument│Alias_analysis│Allocated_const│Annot│Arch│Arg│Arg_helper│Array│ArrayLabels│Asmgen│Asmlibrarian│Asmlink│As│
(out)└──────────────┴──────────────┴───────────────┴─────┴────┴───┴──────────┴─────┴───────────┴──────┴────────────┴───────┴──┘
Reload the VSCode window. You can do this by typing Type
command + shift + p.
Then, type reload and select the option that states
Developer: Reload Window. When the window reloads,
look down in the bottom left corner. You will likely see
something that says opam(4.14). This means that VSCode
understands that it is in a Reason project.