From 3cab3f1000947bb467eccd4dd83f209cc1baa80d Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Fri, 18 Jul 2014 12:16:10 +0100 Subject: [PATCH] raco exe: document command-line flags --- .../racket-doc/scribblings/raco/exe.scrbl | 115 ++++++++++++++++-- 1 file changed, 105 insertions(+), 10 deletions(-) diff --git a/pkgs/racket-pkgs/racket-doc/scribblings/raco/exe.scrbl b/pkgs/racket-pkgs/racket-doc/scribblings/raco/exe.scrbl index 636398526f..740230d9e0 100644 --- a/pkgs/racket-pkgs/racket-doc/scribblings/raco/exe.scrbl +++ b/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}.} + +] @; ----------------------------------------------------------------------