lavandeira.net

(This is another looooong post. Be sure to click the “Read more” button if you’re previewing this post from the blog summary.)

By the end of the previous post we had MSX-DOS2 and MSX-DOS2 TOOLS installed on an MSX with a hard drive. So far everything is installed in drive A:, the first partition in the hard drive.

In this post we’ll proceed to install ASCII’s MSX-C v1.2. We’ll copy some utilities to the A: drive for convenience, but we will use the B: drive for all the compile environment.

Let’s get started.

MSX-C versions

ASCII released two versions of the MSX-C compiler:

• MSX-C v1.1: runs under either MSX-DOS or MSX-DOS2 and generates code that also works on either operating system, but doesn’t have support for MSX-DOS2 functionality
• MSX-C v1.2: runs on MSX-DOS2, and generates MSX-DOS2 applications, and has full MSX-DOS2 support

We will be using MSX-C v1.2.

MSX-C disk contents

First of all go to The MSX Archive and download the MSX-C v1.20 disk:

MSX-C_v1.2.zip (111 KB)

Extract the disk image from the archive. If you’re using a real MSX then write it to a floppy disk. If you’re using openMSX then save the disk image to your Disks folder and insert it in the emulated FS-A1GT.

Looking at the contents of the disk we see a bunch of programs at the root level: CF.COM, CG.COM, FPC.COM and MX.COM. These are all components of the MSX-C compiler.

There are also a few .REL files: CK.REL, CLIB.REL, CRUN.REL and CEND.REL. These four are the relocatable libraries that contain the C functions for our programs. There’s also a file called LIB.TCO that we’ll talk about later.

Lastly, we see the following directories:

• BATCH: Contains a few .BAT files to rebuild the C libraries, set up environment variables, etc. We won’t touch these files for now.
• INCLUDE: Contains the C header files. We will use these ALL THE TIME.
• SAMPLE: A few sample programs.
• SRC: The source code in C and Z80 assembler for all the library functions and the C kernel, in case you want to modify or extend them.

We’ll ignore the C.BAT file for now. This file automates the compile process, but we’ll make our own later.

Installation

The installation process is simple, but let’s be careful and make sure  we put everything in the right place. In our installation we’ll follow the this convention:

• A:\UTILS : Compiler components and batch files, because this directory is already in our environment’s PATH
• B:\INCLUDE : All the C header files
• B:\LIB : All the library (.REL) files

Run these commands to install the files:

MKDIR B:¥INCLUDE
MKDIR B:¥LIB
COPY F:¥*.COM A:¥UTILS
COPY F:¥INCLUDE¥*.* B:¥INCLUDE
COPY F:¥*.REL B:¥LIB
COPY F:¥*.TCO A:¥UTILS

At this point MSX-C is installed. We can compile C programs by running each of the compiler’s components one by one. This is a pain in the ass, so later we’ll make a batch file to help us with this process. Now we’ll compile a simple program by hand in order to confirm that everything works as expected.

Prepare a simple C program

First we’ll write a Hello World! program using the AKID text editor. I haven’t explained how to use AKID yet, so for now just follow these steps:

1) Change to the B: drive (just type B: at the MSX-DOS2 prompt)

2) Enter the following command to create and edit a text file named HELLO.C in AKID

  AKID HELLO.C

3) Type this program in AKID:

#include <stdio.h>

main()
{
        printf("Hello, MSX world!¥n");
}

4) Exit AKID saving the file (press F1, then E)

At this point we have a HELLO.C file in the root of the B: drive:

Compile time!

First of all, we have to tell the compiler where to find the header files. We do this via the INCLUDE environment variable. Run this command to point to the location of our INCLUDE directory (if you’re using a different location then remember to point it to the right location on your hard drive):

SET INCLUDE=B:¥INCLUDE

First step: parser

The first step in the compile process is the parser. CF.COM handles this step. Run CF.COM with the name of our program, without the .C extension:

CF HELLO

If there are no errors this will generate a HELLO.TCO file. If there’s a problem with the source code the parser will return an error message explaining the issue. If that’s the case, confirm that the environment variables are set up correctly and that the source code matches the code above. Make sure the function names are lowercase, because (unlike MSX BASIC) C distinguishes between upper and lowercase.

If you want, feel free to take a look at the contents of HELLO.TCO. It’s just a plain text file, but the contents aren’t intended to be human-readable. This is known as T-code, an intermediate form of our C program, converted to a format that is easy for the compiler to understand and generate code from.

 Second step: code generator

Next, we’ll run CG.COM with the same parameter . This will read the HELLO.TCO file and generate the Z80 assembler version of our program:

CG HELLO

After the copyright notice, CG lists all the functions in the source file as it compiles. In this case we have a very simple program with only one function, main(), so that’s the only one listed.

Now we see that there’s a new file, HELLO.MAC. This is the Z80 assembler version of our program:

Third step: assemble

Now that we have the Z80 assembler code for our program, we need to assemble. Microsoft’s M80 (part of MSX-DOS2 TOOLS) is responsible for this task. Please note that the original M80/L80 /LIB80/CREF80 suite is really, really old and predates MSX computers (if you’re curious, here‘s a manual from 1981). The versions included in MSX-DOS2 TOOLS are not these original versions, but newer versions developed especifically for MSX-DOS2 by Microsoft in 1989.

Run M80 like this to assemble the HELLO.MAC file (I’ll go over the parameters in another post, but we don’t need to go very deep into these details in order to code in C):

M80 =HELLO/Z

This will generate a new HELLO.REL file which contains an assembled relocatable code. Later we’ll see what this means. If you look at your B: drive now you should have the following files:

Fourth (and last) step: link

The last step in the compile process is linking. This means that we take the assembled code for our program (in this case, HELLO.REL) and we join it together with other parts of the MSX-C runtime. Those are the bits of code that check for command line parameters, open the default files, etc. We also have to add the code for the library functions that we used, in this case, printf().

Microsoft’s L80 does all this. Run it with the following command (which I’ll explain in another post):

L80 B:¥LIB¥CK,HELLO,B:¥LIB¥CLIB/S,B:¥LIB¥CRUN/S,B:¥LIB¥CEND,HELLO/N/E

Yes, I know. That’s a lot of typing C:\LIB\. Later we will prepare a batch file to handle all of this for us, so we won’t have to deal with these annoying details. For now, type this command just this time to confirm that it works.

If you didn’t make any mistakes (I’ll forgive you if you did), then now you should have a nice, shiny HELLO.COM program sitting in your B: drive:

The file is huge (3.5 KB!) because it contains all the initialization code for the C runtime. This is completely normal.

Try running the program now, and you should see it greet you:

There you have it. Our first C program compiled with ASCII’s MSX-C compiler. If you had any problem whatsoever following these steps, just post in the comments below and we’ll try and sort it out.

Next steps

There’s one extra compiler step that I left out intentionally: FPC.COM. This is the Function Parameter Checker. It checks the TCO file against the MSX-C library to check that we didn’t give the wrong parameters to a function. We’ll incorporate it into our batch files in another post.

We now have a functional compiler, but it’s still very limited. There’s limited support for MSX graphics or sound, and numeric data types aren’t powerful enough for some programs.

We will take care of these problems in the next post by installing the MSX-C Library package. After that, we will prepare a batch file to automate the compilation/assembling/linking so we won’t have to type lots of boring commands every time we want to compile a program.

---

This series of articles is supported by your donations. If you’re willing and able to donate, please visit the link below to register a small pledge. Every little amount helps.

Javi Lavandeira’s Patreon page