Relearning MSX #8: Setting up the MSX-C environment (part 4)
Posted by Javi Lavandeira 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
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
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.
great, thanks!
Hi, great tuto. How do I type { and } in the emulated keyboard?
Thanks
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?
I don’t seem to be able to make those { } characters inside openMsx. Is there some trick? Shift+square bracket doesn’t work. nor any other combination i tryed
What MSX machine are you emulating? And what keyboard does your computer have?
I’m emulating the Panasonic_FS-A1GT, my pc has a standard european keyboard.
I worked around it by pressing F10 to bring up the console and entering: type “{”
Thanks :)
Thanks Javi, great stuff! Thanks to you I just compiled my first C program in MSX!
I’m following, using blueMSX. Everything is working fine here. Wowful Tutorial!
Thanks for all these fun!
ありがとうございます。! (Japanese material are awsome too!)
Yes, these Japanese manuals are fantastic. The documentation we had in Europe back in the day was nowhere as good.
I am enjoying as a child with a new toy. Well documented!
Great, thanks Javi.
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.