hexforge / install

Install

Source only. There are no distribution packages, no installer and no container image, because maintaining those for a pre-1.0 project would cost more attention than the router currently gets.

Host platforms

Dependencies

• A C++20 compiler. GCC 12 or newer, or Clang 15 or newer. Older compilers fail on the designated initialisers in the device tables, and the error messages are not kind.
• CMake 3.22 or newer.
• Python 3.10 or newer, used once during the build to turn the device description into static C++ tables. It is not needed to run the tools afterwards.
• Nothing else. No Boost, no LLVM, no GUI libraries, no package manager fetching anything over the network at configure time.

The deliberate absence of a network step at build time is the reason the device tables are generated by a script in the tree rather than downloaded. It also means a build works on a machine that has never seen the internet, which is how it gets tested on the aarch64 board.

Building

$ git clone https://git.hexforge.cloud/hexforge.git
$ cd hexforge
$ cmake -B build -DCMAKE_BUILD_TYPE=Release
$ cmake --build build -j8

On eight cores that takes about three and a half minutes and leaves a 40 MB build directory. The four binaries together come to 11 MB stripped. A debug build is roughly three times larger and the router is about twenty times slower, which matters: do not debug placement problems in a debug build unless you are prepared to wait.

$ cmake --install build --prefix ~/.local
-- Installing: ~/.local/bin/hxc
-- Installing: ~/.local/bin/hxsyn
-- Installing: ~/.local/bin/hxta
-- Installing: ~/.local/bin/hxpack
-- Installing: ~/.local/share/hexforge/devices/t4.hxd
-- Installing: ~/.local/share/hexforge/devices/m1.hxd

Running the tools from the build directory without installing works too; they locate device data relative to their own path, and fall back to HEXFORGE_DEVICES if that fails.

The test suite, including the failures

$ ctest --test-dir build --output-on-failure
...
97% tests passed, 4 tests failed out of 221

Total test time (real) =  96.41 sec

The following tests FAILED:
    118 - ta_corner_interp (Failed)
    164 - pack_dense_m1 (Failed)
    189 - route_congestion_45k (Timeout)
    203 - pack_clock_region_split (Failed)

These four fail on every platform and have failed for at least two releases. They are listed here rather than quietly skipped, because a test suite that always prints green teaches you nothing:

ta_corner_interp

Interpolation between temperature corners disagrees with the reference by up to 1.8%. The reference was computed by hand and may itself be wrong; until that is resolved the test stays red.

pack_dense_m1

Packing a design to above 94% occupancy on M1-8K fails to find a legal arrangement. Known weakness of the packer on the smaller family, tracked since 0.5.0.

route_congestion_45k

A deliberately congested T4-45K case exceeds the 180-second test timeout. It does finish, in about four minutes. This is the clearest single statement about router quality on the large part.

pack_clock_region_split

A design with two clocks whose loads straddle a clock region boundary gets packed into an illegal configuration. Workaround is in limitations; a fix needs the packer to understand clock regions, which it currently does not.

Device data files

Two files describe the hardware: t4.hxd at 2.1 MB and m1.hxd at 0.6 MB. They hold the tile grid, routing graph, bitstream frame layout and a delay table per cell type. Everything the tools know about silicon lives there; the binaries contain no device-specific code paths beyond reading those files.

They were built by measuring, and that shows. Delay numbers came from ring oscillators of varying length on real boards, fitted to a straight line per cell type, which is accurate to roughly ±12% and systematically optimistic on long routes. If you want to know how much to distrust a timing report, that sentence is the answer, and the timing page expands on it.

Upgrading from 0.6.x

Flag changes in the same release: --chip became --device, and hxsyn --timing was removed in favour of running hxta separately. Both old spellings print an error naming the replacement instead of silently doing nothing.