Cebollita Toolset Tutorial Last modified: February 01, 2006

CSE Home

About Us

Search

Contact Info

Introduction

This document provides a simple tutorial for the Cebollita toolset and application build process. It describes how to compile/assemble/link and run using the software simulator, doing this manually. The set of Makefile's distributed with Cebollita automate this process, and involve less typing at the cost of some additional reading: this page describes the process.

More details on the tools described here are available in the Cebollita Tools User Guide.

Note: A version of this file exists in the distribution as cebollita/apps/tests/helloworld.c. In that directory, make for-iolib-ceb followed by make helloworld will build helloworld.exe. java dbg.UI helloworld.exe will run it. The same sequence of commands will work in the myPrograms directory as well, once you have made a minor edit to the Makefile there and created helloworld.c.

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 C-- Language Specification .

Now compile the program:

$ java comp.parser helloworld.c

The above step translated your C-- source code to Cebollita assembly code. You might want to have a look at the file that was created. If all went well, it should be called helloworld.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();

The I/O library comes in a number of varieties, depending on the build target. The source code for it is in cebollita/apps/iolibs/.

Assembling

Next, you'll have to translate the Cebollita assembly code produced by the compiler to object code.

$ java asm.Asm helloworld.s

This should have produced file helloworld.o. For more information on the assmebler, see the Cebollita Assembler Specification.

Linking

To build an executable, you'll have to link together various required modules. Which these are depends on the environment in which you want your program to run: standalone, with the I/O library using system calls to the Cebollita software syscall call handler, or with the Cebollita operating system. The most common case is with the second above, and is the one shown here.

There are three modules required: helloworld.o, cebollita/apps/iolibs/iolib.o, and cebollita/apps/prologues/prologue-iolib-ceb.o. The following invocation should do the trick, assuming you're in directory cebollita/apps/myPrograms:

$ java asm.Linker --output helloworld.exe ../prologues/prologue-iolib-ceb.o helloworld.o ../iolibs/iolib.o

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

Running Your Program

To run your program, you'll need a simulated Cebollita machine, which is also provided by the Cebollita toolset. You have to indicate the configuration under which you want to run, as arguments. Run your program like this:

$ java dbg.UI helloworld.exe

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 ISA 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:

$ java asm.Module helloworld.o

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

$ java util.Exe helloworld.exe

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));
}

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 and use the Makefile's to automate these steps as needed. We prefer the latter approach, and in fact Cebollita ships with a Makefile infrastructure that you can look at to get you started down this path. (These are production Makefile's, though, and are not the gentlest introduction to make.)

Department of Computer Science & Engineering University of Washington Box 352350 Seattle, WA  98195-2350 (206) 543-1695 voice, (206) 543-2969 FAX [comments to zahorjan@cs.washington.edu]