Re: GNAT documentation question

Re: GNAT documentation question

[Larry Kilgallen]

dIn
article <343ba5ba.1354247@news.mindspring.com>, spamsux@mindspring.com (Herman) writes:
> I know where it is, but it's a tar.gz file.  What in the world do I
> use in Windows 95 to open it?

Check your software that does Zip :-)

I got a ZIP file by mail from Aonix and I had to find a way to read it.
The computer store I chose did not have PKzip (a name I have heard) so
I bought some other brand of ZIP software ( don't have the name handy).
The fine print said something to the effect that "the whole world does
ZIP, but some Unix systems produce Tar, so our software will read Tar
as well").

I could not find anything in the top-level Microsoft subscription discs
which does Zip, but NT allegedly has Posix so perhaps that includes tar.

Re: GNAT documentation question

[Kenneth W. Sodemann]

Larry Kilgallen wrote in message <1997Oct8.122433.1@eisner>...
>dIn
>article <343ba5ba.1354247@news.mindspring.com>, spamsux@mindspring.com
(Herman) writes:
>> I know where it is, but it's a tar.gz file.  What in the world do I
>> use in Windows 95 to open it?
>
>Check your software that does Zip :-)
>

Two options off the top of my head:

1.)  Go to the Cygnus site.  They have a collection of UNIX utilities that
have been ported to Win32.  You can find information about this at:
http://www.cygnus.com/techie/ by clicking on "The GNU-Win32 Project".

Download the user tools, run the install, and then be sure to add the proper
directories to your path.

This solution has the advantage that it is free.  The easiest way to unpack
your file then (assuming that your file is currently called filename.tar.gz)
would be to do the following:
    gzip -d filename.tar.gz
    tar xvf filename.tar
There is a way to pipe these together, thus keeping the original .gz file
compressed, but I cannot remember what it is off the top of my head.

2.)  Get WinZip from http://www.winzip.com.  This has the advantage of being
dirt simple to use.  It has the disadvantage that if you want to continue
using it beyond the evaluation period, you really should pay for it.

Hope this helps.

