Contents Previous Next

24 Using the UIL Compiler

This chapter explains how to use the UIL compiler. The chapter describes all of the different compiler options and looks at the different types of messages that the compiler can generate.

The job of the UIL compiler is to turn a UIL module (or UIL source file) into a user interface description (UID) file, which contains a compact, Mrm-readable form of your UIL source module. The compiler checks the module for coding errors and potential problems and reports what it finds. As with any compilation process, the source module must be free of errors before the compiler can successfully generate a UID file.

The UIL compiler is invoked with the uil command, followed by the name of the file to be compiled. You may also provide a number of options. A typical compilation command looks like this:

   uil interface.uil
In this simple invocation, the compiler outputs a file named a.uid , assuming there are no errors in interface.uil. (This default output name is similar to the a.out file generated by most C compilers.) For obvious reasons, the standard suffix for a UIL source module is .uil and the suffix for UID files is .uid. In addition, we use the suffix .uih for UIL include files. The OSF/Motif documentation uses .uil for both main modules and include files, but we feel that using .uil and .uih is easier to work with, as well as being more C-like.

24.1 Compiler Options

The UIL compiler supports a number of options that affect the compilation process. These options are summarized in tab(@),linesize(2); l | l l | l. Option@Description
-o filename@Name the UID output file -I path@Specify an include file directory name -v filename @Generate a listing file -s@Set the locale when parsing strings -w@Suppress warning and informational messages

-m@Generate machine (UID) code in the listing -wmd filename@Use the widget descriptions from filename

24.1.1 Output File

The -o option names the UID output file. The format of this option is -o filename. As we just mentioned, the default output filename is a.uid. You probably don't want a file named a.uid, just like you usually don't want an executable named a.out. The following command line shows the use of this option:

   uil -o interface.uid interface.uil
Under Motif 1.2.x and earlier releases, the generated UID file is platform dependent. This means that you must recompile your UIL modules under each operating system that your application runs under. For OSF/Motif release 2.0 and later, UID files are platform independent, so you can use one instance of a UID file under any operating system that supports Motif 2.0.

24.1.2 Include Path

The -I option tells the UIL compiler where to look for include files. By default, the compiler looks in the same directory as the UIL source module and then in /usr/include. You can use this option repeatedly to specify more than one include directory. Any directories you specify with the -I option are searched after the directory that contains the source module and before /usr/include. Consider the following command:

   uil -o menus.uid -I../uil_headers -I/global/uil menus.uil
The search path is . (the current directory), ../uil_headers , /global/uil, and /usr/include. This path applies to all included files, even nested includes. The current directory always refers to the directory in which the compiler was invoked and does not change to the directory of include files.

24.1.3 Generate Listing

The -v option tells the compiler to generate a printable listing from the compiled module. The syntax for the option is -v filename. On UNIX systems, a filename of /dev/tty can be used to send the listing to the terminal. The output contains a listing of the source module and all included files. A header with the compiler version, the date, the page number, and the module name appear on the top of each page. Here's an example of a listing generated using the -v option with a small module:

   Motif Uil Compiler V2.0-000     Sat Apr 17 12:12:22 1993    Page 1
   Module: listme
       1 (0)       /* listme.uil -- Test module for the -v option. */
       2 (0)
       3 (0)       module listme
       4 (0)
       5 (0)       include file 'listme.uih';
       1 (1)       procedure
       2 (1)         exit();
       6 (0)
       7 (0)       object lister : XmList { };
       8 (0)
       9 (0)       end module;

        File (0)   listme.uil
        File (1)   listme.uih
The first column of the listing is the line number, and the second column is a number representing the file that contains the line. There is a key of file names and numbers at the end of the listing. If the compiler detects any errors or warnings, the messages appear interspersed with the lines in the listing, and a summary of the number of each type of message is printed at the end.

24.1.4 Set Locale

The -s option causes the compiler to set the locale based on the LANG environment variable. The setting affects how the compiler parses multibyte string values. On ANSI-C systems, the locale is set with a call to setlocale (LC_ALL, ""). Note, however, that if the module-wide character_set option is set, then the -s option has no effect. (The character_set option is described in Chapter 22, Introduction to UIL.) If you are going to use the -s option, you should specify the character set in the codeset portion of the LANG environment variable. In early releases of Motif 1.2, the UIL compiler may crash if you use the -s option when LANG is set to a value that is not supported by the operating system. This problem is fixed as of release 1.2.3.

24.1.5 Suppress Warnings

The -w option suppresses the printing of warning and informational messages. Normally the compiler prints errors, warnings, and informational messages. Error messages are always printed and cannot be suppressed. This option can be useful if your module has a lot of errors and warnings and you want to concentrate the on errors only. Section #suilmsgs describes the different types of messages in more detail.

24.1.6 Machine Listing

The -m option tells the compiler to print the information written to the UID file along with the module listing. This option has no effect unless the -v option is also used. The option was probably intended to help debug the compiler. It is useful for determining exactly how the compiler interprets a particular statement and approximately how much storage is used for each definition in the module. If a module contains errors, the compiler cannot generate a machine listing because it doesn't generate a UID file.

