Improve documentation of save-application

[alms]

See e-mail thread below for suggested improvement.

Begin forwarded message:

From: "Mark H. David" <mhd@yv.org>
Date: July 28, 2010 6:37:11 AM EDT
To: Gary Byers <gb@clozure.com>
Cc: openmcl-devel@clozure.com
Subject: Re: [Openmcl-devel] save-application

Yes, (save-application ... :prepend-kernel t) does the trick.

> C:\Program Files\ccl>wx86cl.exe
> Welcome to Clozure Common Lisp Version 1.4-r13122  (WindowsX8632)!
> ? (ccl::save-application "\\foo.exe" :PREPEND-KERNEL t)
>
> C:\Program Files\ccl>\foo.exe
> Welcome to Clozure Common Lisp Version 1.4-r13122  (WindowsX8632)!
> ? (print "Hello World!")
>
> "Hello World!"

Doc could be improved.  The documentation for function save-application (http://openmcl.clozure.com/manual/chapter4.9.html#Saving-Applications) no information about prepend-kernel nor any other of these keyword args:

 (purify t)  impurify  (mode #o644)  prepend-kernel

The text of this chapter leading up to the function does, in retrospect, explain the wonders of prepending the kernel in a somewhat chatty and roundabout style while managing to never actually refer to the PREPEND-KERNEL arg by name.

Thanks!

Mark

Gary Byers wrote:
>
>
> On Tue, 27 Jul 2010, Mark H. David wrote:
>
> > Anyone know why this doesn't work?
>
> You can use the :PREPEND-KERNEL option to SAVE-APPLICATION
> to create a self-contained executable file; without that
> option, it just writes a heap image that can be mapped into
> memory by the lisp kernel.
>
> Giving a file a ".exe" extension doesn't turn it into a valid
> Windows executable file (with the right signatures and structure.)
>
> > 
> > C:\Program Files\ccl>wx86cl.exe
> > Welcome to Clozure Common Lisp Version 1.4-r13122  (WindowsX8632)!
> > ? (ccl::save-application "\\foo.exe")
> > 
> > C:\Program Files\ccl>\foo
> > Access is denied.
>
> Some variant of "File isn't in executable format" might be a clearer
> error message, though it's hard to say "an OS should spend N cycles
> checking to see if alleged executable files are in the right format
> so that better error messages can be produced in this case" - the case
> is probably not exactly common, and the N cycles might add up.
>
> It's likely unrelated to what you describe above, but some versions of
> Windows may dislike writing files to / executing files in the root directory.
> (I don't know what versions of Windows limit this or exactly what the
> limits are, but I'm fairly sure that some limits exist.)
>
> > 
> > C:\Program Files\ccl>
> > _______________________________________________
> > Openmcl-devel mailing list
> > Openmcl-devel@clozure.com
> > http://clozure.com/mailman/listinfo/openmcl-devel

_______________________________________________
Openmcl-devel mailing list
Openmcl-devel@clozure.com
http://clozure.com/mailman/listinfo/openmcl-devel

[rme]

(In [14694]) A few additions to the documentation for save-application.

Closes ticket:710.