suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

raco setup: reorganize command-line flags

Browse Source 
Group flags and refine the descriptions and documentation.

Merge to v6.1
(cherry picked from commit 95a126b2e1)
This commit is contained in:
Matthew Flatt 2014-07-10 09:39:29 +01:00 committed by Ryan Culpepper
parent dbc1b565a4
commit adf9f50b73
2 changed files with 111 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

103
pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl
View File

@ -99,34 +99,41 @@ flags:
@itemize[ @itemize[
@item{@DFlag{jobs} @nonterm{n}, @DFlag{workers} @nonterm{n}, @item{Constraining to specified collections or @|PLaneT| packages:
or @Flag{j} @nonterm{n} --- use up @itemize[
to @nonterm{n} parallel processes. By default, @exec{raco setup}
uses @racket[(processor-count)] jobs, which typically uses
all of the machine's processing cores.}
@item{@DFlag{only} --- restrict setup to specified collections and @item{@DFlag{only} --- restrict setup to specified collections and
@|PLaneT| packages, even if none are specified. This mode is the @|PLaneT| packages, even if none are specified. This mode is the
default if any collection is specified as a command-line argument, default if any collection is specified as a command-line argument
through the @Flag{l} flag, or through the @Flag{P} flag.} or through the @Flag{l}, @DFlag{pkgs}, or @Flag{P} flag.}
@item{@Flag{P} @nonterm{owner} @nonterm{package-name} @nonterm{maj} @item{@Flag{l} @nonterm{collection} @racket[...] --- constrain setup
@nonterm{min} --- constrain setup actions to the specified @|PLaneT| actions to the specified @nonterm{collection}s (i.e., the same as
package, in addition to any other specified @|PLaneT| packages or providing @nonterm{collections}s without a flag, but with no
@nonterm{collection}s.} possibility that a @nonterm{collection} is interpreted as a flag).}
@item{@DFlag{pkgs} @nonterm{pkg} @racket[...] --- constrain setup @item{@DFlag{pkgs} @nonterm{pkg} @racket[...] --- constrain setup
actions to collections that are within (or partially within) the actions to collections that are within (or partially within) the
named @nonterm{pkg}s.} named @nonterm{pkg}s.}
@item{@DFlag{tidy} --- remove metadata cache information and @item{@Flag{P} @nonterm{owner} @nonterm{package-name} @nonterm{maj}
documentation for non-existent collections (to clean up after removal) @nonterm{min} --- constrain setup actions to the specified @|PLaneT|
even when setup actions are otherwise confined to specified collections.} package, in addition to any other specified @|PLaneT| packages or
collections.}
@item{@DFlag{doc-index} --- builds collections that implement @item{@DFlag{doc-index} --- build collections that implement
documentation indexes (when documentation building is enabled), in documentation indexes (when documentation building is enabled), in
addition to specified collections.} addition to specified collections.}
@item{@DFlag{tidy} --- remove metadata cache information and
documentation for non-existent collections or documentation (to
clean up after removal), even when setup actions are otherwise
confined to specified collections.}
]}
@item{Constraining to specific tasks:
@itemize[
@item{@DFlag{clean} or @Flag{c} --- delete existing @filepath{.zo} @item{@DFlag{clean} or @Flag{c} --- delete existing @filepath{.zo}
files, thus ensuring a clean build from the source files. The exact files, thus ensuring a clean build from the source files. The exact
set of deleted files can be controlled by @filepath{info.rkt}; see set of deleted files can be controlled by @filepath{info.rkt}; see
@ -142,7 +149,7 @@ flags:
executables or installing @tt{man} pages (as specified in executables or installing @tt{man} pages (as specified in
@filepath{info.rkt}; see @secref["setup-info"]).} @filepath{info.rkt}; see @secref["setup-info"]).}
@item{@DFlag{no-foreign-libs} --- refrain from installing foreign @item{@DFlag{no-foreign-libs} or @Flag{F} --- refrain from installing foreign
libraries (as specified in @filepath{info.rkt}; see libraries (as specified in @filepath{info.rkt}; see
@secref["setup-info"]).} @secref["setup-info"]).}
@ -166,20 +173,11 @@ flags:
documentation, render documentation to PDF and place files in documentation, render documentation to PDF and place files in
@nonterm{dir}.} @nonterm{dir}.}
@item{@DFlag{no-user} or @Flag{U} --- refrain from any user-specific
(as opposed to installation-specific) setup actions.}
@item{@DFlag{no-planet} --- refrain from any setup actions for
@|PLaneT| actions; this flags is implied by @DFlag{no-user}.}
@item{@DFlag{avoid-main} --- refrain from any setup actions that
affect the installation, as opposed to user-specific actions.}
@item{@DFlag{no-pkg-deps} or @Flag{K} --- refrain from checking @item{@DFlag{no-pkg-deps} or @Flag{K} --- refrain from checking
whether dependencies among libraries are properly reflected by whether dependencies among libraries are properly reflected by
package-level dependency declarations, whether modules are declared package-level dependency declarations, whether modules are declared
by multiple packages, and whether package version dependencies are by multiple packages, and whether package version dependencies are
satisfied. Dependency checking uses compiled bytecode, associated satisfied. Dependency checking uses @filepath{.zo} files, associated
@filepath{.dep} files, and the documentation index. Unless @filepath{.dep} files, and the documentation index. Unless
@DFlag{check-pkg-deps} is specified, dependency checking is disabled @DFlag{check-pkg-deps} is specified, dependency checking is disabled
if any collection is specified for @exec{raco setup}, and missing if any collection is specified for @exec{raco setup}, and missing
@ -204,8 +202,37 @@ flags:
dependencies may be reported as unused only because compilation of dependencies may be reported as unused only because compilation of
relevant modules has been suppressed.} relevant modules has been suppressed.}
@item{@DFlag{fail-fast} --- attempt to break as soon as any error is ]}
discovered.} @item{Constraining user versus installation setup:
@itemize[
@item{@DFlag{no-user} or @Flag{U} --- refrain from any user-specific
(as opposed to installation-specific) setup actions.}
@item{@DFlag{no-planet} --- refrain from any setup actions for
@|PLaneT| actions; this flags is implied by @DFlag{no-user}.}
@item{@DFlag{avoid-main} --- refrain from any setup actions that
affect the installation, as opposed to user-specific actions.}
]}
@item{Selecting parallelism and other build modes:
@itemize[
@item{@DFlag{jobs} @nonterm{n}, @DFlag{workers} @nonterm{n},
or @Flag{j} @nonterm{n} --- use up
to @nonterm{n} parallel processes. By default, @exec{raco setup}
uses @racket[(processor-count)] jobs, which typically uses
all of the machine's processing cores.}
@item{@DFlag{verbose} or @Flag{v} --- more verbose output about
@exec{raco setup} actions.}
@item{@DFlag{make-verbose} or @Flag{m} --- more verbose output about
dependency checks.}
@item{@DFlag{compiler-verbose} or @Flag{r} --- even more verbose
output about dependency checks and compilation.}
@item{@DFlag{mode} @nonterm{mode} --- use a @filepath{.zo} compiler @item{@DFlag{mode} @nonterm{mode} --- use a @filepath{.zo} compiler
other than the default compiler, and put the resulting other than the default compiler, and put the resulting
@ -217,23 +244,16 @@ flags:
@racket[compile]; see the @filepath{errortrace} collection for an @racket[compile]; see the @filepath{errortrace} collection for an
example.} example.}
@item{@DFlag{verbose} or @Flag{v} --- more verbose output about @item{@DFlag{fail-fast} --- attempt to break as soon as any error is
@exec{raco setup} actions.} discovered.}
@item{@DFlag{make-verbose} or @Flag{m} --- more verbose output about
dependency checks.}
@item{@DFlag{compiler-verbose} or @Flag{r} --- even more verbose
output about dependency checks and compilation.}
@item{@DFlag{pause} or @Flag{p} --- pause for user input if any @item{@DFlag{pause} or @Flag{p} --- pause for user input if any
errors are reported (so that a user has time to inspect output that errors are reported (so that a user has time to inspect output that
might otherwise disappear when the @exec{raco setup} process ends).} might otherwise disappear when the @exec{raco setup} process ends).}
@item{@Flag{l} @nonterm{collection} @racket[...] --- constrain setup ]}
actions to the specified @nonterm{collection}s (i.e., the same as @item{Unpacking @filepath{.plt} archives:
providing @nonterm{collections}s without a flag), but with no @itemize[
possibility that a @nonterm{collection} is interpreted as a flag.}
@item{@Flag{A} @nonterm{archive} @racket[...] --- Install each @item{@Flag{A} @nonterm{archive} @racket[...] --- Install each
@nonterm{archive}; see @secref["raco-setup-A"].} @nonterm{archive}; see @secref["raco-setup-A"].}
@ -245,6 +265,7 @@ flags:
install archive into the installation instead of a user-specific install archive into the installation instead of a user-specific
location.} location.}
]}
] ]
@ -258,7 +279,7 @@ collections during an install:
@history[#:changed "1.2" @elem{Added the @DFlag{pkgs}, @history[#:changed "1.2" @elem{Added the @DFlag{pkgs},
@DFlag{check-pkg-deps}, and @DFlag{check-pkg-deps}, and
@DFlag{fast-break} flags.}] @DFlag{fail-fast} flags.}]
@; ------------------------------------------------------------------------ @; ------------------------------------------------------------------------