24.1.7 Use WML Description

The -wmd option directs the compiler to load an alternate widget set description from a compiled Widget Meta-Language (WML) description file. The format of this option is -wmd filename. By default, the compiler uses a set of built-in tables that describe the OSF/Motif widget set. This option is rarely used because few people write widget set descriptions in WML. Recently, however, some companies have started to ship Widget Meta-Language Database (WMD) files with their custom widget sets, so use of this option will probably increase.

24.2 Errors, Warnings, and Informational Messages

As we mentioned, the UIL compiler can generate several different types of messages: severe errors, regular errors, warnings, and informational messages. The type of each message is indicated by a prefix of either Severe, Error, Warning, or Info. When a message is generated as a result of a problem in the module (as opposed to, say, a system error), the message is printed with the line number and source line that triggered the problem. When a compilation results in one or more of these messages, a summary of the nomber of occurrences of each type is output at the end of the compilation.

24.2.1 Severe Error Messages

Severe errors occur when something prevents the UIL compiler from continuing. Severe errors commonly occur when an input or output file cannot be opened or an internal compiler error is detected. Severe errors can also occur after too many regular errors are encountered. Unlike the other types of problems, severe errors never contain an associated line number, even when the error occurs because an include file cannot be found. For example, if you attempt to compile a nonexistent file or write a listing to a non-writable directory, UIL generates the following errors:

   % uil bogus.uil
   Severe: error opening source file: bogus.uil

   % uil -v /cant-write listme.uil
   Severe: error opening listing file: /cant-write

24.2.2 Regular Error Messages

The most common causes of other errors are syntax mistakes, type mismatch problems, and identifier redefinitions. Regular errors are almost always associated with a specific source line. the source code shows a UIL module with one of each of these types of errors.

   module buggy

   object button : XmPushButton { };;

     duplicate : 10;
     duplicate : "whoops!";

   object label : XmLabel {
     arguments {
       XmNlabelString = button;

   end module;
An attempt to compile this module results in the following output:
           object button : XmPushButton { };;
   Error: unexpected SEMICOLON token seen - parsing resumes after ";"
                    line: 3  file: buggy.uil
             duplicate : "whoops!";
   Error: name duplicate previously defined as integer
                    line: 7  file: buggy.uil
               XmNlabelString = button;
   Error: found widget_ref widget when expecting compound_string value
                    line: 11  file: buggy.uil
   Info: no UID file was produced
   Info: errors: 3  warnings: 0  informationals: 1
The compiler prints an asterisk (*) under the offending line to show you exactly where the error occurred. Note that because errors were detected, the compiler did not produce a UID file.

24.2.3 Warning Messages

Warning messages turn up most often when part of a widget definition does not make sense to the compiler. Since warnings are not critical problems, a UID file is still produced when they occur. You shouldn't ignore warnings, as they typically indicate a misunderstanding of some kind. For example, in the source code we incorrectly try to create a List gadget and use the XmNset resource in a Label widget.

   module mistakes

   object files : XmList gadget { };

   object label : XmLabel {
     arguments {
       XmNset = true;

   end module;
Running this module through the compiler produces the following warnings:
           object files : XmList gadget { };
   Warning: XmList gadget is not supported - XmList widget will be used instead
                    line: 3  file: warn.uil
               XmNset = true;
   Warning: the XmNset argument is not supported for the XmLabel object
                    line: 7  file: warn.uil
   Info: errors: 0  warnings: 2  informationals: 0
Warning messages are usually associated with a line in the source module. Warnings are also generated if you specify an unknown option to the uil command or when the compiler cannot close a file.

24.2.4 Informational Messages

The UIL compiler uses informational messages to let you know about the state of the compilation. The compiler also generates an informational message if you set the same resource or callback more than once. You've already seen two of the three possible informational messages in the example output from above. The module in the source code demonstrates the third situation.

   module infos

   list base : arguments {
     XmNlabelString = "original";

   object main_widget : XmLabel {
     arguments {
       arguments base;
       XmNlabelString = "actual";

   end module;

The compiler output for this module is as follows: These informational messages were generated by an early version of the Motif 1.2 compiler, which incorrectly outputs the line of the original resource rather than the line that superseded it.

             XmNlabelString = "original";
   Info: this XmNlabelString argument supersedes a previous definition in this
   argument list
                    line: 4  file: info.uil
   Info: errors: 0  warnings: 0  informationals: 1

Although you may set the same resource twice by mistake, you may want to do it intentionally. This technique can be used (as above) to override the value of a resource obtained from a reusable list of resources, as described in Section #suillist.

24.3 Summary

The UIL compiler is needed to convert a UIL source module into a UID file that can be read at run-time by Mrm. The uil command invokes the compiler; it is typically used with the -o filename option to specify the output UID file name. The compiler also supports a number of other options that affect the output of the compilation. A compilation can result in messages that report severe errors, regular errors, warnings, and informational messages. A UID file is never produced when one or more errors occur, but can still be generated when only warnings or informational messages occur.

Contents Previous Next