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.uilIn 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.
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
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.uilUnder 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.
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.uilThe 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.
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.
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.
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.
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.
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.
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.
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
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 { };;
value
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.
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.
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.
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.