Cebollita Toolset Tutorial

Introduction and Overview

This document provides a simple tutorial for using the Cebollita toolset. Related documents:

Compiling

Start by writing a simple C-- program. Something like this might do the trick:

// My first program
void main() {
  printString("Hello world.\n");
}

The Cebollita compiler compiles a language called C--. Not suprisingly, C-- looks a lot like C. Roughly speaking, C-- is a subset of the C programming language. For more details on what you can and can't do with C--, see the specification.

Now compile the program:

prompt %java comp.Scc hello.c

The above step translated your C-- source code to MIPS assembly code. You might want to have a look at the file that was created. If all went well, it should be called hello.s.

A Note about I/O

C-- doesn't provide any "built in" I/O functions, so it must be accomplished via normal procedure calls (as in C). To save you the work of doing this yourself, the toolset comes with source code that implements a really simple set of I/O functions. In brief, here are the signatures of the I/O functions we provide:

void printString(char* str);

void printInt(int x);

int readString(char* buffer, int length);

int readInt();

You'll have to compile the source code for this module (currently it lives in the tests directory) as well:

prompt %java comp.Scc tests/iolib.c

Assembling

Next, you'll have to translate the MIPS assembly code produced by the compiler to object code. You'll also want to assemble a prologue file. Don't worry too much about it right now -- this file just does some basic setup stuff to kick off your program. The file is called tests/prologue.s

prompt %java asm.Asm hello.s
prompt %java asm.Asm tests/iolib.s
prompt %java asm.Asm tests/prologue.s

This should have produced three files: hello.o, tests/iolib.o, and tests/prologue.o. From now on, you should never have to recompile or reassemble the iolib or the prologue file, unless you feel compelled to change them for some reason.

Linking

To build an executable, you'll have to link together the various required modules. In this case, there are three: hello.o, tests/iolib.o, and tests/prologue.o. The following invocation should do the trick:

prompt %java asm.Linker tests/prologue.o hello.o tests/iolib.o

This should produce a file called a.out, your first Cebollita executable.

Running Your Program

To run your program, you'll need a simulated MIPS machine, which is also provided by the Cebollita toolset. Run your program like this:

prompt %java sim.UI a.out

A window should pop up and you can hit the run button. You should see the message printed to the console where you started the program. See the Cebollita MIPS Simulator document for more information on the simulator, and its console based cousin...

Utilities

Cebollita provides two utilities that are sometimes helpful or interesting. The first lets you inspect object modules:

prompt %java asm.Module hello.o

Try it. What do you see? The other utility lets you inspect whole executables:

prompt %java util.Exe a.out

Try it and have a look at the output.

What Next?

Try writing a more complicated program, like one with function calls:

int fib(int n) {
    printString("Calculating fib of: ");
    printInt(n);
    printString("\n");
  if (n == 1) {
    return 0;
  }
  if (n == 2) {
    return 1;
  }
  else {
    return fib(n-1) + fib(n-2);
  }
}

void main() {
  printInt(fib(6));
}

Rationale: A Note about the Toolset

Once you start writing more complicated Cebollita programs, you'll see that using the toolset can be a bit of a pain. Every time you change your code, you need to re-compile, re-assemble, and re-link your program. Wouldn't it be better if we had provided you with a "development environment" that would do this for you? We could have even called it VisualOnion or something trendy like that.

The answer is that the toolset was designed and presented to you in this manner to expose you to the things that are normally hidden by modern development environments. We wanted to make the steps taken en camera by integrated development environments explicit. We did it not to make life hard, but to help people learn things.

Obviously, the next step would be for you to (a) write your own simple development environment or (b) to learn a little about Makefiles to cobble together these steps as needed. We prefer the latter approach, and in fact Cebollita ships with a simple Makefile that you can look at to get you started down this path.