Getting Started

Installation

For now, Virdant only works on Linux. You can install it by cloning the repository and running make install:

console

$ git clone https://github.com/virdant-lang/virdant
$ cd virdant
$ make install

This will build Virdant from source (in release mode) and then copy everything to $HOME/.local/virdant.

Warning

You will need to add $HOME/.local/virdant/bin to your $PATH! If you forget, you’ll see vir: command not found.

Running Hello World

Create a new Virdant project by running:

console

$ vir new hello
$ cd hello

Next, we can run our project in the Virdant simulator.

console

$ vir run
Hello, world!

Oh! Why hello, Virdant!

What Virdant Looks Like

Next, let’s just glance at the source code. Open the file src/top.vir in the hello project you just created. You will see our hello world design.

Note

In software, you may be used to talking about your “program”. But in hardware, we call them “designs”.

And rather than a function called main, as you might be used to in programming, the entry point to a hardware design is traditionally a module called Top

We won’t worry about how any of this works for now. The guide will teach you from scratch. Just get a feel for what Virdant looks like:

src/top.vir

//! Hello World!

// Import the `virt` package
// This gives us the `Virt` platform and the `Hello` module.
import virt

//> `Top` is the top module (`mod`) and entry point to your design.
//>
//> It is public (`pub`) and it targets `Virt`, the virtual Virdant platform.
pub mod Top for virt::Virt {
    //> `clock` is the system clock
    @frequency("1 MHz")
    incoming clock : Clock

    //> `tx` is the UART data transmit line.
    //> It's used for printing things to the terminal.
    outgoing tx : Bit

    //> `exit` determines when to exit and with what return code.
    outgoing exit : Valid[Word[8]]

    //> `hello` is a submodule which instantiates
    //> the `Hello` module from the `virt` package.
    //> It contains all the logic to print "Hello, world!" to the screen.
    mod hello of virt::Hello {
        it.clock := clock
        tx       := it.tx
        exit     := it.exit
    }
}

Compiling to Verilog

You can compile Virdant to Verilog with the following:

console

$ vir build

We won’t be using this feature for now. But I’ll mention it for those who are experienced with hardware design.