[Coco] Assemblers' Documentation

[Lothan]

From: Stephen H. Fischer

>In my thread about the "C" Compiler I say nothing about why RMA and RLINK
>were created.
>Because I do not have that information.
>
>I wondered the other day and looked at the documentation for "OS-9 Level II
>Development System and Tech Reference - Tandy (1987)" and other than
>becoming so sick upon reading about Scred that I added a thread for 
>Colorful
>SLED, the exercise was unrewarded.  I could not see any reason given for
>their creation.
>
>What was added to change c.asm and c.link into RMA and RLINK must be for
>assembly programmers only.
>
>Can you or anyone help me add to the "C" Compiler thread to explain why.

I think it makes a lot more sense if you consider it from the perspective of 
the C compiler and the need for a more modular source code layout. The first 
issue is that the C compiler needs to compile individual C sources into 
their equivalent assembly source file and then assemble all these files into 
a single executable. You can do this with asm, but it's awkward from the 
compiler perspective. The basic premise of asm is that you assemble a 
collection of assembly source files (and perhaps a set of includes like 
OS9Defs) into a single executable:

asm file1.asm file2.asm -o=/dd/cmds/file

The other issue is that the K&R C standard at the time included a 
specification for a common C library and asm doesn't support libraries. The 
best Microware could have done would be include the library source code on 
disk and then try to assemble it all together. The disadvantage is that 
there isn't enough space on the command line to support this with asm:

asm compiled1.asm compile2.asm /lib/fopen.asm /lib/fread.asm /lib/fwrite.asm 
...

A theoretical way around the command line limitation would be say bundle all 
the standard I/O code (fopen, fread, fwrite, fclose, fprintf, fscanf, and a 
bunch of other stuff) into one assembly file. The disadvantage here is that 
now your executable includes a ton of stuff you don't use.

In my opinion, asm just doesn't cut the mustard for use by a C compiler even 
back in the '80s. It's a fine assembler, but it's just not designed to 
handle high-level languages.

The real advantage with c.asm (RMA) and c.link (RLink) is that they are 
designed to support multiple source files and libraries in such a way that 
RLink can pick and choose the appropriate dependencies from a library file 
without pulling in stuff you don't use. This is because the generated object 
files contains a list of symbols (external dependencies) that the assembler 
couldn't resolve.

rma file1.asm -o=file1.obj
rma file2.asm -o=file2.obj
rlink file1.obj file2.obj -l=/dd/lib/stdlib.lib -o=/dd/cmds/file

The command line seems pretty simple, but it hides a lot of complexity. 
Think about when you compile file1.c into file1.asm and then assemble this 
into file1.obj. Your code may need say printf, fopen, and fread. When RMA 
assembles the code into an object file, it resolves all symbols that it can 
and then creates a table of unresolved symbols. When RLink links everything 
together, it goes through the library file(s) trying to find object files 
containing these symbols. In turn, the object files in the library itself 
may have external dependencies that need to be resolved (say printf needs 
ltoa to convert a number into a string).

RMA is also a macro assembler, meaning that you can define common code or 
data structures as a macro and reuse them just by referencing the name of 
the macro.

This is by no means to say that asm is a bad or inferior assembler. It's 
really that asm and RMA are two completely different assemblers with 
completely different design goals. I think asm is the easier and more 
straight-forward of the two whereas RMA offers a lot of features and power 
that isn't available with asm.