Spade Projects and Swim

Swim is the build tool for Spade, it manages the files in your project, sets up and calls the Spade compiler for you, can install and run backend tools for you, and is used to run tests. This is the main program you will interact with while writing Spade. The command itself is called swim and has a variety of sub-commands.

For software developers, think of swim as the cargo, npm, pip etc. of the Spade world.

Creating a Project

You can create a Spade project with swim init. If you run it inside an empty directory, it will initialize a project with the same name as the directory. You can also run swim init <project_name> to create a new directory for your project.

Project Structure

A Swim project consists of two important parts. The Spade source code in the src folder, and the project configuration in the swim.toml file. For now, you can just write all your code in the single file src/main.spade until we discuss namespacing later.

Building your Project

Swim has a few sub-commands for building your code. First, swim build simply compiles the Spade code into Verilog.

From there, you can either simulate or synthesize your code. To simulate, use swim simulate, though unlike on the playground this requires writing tests, which we will cover in the Simulation and Testing chapter.

Hint Many of Swims sub-commands can be abbreviated through aliases. For example, swim simulate, swim test, swim sim and swim t all do the same thing. (There is no swim s alias though.)

Hint You don’t actually need to run swim build and swim test, Swim will call swim build automatically if required, so you can simply run swim test and let Swim handle the dependencies.

Uploading to Real Hardware

For now, in this tutorial you can continue running simulation and skip this section, but if you want to try your code on real hardware, this is how to do it.

If you want to synthesize your code and run it on an FPGA, call swim upload. This will synthesize, place and route, pack, and then upload the result to whatever FPGA board you have set. These steps require configuring the project for your target FPGA though, see the project configuration section for details. You can also directly set up your project from a template as described below.

Hint Like swim test, you don’t actually need to run both swim build and swim upload, upload will run build automatically if required.

Note swim upload consists of several separate steps, namely swim synth, swim pnr and swim upload. It can be helpful to run these individually in some cases, but most of the time simply running swim upload is the easiest option.

Project Templates

You can also create a project from a template which will pre-populate the swim.toml file with synthesis configuration for a particular FPGA. Run swim init --list-boards to see a list of boards supported via ready-made templates.

If your board is supported, you can then run swim init --board <your_board> to quickly get started.

If your board is not supported yet, you can also fill in the [simulation], [pnr], [packing] and [upload] fields manually, see the Project Configuration reference section for details.

Consider submitting a merge request in case you made a configuration for an unsupported board.