GNAT's gnatchp

GNAT's gnatchp

[Peter J. Pierce]

I have been trying to get the GNAT utility "gnatchp" to work 
without success.  

I have strictly followed the documentation 
in the help file gcc.hlp which was distributed with 
version 3.01 for Windows95/NT.  I have tried it both with 
version 3.01 for Windows95/NT and with version 3.03 on a SUN.

I get the display "splitting filename.ext into:" with 
each but then nothing happens.  In both cases I have changed
directory to where the source code is located.

Any hints?  Thank you in advance.

-- Peter Pierce 3/29/96

Re: GNAT's gnatchp

[Tom Griest]

Peter J. Pierce <pierce@patriot.net> writes:
>I have been trying to get the GNAT utility "gnatchp" to work 
>without success.  
>
>I have strictly followed the documentation 
>in the help file gcc.hlp which was distributed with 
>version 3.01 for Windows95/NT.  I have tried it both with 
>version 3.01 for Windows95/NT and with version 3.03 on a SUN.

Well, I can't speak for the Sun version, but on Win32 platforms
you want to use "gnatchop" not "gnatchp".  This is especially
confusing since there is a gnatchp.exe program that is invoked
by gnatchop.bat.  I think in future versions, it might be a good
idea to give gnatchp a different name so that this type of error
doesn't happen.  I'll submit a comment to the list that is
involved in maintaining gnat, since we would have to coordinate all
the ports to change at the same time.

-Tom

Re: GNAT's gnatchp

[Robert Dewar]

"I have been trying to get the GNAT utility "gnatchp" to work
without success.

I have strictly followed the documentation"

Well that's a nice contradiction. There is no such thing as the
GNAT utility "gnatchp", so it would be *quite* hard to follow
the documentation, strictly or otherwise, on gnatchp, since
there is none.

Undoubtedly you read the documentation or GNATCHOP, not gnatchp.
Changing names in commands does not come under the category'
of strictly following documentation I am afraid :-) :-)

Nearly all difficulties with GNAT come from not following the
documentation exactly in our experience (I mean intallation
difficulties here).

One of my students in my class wrote a note today saying that books
in CS were useless, the only way to learn is by example! I replied
that the ability to read documentation accurately is an important
skill! I guess this is a nice example :-)

Re: GNAT's gnatchp

[Peter J. Pierce]

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.

Peter J. Pierce 4/1/96





dewar@cs.nyu.edu (Robert Dewar) writes:
> "I have been trying to get the GNAT utility "gnatchp" to work
> without success.
> 
> I have strictly followed the documentation"
> 
> Well that's a nice contradiction. There is no such thing as the
> GNAT utility "gnatchp", so it would be *quite* hard to follow
> the documentation, strictly or otherwise, on gnatchp, since
> there is none.
> 
> Undoubtedly you read the documentation or GNATCHOP, not gnatchp.
> Changing names in commands does not come under the category'
> of strictly following documentation I am afraid :-) :-)
> 
> Nearly all difficulties with GNAT come from not following the
> documentation exactly in our experience (I mean intallation
> difficulties here).
> 
> One of my students in my class wrote a note today saying that books
> in CS were useless, the only way to learn is by example! I replied
> that the ability to read documentation accurately is an important
> skill! I guess this is a nice example :-)
> 

Re: GNAT's gnatchp

[Richard Pitre]

In article <dewar.828333453@schonberg> dewar@cs.nyu.edu (Robert Dewar) writes:
> "I have been trying to get the GNAT utility "gnatchp" to work
> without success.
> 
> I have strictly followed the documentation"
> 
> Well that's a nice contradiction. There is no such thing as the
> GNAT utility "gnatchp", so it would be *quite* hard to follow
> the documentation, strictly or otherwise, on gnatchp, since
> there is none.
> 
> Undoubtedly you read the documentation or GNATCHOP, not gnatchp.
> Changing names in commands does not come under the category'
> of strictly following documentation I am afraid :-) :-)
> 
> Nearly all difficulties with GNAT come from not following the
> documentation exactly in our experience (I mean intallation
> difficulties here).
> 
> One of my students in my class wrote a note today saying that books
> in CS were useless, the only way to learn is by example! I replied
> that the ability to read documentation accurately is an important
> skill! I guess this is a nice example :-)

The ability to write documentation that makes simple and obvious
things look simple and obvious is also an important skill.
It sounds like your documentation could use a little rearrangment so that
priority items like installation, got priority billing.

richard

Re: GNAT's gnatchp

[Robert Dewar]

Richard said

"The ability to write documentation that makes simple and obvious
things look simple and obvious is also an important skill.
It sounds like your documentation could use a little rearrangment so that
priority items like installation, got priority billing."

Actually, most cases of installation difficulties with the ACT versions
of GNAT have to do with experienced users figuring that they know enough
to deliberately not follow the directions :-)

Re: GNAT's gnatchp

[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.

Re: GNAT's gnatchp

[Tom Griest]

In article <dewar.828449600@schonberg> dewar@cs.nyu.edu (Robert Dewar) writes:

[example of gnatchop error in gcc.hlp doc on Win95 platform snipped]

>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).

Actually, I did not create the help file, but one of my employees did,
which ultimately I take responsibilty for.  I thought she had just
"included" the then-current gnatinfo.txt, but it seems in this case
she altered it beyond added the hyperlinks.  The text seems so close, 
and yet so far.... :)   I do know that at one time the gnatchop batch
file did not work on NT, but I'm at a loss as to how it got scrambled.

We do include the gnatinfo.txt too.  I plan to take a sweep over the
help files, but I was waiting for the release of the gnat users guide.
Maybe I should get the release from SGI.  In any case, this error
has been corrected in the help sources.