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[
@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{Constraining to specified collections or @|PLaneT| packages:
@itemize[
@item{@DFlag{only} --- restrict setup to specified collections and
@|PLaneT| packages, even if none are specified. This mode is the
default if any collection is specified as a command-line argument,
through the @Flag{l} flag, or through the @Flag{P} flag.}
default if any collection is specified as a command-line argument
or through the @Flag{l}, @DFlag{pkgs}, or @Flag{P} flag.}
@item{@Flag{P} @nonterm{owner} @nonterm{package-name} @nonterm{maj}
@nonterm{min} --- constrain setup actions to the specified @|PLaneT|
package, in addition to any other specified @|PLaneT| packages or
@nonterm{collection}s.}
@item{@Flag{l} @nonterm{collection} @racket[...] --- constrain setup
actions to the specified @nonterm{collection}s (i.e., the same as
providing @nonterm{collections}s without a flag, but with no
possibility that a @nonterm{collection} is interpreted as a flag).}
@item{@DFlag{pkgs} @nonterm{pkg} @racket[...] --- constrain setup
actions to collections that are within (or partially within) the
named @nonterm{pkg}s.}
@item{@DFlag{tidy} --- remove metadata cache information and
documentation for non-existent collections (to clean up after removal)
even when setup actions are otherwise confined to specified collections.}
@item{@Flag{P} @nonterm{owner} @nonterm{package-name} @nonterm{maj}
@nonterm{min} --- constrain setup actions to the specified @|PLaneT|
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
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}
files, thus ensuring a clean build from the source files. The exact
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
@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
@secref["setup-info"]).}
@ -166,20 +173,11 @@ flags:
documentation, render documentation to PDF and place files in
@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
whether dependencies among libraries are properly reflected by
package-level dependency declarations, whether modules are declared
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
@DFlag{check-pkg-deps} is specified, dependency checking is disabled
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
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
other than the default compiler, and put the resulting
@ -217,23 +244,16 @@ flags:
@racket[compile]; see the @filepath{errortrace} collection for an
example.}
@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{fail-fast} --- attempt to break as soon as any error is
discovered.}
@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
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
providing @nonterm{collections}s without a flag), but with no
possibility that a @nonterm{collection} is interpreted as a flag.}
]}
@item{Unpacking @filepath{.plt} archives:
@itemize[
@item{@Flag{A} @nonterm{archive} @racket[...] --- Install each
@nonterm{archive}; see @secref["raco-setup-A"].}
@ -245,6 +265,7 @@ flags:
install archive into the installation instead of a user-specific
location.}
]}
]
@ -258,7 +279,7 @@ collections during an install:
@history[#:changed "1.2" @elem{Added the @DFlag{pkgs},
@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
#:program long-name
#:argv argv
#:help-labels
" --------------------------- collections --------------------------- "
" If no collection, package, or archive is specified, all are setup"
#:once-each
[("-j" "--jobs" "--workers") n "Use <n> parallel jobs"
(add-flags `((parallel-workers ,(string->number n))))]
[("--only") "Set up only specified <collection>s"
[("--only") "Set up only specified, even if none"
(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
[("-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)
x-specific-planet-packages))]
#:once-each
[("--tidy") "Clear references to removed, even if not a specified <collection>"
(add-flags '((make-tidy #t)))]
[("--doc-index") "Rebuild documentation indexes with specified <collection>s"
[("--doc-index") "Rebuild documentation index along with specified"
(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)
(make-zo #f)
(call-install #f)
(make-launchers #f)
(make-info-domain #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)))]
[("--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)))]
[("-x" "--no-launcher") "Do not produce launcher programs"
(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)))]
[("-i" "--no-install") "Do not call collection-specific pre-installers"
(add-flags '((call-install #f)))]
@ -71,17 +83,11 @@
(add-flags '((make-info-domain #f)))]
[("-D" "--no-docs") "Do not compile .scrbl files and do not build documentation"
(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)))]
[("-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"
(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)))]
[("--fix-pkg-deps") "Auto-repair package-dependency declarations"
(add-flags '((check-dependencies #t)
@ -89,10 +95,20 @@
[("--unused-pkg-deps") "Check for unused package-dependency declarations"
(add-flags '((check-dependencies #t)
(check-unused-dependencies #t)))]
[("--fail-fast") "Trigger break on error"
(add-flags '((fail-fast #t)))]
[("--mode") mode "Select a compilation mode"
(add-flags `((compile-mode ,mode)))]
#:help-labels
" ------------------------------ users ------------------------------ "
#:once-each
[("-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"
(add-flags '((verbose #t)))]
[("-m" "--make-verbose") "See make and compiler usual messages"
@ -100,16 +116,15 @@
[("-r" "--compile-verbose") "See make and compiler verbose messages"
(add-flags '((make-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"
(add-flags '((pause-on-errors #t)))]
[("-l") => (lambda (flag . collections)
(check-collections short-name collections)
(cons 'collections (map list collections)))
'("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")]
#:help-labels
" ---------------------------- archives ----------------------------- "
#:once-each
[("-A") => (λ (flag . archives)
(cons 'archives archives))
'("Unpack and install <archive>s" "archive")]
@ -117,6 +132,9 @@
(add-flags '((force-unpacks #t)))]
[("-a" "--all-users") "Install archives to main (not user-specific) installation"
(add-flags '((all-users #t)))]
#:help-labels
" ------------------------------ misc ------------------------------- "
#:handlers
(lambda (collections/pkgs/archives . rest)
@ -141,9 +159,6 @@
(if raco? '("collection") '("archive"))
(lambda (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))))
(values short-name x-flags