--
with Std_Disclaimer;  use Std_Disclaimer;
Signature.Put (Name => Ken Sodemann,
    E_Mail => kwsodema@avistainc.com
    Web => http://www.pcii.net/~stuffel
    Company_Web => http://www.avistainc.com);

Re: GNAT documentation question

[David C. Hoos, Sr.]

WinZip available for download at http://www.winzip.com
Download the evaluation version.

Herman wrote in message <343ba5ba.1354247@news.mindspring.com>...
>I know where it is, but it's a tar.gz file.  What in the world do I
>use in Windows 95 to open it?
>
>
>------------------------------------
>Change spamsux to johnson64 to email

Re: GNAT documentation question

[Robert S. White]

In article <61ign3$ok7$1@polo.advicom.net>, david.c.hoos.sr@ada95.com says...
>
>WinZip available for download at http://www.winzip.com
>Download the evaluation version.
>
>Herman wrote in message <343ba5ba.1354247@news.mindspring.com>...
>>I know where it is, but it's a tar.gz file.  What in the world do I
>>use in Windows 95 to open it?

  But completely free (not shareware evaluation) versions of 
gunzip.exe and tar.exe are available from a lot of places.  Suppose 
you got an archive superstuff.taz .  First you do a:
  
  gunzip superstuff.taz

which converts (uncompresses) and renames in place the file to
superstuff.tar .  Sometimes you have to copy gzip.exe to gunzip.exe
to get the expected behaviour - otherwise do a:

   gzip -d superstuff.taz

Then you do a:

   tar xvh -f superstuff.tar

do break apart the archive to subdirectories and files - starting from
the current default directory.  A good place to look for these UN*X 
like tools for Win95 and NT is:

  http://www.itribe.net/virtunix/mystuff.html

but there are a lot of other sites that have gzip.exe and tar.exe that 
work for Win95 or WinNT that cane be found with web search sites like 
Yahoo, Lycos, etc.
_____________________________________________________________________
Robert S. White         -- An embedded systems software engineer
e-mail reply to reverse of: ia us lib cedar-rapids crpl shift2 whiter

GNAT documentation question

[James Squire]

A.13.15 says:
	The implementation shall document the conditions under which
Name_Error, Use_Error and Device_Error are propagated.

I've looked through the GNAT Reference Manual and I can't find this
anywhere.  Can anyone point me to where it is?
-- 
James Squire
Software Engineering Tools and Environments
Boeing St. Louis
Work: (314)-232-7010
Work@Home: (314)-831-4812
Pager#: (314)-318-2376

Re: GNAT documentation question

[Grein, Christoph]

> A.13.15 says:
> 	The implementation shall document the conditions under which
> Name_Error, Use_Error and Device_Error are propagated.
> 
> I've looked through the GNAT Reference Manual and I can't find this
> anywhere.  Can anyone point me to where it is?
> -- 

I would expect this to be in Gnat RM under Implementation Defined 
Characteristics - but I could not locate it there.

BTW, you quote chapter and verse incorrectly, it should be A.13(15).

Re: GNAT documentation question

[Mark Johnson]

James Squire wrote:
> 
> A.13.15 says:
>         The implementation shall document the conditions under which
> Name_Error, Use_Error and Device_Error are propagated.
> 
> I've looked through the GNAT Reference Manual and I can't find this
> anywhere.  Can anyone point me to where it is?

Hmm. That is an interesting comment. There IS a description of when
Use_Error is generated in the case of shared files (I know about that
problem - we had code that needed fixing...). But in general, that
description doesn't appear to be in ANY of the gnat documentation.
Perhaps I should submit a bug report on it.

On the other hand, it is a quick search to do something like...
  grep -inr "raise.*name_error;"
/usr/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adainclude
  (rewrite the phrase and/or path as needed)
to get the list of 5 locations where Name_Error is raised, the 14
locations for Use_Error, and 35 locations for Device_Error to get the
REAL answer. I did this with a 3.16w version of gnat, the same search on
3.14a1 has slightly different results (3, 14, 33).

If you also have glide, you could take that output, put the output of
grep into a buffer, and enable compilation-mode to let you go directly
to each reference. It would be far better to get it in the
documentation, but this should help for now.

  --Mark

Re: GNAT documentation question

[James Squire]

"Grein, Christoph" wrote:
> 
> > A.13.15 says:
> >       The implementation shall document the conditions under which
> > Name_Error, Use_Error and Device_Error are propagated.
> >
> > I've looked through the GNAT Reference Manual and I can't find this
> > anywhere.  Can anyone point me to where it is?
> > --
> 
> I would expect this to be in Gnat RM under Implementation Defined
> Characteristics - but I could not locate it there.

I was expecting it under "The Implementation of Standard I/O", but
didn't find it there either.

> 
> BTW, you quote chapter and verse incorrectly, it should be A.13(15).

Whatever.
-- 
James Squire
Software Engineering Tools and Environments
Boeing St. Louis
Work: (314)-232-7010
Work@Home: (314)-831-4812
Pager#: (314)-318-2376

Re: GNAT documentation question

[Robert Dewar]

James Squire <james.a.squire@boeing.com> wrote in message news:<3D406C6B.9DE867E4@boeing.com>...
> A.13.15 says:
> 	The implementation shall document the conditions under which
> Name_Error, Use_Error and Device_Error are propagated.
> 
> I've looked through the GNAT Reference Manual and I can't find this
> anywhere.  Can anyone point me to where it is?


Easy to point to! The detailed documentation for such
details is always in the sources. These sources are very
much part of the documentation for questions like this.
This has the advantage of providing absolutely precise,
complete and up to date documentation of implementation
details like this.

The source of the run-time library, always distributed
with all versions of GNAT, provides completely detailed
documentation of the mapping of Ada 95 run-time features
to the operating system in use.

Re: GNAT documentation question

[Robert Dewar]

James Squire <james.a.squire@boeing.com> wrote in message news:<3D417AB2.ADDD3F7A@boeing.com>...
> "Grein, Christoph" wrote:
> > 
> > BTW, you quote chapter and verse incorrectly, it should 
> > be A.13(15).

By the way, it seems that this particular documentation
requirement got omitted from Annex M, which is probably
an oversight.

Re: GNAT documentation question

[Robert A Duff]

dewar@gnat.com (Robert Dewar) writes:

> By the way, it seems that this particular documentation
> requirement got omitted from Annex M, which is probably
> an oversight.

I created the contents of Annex M, so the fact that this one is missing
is my fault.

I was always against having Annex M in the first place, and against any
form of documentation requirements, so it might be the case that I was
(therefore) sloppy.  (I am very much in favor of good documentation -- I
just don't think an International Standard is the way to go about it.)

- Bob

Re: GNAT documentation question

[Robert Dewar]

Robert A Duff <bobduff@shell01.TheWorld.com> wrote in message news:<wcc3cu3ikab.fsf@shell01.TheWorld.com>...
> dewar@gnat.com (Robert Dewar) writes:


> I was always against having Annex M in the first place, and against any
> form of documentation requirements, so it might be the case that I was
> (therefore) sloppy.  (I am very much in favor of good documentation -- I
> just don't think an International Standard is the way to go about it.)

I think it's fine to have them there if you regard them as having the same
status as implementation advice, which is what happens in practice.

The idea that they ar eformal normative requirements is of course ludicrous
given the complete absence of a formal definition of what documentation means!

Re: GNAT documentation question

[Mark Johnson]

Robert Dewar wrote:
> 
> James Squire <james.a.squire@boeing.com> wrote in message news:<3D406C6B.9DE867E4@boeing.com>...
> > A.13.15 says:
> >       The implementation shall document the conditions under which
> > Name_Error, Use_Error and Device_Error are propagated.
> >
> > I've looked through the GNAT Reference Manual and I can't find this
> > anywhere.  Can anyone point me to where it is?
> 
> Easy to point to! The detailed documentation for such
> details is always in the sources. These sources are very
> much part of the documentation for questions like this.
> This has the advantage of providing absolutely precise,
> complete and up to date documentation of implementation
> details like this.
> 
The source of course is where you hide these obscure details. I should
have expected you to make this kind of comment. :-)

As an example and an exercise for the reader - can you find the
configuration pragma that is necessary with GNAT on Linux to get real
time priorities. In our case, it took a search through the
documentation, then the source code, and then a message to ACT to
confirm that what we read was actually correct. It also didn't help that
you can't dig the real time priority out of Linux w/o a patched (or
extremely recent) kernel.

  --Mark

Re: GNAT documentation question

[Simon Wright]

Mark Johnson <mark_h_johnson@raytheon.com> writes:

> As an example and an exercise for the reader - can you find the
> configuration pragma that is necessary with GNAT on Linux to get
> real time priorities. In our case, it took a search through the
> documentation, then the source code, and then a message to ACT to
> confirm that what we read was actually correct. It also didn't help
> that you can't dig the real time priority out of Linux w/o a patched
> (or extremely recent) kernel.

It used to be that you just had to run your (tasking) program as
root. I take it this has changed? probably in the same way that the
Solaris implementation changed (at around 3.13, I seem to remember)

Re: GNAT documentation question

[James Squire]

Robert Dewar wrote:
> 
> James Squire <james.a.squire@boeing.com> wrote in message news:<3D406C6B.9DE867E4@boeing.com>...
> > A.13.15 says:
> >       The implementation shall document the conditions under which
> > Name_Error, Use_Error and Device_Error are propagated.
> >
> > I've looked through the GNAT Reference Manual and I can't find this
> > anywhere.  Can anyone point me to where it is?
> 
> Easy to point to! The detailed documentation for such
> details is always in the sources. These sources are very
> much part of the documentation for questions like this.
> This has the advantage of providing absolutely precise,
> complete and up to date documentation of implementation
> details like this.

I've been all through a-textio.ads and a-textio.adb, and I see a comment
about explicitly raising Constraint_Error, but that's it.  I'm not sure
what you are referring to here.  I'm used to seeing a comment block
preceding a procedure or function spec documenting among other things
what exceptions can be raised by this routine and why.
-- 
James Squire
Software Engineering Tools and Environments
Boeing St. Louis
Work: (314)-232-7010
Work@Home: (314)-831-4812
Pager#: (314)-318-2376

Re: GNAT documentation question

[Robert Dewar]

Mark Johnson <mark_h_johnson@raytheon.com> wrote in message news:<3D458108.A5D88B80@raytheon.com>...

> As an example and an exercise for the reader - can you find the
> configuration pragma that is necessary with GNAT on Linux to get real
> time priorities. In our case, it took a search through the
> documentation, then the source code, and then a message to ACT to
> confirm that what we read was actually correct. It also didn't help that
> you can't dig the real time priority out of Linux w/o a patched (or
> extremely recent) kernel.

