[info-sather] Option "-main": Compiler and Browser

[Sather User]

The option "-main" is used to designate the class containing the
Sather program's main routine.

For example if you want to run the browser on the browser itself
(using "sabrowse", the name of the browser executable in
Sather-1.2.3), you have to type:

$ sabrowse -main BROWSER Browser/browser.module

There is a special case that doesn't need the option to be given: if
the main class is named MAIN the option "-main" is not required.

It's a good idea to notice that a class named MAIN is the exception,
not the rule.  It is a special case.  It saves typing if the main
class of hello.sa is named MAIN and not HELLO.  If it is named MAIN
one has the option of omitting the "-main" option, though there would
be nothing wrong with supplying it anyway.

That is okay if you are typing the compile command, which in
Sather-1.2.3 is "sacomp".  To name the main class HELLO and then have
to type:

$ sacomp -main HELLO -o hello hello.sa

is not very convenient.  But most of the time the Sather-1.2.3
programmer won't be typing "sacomp" and options by hand every time.
There will be a module file or a make file or both, e.g. Makefile with
the lines

all:
        sacomp hello.module

hello.module is so bone simple

        hello.sa
        -o hello
        -main HELLO

and you only have to do it once, practically there's no advantage in
calling the main class MAIN.

There are advantages in not, in giving some meaningful name to the
main class.  One is that you can then, if it suits what you're doing,
have more that one main class in a Sather source file.  You can have
different module files, or different make targets, and use the same
source file to produce several independent executables that share some
classes.

E.g. if you've been writing various classes to handle TIFF files you
might have had a main class, done test compiles, but then decide you
want to generate a different program.  Fine, add another main class.
Down the track you might want to put the TIFF classes in your library
in separate files, but for now you have a file with two main classes,
SANE_TAGINSERT and TIFF_LOOK, say.

Another case is found in the source tree's Test directory.  The code
for testing classes happens to have a lot of main classes.  The class
TEST_OBLIG in Test/test-oblig.sa has lines like

      BOOL_TEST::main;
      CHAR_TEST::main;
      INT_TEST::main;

After all, why should the main class of test-oblig.sa be called MAIN?
And a routine doesn't need an explicit return unless it returns a
value.  We can have a Sather program calling the main routines of
stand-alone test programs to handle the tests from one point.  They
are main classes but they can't be called MAIN.

This brings us to a funny piece of code, the file
Browser/all-classes.sa.  That is all it is, all classes.  It has lines
like BOOL_TEST::main; designating classes that don't instantiate
objects, and like queue:$QUEUE{INT}; or a:STR_CURSOR; or m7:JACOBI;
for those that do.  In effect an index of them.  It's not code that
can be compiled.  All it's for is that the browser is run on it with
special options by the csh script Browser/gen_lib to generate the
Online Sather Code Browser pages.  You go dotty if you spend too much
time with gen_lib but you finish up with some good documentation.

Oops.  It's been changed to a Bourne shell script in sather-1.2.3 now
I look at it, gen_lib has.  For some reason.  Or none.  Another of
those changes... won't get into that.

When no main class has been designated the compiler aborts with an
error message, "There is no class named MAIN."  But the browser
doesn't exit nicely like that, it segfaults.  The browser refuses to
run if not given an argument but you can type (Sather-1.2.3) "sabrowse
x" where x means nothing and the browser will run, put up its tower
photograph and segfault.  The reason might be that the browser has to
run in situations we haven't all thought of.  Will come now to one case.

The same thing will happen, it'll crash, if you run the browser on
all-classes.sa, this time because it's simply an index of existing
classes.  The browser can't locate those classes because you aren't
running it on a module file which might say where they are.
Possibly, if you could be bothered setting up such a file and
designating a main class, the browser would handle it without crashing.

But it handles it without crashing anyway.  That's all all-classes.sa
is for, to be run by the browser, with the special options and
arguments supplied by gen_lib, and it does it without a whimper.

So, the main class.  Good idea to give it a distinctive name, avoid
MAIN except in that very basic situation of typing in "cs" or "sacomp"
with options on the command line.  If you are in the habit of
designating a main class, conscious that you have to do that, suppose
for some reason you enter

$ sabrowse Browser/browser.module

Of course, it crashes.  But along the way it spits out error messages
like "void class... May crash later:MAIN".  If you are in the habit of
entering the "-main" option a message like that might, just might,
shout at you that you forgot to supply that option and designate the
main class, BROWSER.

Of course, that the browser crashes in such a situation, it's not a
bug, it's a feature. :-)  You can aim it at anything.

Inching our way forward but the pre-announced release is still a few
weeks away.


-- 
Michael Talbot-Wilson