8. Appendix: Course Software

Todo

Under construction for spring 2024!

You can choose either or both of the following options.

8.1. Cloud-based development environment

This option is recommended if you have any problems with your local setup or if you prefer a basic cloud-based setup.

8.1.1. Pros

consistent, cloud-based environment
out-of-the-box integration with GitHub

8.1.2. Cons

requires good network connection
might lack some code completion features
free plan might be underresourced (CPUs, RAM, disk space, etc.)

8.1.3. Gitpod (recommended)

Gitpod is a cloud-based development environment based on Visual Studio Code running on Ubuntu LTS.

To launch, visit gitpod.io and log in using your GitHub account.

The first time around, create a new workspace and paste the URL of the GitHub project you want to work on in the new workspace; you can also select a project from the dropdown menu.
After that, your GitHub landing page will show your workspace(s); inactive workspaces are deleted after a certain amount of time.
For each new workspace, using the installed SDKMAN!, perform a one-time installation of java and sbt;
In case your workspace no longer recognizes the sbt command, reinstall via the command
```
sdk install sbt
```
Install the VS Code extensions listed below.
Now you should be able to work on the project by following the instructions in the readme.

8.2. Locally installed development environment

This option will give you an advanced development environment with code completion, type info, etc.

8.2.1. Pros

provides powerful capabilities, including code completion
does not require network connection once installed

8.2.2. Cons

might be slow on older machines
need to maintain on each machine you use
it can be challenging to match the versions of the various packages
GitHub account access might be tedious to configure
possible difficulty managing coexisting Java versions

8.2.3. Required packages

Java 17 LTS recommended (newer versions might have compatibility issues with certain sbt plugins)
Git distributed version control system (usually preinstalled on Mac OS and Linux)
- recommended installation option on Windows: Use Git and optional Unix tools from the Windows Command Prompt
- optional on any platform, especially when not an IDE: some GUI-based Git client
sbt Scala build tool
Mac and Linux users are strongly encouraged to use SDKMAN! to manage their Java, sbt, VisualVM, and other command-line development tools.

8.2.4. Choices of local development environments

Visual Studio Code (recommended for PlusCal/TLA+ development, supports Java development)
- need to install the actively developed TLA+ extension
- if you see false syntax errors in your Java source editor in an sbt project, try disabling the “Extension pack for Java” and related extensions for your current workspace
- if you’re not seeing arrows in the source file for running the tests, try importing the build in Metals (big “M” near the bottom of the leftmost column)
- see below for recommended VS Code extensions
IntelliJ IDEA CE integrated development environment (alternative for Java development)
- has an unofficial TLA+ plugin
- check specific prerequisites for your platform
- for the following steps, make sure you have no projects open and are looking at the welcome window as in the attached screenshot
- JDK configuration: IntelliJ IDEA > Configure > Project Defaults > Project Structure > Platform Settings > SDKs > + > JDK > navigate to the installation directory of your Java 17 JDK > OK
conventional text editor (OK for general development but not recommended for working with PlusCal/TLA+, though one can use them with the standalone TLA Toolbox)
- Emacs
- vim
- etc.

8.3. Recommended Visual Studio Code extensions and settings

Install via the extensions tool in the VS Code toolbar:

Scala/Metals - required for sbt-based Java projects
You should also disable the official Microsoft or Red Hat Java extensions while working on sbt-based Java projects
TLA+ Nightly - required for model development and checking
Conceal - recommended for nicer rendering of mathematical symbols in TLA+ (see here and here for instructions)

When running VS Code locally, autosave isn’t on by default, and you need to save your files manually: When there is a solid circle on the file’s tab, it’s not saved yet. I strongly recommend turning on autosave so your local instance of VS Code works the same way as browser-based instances:

click the cogwheel in the bottom left corner to open settings
type “autosave” in the search box
look for the actual setting and choose onFocusChange

8.4. GitHub

GitHub is a provider of hosted Git repositories, which emphasizes community and collaboration. For this reason, we use it to host our course examples.

Create a GitHub account if you don’t already have one.
Get the GitHub Student Developer Pack using your official @luc.edu address. This will give you free unlimited private repositories.
Find and follow a few practitioners you respect. For example, I follow these developers. You’ll probably recognize a number of them.
Review these notes to understand the community-based development process.
For credit toward class participation, create some meaningful GitHub issues and/or GitHub pull requests for one or more of our course examples. (Make sure to navigate to the original repos as these forks do not have their own issue trackers). These can be functional or nonfunctional enhancements, requests for clarification, etc.
To enhance your visibility in the professional community, start doing the same for some open-source projects you are interested in.

You may find both of these cheat sheets useful:

GitHub
GitLab (includes useful diagrams)

8.5. Remote participation

This software allows you to participating in class remotely in case of weather emergencies, pandemics, etc. For security and privacy reasons, be sure to update it frequently.

Zoom

In case of a Zoom outage, we will fall back to MS Teams chat and reorganize from there.