To run Forge, you will need to have installed:
- Racket (we suggest the latest version, and certainly no lower than 8.7);
- Java 11 or later (which you can get here if you don't have it);
- A modern web-browser for visualizing output (we suggest, and primarily test on, Firefox).
We strongly suggest using our VSCode extension to write Forge, although you can also run from the terminal or use DrRacket (Racket's built-in IDE). You can get VSCode here.
To install Forge, you have two options. The first is to install from Racket’s package server, and the second is to install from Git, which also allows (but doesn't require) you to use the latest development build if you wish.
We recommend installing from Git, because this way you can pull updates immediately if you wish to.
For the standard package-server installation, after installing Racket, run
raco pkg install forge froglet from your command line. Alternatively, you can run Racket's IDE, DrRacket, and navigate to File > Install Package. Type
forge as the package name and choose Install, then do the same for
If the package is already installed, you'll see an Update button instead of an Install button.
When you run a Forge file (via
racket <filename> at the command line), you'll be told the Forge version you're running. This is important information to include with questions, etc. If you're taking a class that uses Forge, you can expect a few Forge updates throughout the semester---please keep Forge updated!
To install via Git, open a terminal window. Then:
- clone our Git repository (
git clone https://github.com/tnelson/forge);
- change directory to the repository folder (
- install the
raco pkg install ./forge ./froglet).
If you wish to switch to the development branch, you must:
- check out the development branch (
git checkout dev);
- rebuild Forge (
raco setup forge).
./ in the
install command! If you write
raco pkg install forge froglet, that will install both from the package server instead of your local directory. Adding prefix
raco that you're talking about folders instead. It's also important to have both
./froglet in the single command; they depend on each other, so leaving one out will cause
raco to "helpfully" install it from the package server, not your local drive.
To get Forge's VSCode extension:
- Download the latest release from here. You should download the file that says
[version]is the latest version of the extension).
- Open VSCode and click on the Extensions button on the left hand side of the window.
- Click the three dots on the top.
- Select “Install from VSIX” and select the file you just downloaded.
Please keep the extension updated!
If you're working in a file with the
.frg extension, you should see an eye icon in your VSCode toolbar (usually on the upper right). This can be used to opt out of (and back into) logging. By default, we log the state of your Forge model whenever you click the run button in VSCode. This includes the contents of every
.frg file being edited in VSCode. No other information is recorded, not even your identity.
In prior years, logging was done via annotations to
#lang in homework files. We no longer do this. A major consequence is that we no longer know your identity from logs; we believe this is an improvement! However, it does mean we can't reach out if we see a problem happening. Please report problems if you see them.
We log primarily for two reasons.
- First, Forge is under active development---the majority of the codebase was written by undergraduate researchers working with Tim! This means that information about how Forge is used, what errors arise, etc. can be useful in making Forge better.
- Second, Forge is mainly used in the classroom. It's easy for instructors to claim, anecdotally, that students "like" something or "find it useful" based on a handful of office-hours conversations. We want to hold ourselves to a higher standard. What proportion of students actually uses that feature? Is the hinting we provide on some problems effective? Questions like these are impossible to answer without knowing something about patterns of use.
Once Racket, Forge, and Java are installed, you should confirm that everything is working properly. Create a text file
test.frg with only the contents
#lang forge and then, from your command line, type
racket test.frg. If this runs without error, congratulations, Forge should now be installed!
If you encounter any issues installing, please report them. We'll do our best to get you help as soon as possible.
- If you're taking CSCI 1710 at Brown, a class that uses Forge, report bugs on EdStem.
- If you don't have a course-related means of reporting bugs, please mail Tim (Tim_Nelson@brown.edu).
Please remember to update using the method appropriate for your install.
raco pkg update forgeand
raco pkg update froglet.
Updatefor both in the DrRacket package manager.
cdto the location of the
Forgerepository on your system;
- make sure you're in the branch you want (
mainfor published updates,
devfor our development build);
git pullin the repository, and then
raco setup forgeand
raco setup froglet(to rebuild the packages).
Confirm that these packages are installed properly using
raco pkg show froglet and
raco pkg show forge.
If one is installed from a directory on your machine, and another via the Racket package system, issues can occur. Here's how to read the information that
raco provides. If it says:
link <path on your machine>then the package is installed from a local folder; and
catalog ...means the package is installed via Racket's servers.
If you use Windows, running Forge from
cmd or PowerShell is not recommended (as of January 2024); we strongly suggest using the VSCode extension, DrRacket, the Windows Subsystem for Linux (
bash, or Cygwin.