Compiler setup

==============

Before using the compiler, you need to compile the compiler itself:

1.  Install the software necessary to build the compiler.  (This

    includes a Linux- or UNIX-like environment; you can use Cygwin on

    Windows.  It also requires an installation of OCaml.)

2.  Change to the main compiler directory (the directory containing

    README and Makefile).

3.  Use the `make` command to build the compiler:

        make

Using the interpreter

=====================

You can use the interpreter to run Verity progams directly, without

compiling them.

1.  Find a Verity program you want to interpret it (either write one,

    or look in the "examples" directory for some examples).  It need

    not be in the main compiler directory.

2.  The interpreter does not yet support libraries, so you must first

    remove or comment out any library calls (e.g. "print" statements)

    in the file you want to interpret (and alter the progam to return

    a value, if you want output out of it).

3.  Change to the main compiler directory.

4.  Use the `./gosi` command, giving it the path to the file you want

    to interpret as an argument:

        ./gosi examples/your_modified_file.ia

5.  The interpreter will output the final result of the program.

Compiling to hardware descriptions

==================================

The main purpose of the gosc compiler is to produce hardware

descriptions, that can be simulated, or (using other tools)

automatically synthesized into appropriate hardware.

Compiling for simulation

------------------------

1.  Find a Verity program you want to compile (either writing one, or

    using one of the provided examples in the examples/ directory).

2.  Change to the main compiler directory.

3.  Use the `./gosc` command to compile the program into VHDL:

    *   Use the `-m sim` switch to specify compiling for simulation.

    *   Use the `-o` switch to specify the filename of the generated

        linking file.

    *   If using GHDL as your simulator, use the `-l ghdl-fix` option

        to work around a bug in GHDL.  (You don't need this option

        with other simulators.)

    *   You might also want to use the `-v` option for the compiler to

        tell you what it is doing.

    A sample compilation command would look like this:

        ./gosc -m sim -l ghdl-fix -o /tmp/t.vhd examples/fibonacci-memoized.ia

    The compiler will compile the file given if it's never been

    compiled or is out of date, and any dependencies of it that are

    out of date, and list the resulting list of files that need to be

    used as input to your simulator:

        Use the following files as input to your simulation/synthesis tool:

        ./lib/constants.vhd

        tests/fibonacci-memoized.vhd

        ./include/ghdl-fix.vhd

        ./lib/sim/print.vhd

        /tmp/t.vhd

        ./lib/sim/toplevel.vhd

    Note that with many simulators, the order is significant.

4.  Give the resulting files as input to your simulator.  (Your

    simulator will also need to know the name of the top-level entity;

    for `-m sim`, unless your code imports platform-specific

    libraries that have their own simulation top-level entities, it

    will be called `work.simulation_toplevel`.)

    To do this in GHDL:

    1.  Analyze the files, by passing them to `ghdl -a` in the order

        listed.  You will also need to link in the IEEE libraries, for

        instance with the option `--ieee=synopsys`:

            ghdl -a --ieee=synopsys lib/constants.vhd tests/fibonacci-memoized.vhd include/ghdl-fix.vhd lib/sim/print.vhd a.vhd lib/sim/toplevel.vhd

    2.  Elaborate the files, by using `ghdl -e` and the name of the

        top-level entity, `simulation_toplevel`:

            ghdl -e --ieee=synopsys simulation_toplevel

    3.  Run the resulting simulation:

    

            ./simulation_toplevel

            

    To do this in ModelSim:

    

    1.  Open ModelSim.

    

    2.  Create a new project, and add the files listed by the compiler

        to it, in the order given.  (ModelSim cares about the order;

        if the files are added in the wrong order, you can change it

        via the "Compilation" right-click option on the list of

        files.)

    

    3.  Choose the `Compile All` option from the right-click menu on

        the file list.  (ModelSim might not seem to react to this

        immediately; look at the progress bar at the bottom of the

        screen to see its progress.)

        

    4.  Start the simulation (via the menu), choosing

        `work.simulation_toplevel` as the top-level entity.

        

    5.  Run the simulation.  (If your program terminates, it should

        work fine with no time limit.)

    

    The simulation will run.  If you imported the `<print>` library,

    then print statements in your code will produce output in the

    simulator's output window (standard output for GHDL, at the pane

    at the bottom of the screen for ModelSim).  Note that you might

    get warnings during the first 10 nanoseconds of simulated time;

    this is because the code is simulating a reset.  Additionally,

    code that uses the `<print>` library will halt the simulation when

    the code exits via asserting a failure (so if you see a "failure"

    message, it means your program terminated).

    

