Skip to main content


Install Racket#

Install racket:

apt install racket

On MacOS and Windows, you can download the installer from the Racket website, and setup the commandline properly.

Install BHDL package#

Step 2: Install the BHDL directly as a racket package:

raco pkg install --auto

You can now run racket and require bhdl. The first time requiring bhdl, it will download footprint library to ~/.config/bhdl/bhdl-footprints (Linux) or ~/Library/Application Support/bhdl/bhdl-footprints (MacOS).

> (require bhdl)

Then try some of the examples.

Update BHDL#

In the future, you can update the package if there're updates upstream via:

raco pkg update src
TODO package name should be bhdl

JupyterLab IDE#

In general, you can run racket programs via command line, editor plugins, IDEs. We are not covering them here. Instead, we recommand run the program via jupyter notebook. To set it up, first install jupyter:

pip install jupyterlab

The iracket kernel requires on libzeromq:

sudo apt install libzmq5

On MacOS, it is a little trickier to setup libzmq. Specifically, you need to copy the library to the racket's library path, otherwise racket won't find it:

brew install zmq
cp /opt/homebrew/Cellar/zeromq/4.3.4/lib/libzmq.5.dylib Library/Racket/8.2/lib

Then install the kernel itself:

raco pkg install iracket
raco iracket install

iracket does not allow write access to file system by default. So you have to modify the kernel file with a -t parameter. In short, you need to modify the content of ~/.local/share/jupyter/kernels/racket/kernel.json on your system from ["racket","-l","iracket/iracket","--","{connection_file}"] to ["racket","-l","iracket/iracket","--","-t","{connection_file}"]

Then start the jupyterlab server:

jupyter lab

You'll be able to create racket notebooks in the JupyterLab IDE. Inside the notebook, try (require bhdl) and some of the exampels.

Placement (Optional)#

To run the placement engine, you need setup julia. Refer to their installation guide on how to install Julia.

Install the BHDL julia package:


Then run the server:

import BHDL

This will listen on To use this, in racket, set the parameter placer-url, and call circuit-export with #:auto-place #t:

;; set placer url
(placer-url "")
(circuit-export three-button #:auto-place #t ...)

This package will detect if Nvidia GPU is available, and use it if possible. The first time invoking the package, julia will download and instantiate the dependencies and download CUDA (julia will not use your system's CUDA setup). The first time the placement is running, Julia will pre-compile the code, thus maybe a little slower. Subsequent placement request will be much faster (which is why we use a server instead of invoking the command for every placement request).

Freerouting (Optional)#

To use routing, you need to have freerouting available. We tested on freerouting-v1.4.4. Make sure freerouting-1.4.4-executable.jar is available in your $PATH.

The executable can be downloaded here on the new freerouting maintainer website:

UPDATE: the jar file is often not an executable command. You'll need

java -jar freerouting-1.4.4-executable.jar

Thus, you need to create a executable called freerouting, containing:

java -jar /path/to/freerouting-1.4.4-executable.jar

freerouting will need X11 window, even if we are running it in command line. Simulate the X11 session via:

sudo apt install xvfb
Xvfb :1

But it seems to be impossible to view the progress. We'll probably need to use VNC if we really want to know what's going on.