Assignment 1 -- Design, develop, and deliver a translator for the SIC/EM

There is now a list of questions and answers about the assignment.

Project Deadline: Feb. 26, 2003

Turn In

You shall turn in your assignment by sending an email to me from your class account, with your class account as the subject line. The contents of the email shall contain the names and corresponding class accounts for each member of your team, and the CVSROOT for your repository. The module name shall be "as1".

You may develop your project on any machine/OS/architecture you desire; however, on delivery, the code must checkout, compile, and run on rohan.

• You may work in teams of up to two people.
• You must inform me of the fact that you are working in a team.
• Collaboration between teams and sharing of files between teams is prohibited. Evidence of collaboration between teams (or outsiders) for this assignment is grounds for expulsion from SDSU. Exceptions are:
  • Things discussed publically with me in class are okay.
  • High-level discussions between teams are probably safe. No code, nothing in writing. You are welcome to show me early results to see if I think the similiarities are unacceptable (note that this doesn't help much late in the development life cycle of the assignment).
  • You are expected to collaborate with your teammate.
• The identity of the team members shall appear at the top of every file, along with the course name, due date, instructor name, and file name.

Assignment

The program you shall develop is the first pass of a two-pass absolute assembler for a SIC/XE subset computer and the intermediate file format it produces. See the SIC/EM (SIC - Economy Model) specification for a detailed "user manual". (This assembler uses a heavily-modified variant of the syntax described in the text.) You may develop your code using C or Java, provided you are using the same version as found on rohan. You may not use any non-standard/third-party libraries without prior approval by me, aside from those found in the /opt or /usr/local directories on rohan. When in doubt, ask.

You shall develop a text file called README. The README file shall be a flat-ASCII text file that contains (in addition to the required information specified above):

• A listing of all files in the project, and a one-sentence description of their purpose
• Instructions on how to compile and run the program
• Program inputs and outputs
• A description of the organization of your program
• Lessons learned and significant findings

In addition, you shall have a file called gradernotes, a flat-ASCII text file that contains (in addition to the required information specified above):

• Issues (functionality not implemented, potential errors, limitations/assumptions)
• Anything else you want me to know before I start grading your program
• A statement of the form:
  I/We believe that (with the preceding caveats) my/our program works correctly in every way.

Both of these files shall reside in the top-level directory of your as1 module.

Here are some details about how you should do the project. Many, if not most, of these decisions are the sort that should be made by the designer, and not the customer. Frequently, what I ask for may not be the best choice -- you may want to think about the pros and cons of my choices. If you find anything that seems inconsistent or unreasonable in the specification, please let me know.

This version of the translator does not produce any source code files or object files. All output will be to stdout. The output shall be well organized, printable, and readable.

If there are any errors in the user-supplied input, you are expected to identify the error and print out an error message as a result of processing that input. Helpful error messages are to be preferred.

The output will be the location counter, an intermediate code format and a symbol table. Part of your assignment is to design an intermediate code format. The requirements for your intermediate code format are:

1. The intermediate code shall be printable
2. Each line of the intermediate code shall begin with the source-line number of the code that generated the line of intermediate code. The line numbers shall be decimal.
3. Each source line in the assembler input shall output one and only one line of intermediate code
4. The intermediate code should show the complete object code except for those data that depend on a knowledge of the value of user symbols.
5. Numeric data (except for source-line numbers) shall be in hex.

[The goal is to make the intermediate code so simple that the second pass of the assembler will not have to know any machine mnemonics or assembler directives. The second pass can simply look at the user symbol table produced by the first pass and the intermediate code, and produce final object code. If a listing was required, pass 2 could use the original source and line numbers in the intermediate code to produce a listing at the same time.]

Your program should only look at each line of source just once. You are not allowed to keep copies of source lines in memory once they have been processed, or to "look ahead" in the source file.

You may not write to any intermediate file while running your program. You may read in data files used by your assembler (such as a symbol table), but all files other than the one specified on the command line that you read must be documented, in the CVS repository, and be a text file.

You must use the Concurrent Version System (CVS) to manage the stages of all of your source files. It's important to use the documentation services that CVS provides. I will try to set up a lab session in order to discuss CVS in class and to provide hands-on experience and guidance. At no time should any of your files be world-readable. If you are not working on a team, then none of your files should ever be group-readable either; if you are working on a team, then all files should be owned by the team group (I will be arranging and will inform you when it's ready).

Given the CVSROOT you specify (say, in a variable $CVSROOT), I should be able to check out your module with:

   cvs -d $CVSROOT checkout as1

Java Developers

You may develop this program in a single (default) package, or you may use the Java-standard package hierarchy approach. If you do the latter, your packages shall reside under edu.sdsu.cs530s2.

If you are using Ant, the name of the buildfile shall be "build.xml", and the default target should be to compile all of your code, and be named "code". You should have two additional targets, "clean" and "jar". The clean target should delete all generated .class and .jar files. The jar target should depend on the code target, and should generate a file named "as1.jar", that can be invoked with:

	java -jar as1.jar filename

Here is what a build.xml file looks like.

If you choose not to use Ant, then you should use make, and the name of your makefile should be "Makefile". The default (first) target should compile all of your code, and be named "code". You should have two additional targets, "clean" and "jar", that behave as do the Ant targets of the same name. You may have as many additional targets as you feel necessary.

C Developers

You should develop this program in the module, without using any subdirectories. You shall have a makefile named "Makefile", which should have two primary targets: "all" (the first target in the makefile) and "clean" (the last target in the makefile). The "all" target should compile all of your code and leave an executable named "as1" in the current directory that can be run with:

	./as1 filename

Here is an example Makefile.