Building from Source

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.

Building on Linux / UNIX

In order to build on Linux:

Unzip the source archive or clone the GitHub repo.
Install Prerequisites:
The following command is for Debian (APT), but those packages have the same names across most distros.
```
sudo apt-get update
sudo apt-get install -y bison build-essential diffutils flex git libcmocka-dev libncurses-dev libpcre2-dev libunistring-dev terminfo vim-common
```
Of those, only libncurses, libunistring, and PCRE2 are libraries that are used at runtime. Everything else is just for building, including Flex and Bison. vim-common provides the xxd tool, which is used by some of our test cases.
The location of the system-wide config file is compiled in, so if you don’t like it’s default location, you can edit the top level Makefile and change the value of GLOBALCONF to 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.
Also note that the value of GLOBALCONF is a full file name. It does not specify a directory into which to copy the config file.
From the top level directory:
```
make
make utest
make test-sunny
make test
```
This will build the project and execute the unit tests (utest), the sunny-day tests (test-sunny), and the black-box tests (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.

Deployment on Linux / UNIX

In order to deploy your newly created binary on Linux/UNIX, these steps are recommended:

Copy doc/boxes.1 to an appropriate manual page directory.
Copy boxes-config to the location specified in the Makefile as being the name of the system-wide boxes config file. Note that the value of GLOBALCONF is 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.
Copy out/boxes (the binary) to a location which is in your path.

Example (as root):

cp doc/boxes.1 /usr/share/man/man1
cp boxes-config /usr/share/boxes
cp out/boxes /usr/bin

Optionally, install the Vim syntax file (make sure to find the right target directory for your system):

cp boxes.vim /usr/share/vim/vim90/syntax

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.

Test Coverage

Full test coverage information can be produced by the build. In order to support that, additionally install:

sudo apt-get install -y lcov

Then invoke these targets:

make clean cov
make utest
make covtest-sunny
make covtest

The results will be logged in the console and also recorded in out/lcov-total.info.

Static Binary

Sometimes, you may want to run boxes on a system where the required libraries are not available as shared libraries. In such cases, linking all the dependencies into the boxes binary can be helpful. This is achieved by

make clean static

This will download and compile the dependencies, and then produce a static binary with everything on board.

Building on Windows

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 several of our early Windows versions of boxes.

In order to build boxes on Windows, the required win32 executable can be created like this:

Install MinGW
Configure MinGW
Open a MinGW shell and run make win32

Basically very simple, but there may be a few pitfalls, so we’ll go through each step in detail.

1. Install MinGW

Download MinGW from SourceForge. You’ll receive a small mingw-get-setup.exe.
Right-click mingw-get-setup.exe and choose Run as Administrator from the pop-up menu.
Press Install.
This will download the Installation Manager. Some time later, you can make some choices.
Make sure that you install to 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, C:\MinGW_2.
Select “install support for GUI” (yes, even though boxes has no GUI) and install “for all users”.
In the Installation Manager menu, select Installation → Update Catalogue.
Choose the following packages:
```
mingw32-base
msys-base
mingw32-libunistring
mingw32-libiconv
msys-diffutils
msys-dos2unix
msys-vim
msys-unzip
msys-zip
```
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).
In the menu, select Installation → Apply Changes. Something like 80 Packages will be installed, which may take a few minutes.
Upon success, select Installation → Quit from the menu.

2. Configure MinGW

Change into C:\MinGW\msys\1.0\etc.
Copy the file fstab.sample to a new file called simply fstab.
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.
Add C:\MinGW\bin to your system PATH.
Create a “MinGW Shell” shortcut somewhere (I chose my desktop). The shortcut invokes the C:\MinGW\msys\1.0\msys.bat script, which is installed as a component of MSYS; (if you installed to an alternative directory, you should adjust the C:\MinGW prefix accordingly). An icon file is provided in the same directory, in case you want to set it on the new shortcut.

3. Open a MinGW shell and trigger the Windows build

Double click your new MinGW Shell shortcut icon. This opens a command window with the correct environment set up for you, including the correct path references, allowing you to run any of the MinGW or MSYS applications within that command window.
The remainder of the steps happen within the MinGW shell:
```
cd /boxes
```
Make sure curl is on your path. That normally means that you download and install it separately from its website. At the end of this step, you should be able to curl -V from within the MinGW shell.
Download and build PCRE2, and download flex and bison. This is summarily handled by
```
make win32.prereq
```
In case this doesn’t work, you must somehow get PCRE2 to compile on your own. The goal is to have pcre2-10.40/.libs/libpcre2-32.a available. We only need the static library for UTF-32. The version number of PCRE may change in the future.
Next,
```
make win32
```
If you want to create an executable with debug information, call make clean && make win32.debug instead.
Run the tests:
```
make win32.utest
make test
```
Yes, the black-box tests don’t need a win32. prefix, because they are run via a shell script.
boxes.exe is created in /boxes/out.

4. Deployment

In order to run boxes on any Windows machine, two files are required:

boxes.exe
boxes.cfg

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.

Page created: March 17, 2015 Last updated: January 21, 2024