That's straightforward. If you want Annex D dispatching rules (that's the
semantically significant issue here), then you need to use the pragmas
documented in Annex D to have this effect. I would be surprised if there
was anything else to this issue. In other words, real time priorities are
not an end here, they are simply a means to an end, the end being the proper
implementation of annex D features.

Re: GNAT documentation question

[Robert Dewar]

Mark Johnson <mark_h_johnson@raytheon.com> wrote in message news:<3D458108.A5D88B80@raytheon.com>...

> The source of course is where you hide these obscure details. I should
> have expected you to make this kind of comment. :-)

Well I am not sure that it would prove useful to try to detail the exact
conditions under which use error etc are raised anyway. The exact details
are quite target dependent, and no well written code in Ada should depend
on these kind of implementation differences anyway. So yes, these are indeed
fairly obscure.

The code of the I/O packages is actually quite transparent, and it is not so
unreasonable to suggest that people look at this code if they want to know more
about the exact mapping of Ada stuff to OS stuff. For one thing there are many
implementation defined choices here that are NOT required to be documented. In
particular, you really need to know these details if you plan to mix Ada and
C simultaneous I/O.

Re: GNAT documentation question

[Simon Wright]

dewar@gnat.com (Robert Dewar) writes:

> That's straightforward. If you want Annex D dispatching rules
> (that's the semantically significant issue here), then you need to
> use the pragmas documented in Annex D to have this effect. I would
> be surprised if there was anything else to this issue. In other
> words, real time priorities are not an end here, they are simply a
> means to an end, the end being the proper implementation of annex D
> features.

Our point of view was:

* we have a mixed language, multi-process program

* we need parts of it to run with priorities higher than those of
  normal processes

* we can use priocntl to get this to happen (this was Solaris)

* wow! if we run as root, GNAT does what we want! (this was 3.11, I
  think)

so the question of whether we had Annex D dispatching rules never
entered our heads.

We were delighted to have found a solution, so never raised the
question with ACT. Had we still been supported on that contract when
we discovered the changed behaviour, we would of course have asked!

Re: GNAT documentation question

[Mark Johnson]

Simon Wright wrote:
> 
> Mark Johnson <mark_h_johnson@raytheon.com> writes:
> 
> > [snip - enabling real time priorities on Linux]
> 
> It used to be that you just had to run your (tasking) program as
> root. I take it this has changed? probably in the same way that the
> Solaris implementation changed (at around 3.13, I seem to remember)

As you suggest, I expected to get real time priorities by setting the
task priorities with pragma Priority and then running the program as
root. That is necessary but not sufficient. The additional required step
was to specify FIFO_Within_Priorities as the task dispatching policy. It
was certainly not obvious from what we had read prior to reading the
source code.
  --Mark

Re: GNAT documentation question

[Robert A Duff]

Simon Wright <simon@pushface.org> writes:

> dewar@gnat.com (Robert Dewar) writes:
> 
> > That's straightforward. If you want Annex D dispatching rules
> > (that's the semantically significant issue here), then you need to
> > use the pragmas documented in Annex D to have this effect. I would
> > be surprised if there was anything else to this issue. In other
> > words, real time priorities are not an end here, they are simply a
> > means to an end, the end being the proper implementation of annex D
> > features.
> 
> Our point of view was:
> 
> * we have a mixed language, multi-process program
> 
> * we need parts of it to run with priorities higher than those of
>   normal processes
> 
> * we can use priocntl to get this to happen (this was Solaris)
> 
> * wow! if we run as root, GNAT does what we want! (this was 3.11, I
>   think)
> 
> so the question of whether we had Annex D dispatching rules never
> entered our heads.

This is a good example of why I think Annex M is useless.  This
programmer wants to know how to fiddle with *process* priorities, which
have nothing to do with what's in the RM, and in fact Annex M doesn't
give any pressure toward answering it.  How could it?  The RM knows
nothing of processes.  Nonetheless, good documentation would explain how
Ada priorities affect process priorities and the like.

You can't legislate "good documentation", any more than "morality".

I think compiler documentation should be driven by "what do we think the
programmer wants to know about" rather than by "the RM says we have to
document certain things".

> We were delighted to have found a solution, so never raised the
> question with ACT. Had we still been supported on that contract when
> we discovered the changed behaviour, we would of course have asked!

When I wrote the docs for AdaMagic for the SHARC chip, I *first* wrote
what I thought was useful: sections about "how to debug" and "how to
handle interrupts", etc, with examples and whatnot.  This was somewhat
driven by my own knowledge, and somewhat by questions from customers.
Then I went through Annex M, and if it said I must document
something-or-other about interrupts, I referred the reader to the
interrupt section, rather than inserting some out-of-context factoid
about interrupts in Annex M.

Our documentation of Annex M ensures that we obey the rules (although as
Robert Dewar pointed out, this can't be formally verified), but it not
particularly useful to users.

- Bob

Re: GNAT documentation question

[Randy Brukardt]

Robert Dewar wrote in message
<5ee5b646.0207281109.3894cc74@posting.google.com>...
>James Squire <james.a.squire@boeing.com> wrote in message
news:<3D417AB2.ADDD3F7A@boeing.com>...
>> "Grein, Christoph" wrote:
>> >
>> > BTW, you quote chapter and verse incorrectly, it should
>> > be A.13(15).
>
>By the way, it seems that this particular documentation
>requirement got omitted from Annex M, which is probably
>an oversight.

No, I think it is intentional (Bob probably can tell us for sure).
A.13(15) is a "documentation requirement"; Annex M lists
"implementation-defined characteristics". They're not the same.

Annex M also omits some of the other core "documentation requirements"
(J.7.1(12-13); A.5.2(44); as well as A.13(15)) but also includes others
(A.5.2(45), 13.11(22)), so it hard to tell what the intent is. (This is
also true for the specialled needs annexes; a large number of the
"documentation requirements" are not included in Annex M.)

I think this will have to be taken to the ARG for a (short) discussion,
so the editor (me) can determine what fix is appropriate.

             Randy.

Re: GNAT documentation question

[Robert A Duff]

"Randy Brukardt" <randy@rrsoftware.com> writes:

> Robert Dewar wrote in message
> <5ee5b646.0207281109.3894cc74@posting.google.com>...
> >James Squire <james.a.squire@boeing.com> wrote in message
> news:<3D417AB2.ADDD3F7A@boeing.com>...
> >> "Grein, Christoph" wrote:
> >> >
> >> > BTW, you quote chapter and verse incorrectly, it should
> >> > be A.13(15).
> >
> >By the way, it seems that this particular documentation
> >requirement got omitted from Annex M, which is probably
> >an oversight.
> 
> No, I think it is intentional (Bob probably can tell us for sure).
> A.13(15) is a "documentation requirement"; Annex M lists
> "implementation-defined characteristics". They're not the same.

I *think* you're right.  I think I created Annex M by searching for
"implementation-defined" and the like, and adding macro calls.  Each
macro call generates a comment in the AARM, and an entry in Annex M.

But no, Bob cannot "tell us for sure".  I don't remember.

> Annex M also omits some of the other core "documentation requirements"
> (J.7.1(12-13); A.5.2(44); as well as A.13(15)) but also includes others
> (A.5.2(45), 13.11(22)), so it hard to tell what the intent is. (This is
> also true for the specialled needs annexes; a large number of the
> "documentation requirements" are not included in Annex M.)

Which lends credence to this theory.

> I think this will have to be taken to the ARG for a (short) discussion,
> so the editor (me) can determine what fix is appropriate.

I'm not sure it's worth fixing.  Annex M is non-normative anyway.

- Bob