Re: GNAT's gnatchp

[dewar@cs.nyu.edu (Robert Dewar)]

Peter Pierce wrote:

   Mr. Dewar:
   
   In self defense, the following is verbatim from file gcc.hlp
   which is distributed with gnat for Windows95/NT:
   
   
   --- begin excerpt ---
   
   Usage : gnatchp [-ksw] filename [directory]
   k               limit filenames to 8 characters.
   r               generate source reference pragmas
   s               generate a compilation script.
   w       overwrite existing filenames.
   
   --- end excerpt -----
   
   Why would you take an unfounded jab at me?  There is a file
   gnatchp.exe, by the way - which adds to the confusion.
   
   I got other HELPFUL responses which allowed me to determine
   I had a "bad" copy of gnatchop.bat.  Once replaced, it worked
   fine.

OOPS! This indeed is a goof. Our documentation (gnatinfo.txt) of course
does not contain this error, but apparently Tom Griest (the source of
a helpful response, but also apparently responsble for the confusion
in the first place :-) slipped up in creating this gcc.hlp file (which
is not something we have anything to do with).

So I apologize for what was indeed an unfair comment! In future
I strongly suggest that you ONLY refer to the GNAT documentation
that we produce (i.e. gnatinfo.txt) which is far less likely
to have serious errors like this one.

We find that, for people using our documentation, 99% of installation
and usage problems result from inaccurate reading of the documentation.
But certainly if errors like this creep into other sources, then
that generates understandable confusion. here is the relevant
section from gnatinfo.txt. Be sure to get a copy of this file,
and refer only to it, not to any other documentatoin sources.


Compiling Files With Several Compilation Units.
-----------------------------------------------

GNAT can only deal with files that contain a single Ada compilation unit.
However, since it is an established style for certain types of programs
to contain more than one compilation in a file, such as in test suites,
a simple utility program, "gnatchop", is provided to preprocess the file
and split it several other files, one for each compilation unit.
gnatchop takes a filename with any extension. This name can basically
be anything.

Usage : gnatchop [-k] [-r] [-s] [-w] filename [directory]

  k         limit filenames to 8 characters
  r         generate source reference pragmas
  s         generate a compilation script
  w         overwrite existing filenames
  filename  source file
  directory directory to place split files (default is the current directory)

For example, assume archive contains package spec part1, package body
part1, package spec part2, package body part2.adb and subprogram part3 in
any sequence.

"gnatchop archive" will create five files in the current directory called
part1.ads, part1.adb, part2.ads, part2.adb, part3.adb. The optional directory
argument places all the split files in that directory rather than the current
directory. The directory must already exist otherwise gnatchop will reject it.

If at least one of the files to be split already exists, gnatchop will issue a
message and exit unless the -w flag is used to overwrite existing files.

The -r flag causes source reference pragmas to be generated at the start of
each file written. These pragmas will cause error message references and
debugging source information to refer back to the original unchopped files.
This is appropriate if you intend to maintain the program in unchopped form.

The -s flag generates a script which can be used to compile all the units
contained in the original source file.

  Suppose that you wanted to compile all the units contained in a given file
  called "archive" with some specific options like -gnatv, -O2 and -g. The
  gnatchop with -s option will generate a script with the appropriate
  extension depending on the the operating system. Then the script is
  invoked with the options following at the end as given below.

  gnatchop -s archive
  In Unix:  sh archive.sh -gnatv -O2 -g 
  In Dos :  archive.bat -gnatv -O2 -g
  In OS/2:  archive.cmd -gnatv -O2 -g

The -k flag krunches the names of the units to be 8 characters followed by the
ads or adb extension.

Currently, if you want to specify more than one flag, you need to specify
them separately.  For example, if you want to split archive.adb and specify
both the -s and the -w flags, type "gnatchop -s -w archive" instead of
"gnatchop -sw archive". This limitation will be lifted in the near future.

Note: gnatchop works fine for the case of a single compilation unit in a
file, and this is useful in dealing with files that do not have names
satisfying the GNAT naming requirements.