Introduction

Surfer is a wave form viewer supporting VCD, FST, and GHW files as well as the memory transaction format FTR.

The GHW support is not as complete as VCD and FST, but please file issues with examples of files not working.

It is built to be highly configurable.

Installation

You can install Surfer either as a binary or from source. It is in general recommended to run the latest version from git.

Installing Surfer from source

To install from source you must have a Rust compiler. To install the Rust compiler go to https://rust-lang.org/tools/install/.

Now, you can do

cargo install --git https://gitlab.com/surfer-project/surfer.git surfer

Replace surfer with surver to install the server only version.

There are a number of compile-time features that can be enabled/disabled.

If you plan to contribute to the development, please see the [development](development information).

Surfer depends on openssl. If you get linker errors, please install this via your package manager.

Debian/Ubuntu

sudo apt install openssl
sudo apt install libssl-dev

Fedora

sudo dnf install openssl
sudo dnf install openssl-devel

Arch

sudo pacman -S openssl

Installing a specific version

To install an earlier version, use:

cargo install --locked --root <PREFIX> --git https://gitlab.com/surfer-project/surfer.git --tag v0.4.0 surfer

where

<PREFIX> is the install location, see cargo install documentation for location order if --root <PREFIX> is ignored.
v0.4.0 is the tag

Note that --locked is important here as it will install with exactly the same dependencies that worked when releasing that version.

You may also want to replace --tag <TAG> with --rev <COMMIT-HASH> to get the version at a specific commit. For example, the version just before we broke something that we have not yet fixed.

Also note that Surfer versions are not yet that important, but more a reason to write an announcement (and to update the distributions in the next section).

Installing Surfer as a binary

Some Linux distributions have Surfer available as a package to be installed through the package manager. These include:

Homebrew also has a formulae.

In addition, it is possible to download and install the latest binary built after each merge to main:

Linux (x86)
Rocky Linux (x86)
Linux (ARM)
macOS (ARM) This binary is currently not signed, so most users will not be able to install it as is. We are looking for a solution to this.
Windows (x86) Note that sometimes Windows Defender has been known to report Surfer and other rust projects as a trojan. If in doubt, please use Virus total to check.

Once Surfer is installed, it can be started by typing surfer or surfer WAVEFORMFILE.vcd to directly load a waveform file. There are also additional arguments that can be seen by typing surfer --help. This should now display the arguments as:

Usage: surfer [OPTIONS] [WAVE_FILE] [COMMAND]

Commands:
  server  starts surfer in headless mode so that a user can connect to it
  help    Print this message or the help of the given subcommand(s)

Arguments:
  [WAVE_FILE]  Waveform file in VCD, FST, or GHW format

Options:
  -c, --command-file <COMMAND_FILE>  Path to a file containing 'commands' to run after a waveform has been loaded.
                                     The commands are the same as those used in the command line interface inside the program.
                                     Commands are separated by lines or ;. Empty lines are ignored. Line comments starting with
                                     `#` are supported
                                     NOTE: This feature is not permanent, it will be removed once a solid scripting system
                                     is implemented.
      --script <SCRIPT>              Alias for --command_file to support VUnit
  -s, --state-file <STATE_FILE>      Load previously saved state file
      --wcp-initiate <WCP_INITIATE>  Port for WCP to connect to
  -h, --help                         Print help
  -V, --version                      Print version

Keyboard shortcuts

Surfer