Compiling for synthesis, on an already supported architecture

-------------------------------------------------------------

Synthesizing a Verity program into hardware requires the use of

appropriate libraries in the hardware for communicating with the

hardware, and an appropriate synthesis tool.  So far, `gosc` has been

tested only in conjunction with the Quartus II tool by Altera,

although the process should be similar with other manufacturers.

This example uses the DE2-115 Development and Education board by

terasIC and Altera, for which drivers for some of the functionality

are provided in the `lib` and `include` directories.

1.  Find a Verity program you want to compile (either writing one, or

    using one of the provided examples in the examples/ directory).

    There may be translations of standard libraries for your platform

    (e.g. `<print>` exists for the DE2-115, and outputs the number

    given in hexadecimal on its seven-segment displays); but you will

    need to use a platform-specific library (e.g. `<de2>`) to take

    full advantage of the hardware.

2.  Create a new directory to use for the Quartus project.

3.  Change to the main compiler directory.

4.  Use the `./gosc` command to compile the program into VHDL:

    *   Use the `-m` switch to specify the architecture you are

        targeting (e.g. `-m de2`).

    *   Use the `-o` switch to specify the filename of the generated

        linking file.  (You probably want to put it in your new

        directory, but we'll use `tmp/t.vhd` in this example.)

    *   You might also want to use the `-v` option for the compiler to

        tell you what it is doing.

    A sample compilation command would look like this:

        ./gosc -m de2 -o /tmp/t.vhd examples/fibonacci-memoized.ia

    The compiler will compile the file given if it's never been

    compiled or is out of date, and any dependencies of it that are

    out of date, and list the resulting list of files that need to be

    used as input to your synthesis tool:

        Use the following files as input to your simulation/synthesis tool:

        ./lib/constants.vhd

        example/fib.vhd

        ./include/de2/print.vhd

        ./include/de2.vhd

        /tmp/t.vhd

        ./lib/de2/toplevel.v

    With some synthesis tools, the order is significant, but Quartus II

    is capable of inferring it.

5.  Start the DE2 System Builder tool (that generates Quartus II

    projects for use with the DE2-115 board.)

    

6.  For the libraries provided with the compiler, use the following

    configuration: disable all the checkbox options apart from Clock,

    Button x 4, 7-Segment x 8, Switch x 18, and leave all the other

    options at their defaults.

7.  Use the "generate" button, and place the generated project file in

    your new directory.  (You can close the system builder tool at

    this point.)

8.  Open your generated project file in Quartus II (by double-clicking

    on it, while Quartus II is closed, not from within Quartus II).

9.  Add the files mentioned by `gosc` above to your project.

10. In order for the entities in the files you just added to show up

    within Quartus II, run "Partition Merge" from the list in the

    sidebar.  (You're likely to get many warnings, because Quartus

    will be trying to compile the wrong top-level entity, but this is

    necessary before the top-level entity can be set.)

11. Set the top-level entity to `DE2_button_switch_7seg` (the

    top-level entity setting in Quartus is a little hard to find;

    right-click the device in the "hierarchy" tab, choose

    "settings...", then select general, then select the "..." next to

    the "Top-level entity" checkbox, and choose the entity from the

    resulting list).

12. Run "Fitter (Place and Route)" from the list in the sidebar.

13. Run "Assembler" from the list in the sidebar.

14. Connect the DE2-115 board to your computer (use a USB cable

    between your computer's USB port and the board's "BLASTER" port).

15. Run "Program Device" from the list in the sidebar.

16. Click the "Start" button in the programmer.

This should program the board with your program. To use it, press KEY3

on the board (which is mapped to the reset input); the program will

start running as soon as you release it.