Here’s how to build your own version of boxes using the boxes sources.
The boxes development platform is currently Debian Linux on WSL2. The author also supports MinGW on win32 and derived from that, a choco package for Windows.
In order to build on Linux:
The following command is for Debian (APT), but those packages have the same names across most distros.
sudo apt-get install -y build-essential diffutils flex bison libunistring-dev libpcre2-dev git vim-common
Of those, only libunistring and PCRE2 are
libraries that are used at runtime. Everything else is just for building, including
vim-common provides the xxd tool, which is used
by some of our test cases.
GLOBALCONFto whereever you want the system-wide config file to reside. Note that each user may have his/her own config file in $HOME/.boxes or other locations.
GLOBALCONFis a full file name. It does not specify a directory into which to copy the config file.
make && make test. Find the resulting binary in the out folder. In case of problems, check the compilation faq.
That should be all. Boxes is built so that this works almost everywhere.
In order to deploy your newly created binary on Linux/UNIX, these steps are recommended:
GLOBALCONFis the name of the file, and not the name of a directory into which to copy the file. So, the name of the config file may be changed from boxes-config to just boxes.
Example (as root):
cp doc/boxes.1 /usr/share/man/man1 cp boxes-config /usr/share/boxes cp out/boxes /usr/bin
If you want to make your own changes to the config file, copy the system-wide config file
into your home as $HOME/.boxes, then modify it. Boxes will use $HOME/.boxes if it exists.
Since boxes v2.1.0, you can also start your local config with
parent :global:, which will inherit everything from
the global file, and you can add or override box designs in your local file.
Boxes was written for UNIX, but it can also run on Windows! Boxes is a 32bit application, but it works on 64bit systems, too. Here’s how to build on Windows.
Special thanks go to Ron Aaron, who provided a specially crafted Makefile for win32 and also created the Windows versions of boxes that have been around to this day.
In order to build boxes on Windows, the required win32 executable can be created like this:
Basically very simple, but there may be a few pitfalls, so we’ll go through each step in detail.
C:\MinGW. This is really important. If for some reason you cannot use this highly recommended directory, choose another one that has a short path, does not contain spaces (!), and does not include a Windows “special path”. For example,
Choose the following packages:
mingw32-base msys-base mingw32-libunistring mingw32-libiconv msys-diffutils msys-dos2unix msys-zip msys-unzip
PCRE2 is unfortunately not available here, so we must handle this in a later step. For each of the above components,
choose all the items (bin, doc, lic, etc.). We also don’t choose flex and bison.
Do not install mingw-developer-toolkit, because if on 64bit, this requires tweaking of several environment variables to get gcc to use 32bit libs all around (which may be hard to get right for laymen).
Open fstab and make sure that the only lines which are not comments are these:
c:/mingw /mingw d:/path/to/boxes /boxes
Note that the whitespace in this example are tab characters. The d:/path/to/boxes is the path where you placed your clone of the boxes repo. Avoid spaces in its path, too.
The remainder of the steps happen within the MinGW shell:
curl -Vfrom within the MinGW shell.
Download and build PCRE2, and download flex and bison. This is summarily handled by
In case this doesn’t work, you must somehow get PCRE2 to compile on your own. The goal is to have pcre2-10.36/.libs/libpcre2-32.a available. We only need the static library for UTF-32. The version number of PCRE may change in the future.
If you want to create an executable with debug information, call
make clean && make win32.debug instead.
make testto check that your executable is working OK.
In order to run boxes on any Windows machine, two files are required:
boxes.cfg is obtained by simply renaming the boxes-config file from the root of the boxes repo into boxes.cfg.
Both files should be placed together somewhere on your PATH.