83
racket/collects/setup/setup-cmdline.rkt
View File

@ -33,35 +33,47 @@
(command-line (command-line
#:program long-name #:program long-name
#:argv argv #:argv argv
#:help-labels
" --------------------------- collections --------------------------- "
" If no collection, package, or archive is specified, all are setup"
#:once-each #:once-each
[("-j" "--jobs" "--workers") n "Use <n> parallel jobs" [("--only") "Set up only specified, even if none"
(add-flags `((parallel-workers ,(string->number n))))]
[("--only") "Set up only specified <collection>s"
(add-flags '((make-only #t)))] (add-flags '((make-only #t)))]
[("-l") => (lambda (flag . collections)
(check-collections short-name collections)
(cons 'collections (map list collections)))
'("Setup specified <collection>s" "collection")]
[("--pkgs") => (lambda (flag . pkgs)
(check-packages short-name pkgs)
(cons 'packages pkgs))
'("Setup collections in specified <pkg>s" "pkg")]
#:multi #:multi
[("-P") owner package-name maj min [("-P") owner package-name maj min
"Setup specified PLaneT packages only" "Setup specified PLaneT packages"
(set! x-specific-planet-packages (cons (list owner package-name maj min) (set! x-specific-planet-packages (cons (list owner package-name maj min)
x-specific-planet-packages))] x-specific-planet-packages))]
#:once-each #:once-each
[("--tidy") "Clear references to removed, even if not a specified <collection>" [("--doc-index") "Rebuild documentation index along with specified"
(add-flags '((make-tidy #t)))]
[("--doc-index") "Rebuild documentation indexes with specified <collection>s"
(add-flags '((make-doc-index #t)))] (add-flags '((make-doc-index #t)))]
[("-c" "--clean") "Delete existing compiled files; implies -nxi" [("--tidy") "Clear references to removed items outside of specified"
(add-flags '((make-tidy #t)))]
#:help-labels
" ------------------------------ tasks ------------------------------ "
#:once-each
[("-c" "--clean") "Delete existing compiled files; implies -nxiD"
(add-flags '((clean #t) (add-flags '((clean #t)
(make-zo #f) (make-zo #f)
(call-install #f) (call-install #f)
(make-launchers #f) (make-launchers #f)
(make-info-domain #f) (make-info-domain #f)
(make-docs #f)))] (make-docs #f)))]
[("-n" "--no-zo") "Do not produce .zo files" [("-n" "--no-zo") "Do not create \".zo\" files"
(add-flags '((make-zo #f)))] (add-flags '((make-zo #f)))]
[("--trust-zos") "Trust existing .zos (use only with prepackaged .zos)" [("--trust-zos") "Trust existing \".zo\"s (use only with prepackaged \".zo\"s)"
(add-flags '((trust-existing-zos #t)))] (add-flags '((trust-existing-zos #t)))]
[("-x" "--no-launcher") "Do not produce launcher programs" [("-x" "--no-launcher") "Do not produce launcher programs"
(add-flags '((make-launchers #f)))] (add-flags '((make-launchers #f)))]
[("--no-foreign-libs") "Do not install foreign libraries" [("-F" "--no-foreign-libs") "Do not install foreign libraries"
(add-flags '((make-foreign-libs #f)))] (add-flags '((make-foreign-libs #f)))]
[("-i" "--no-install") "Do not call collection-specific pre-installers" [("-i" "--no-install") "Do not call collection-specific pre-installers"
(add-flags '((call-install #f)))] (add-flags '((call-install #f)))]
@ -71,17 +83,11 @@
(add-flags '((make-info-domain #f)))] (add-flags '((make-info-domain #f)))]
[("-D" "--no-docs") "Do not compile .scrbl files and do not build documentation" [("-D" "--no-docs") "Do not compile .scrbl files and do not build documentation"
(add-flags '((make-docs #f)))] (add-flags '((make-docs #f)))]
[("--doc-pdf") dir "Build doc PDFs, write to <dir>" [("--doc-pdf") dir "Build documentation PDFs, write to <dir>"
(add-flags `((doc-pdf-dest ,dir)))] (add-flags `((doc-pdf-dest ,dir)))]
[("-U" "--no-user") "Do not setup user-specific collections (implies --no-planet)"
(add-flags '((make-user #f) (make-planet #f)))]
[("--no-planet") "Do not setup PLaneT packages"
(add-flags '((make-planet #f)))]
[("--avoid-main") "Do not make main-installation files"
(add-flags '((avoid-main-installation #t)))]
[("-K" "--no-pkg-deps") "Do not check package dependencies" [("-K" "--no-pkg-deps") "Do not check package dependencies"
(add-flags '((check-dependencies #f)))] (add-flags '((check-dependencies #f)))]
[("--check-pkg-deps") "Check package dependencies when <collection>s specified" [("--check-pkg-deps") "Check package dependencies when collections specified"
(add-flags '((always-check-dependencies #t)))] (add-flags '((always-check-dependencies #t)))]
[("--fix-pkg-deps") "Auto-repair package-dependency declarations" [("--fix-pkg-deps") "Auto-repair package-dependency declarations"
(add-flags '((check-dependencies #t) (add-flags '((check-dependencies #t)
@ -89,10 +95,20 @@
[("--unused-pkg-deps") "Check for unused package-dependency declarations" [("--unused-pkg-deps") "Check for unused package-dependency declarations"
(add-flags '((check-dependencies #t) (add-flags '((check-dependencies #t)
(check-unused-dependencies #t)))] (check-unused-dependencies #t)))]
[("--fail-fast") "Trigger break on error" #:help-labels
(add-flags '((fail-fast #t)))] " ------------------------------ users ------------------------------ "
[("--mode") mode "Select a compilation mode" #:once-each
(add-flags `((compile-mode ,mode)))] [("-U" "--no-user") "Do not setup user-specific collections (implies --no-planet)"
(add-flags '((make-user #f) (make-planet #f)))]
[("--no-planet") "Do not setup PLaneT packages"
(add-flags '((make-planet #f)))]
[("--avoid-main") "Do not make main-installation files"
(add-flags '((avoid-main-installation #t)))]
#:help-labels
" ------------------------------ modes ------------------------------ "
#:once-each
[("-j" "--jobs" "--workers") n "Use <n> parallel jobs"
(add-flags `((parallel-workers ,(string->number n))))]
[("-v" "--verbose") "See names of compiled files and info printfs" [("-v" "--verbose") "See names of compiled files and info printfs"
(add-flags '((verbose #t)))] (add-flags '((verbose #t)))]
[("-m" "--make-verbose") "See make and compiler usual messages" [("-m" "--make-verbose") "See make and compiler usual messages"
@ -100,16 +116,15 @@
[("-r" "--compile-verbose") "See make and compiler verbose messages" [("-r" "--compile-verbose") "See make and compiler verbose messages"
(add-flags '((make-verbose #t) (add-flags '((make-verbose #t)
(compiler-verbose #t)))] (compiler-verbose #t)))]
[("--mode") mode "Select a compilation mode, such as \"errortrace\""
(add-flags `((compile-mode ,mode)))]
[("--fail-fast") "Trigger a break on the first error"
(add-flags '((fail-fast #t)))]
[("-p" "--pause") "Pause at the end if there are any errors" [("-p" "--pause") "Pause at the end if there are any errors"
(add-flags '((pause-on-errors #t)))] (add-flags '((pause-on-errors #t)))]
[("-l") => (lambda (flag . collections) #:help-labels
(check-collections short-name collections) " ---------------------------- archives ----------------------------- "
(cons 'collections (map list collections))) #:once-each
'("Setup specific <collection>s only" "collection")]
[("--pkgs") => (lambda (flag . pkgs)
(check-packages short-name pkgs)
(cons 'packages pkgs))
'("Setup <collection>s in specific <pkg>s only" "pkg")]
[("-A") => (λ (flag . archives) [("-A") => (λ (flag . archives)
(cons 'archives archives)) (cons 'archives archives))
'("Unpack and install <archive>s" "archive")] '("Unpack and install <archive>s" "archive")]
@ -117,6 +132,9 @@
(add-flags '((force-unpacks #t)))] (add-flags '((force-unpacks #t)))]
[("-a" "--all-users") "Install archives to main (not user-specific) installation" [("-a" "--all-users") "Install archives to main (not user-specific) installation"
(add-flags '((all-users #t)))] (add-flags '((all-users #t)))]
#:help-labels
" ------------------------------ misc ------------------------------- "
#:handlers #:handlers
(lambda (collections/pkgs/archives . rest) (lambda (collections/pkgs/archives . rest)
@ -141,9 +159,6 @@
(if raco? '("collection") '("archive")) (if raco? '("collection") '("archive"))
(lambda (s) (lambda (s)
(display s) (display s)
(if raco?
(printf "If no <collection> is specified, all collections are setup\n")
(printf "If no <archive> or -l <collection> is specified, all collections are setup\n"))
(exit 0)))) (exit 0))))
(values short-name x-flags (values short-name x-flags