Blog

Relearning MSX #8: Setting up the MSX-C environment (part 4)

Posted by in How-to, MSX, Retro, Technology | January 05, 2015

(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

msx_magazine_1988-04_msx-c_ad

MSX-C v1.1 ad. MSX Magazine (April 1988). Click to enlarge.

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.

MSX-C_v1.2_disk_contents

Contents of the MSX-C v1.20 disk

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.
MSX-C_v1.2_include

Header files in MSX~C v1.2

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:

MSX-C_hello_world

Hello World! in MSX-C

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.

MSX-C’s parser generates a T-code file

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:

MSX-C_cg_and_mac_file

HELLO.MAC file generated by MSX-C’s code generator

hello_mac_z80_assembler_version

Contents of HELLO.MAC. Z80 assembler code generated by CG.COM

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:

m80_assembling_MSX-C_code_and_rel_file

M80 compiled HELLO.MAC into HELLO.REL

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:

l80_linking_code_and_com_file

L80 linking everything together into our HELLO.COM program

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:

MSX-C_hello_world_running

Our first MSX-C program running

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

15 comments on “Relearning MSX #8: Setting up the MSX-C environment (part 4)

  1. wow, that’s great… just for fun: what do the hex numbers that appear at the end of the m80 command mean?

    great tutorials!!

    • It’s all in the MSX-DOS2 TOOLS manual, in the L80 chapter (page 215), but it’s in Japanese.

      The first name is the address of the first executable instruction in the program (0103h in this case). The first three bytes in the file are a jump to that address, but they don’t have to be.

      The next number is the last memory address of the program + 1.

      The last number is the size of the program in 256-byte pages.

    • Good question. I’m using a Japanese keyboard and the layout is the same as in the MSX turbo R. It’s the two keys immediately to the left of the RETURN key, while pressing SHIFT.

      SHIFT + [ = {
      SHIFT + ] = }

      What keyboard layout do you have? And what operating system are you using?

  2. Marcio Rezende on said:

    I’m following, using blueMSX. Everything is working fine here. Wowful Tutorial!
    Thanks for all these fun!

    ありがとうございます。! (Japanese material are awsome too!)

  3. Tiago Rocha on said:

    Hi

    I am totally new on MSX(and programming), never knew that it even existed about 2 months ago, but I am already 100% in loved for it. It is amazing. I am now in a hard and long journey of knowing/reading everything about MSX. It’s so cool! Discovering everything for the first time. :)

    Your tutorials are EXCELLENT! I have 1 question.

    How could I program games for MSX in a modern environment(outside the MSX emulator)? Example: using a “sublime text” + a test console.

    I am asking if there a easy way to create MSX games.

    thanks

    • Hi Tiago, sorry it took so long to reply. I don’t look at these messages often lately.

      Yes, you can cross-compile on a PC using Windows or Linux. Maybe even on a Mac if you prepare the environment. Most people use the SDCC compiler (http://sdcc.sourceforge.net), but please note that the syntax and libraries are different from the ones in MSX-C.

      If you’re a bit creative then you can also write a script that takes your Sublime Text input, copies it into an openMSX instance and compiles it, but that would take a little bit of tinkering with parameters.

Leave a Reply

Your email address will not be published. Required fields are marked *


Warning: Illegal string offset 'share_counts' in /www/javi_lavandeira/lavandeira.net/ftproot/htdocs/wp-content/plugins/simple-social-buttons/simple-social-buttons.php on line 477