Development Environment Guide
This guide draws inspiration from the cs300 lab on setting up your development environment.
In this course, we'll be using C++ and a few associated libraries, alongside CMake as our primary build tool. We use Docker containers to ensure a standardized environment between all students and machines.
Docker
To get started, you should download and install Docker here. If you're running Linux, you can follow instructions here, if you're running MacOS and have Brew installed, you can run brew install docker to install Docker using brew.
Verify that you have docker installed:
docker --version
which should print a version number. You can verify that Docker is running:
docker info
If you get a message like
ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
You should start Docker. On Mac and Windows, ensure that Docker Desktop is running. On Linux, try sudo systemctl docker restart to restart the process.
You can follow additional instructions from the cs300 lab if you are on Windows and do not yet have WSL (Windows Subsystem for Linux) set up.
Running Docker
You can pull the cs1515 dev environment using:
git clone https://github.com/BrownAppliedCryptography/devenv.git <folder_name>
Your work (homework repos, etc) will live in this folder, so replace <folder_name> with the name you would like to call this folder and clone this folder into where you would like your coursework to live. We'll assume you clone the folder as cs1515.
cd into the directory:
cd cs1515
and pull the Docker image by running the following script:
./docker/cs1515-setup-docker
The script should tag the image correctly, but if it doesn't (you get an error saying the image was not found), you can also tag it manually:
arch=$([ $(arch) = arm64 ] && echo "arm64" || echo "latest") && docker tag jiahuac/cs1515:$arch cs1515:$arch
(This will attempt to pull our Docker image that has been prebuilt. If you wish to do so, ./docker/cs1515-build-docker will build the image from scratch.)
After this, you can run Docker for the first time:
./cs1515-run-docker
where you can interact with the shell of the container. You can Ctrl-D to exit.
Container Directories
You'll notice that your devenv folder contains a home directory. This is mirrored to the home directory in your Docker container. Outside of your Docker container, you can clone your assignment repositories into this folder, commit and push changes as normal. If you wish to do the same inside your Docker container, you can set up git again within the container using git config (you might also need to provision SSH keys, etc). We recommend the former option.
Dev Containers
We have a secondary development environment should the default not work well for you that uses Dev Containers. Ensure that you have both Docker and the Dev Containers VSCode extension installed. To use it, open VSCode and navigate to the project you're working on. Then hit Ctrl-Shift-P or Cmd-Shift-P and type > Dev Containers: Open Folder in Container.... Select the project folder, and VSCode will open the project folder in the Docker container.
IDEs
You should use the IDE or text editor that you are most comfortable with to work on assignments. While our editor of choice is VSCode for its support for Docker containers and autocompletion, you are not obliged to use VSCode. However, we won't be able to provide support beyond basic debugging for other editors. We detail instructions to set up your environment for VSCode and CLion here, but do use something that you're familiar with.
All tests and make commands are meant to be run from the terminal, and hence do not depend on which editor you pick.
VSCode
First, ensure that you have the Docker extension and the Dev Containers extension installed. You should see the Docker icon in your left toolbar. From there, you should see cs1515:latest or cs1515:arm64 in the left panel. Right click this, and you should be able to 'Start' and/or 'Attach Visual Studio Code'. Upon attaching VSCode, you will be in an editor window inside your Docker container. You will need the 'Remote Development' extension installed for you to be able to do this.
Then, from the VSCode terminal, you can navigate to your assignment repository (which you probably cloned from outside the container), and code . will open that specific project in VSCode. Make sure you have VSCode open to your assignment folder inside your Docker container, the easiest way to tell is that the bottom left of your window should show 'Container cs1515...". If you don't see this, try to attach VSCode to the container (above) and follow these steps again. You should be running your make and cmake commands within your VSCode/Docker terminal.
We have tried to preconfigure (as much as possible) assignments for VSCode development. Your VSCode might prompt you to install some suggested extensions, do this. Specifically, you should make sure that the "C/C++ Extension Pack" is installed in your Docker container. Once that is done, you might have to reload your VSCode window (Cmd/Ctrl-Shift-P and search 'Reload') for changes to take effect.
If you encounter errors (something along the lines of "cpptools doesn't have execute permission"), try to make sure that your extension tools are executable by running (within your Docker container):
chmod +x -R /home/cs1515-user/.vscode-server/extensions/
CMake should pick up your project and build artifacts (an output window should show), which can take a while. This process tells your IDE where your source files and libraries are.
To check that your autocompletion is configured correctly, from any src/*.cxx file, Cmd/Ctrl-click on a CryptoPP class or function, or start typing CryptoPP::, and ensure that they work.
CLion
Assignment repos should also work with CLion, if you so wish. (You can obtain copies of JetBrains IDEs for free using your Github student developer pack.)
In CLion, you should open up your assignment folder as a project. Then, in
Settings/Preferences > Build, Execution, Deployment > Toolchains
you should add a Docker toolchain. Click the + button, and select Docker. From the "Image" dropdown, select cs1515:latest or cs1515:arm64. CLion should detect CMake, build tools, compilers and debuggers. Then, drag the Docker configuration above "Default".
You might have to delete your cmake-build-debug folder and have CMake rerun, after which autocompletion should be configured.
To access your Docker container terminal, from the bottom bar, select Services and under Docker > Containers you should see your running container. Select that and click Terminal for CLion to bring up a terminal into your container.