|
www.riscos.com Technical Support: |
CMHG (the C Module Header Generator) is a desktop tool which provides an easy interface to the CMHG program that Acorn C/C++ installs in your computer's library. The CMHG tool constructs command lines and passes them to the CMHG program. By using CMHG you can write a RISC OS relocatable module entirely in C without having to use ARM assembly language.
Every relocatable module has at its start (ie the part that loads into memory at its lowest address) a header table pointing to various items of data and program. Most of the items pointed to are optional, the pointers being zero if not needed. When writing a relocatable module in assembly language you lay this table out yourself, but when writing in C, you use CMHG to generate this for you. In addition to generating a module header, CMHG also inserts small standard routines to, for example, initialise the C language library support and make service call handling efficient.
To construct a relocatable module you write a number of routines in C with standard prototypes, some of these routines to be called with the processor in supervisor (SVC) mode. These are accompanied by a text description file written in a special syntax which CMHG understands. For details of this language and the specifications of the C routines, see the chapter entitled How to write relocatable modules in C. For more details of relocatable module headers, see the chapter entitled Modules in the RISC OS 3 PROGRAMMER'S REFERENCE MANUAL. FOR SOME HINTS ABOUT MEMORY USAGE FROM RELOCATABLE MODULE CODE_ SEE THE RISC OS 3 Programmer's Reference Manual.
The rest of this chapter explains the (simple) controls of the CMHG tool. CMHG is one of the non-interactive desktop tools, its desktop user interface being provided by the FrontEnd module. It shares many common features with the other non-interactive tools. These common features are described in the General features of the accompanying Desktop Tools guide.
The Make tool (see the chapter entitled Make of the Desktop Tools guide) can also construct command lines for the underlying CMHG program. You'll find it a better tool for managing large projects. However, much of what is in this chapter is relevant, since Make sets options for the CMHG program with the CMHG tool's user interface.
To start the CMHG tool, first open the AcornC_C++.Tools directory display, then double click on !CMHG. Its icon appears on the icon bar:
Clicking Select on this icon, or dragging a CMHG description file from a directory display to this icon, brings up the SetUp dialogue box, from which you control the running of CMHG:
CMHG has hardly any options for its use, so its interface is simpler than most of the other Acorn C/C++ tools.
The Source writable icon is for the name of the description file to be processed. If you displayed the SetUp dialogue box by clicking on the CMHG icon bar icon, you will want to fill this in by dragging a CMHG description file from a directory display to this icon before running CMHG.
Clicking Menu on the SetUp dialogue box brings up the CMHG SetUp menu, which owing to the simplicity of CMHG only has a single Command line item:
You can get CMHG to generate a header file from the description file, which contains #defines of constants for the commands declared in the description file. To do so, you need to append the name of the header file to the text in the Command line writable icon:
Clicking Menu on the CMHG application icon on the icon bar gives access to the following options:
For a description of each option in the application menu see the chapter entitled General features of the accompanying Desktop Tools guide.
The following is an example CMHG description file, similar to that used within Acorn to construct the FrontEnd module, which is itself a relocatable module written in C:
; Purpose: module header for the generalised front end module
;
module-is-runnable: ; module start code
initialisation-code: FrontEnd_init
service-call-handler: FrontEnd_services 0x11 ; service-memory
title-string: FrontEnd
help-string: FrontEnd 1.00
command-keyword-table: FrontEnd_commands
FrontEnd_Start(min-args: 4, max-args: 5,
help-text: "Help text\n"),
FrontEnd_Setup(min-args: 8, max-args: 8,
help-text: "Help text\n")
swi-chunk-base-number: 0x081400
Running CMHG displays any error messages in the standard text output window for non-interactive tools. If all goes well, as it should do if you try CMHG with the above description file, this window is empty:
The output file produced is an object file. You link this with the object files compiled from your C code to produce your relocatable module.
For normal use you do not need to understand the syntax of the underlying CMHG program's command line, as it is generated automatically for you from the SetUp dialogue box and menu settings.
The syntax of the CMHG command line is:
cmhg descfile«objfile «defsfile»»