Spade projects and swim

So far the Spade playground has been a convenient way to get started with the language, but as our projects get more complex we will move on to real Spade projects. If you haven't already, go back and read the installation to install Swim and its surrounding tools.

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.

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 in 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 has two important parts. The source code in the src folder, and a project configuration file in swim.toml. For now, you can just write your code in 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 sim (or swim test or swim t), though unlike the playground this requires writing tests, which we will cover in the next section.

Hint You don't actually need to run swim build and swim test, swim will call swim build automatically if it is required, so you can simply run swim test.

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, use swim upload which will synthesize, place and route, pack, and then upload the result to whatever FPGA board you have configured. These steps require configuring the project for your target FPGA though, see the project configuration section for details, or set your project up with 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 it is required.

swim upload also consists of several steps, namely swim synth, swim pnr, swim pack and swim upload. These can be helpful to run 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 configuration file for synthesis for a particular FPGA. If you have an FPGA board already, run swim init --list-boards. If your board is supported, you can then run swim init --board <your_board> to quickly get started.

If your board isn't supported yet, you can also fill in the [simulation], [pnr], [packing] and [upload] fields manually, see the project configuration section for the