Relearning MSX #13: MSX-C commands: CF.COM
Posted by Javi Lavandeira in How-to, MSX, Retro, Technology | February 13, 2015It’s been a while since the last post in this series. At the end of the previous chapter we had a working installation of MSX-C Ver 1.2 with the MSX-C Library package.
Today’s post and the few that follow are a lot more technical. What comes now is a detailed description of the command line programs that compose the MSX-C compiler. The purpose is to allow users who already have some experience programming in C to dive deeper into software development in the MSX platform. If you’re new to compilers and the C language then this probably won’t make much sense yet, and that’s ok. We’ll go back to the basics after explaining these tools.
The information here comes from the books MSX-C Ver.1.2 User’s Manual and the Introduction to MSX-C (MSX-C入門上巻）, both by ASCII Corporation.
MSX-C Ver.1.2 package and the Introduction to MSX-C book
CF.COM : Preprocessor and syntactic analyzer
MSX-C is a two-pass compiler. The CF program is the first pass: it processes all the #include, #define and #pragma preprocessor directives in the source code, then examines the code to ensure it is syntactically correct (that the program is valid C code), and generates a .TCO file containing intermediate code for CG.COM to use.
CF.COM’s command line options
CF.COM has several command line options:
-c
Disables comment nesting. By default MSX-C allows to insert comments inside comments, but this is not part of standard C. Adding this command line switch enables the standard behaviour. Consider the following program:
1.c : Nested comments in MSX-C
This program has three comments:
- Comment #1 will never cause an error because it doesn’t have nested comments
- Comment #2 has another comment inside it (comment #3). This can happen if you comment out blocks of code in order to disable parts of your program.
- Comment #3 is a valid comment by itself, but it is nested inside comment #2
MSX-C doesn’t by default consider nested comments to be an error, and CF will process this program fine:
Use the -c command line option when you want nested comments to return a compile error:
-e [filename]
This command line option causes CF to output error messages to a file on disk. The filename is optional. If you don’t especify a filename then it will generate a diagnostics file with the same name as the source code file, but with the .DIA extension:
CF.COM -e option
You can also especify any filename with any extension:
CF.COM -e option with a filename
This command line option is useful if you’re using a batch file to compile a big program composed of many source files. It allows you to see what errors CF found in each file. In this case it’s better not to especify a filename, because CF overwrites the diagnostics file each time it runs.
-f
In standard C undeclared functions and function parameters are by default of type int, but MSX-C doesn’t allow these to be undeclared. This command line option enables the standard behaviour.
To see how it works, consider the following program:
2.c : program with an undeclared function
In the printf(…) line the program calls a function called whatever() that hasn’t been defined anywhere. Under standard C this is legal, and the compiler would assume that this function requires an integer parameter and it also returns an integer. However, in MSX-C undeclared functions and parameters are not allowed:
CF finds an undeclared function and returns an error
Adding the command line option -f causes CF to accept undeclared functions and parameters without complaining:
CF accepts undeclared functions with the -f command line option
Use this option only when compiling code ported from another platform, and only if you really really know what you’re doing.
-j
This command line option enables support for kanji in text strings. Consider the following program:
Kanji characters inside a string
The character string passed to the printf() function contains multibyte characters. Depending on the characters used this program may or may not compile. The -j option ensures that CF will process multibyte characters properly.
On the other hand, this option is incompatible with source files that contain single-byte Japanese characters (hiragana).
You don’t need to worry about this unless you’re writing Japanese text in your program.
-o
By default CF will create the intermediate code file (.TCO) in the same directory as the source file. This command line option allows you to especify a different file name or location. Let’s see a couple of examples.
Example 1) Processing the file 1.c and saving the intermediate code file (1.tco) in the H: drive:
cf -oH: 1
The screenshot below illustrates this:
MSX-C CF -o option (different drive)
Example 2) Processing the file 1.c and saving the intermediate code in the same directory as the source, but under a different file name:
cf -otest 1
MSX-C CF -o option (different file name)
This is useful if we want to optimize the compile process by creating the intermediate code files in a RAM disk, or maybe a dedicated directory.
-rP:S:H
CF keeps several tables in memory to store function and variable names. If the file we’re processing is big then CF may run out of space in these tables. A good example of this is the DEN.C demo program included in the MSX-C Library disk:
Preprocessing of the DEN.C program failed. Symbol table is full.
In this example, CF failed while preprocessing the B:\INCLUDE\CURSES.H file (included by DEN.C). The error message explains that the symbol table filled up, and CF prints the status of its internal tables.
In this command line option, the values P:S:H represent the ratio of how much of its memory CF assigns to the pool, symbol and hash tables, respectively. The default values are 13:6:4.
If the preprocessing fails then try increasing the ratio of the table that was too small, or decrease the size of the other tables. For example, preprocessing the DEN.C program works fine with -r5:5:2:
CF processing the DEN.C file with -r5:5:2
-m
Causes CF to print the status of the pool, symbol and hash tables after successfully processing a source code file. This is mostly for informational purposes:
CF printing memory usage information
-s
Bigger programs are usually written in several source code files. Instead of compiling them one by one, we will write a batch file to process them at the same time. Normally CF will abort further processing of the batch if it finds an error:
CF aborts the COMPILE.BAT batch file before processing 2.C
In this example CF aborted COMPILE.BAT because it found an error in the file ERROR.C, and it completely ignored the 2.C file.
The -s command line option tells CF not to abort the execution of batch files when it encounters an error:
CF continues execution of the batch file
This is useful when using batch files to compile several files at the same time.
-t
Adding this option to the command line allows MSX-C to perform automatic type conversion between integers and pointers.
For example, consider this short program:
Sample program that adds an integer to a pointer
In this example, str is a pointer to char. Trying to add an integer number to it without using a cast will by default result in a compilation error. The -t option tells the compiler to automatically convert pointers to integers in these cases:
Automatic type conversion enabled (pointer integer)
The MSX-C manual discourages using the -t and -f options. Use them only during development while porting C programs from another platforms.
In the next post…
The next two posts will explain the two other MSX-C programs: FPC (function parameter checker) and CG (code generator).
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
Pingback: Relearning MSX #13: MSX-C commands: CF.COM | Vintage is the New Old
Qué tal Javi, he vuelto a leerme este capítulo pero no encuentro lo que busco, a ver si por un casual el compilador de MSX-C lo permite. ¿Hay alguna forma de decirle al compilador que reserve un rango de memoria determinado?
No hablo de la función malloc, que reserva dinámicamente, sino directivas de compilador, algo así como decirle “de la A000 a la AFFF déjala libre”.
Muchas gracias.