raco exe: document command-line flags

pkgs/racket-pkgs/racket-doc/scribblings/raco/exe.scrbl

@@ -1,9 +1,14 @@
 #lang scribble/doc
-@(require scribble/manual 
+@(require scribble/manual
+          scribble/bnf
           "common.rkt" 
-          (for-label racket/runtime-path
+          (for-label racket/base
+                     racket/runtime-path
+                     compiler/embed
                      launcher/launcher))
 
+@(define (gtech s) (tech #:doc '(lib "scribblings/guide/guide.scrbl") s))
+
 @title[#:tag "exe"]{@exec{raco exe}: Creating Stand-Alone Executables}
 
 @margin-note{Use a smaller base language to achieve a faster startup time such
@@ -65,15 +70,105 @@ and possibly other run-time files declared via
 support libraries to create a distribution using @exec{raco
 distribute}, as described in @secref["exe-dist"].
 
-The @DFlag{ico} (Windows) or @DFlag{icns} (Mac OS X) flag sets the
-icon for the generated executable. For generally, @DPFlag{aux}
-attaches information to the executable based on the auxilliary file's
-suffix; see @racket[extract-aux-from-path] for a list of recognized
-suffixes and meanings.
+The @exec{raco exe} command accepts the following command-line flags:
 
-The @Flag{l} or @DFlag{launcher} flag creates a @tech{launcher}
-instead of a stand-alone executable. See @secref["launcher"] for more
-information on launchers. The @DFlag{lib} has no effect in that case.
+@itemlist[
+
+ @item{@Flag{o} @nonterm{file} --- create the executable as
+   @nonterm{file}, adding a suffix to @nonterm{file} as appropriate
+   for the platform and executable type. On Mac OS X in @DFlag{gui}
+   mode, @nonterm{file} is actually a bundle directory, but it appears
+   as a file within Finder.}
+
+ @item{@DFlag{gui} --- create a graphical executable based on
+   @exec{gracket} instead of @exec{racket}.}
+
+ @item{@Flag{l} or @DFlag{launcher} --- create a @tech{launcher} (see
+   @secref["launcher"]), instead of a stand-alone executable. Flags
+   such as @DFlag{config-path}, @DFlag{collects-path}, and
+   @DFlag{lib} have no effect on launchers.}
+
+ @item{@DFlag{config-path} @nonterm{path} --- set @nonterm{path}
+   within the executable as the path to the @tech{configuration
+   directory}; if the path is relative, it will be treated as relative
+   to the executable. The default path is @filepath{etc}, with the
+   expectation that no such directory will exist at run time.}
+
+ @item{@DFlag{collects-path} @nonterm{path} --- set @nonterm{path}
+   within the executable as the path to the @tech{main collection
+   directory}; if the path is relative, it will be treated as relative
+   to the executable. The default is to have no path, which means that
+   the @racket[current-library-collection-paths] and
+   @racket[current-library-collection-links] parameters are
+   initialized at empty when the executable starts. Beware that
+   various other directories are located relative to the @tech{main
+   collection directory} by default (see @secref["config-file"]), so
+   that installing @nonterm{path} may allow other directories to be
+   found---intentional or not.}
+
+ @item{@DFlag{collects-dest} @nonterm{path} --- write modules to be
+   included with the executable into @nonterm{path}
+   (relative to the current directory), instead of embedded within the
+   executable. The @DFlag{collects-dest} flag normally makes sense
+   only in combination with @DFlag{collects-path}.}
+
+ @item{@DFlag{ico} @nonterm{.ico-path} --- on Windows, set the icons
+   for the generated executable to ones extracted from
+   @nonterm{.ico-path}; see @racket[create-embedding-executable]'s
+   use of the @racket['ico] auxiliary association for more information
+   about expected icon sizes and transformations.}
+
+ @item{@DFlag{icns} @nonterm{.icns-path} --- on Mac OS X, set the icons
+   for the generated executable to be the content of
+   @nonterm{.icns-path}.}
+
+ @item{@DFlag{orig-exe} --- generate an executable that refers to
+   the original @exec{racket} or @exec{gracket} executable,
+   instead of making a copy. This flag is rarely useful, because the
+   part of the executable that is copied is normally small, and
+   @exec{raco distribute} does not work with executables that are
+   created with @DFlag{orig-exe}.}
+
+ @item{@DFlag{3m} --- generate an executable based on the @gtech{3m}
+   variant of Racket, which is the default unless running a @exec{raco
+   exe} that is based on the @gtech{CGC} variant.}
+
+ @item{@DFlag{cgc} --- generate an executable based on the @gtech{CGC}
+   variant of Racket, which is the default only when running a
+   @exec{raco exe} that is based on the @gtech{CGC} variant.}
+
+ @item{@DPFlag{aux} @nonterm{file} --- attach information to the
+   executable based on @nonterm{file}'s suffix; see
+   @racket[extract-aux-from-path] for a list of recognized suffixes
+   and meanings, and see @racket[create-embedding-executable]'s use of
+   auxiliary association for more specific information about how each
+   kind of file is used.}
+
+ @item{@DPFlag{lib} @nonterm{module-path} --- include @nonterm{module-path}
+   in the executable, even if it is not referenced by the main program,
+   so that it is available via @racket[dynamic-require].}
+
+ @item{@DPFlag{exfl} @nonterm{flag} --- provide the @nonterm{flag}
+   command-line argument on startup to the embedded @exec{racket} or
+   @exec{gracket}.}
+
+ @item{@DFlag{exfl} @nonterm{flag} --- remove @nonterm{flag} from the
+   command-line arguments to be provided on startup to the embedded
+   @exec{racket} or @exec{gracket}.}
+
+ @item{@DFlag{exfl-clear} --- remove all command-line arguments to be
+   provided on startup to the embedded @exec{racket} or
+   @exec{gracket}.}
+
+ @item{@DFlag{exfl-show} --- show (without changing) the command-line
+   arguments to be provided on startup to the embedded
+   @exec{racket} or @exec{gracket}.}
+
+ @item{@Flag{v} --- report progress verbosely.}
+
+ @item{@DFlag{vv} --- report progress more verbosely than @Flag{v}.}
+
+]
 
 @; ----------------------------------------------------------------------