From adf9f50b73fa654602ba2180c562340a2a920b51 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Thu, 10 Jul 2014 09:39:29 +0100 Subject: [PATCH] raco setup: reorganize command-line flags Group flags and refine the descriptions and documentation. Merge to v6.1 (cherry picked from commit 95a126b2e15efcc58cb21ec93abaf9b92bfcb071) --- .../racket-doc/scribblings/raco/setup.scrbl | 103 +++++++++++------- racket/collects/setup/setup-cmdline.rkt | 83 ++++++++------ 2 files changed, 111 insertions(+), 75 deletions(-) diff --git a/pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl b/pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl index 777de3c098..ea985b93c9 100644 --- a/pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl +++ b/pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl @@ -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.}] @; ------------------------------------------------------------------------ diff --git a/racket/collects/setup/setup-cmdline.rkt b/racket/collects/setup/setup-cmdline.rkt index f98ba05e68..434639d98b 100644 --- a/racket/collects/setup/setup-cmdline.rkt +++ b/racket/collects/setup/setup-cmdline.rkt @@ -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 parallel jobs" - (add-flags `((parallel-workers ,(string->number n))))] - [("--only") "Set up only specified 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 s" "collection")] + [("--pkgs") => (lambda (flag . pkgs) + (check-packages short-name pkgs) + (cons 'packages pkgs)) + '("Setup collections in specified 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 " - (add-flags '((make-tidy #t)))] - [("--doc-index") "Rebuild documentation indexes with specified 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 " + [("--doc-pdf") dir "Build documentation PDFs, write to " (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 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 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 s only" "collection")] - [("--pkgs") => (lambda (flag . pkgs) - (check-packages short-name pkgs) - (cons 'packages pkgs)) - '("Setup s in specific s only" "pkg")] + #:help-labels + " ---------------------------- archives ----------------------------- " + #:once-each [("-A") => (λ (flag . archives) (cons 'archives archives)) '("Unpack and install 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 is specified, all collections are setup\n") - (printf "If no or -l is specified, all collections are setup\n")) (exit 0)))) (values short-name x-flags