Herbie is available through Docker, which is sort of like a virtual machine. This page describes how to install the official Docker image for Herbie.
We recommend most users install Herbie from package or source. Herbie via Docker is only recommended if you already have Docker experience.
First, install
Docker. Docker supports Windows, macOS, and Linux. Depending
on how you install Docker, you may need to prefix
the docker
commands with sudo
or run them
as the administrative user.
With Docker installed, you can run the Herbie shell with:
docker run -it uwplse/herbie shell
This will download the Herbie image and then run its shell tool.
You can run the Herbie web server locally with
docker run -it --rm -p 8000:80 uwplse/herbieand access the server at http://localhost:8000.
(Herbie's Docker image binds to the container's port 80 by
default; this command uses the -p 8000:80
option to
expose that container port as the host's port 8000.)
If you want to pass custom flags to the Herbie web server, make
sure to also pass the --public
and --port=80
flags to enable the Dockerized Herbie to
talk to your computer. Make sure to access the server using HTTP,
not HTTPS.
If you are using the --log
or --save-session
flags for the web shell, you will
also need to mount the relevant directories into the Docker
container using the -v
Docker option, as in the
examples below.
To use Herbie in batch mode, you will need to mount the input in the Docker container. Do that with:
docker run -it --rm \ -v in-dir:/in \ -v out-dir:/out \ -u $USER \ uwplse/herbie improve /in/in-file /out/out-file
In this command, you are asking Herbie to read input from in-file in in-dir, and write output to out-file in out-dir. The command looks the same if you want Herbie to read input from a directory; just leave in-file blank.
To generate reports from Herbie, you can run:
docker run -it --rm \ -v in-dir:/in \ -v out-dir:/out \ -u $USER \ uwplse/herbie report /in/in-file /out/
As before, the input and output directories must be mounted inside the Docker container. Note that both here and above, the user is set to the current user. This is to ensure that the files Herbie creates have the correct permissions set.
If you'd like to write and use custom platforms with Herbie in Docker, you'll need to mount the platform directory as well:
docker run -it --rm \ -v platform-dir:/platform \ -u $USER \ uwplse/herbie shell \ --platform /platform/platform.rkt
You can use custom platforms for the web interface or in batch mode using a similar approach.
This section is primarily of interest the Herbie developers.
Clone the repo and confirm that Herbie builds correctly
with make install
. Next, examine the Dockerfile and
Makefile together. The Dockerfile should follow a process exactly
like the Makefile, except a clean initial environment is
assumed.
The build is split into 2 or more stages to limit the size of the
resulting image. Each stage consists of a FROM
command
and a series of further commands to build up the desired
environment, and later stages can refer to earlier stages by
name—for example, COPY --from=earlier-stage ...
can copy files compiled in earlier images.
Before building the official image, bump the version of Rust used for binary compilation and the version of Racket used in production, and adjusting paths to match the newest version of the repo.
Once you are ready, run this from the repository root:
docker build -t uwplse/herbie:test .
This builds a new test image and tags
it uwplse/herbie:test
. You can run this image with:
docker run -p 8000:80 -it uwplse/herbie:test
The web demo should now be visible at http://localhost:8000
.
To open a shell in a running container for testing, first get the container ID with:
docker ps
Then open a root shell in that container with
docker exec -it <CONTAINER ID> sh
The code and egg-herbie
binaries should be
under /src
.