1#lang scribble/doc 2 3@(require scribble/manual 4 scribble/bnf 5 "common.rkt" 6 (for-label racket 7 racket/future 8 setup/setup-unit 9 setup/option-unit 10 setup/option-sig 11 setup/dirs 12 setup/getinfo 13 setup/main-collects 14 setup/collection-name 15 setup/collection-search 16 setup/matching-platform 17 setup/cross-system 18 setup/path-to-relative 19 setup/xref scribble/xref 20 ;; info -- no bindings from this are used 21 (only-in info) 22 setup/pack 23 setup/unpack 24 setup/link 25 compiler/compiler 26 compiler/module-suffix 27 compiler/find-exe 28 launcher/launcher 29 compiler/sig 30 launcher/launcher-sig 31 dynext/file-sig 32 racket/gui/base 33 racket/future 34 mrlib/terminal 35 (only-in ffi/unsafe ffi-lib) 36 racket/path 37 setup/collects 38 syntax/modcollapse 39 racket/runtime-path 40 pkg/path)) 41 42@(define-syntax-rule (local-module mod . body) 43 (begin 44 (define-syntax-rule (go) 45 (begin 46 (require (for-label mod)) 47 . body)) 48 (go))) 49 50@(define ref-src 51 '(lib "scribblings/reference/reference.scrbl")) 52 53@(define (defaults v) 54 @elem{The default is @|v|.}) 55 56@(define pkg-doc '(lib "pkg/scribblings/pkg.scrbl")) 57 58@title[#:tag "setup" #:style 'toc]{@exec{raco setup}: Installation Management} 59 60The @exec{raco setup} command builds bytecode, documentation, 61executables, and metadata indexes for all installed collections. 62 63The collections that are built by @exec{raco setup} can be part of the 64original Racket distribution, installed via the package manager (see 65@other-manual[pkg-doc]), installed via 66@|PLaneT| (see @other-manual['(lib "planet/planet.scrbl")]), linked 67via @exec{raco link}, in a directory that is listed in the 68@envvar{PLTCOLLECTS} environment variable, or placed into one of the 69default collection directories. 70 71The @exec{raco setup} tool itself does not directly support the 72installation of collections, except through the now-discouraged 73@Flag{A} flag (see @secref["raco-setup-A"]). The @exec{raco setup} command is 74used by installation tools such as the package manager or @|PLaneT|. 75Programmers who modify installed collections may find it useful to run 76@exec{raco setup} as an alternative to un-installing and re-installing 77a set of collections. 78 79@local-table-of-contents[] 80 81@; ------------------------------------------------------------------------ 82 83@section[#:tag "running"]{Running @exec{raco setup}} 84 85With no command-line arguments, @exec{raco setup} finds all of the 86current collections---see @secref[#:doc ref-src]{collects}---and 87compiles libraries in each collection. (Directories that are named 88@filepath{.git} or @filepath{.svn} are not treated as collections.) 89 90To restrict @exec{raco setup} to a set of collections, provide the 91collection names as arguments. For example, @exec{raco setup 92scribblings/raco} would only compile and render the documentation for 93@exec{raco}, which is implemented in a @filepath{scribblings/raco} 94collection. 95 96An optional @filepath{info.rkt} within the collection can indicate 97specifically how the collection's files are to be compiled and other 98actions to take in setting up a collection, such as creating 99executables or building documentation. See @secref["setup-info"] for 100more information. 101 102The @exec{raco setup} command accepts the following command-line 103flags: 104 105@itemize[ 106 107@item{Constraining to specified collections or @|PLaneT| packages: 108@itemize[ 109 110 @item{@DFlag{only} --- restrict setup to specified collections and 111 @|PLaneT| packages, even if none are specified. This mode is the 112 default if any collection is specified as a command-line argument 113 or through the @Flag{l}, @DFlag{pkgs}, or @Flag{P} flag.} 114 115 @item{@Flag{l} @nonterm{collection} @racket[...] --- constrain setup 116 actions to the specified @nonterm{collection}s (i.e., the same as 117 providing @nonterm{collections}s without a flag, but with no 118 possibility that a @nonterm{collection} is interpreted as a flag).} 119 120 @item{@DFlag{pkgs} @nonterm{pkg} @racket[...] --- constrain setup 121 actions to collections that are within (or partially within) the 122 named @nonterm{pkg}s.} 123 124 @item{@Flag{P} @nonterm{owner} @nonterm{package-name} @nonterm{maj} 125 @nonterm{min} --- constrain setup actions to the specified @|PLaneT| 126 package, in addition to any other specified @|PLaneT| packages or 127 collections.} 128 129 @item{@DFlag{doc-index} --- build collections that implement 130 documentation indexes (when documentation building is enabled), in 131 addition to specified collections.} 132 133 @item{@DFlag{tidy} --- remove metadata cache information and 134 documentation for non-existent collections or documentation to 135 clean up after removal, even when setup actions are otherwise 136 confined to specified collections. Although tidying is not confined 137 to specified collections, it can be constrained with @DFlag{avoid-main} 138 or @DFlag{no-user}.} 139 140]} 141@item{Constraining to specific tasks: 142@itemize[ 143 144 @item{@DFlag{clean} or @Flag{c} --- delete existing @filepath{.zo} 145 files, thus ensuring a clean build from the source files. The exact 146 set of deleted files can be controlled by @filepath{info.rkt}; see 147 @elemref["clean"]{@racket[clean]} for more information. Unless 148 @DFlag{no-info-domain} or @Flag{d} is also specified, the @filepath{info.rkt} 149 cache is cleared. Unless @DFlag{no-docs} or @Flag{D} is also 150 specified, the documentation-index database is reset.} 151 152 @item{@DFlag{fast-clean} --- like @DFlag{clean}, but 153 without forcing a bootstrap of @exec{raco setup} from source (which 154 means that @DFlag{fast-clean} cannot clean corruption that affects 155 @exec{raco setup} itself).} 156 157 @item{@DFlag{no-zo} or @Flag{n} --- refrain from compiling source 158 files to @filepath{.zo} files.} 159 160 @item{@DFlag{trust-zos} --- fix timestamps on @filepath{.zo} files on 161 the assumption that they are already up-to-date (unless the 162 @envvar{PLT_COMPILED_FILE_CHECK} environment variable is set to 163 @litchar{exists}, in which case timestamps are ignored).} 164 165 @item{@DFlag{recompile-only} --- disallow recompilation of modules 166 from source, imposing the constraint that each @filepath{.zo} file 167 is up-to-date, needs only a timestamp adjustment, or can be 168 recompiled from an existing @filepath{.zo} in machine-independent 169 format (when compiling to a machine-dependent format).} 170 171 @item{@DFlag{sync-docs-only} --- synchronize or move documentation 172 into place to ``build'' it, but do not run or render documentation 173 sources.} 174 175 @item{@DFlag{no-launcher} or @Flag{x} --- refrain from creating 176 executables or installing @tt{man} pages (as specified in 177 @filepath{info.rkt}; see @secref["setup-info"]).} 178 179 @item{@DFlag{no-foreign-libs} or @Flag{F} --- refrain from installing foreign 180 libraries (as specified in @filepath{info.rkt}; see 181 @secref["setup-info"]).} 182 183 @item{@DFlag{only-foreign-libs} --- disable actions other than 184 installing foreign libraries; equivalent to @Flag{nxiIdD}, except 185 that @DFlag{only-foreign-libs} doesn't reject (redundant) 186 specification of those individual flags.} 187 188 @item{@DFlag{no-install} or @Flag{i} --- refrain from running 189 pre-install actions (as specified in @filepath{info.rkt} files; see 190 @secref["setup-info"]).} 191 192 @item{@DFlag{no-post-install} or @Flag{I} --- refrain from running 193 post-install actions (as specified in @filepath{info.rkt} files; see 194 @secref["setup-info"]).} 195 196 @item{@DFlag{no-info-domain} or @Flag{d} --- refrain from building 197 a cache of metadata information from @filepath{info.rkt} 198 files. This cache is needed by other tools. For example, 199 @exec{raco} itself uses the cache to locate plug-in tools.} 200 201 @item{@DFlag{no-docs} or @Flag{D} --- refrain from building 202 documentation.} 203 204 @item{@DFlag{doc-pdf} @nonterm{dir} --- in addition to building HTML 205 documentation, render documentation to PDF and place files in 206 @nonterm{dir}.} 207 208 @item{@DFlag{no-pkg-deps} or @Flag{K} --- refrain from checking 209 whether dependencies among libraries are properly reflected by 210 package-level dependency declarations, whether modules are declared 211 by multiple packages, and whether package version dependencies are 212 satisfied. See @secref["setup-check-deps"] for more information.} 213 214 @item{@DFlag{check-pkg-deps} --- checks package dependencies (unless 215 explicitly disabled) even when specific collections are provided to 216 @exec{raco setup}, and even for packages that have no dependency 217 declarations. See @secref["setup-check-deps"] for more information.} 218 219 @item{@DFlag{fix-pkg-deps} --- attempt to correct dependency 220 mismatches by adjusting package @filepath{info.rkt} files (which 221 makes sense only for packages that are installed as links). See 222 @secref["setup-check-deps"] for more information.} 223 224 @item{@DFlag{unused-pkg-deps} --- attempt to report dependencies that 225 are declared but are unused. Beware that some package dependencies 226 may be intentionally unused (e.g., declared to force installation of 227 other packages as a convenience), and beware that package 228 dependencies may be reported as unused only because compilation of 229 relevant modules has been suppressed. See 230 @secref["setup-check-deps"] for more information.} 231 232]} 233@item{Constraining user versus installation setup: 234@itemize[ 235 236 @item{@DFlag{no-user} or @Flag{U} --- refrain from any user-specific 237 (as opposed to installation-specific) setup actions.} 238 239 @item{@DFlag{no-planet} --- refrain from any setup actions for 240 @|PLaneT| actions; this flag is implied by @DFlag{no-user}.} 241 242 @item{@DFlag{avoid-main} --- refrain from any setup actions that 243 affect the installation, as opposed to user-specific actions.} 244 245 @item{@DFlag{force-user-docs} --- when building documentation, create 246 a user-specific documentation entry point even if it has the same 247 content as the main installation.} 248 249]} 250@item{Selecting parallelism and other build modes: 251@itemize[ 252 253 @item{@DFlag{jobs} @nonterm{n}, @DFlag{workers} @nonterm{n}, 254 or @Flag{j} @nonterm{n} --- use up 255 to @nonterm{n} parallel processes. By default, @exec{raco setup} 256 uses @racket[(processor-count)] jobs, which typically uses 257 all of the machine's processing cores.} 258 259 @item{@DFlag{places} --- use Racket places for parallel jobs; this 260 mode is the default if Racket places run in parallel.} 261 262 @item{@DFlag{processes} --- use separate processes for parallel jobs; 263 this mode is the default if Racket places cannot run in parallel.} 264 265 @item{@DFlag{verbose} or @Flag{v} --- more verbose output about 266 @exec{raco setup} actions.} 267 268 @item{@DFlag{make-verbose} or @Flag{m} --- more verbose output about 269 dependency checks.} 270 271 @item{@DFlag{compiler-verbose} or @Flag{r} --- even more verbose 272 output about dependency checks and compilation.} 273 274 @item{@DFlag{mode} @nonterm{mode} --- use a @filepath{.zo} compiler 275 other than the default compiler, and put the resulting 276 @filepath{.zo} files in a subdirectory (of the usual place) named 277 by @nonterm{mode}. The compiler is obtained by using @nonterm{mode} 278 as a collection name, finding a @filepath{zo-compile.rkt} module in 279 that collection, and extracting its @racket[zo-compile] export. The 280 @racket[zo-compile] export should be a function like 281 @racket[compile]; see the @filepath{errortrace} collection for an 282 example.} 283 284 @item{@DFlag{fail-fast} --- attempt to break as soon as any error is 285 discovered.} 286 287 @item{@DFlag{error-out} @nonterm{file} --- handle survivable errors 288 by writing @nonterm{file} and exiting as successful, which 289 facilitates chaining multiple @exec{raco setup} invocations in 290 combination with @DFlag{error-in}. If there are no errors and 291 @nonterm{file} already exists, it is deleted.} 292 293 @item{@DFlag{error-in} @nonterm{file} --- treat the existence of 294 @nonterm{file} as a ``errors were reported by a previous process'' 295 error. Typically, @nonterm{file} is created by previous @exec{raco 296 setup} run using @DFlag{error-out}. A file for @DFlag{error-in} is 297 detected before creating a file via @DFlag{error-out}, so the same 298 file can be used to chain a sequence of @exec{raco setup} steps.} 299 300 @item{@DFlag{pause} or @Flag{p} --- pause for user input if any 301 errors are reported (so that a user has time to inspect output that 302 might otherwise disappear when the @exec{raco setup} process ends).} 303 304]} 305@item{Unpacking @filepath{.plt} archives: 306@itemize[ 307 308 @item{@Flag{A} @nonterm{archive} @racket[...] --- Install each 309 @nonterm{archive}; see @secref["raco-setup-A"].} 310 311 @item{@DFlag{force} --- for use with @Flag{A}, treat version 312 mismatches for archives as mere warnings.} 313 314 @item{@DFlag{all-users} or @Flag{a} --- for use with @Flag{A}, 315 install archive into the installation instead of a user-specific 316 location.} 317 318]} 319@item{Bootstrapping: 320@itemize[ 321 322 @item{@DFlag{boot} @nonterm{module-file} @nonterm{build-dir} --- For 323 use by directly running @racketmodname[setup] instead of 324 through @exec{raco setup}, loads @nonterm{module-file} in the 325 same way that @exec{raco setup} normally loads itself, 326 auto-detecting the need to start from sources and rebuild the 327 compiled files---even for the compilation manager itself. The 328 @nonterm{build-dir} path is installed as the only path in 329 @racket[current-compiled-file-roots], so all compiled files 330 go there.} 331 332 @item{@DFlag{chain} @nonterm{module-file} @nonterm{build-dir} --- 333 Like @DFlag{boot}, but adds @nonterm{build-dir} to the start of 334 @racket[current-compiled-file-roots] instead of replacing the 335 current value, which means that libraries already built in the 336 normal location (including the compilation manager itself) will 337 be used instead of rebuilt. This mode makes sense for 338 cross-compilation.} 339 340]} 341 342] 343 344When building @exec{racket}, flags can be provided to @exec{raco 345setup} as run by @exec{make install} by setting the 346@as-index{@envvar{PLT_SETUP_OPTIONS}} makefile variable. For 347example, the following command line uses a single process to build 348collections during an install: 349 350 @commandline{make install PLT_SETUP_OPTIONS="-j 1"} 351 352Running @exec{raco setup} is sensitive to the 353@envvar{PLT_COMPILED_FILE_CHECK} environment variable in the same way 354as @exec{raco make}. Specifically, if @envvar{PLT_COMPILED_FILE_CHECK} 355is set to @litchar{exists}, then @exec{raco make} does not attempt to 356update a compiled file's timestamp if the file is not recompiled. 357 358Some additional environment variables are useful for performance 359debugging: 360 361@itemlist[ 362 363 @item{@indexed-envvar{PLT_SETUP_DMS_ARGS} triggers a call to 364 @racket[dump-memory-stats] after each collection is compiled, 365 where the environment variable's value is parsed with 366 @racket[read] to obtain a list of arguments to 367 @racket[dump-memory-stats].} 368 369 @item{@indexed-envvar{PLT_SETUP_LIMIT_CACHE} (set to anything) avoids 370 caching compiled-file information across different collections, 371 which is useful to reduce noise when looking for memory leaks.} 372 373 @item{@indexed-envvar{PLT_SETUP_NO_FORCE_GC} (set to anything) 374 suppresses a call to @racket[collect-garbage] that is issued by 375 default for non-parallel builds after each collection is 376 compiled and after each document is run or rendered.} 377 378 @item{@indexed-envvar{PLT_SETUP_SHOW_TIMESTAMPS} (set to anything) 379 appends the current process time after @litchar[" @ "] for each 380 status message printed by @exec{raco setup}.} 381 382] 383 384@history[#:changed "6.1" @elem{Added the @DFlag{pkgs}, 385 @DFlag{check-pkg-deps}, and 386 @DFlag{fail-fast} flags.} 387 #:changed "6.1.1" @elem{Added the @DFlag{force-user-docs} flag.} 388 #:changed "6.1.1.6" @elem{Added the @DFlag{only-foreign-libs} flag.} 389 #:changed "6.6.0.3" @elem{Added support for @envvar{PLT_COMPILED_FILE_CHECK}.} 390 #:changed "7.0.0.19" @elem{Added @DFlag{places} and @DFlag{processes}.} 391 #:changed "7.2.0.7" @elem{Added @DFlag{error-in} and @DFlag{error-out}.} 392 #:changed "7.2.0.8" @elem{Added @DFlag{recompile-only}.} 393 #:changed "7.9.0.3" @elem{Added @envvar{PLT_SETUP_NO_FORCE_GC}, 394 @envvar{PLT_SETUP_SHOW_TIMESTAMPS}, 395 and @DFlag{sync-docs-only}.}] 396 397@; ------------------------------------------------------------------------ 398 399@section[#:tag "raco-setup-A"]{Installing @filepath{.plt} Archives} 400 401A @filepath{.plt} file is a platform-independent distribution archive 402for software based on Racket. A typical @filepath{.plt} file can be 403installed as a package using @exec{raco pkg} (see @other-manual['(lib 404"pkg/scribblings/pkg.scrbl")]), in which case @exec{raco pkg} supplies 405facilities for uninstalling the package and managing dependencies. 406 407An older approach is to supply a @filepath{.plt} file to @exec{raco 408setup} with the @Flag{A} flag; the files contained in the 409@filepath{.plt} archive are unpacked (according to specifications 410embedded in the @filepath{.plt} file) and only collections specified 411by the @filepath{.plt} file are compiled and setup. Archives processed 412in this way can include arbitrary code that is executed at install 413time, in addition to any actions triggered by the normal 414collection-setup part of @exec{raco setup}. 415 416Finally, the @exec{raco unpack} (see @secref["unpack"]) command can 417list the content of a @filepath{.plt} archive or unpack the archive 418without installing it as a package or collection. 419 420@; ------------------------------------------------------------------------ 421 422@section[#:tag "setup-info"]{Controlling @exec{raco setup} with @filepath{info.rkt} Files} 423 424To compile a collection's files to bytecode, @exec{raco setup} uses the 425@racket[compile-collection-zos] procedure. That procedure, in turn, 426consults the collection's @filepath{info.rkt} file, if it exists, for 427specific instructions on compiling the collection. See 428@racket[compile-collection-zos] for more information on the fields of 429@filepath{info.rkt} that it uses, and see @secref["info.rkt"] for 430information on the format of an @filepath{info.rkt} file. 431 432Additional fields are used by the 433@seclink["top" #:doc '(lib "pkg/scribblings/pkg.scrbl") "Racket package manager"] 434and are documented in @secref["metadata" #:doc '(lib "pkg/scribblings/pkg.scrbl")]. 435The @exec{raco test} command also recognizes additional fields, which are 436documented in @secref["test-config-info" #:doc '(lib "scribblings/raco/raco.scrbl")]. 437 438Optional @filepath{info.rkt} fields trigger additional actions by 439@exec{raco setup}: 440 441@itemize[ 442 443 @item{@as-index{@racketidfont{scribblings}} : @racket[(listof (cons/c string? list?))] --- 444 A list of documents to build. Each document in the list is itself 445 represented as a list, where each document's list starts with a 446 string that is a collection-relative path to the document's source 447 file. A document name (which is derived from the source module's 448 name by default) is intended to be globally unique in the same way 449 as a package or module name. 450 451 More precisely a @racketidfont{scribblings} entry must be a value 452 that can be generated from an expression matching the following 453 @racket[_entry] grammar: 454 455 @racketgrammar*[ 456 #:literals (list) 457 [entry (list doc ...)] 458 [doc (list src-string) 459 (list src-string flags) 460 (list src-string flags category) 461 (list src-string flags category name) 462 (list src-string flags category name out-k) 463 (list src-string flags category name out-k order-n)] 464 [flags (list mode-symbol ...)] 465 [category (list category-string-or-symbol) 466 (list category-string-or-symbol sort-number)] 467 [name string 468 #f] 469 ] 470 471 A document's list optionally continues with information on how to 472 build the document. If a document's list contains a second item, 473 @racket[_flags], it must be a list of mode symbols (described 474 below). If a document's list contains a third item, 475 @racket[_category], it must be a list that categorizes the document 476 (described further below). If a document's list contains a fourth 477 item, @racket[_name], it is a name to use for the generated 478 documentation, instead of defaulting to the source file's name 479 (sans extension), where @racket[#f] means to use the default; a 480 non-@racket[#f] value for @racket[_name] must fit the grammar 481 of a collection-name element as checked by 482 @racket[collection-name-element?]. If a 483 document's list contains a fifth item, @racket[_out-k], it is used 484 a hint for the number of files to use for the document's 485 cross-reference information; see below. If a document's list 486 contains a fourth item, @racket[_order-n], it is used a hint for 487 the order of rendering; see below. 488 489 Each mode symbol in @racket[_flags] can be one of the following, 490 where only @racket['multi-page] is commonly used: 491 492 @itemize[ 493 494 @item{@racket['multi-page] : Generates multi-page HTML output, 495 instead of the default single-page format.} 496 497 @item{@racket['main-doc] : Indicates that the generated 498 documentation should be written into the main installation 499 directory, instead of to a user-specific directory. This 500 mode is the default for a collection that is itself located 501 in the main installation.} 502 503 @item{@racket['user-doc] : Indicates that the generated 504 documentation should be written a user-specific 505 directory. This mode is the default for a collection that 506 is not itself located in the main installation.} 507 508 @item{@racket['depends-all] : Indicates that the document should 509 be rebuilt if any other document is rebuilt---except for 510 documents that have the @racket['no-depend-on] flag.} 511 512 @item{@racket['depends-all-main] : Indicates that the document 513 should be rebuilt if any other document is rebuilt that is 514 installed into the main installation---except for documents 515 that have the @racket['no-depend-on] flag.} 516 517 @item{@racket['depends-all-user] : Indicates that the document 518 should be rebuilt if any other document is rebuilt that is 519 installed into the user's space---except for documents 520 that have the @racket['no-depend-on] flag.} 521 522 @item{@racket['always-run] : Build the document every time that 523 @exec{raco setup} is run, even if none of its dependencies 524 change.} 525 526 @item{@racket['no-depend-on] : Removes the document for 527 consideration for other dependencies. Furthermore, 528 references from the document to other documents are always 529 direct, instead of potentially indirect (i.e., resolved at 530 document-viewing time and potentially redirected to a 531 remote site).} 532 533 @item{@racket['main-doc-root] : Designates the root document for 534 the main installation. The document that currently has this 535 mode should be the only one with the mode.} 536 537 @item{@racket['user-doc-root] : Designates the root document for 538 the user-specific documentation directory. The document 539 that currently has this mode should be the only one with 540 the mode.} 541 542 @item{@racket['keep-style] : Leave the document's style as-is, 543 instead of imposing the document style for manuals.} 544 545 @item{@racket['no-search] : Build the document without a search 546 box.} 547 548 @item{@racket['every-main-layer] : With @racket['main-doc], 549 indicates that the document should be rendered separately 550 at every installation layer (see @secref["layered-install"]).} 551 552 ] 553 554 The @racket[_category] list specifies how to show the document in 555 the root table of contents. The list must start with a category, 556 which determines where the manual appears in the root 557 documentation page. A category is either a string or a symbol. If 558 it is a string, then the string is the category label on the root 559 page. If it is a symbol, then a default category label is 560 used. The available symbols and the order of categories on the 561 root documentation page is as below: 562 563 @itemize[ 564 565 @item{@racket['getting-started] : High-level, introductory 566 documentation, typeset at the same level as other 567 category titles.} 568 569 @item{@racket['language] : Documentation for a prominent 570 programming language.} 571 572 @item{@racket['tool] : Documentation for an executable.} 573 574 @item{@racket['gui-library] : Documentation for GUI and graphics 575 libraries.} 576 577 @item{@racket['net-library] : Documentation for networking 578 libraries.} 579 580 @item{@racket['parsing-library] : Documentation for parsing 581 libraries.} 582 583 @item{@racket['tool-library] : Documentation for programming-tool 584 libraries (i.e., not important enough for the more 585 prominent @racket['tool] category).} 586 587 @item{@racket['interop] : Documentation for interoperability 588 tools and libraries.} 589 590 @item{All string categories as ordered by @racket[string<=?].} 591 592 @item{@racket['library] : Documentation for libraries; this 593 category is the default and used for unrecognized category 594 symbols.} 595 596 @item{@racket['legacy] : Documentation for deprecated libraries, 597 languages, and tools.} 598 599 @item{@racket['experimental] : Documentation for an experimental 600 language or library.} 601 602 @item{@racket['other] : Other documentation.} 603 604 @item{@racket['omit] : Documentation that should not be listed on 605 the root page or indexed for searching.} 606 607 @item{@racket['omit-start] : Documentation that should not be 608 listed on the root page but should be indexed for 609 searching.} 610 611 ] 612 613 If the category list has a second element, it must be a real number 614 that designates the manual's sorting position with the category; 615 manuals with the same sorting position are ordered 616 alphabetically. For a pair of manuals with sorting numbers 617 @racket[_n] and @racket[_m], the groups for the manuals are 618 separated by space if @racket[(truncate (/ _n 10))]and 619 @racket[(truncate (/ _m 10))] are different. 620 621 The @racket[_out-k] specification is a hint on whether to break the 622 document's cross-reference information into multiple parts, which 623 can reduce the time and memory use for resolving a cross-reference 624 into the document. It must be a positive, exact integer, and the 625 default is @racket[1]. 626 627 The @racket[_order-n] specification is a hint for ordering document 628 builds, since documentation references can be mutually recursive. 629 The order hint can be any real number. A value of @racket[-10] or 630 less disables running the document in parallel to other documents. 631 The main Racket reference is given a value of @racket[-11], the 632 search page is given a value of @racket[10], and the default is 633 @racket[0]. 634 635 A directory for pre-rendered documentation is computed from the 636 source file name by starting with the directory of the 637 @filepath{info.rkt} file, adding @filepath{doc}, and then using the 638 document name (which is usually the source file's name without a 639 suffix); if such a directory exists and does not have a 640 @filepath{synced.rktd} file, then it is treated as pre-rendered 641 documentation and moved into place, in which case the documentation 642 source file need not be present. Moving documentation into place 643 may require no movement at all, depending on the way that the 644 enclosing collection is installed, but movement includes adding a 645 @filepath{synced.rktd} file to represent the installation. 646 647 @history[#:changed "6.4" @elem{Allow a category to be a string 648 instead of a symbol.}]} 649 650 @item{@as-index{@racketidfont{release-note-files}} : @racket[(listof (cons/c string? (cons/c string? list?)))] --- 651 A list of release-notes text files to link from the main documentation pages. 652 Each note is itself represented as a list, and the list can specify auxiliary 653 notes that are grouped with the main note. 654 655 A @racketidfont{release-note-files} entry must be a value 656 that can be generated from an expression matching the following 657 @racket[_entry] grammar: 658 659 @racketgrammar*[ 660 #:literals (list) 661 [entry (list note ...)] 662 [doc (list label-string note-path) 663 (list label-string note-path order-integer) 664 (list label-string note-path order-integer 665 (list sub-note ...))] 666 [sub-note (list label-string note-path)] 667 ] 668 669 The @racket[_order-integer] is used to order notes and defaults to @racket[0].} 670 671 @item{@indexed-racket[racket-launcher-names] : @racket[(listof string?)] 672 --- @elemtag["racket-launcher-names"] A list of executable names 673 to be generated in the installation's executable directory to run 674 Racket-based programs implemented by the collection. A parallel 675 list of library names must be provided by 676 @racket[racket-launcher-libraries] or 677 @racket[racket-launcher-flags]. 678 679 For each name, a launching executable is set up using 680 @racket[make-racket-launcher]. The arguments are @Flag{l-} and 681 @tt{@nonterm{colls}/.../@nonterm{file}}, where @nonterm{file} is 682 the file named by @racket[racket-launcher-libraries] and 683 @tt{@nonterm{colls}/...} are the collections (and subcollections) 684 of the @filepath{info.rkt} file. 685 686 In addition, 687 688 @racketblock[ 689 (build-aux-from-path 690 (build-path (collection-path #,(nonterm "colls") _...) #,(nonterm "suffixless-file"))) 691 ] 692 693 is provided for the optional @racket[_aux] argument (for icons, 694 etc.) to @racket[make-racket-launcher], where 695 @nonterm{suffixless-file} is @nonterm{file} without its suffix. 696 697 If @racket[racket-launcher-flags] is provided, it is used as a 698 list of command-line arguments passed to @exec{racket} instead of 699 the above default, allowing arbitrary command-line arguments. If 700 @racket[racket-launcher-flags] is specified together with 701 @racket[racket-launcher-libraries], then the flags will override 702 the libraries, but the libraries can still be used to specify a 703 name for @racket[build-aux-from-path] (to find related information 704 like icon files etc).} 705 706 @item{@indexed-racket[racket-launcher-libraries] : @racket[(listof 707 path-string?)] --- A list of library names in parallel to 708 @elemref["racket-launcher-names"]{@racket[racket-launcher-names]}.} 709 710 @item{@indexed-racket[racket-launcher-flags] : @racket[(listof string?)] 711 --- A list of command-line flag lists, in parallel to 712 @elemref["racket-launcher-names"]{@racket[racket-launcher-names]}.} 713 714 @item{@indexed-racket[mzscheme-launcher-names], 715 @racket[mzscheme-launcher-libraries], and 716 @racket[mzscheme-launcher-flags] --- Backward-compatible variant of 717 @racket[racket-launcher-names], etc.} 718 719 @item{@indexed-racket[gracket-launcher-names] : @racket[(listof string?)] --- 720 @elemtag["gracket-launcher-names"] Like 721 @elemref["racket-launcher-names"]{@racket[racket-launcher-names]}, 722 but for GRacket-based executables. The launcher-name list is treated 723 in parallel to @racket[gracket-launcher-libraries] and 724 @racket[gracket-launcher-flags].} 725 726 @item{@indexed-racket[gracket-launcher-libraries] : @racket[(listof path-string?)] 727 --- A list of library names in parallel to 728 @elemref["gracket-launcher-names"]{@racket[gracket-launcher-names]}.} 729 730 @item{@indexed-racket[gracket-launcher-flags] : @racket[(listof string?)] --- A 731 list of command-line flag lists, in parallel to 732 @elemref["gracket-launcher-names"]{@racket[gracket-launcher-names]}.} 733 734 @item{@indexed-racket[mred-launcher-names], 735 @racket[mred-launcher-libraries], and 736 @racket[mred-launcher-flags] --- Backward-compatible variant of 737 @racket[gracket-launcher-names], etc.} 738 739 @item{@indexed-racket[copy-foreign-libs] : @racket[(listof (and/c 740 path-string? relative-path?))] --- Files to copy into a 741 directory where foreign libraries are found by @racket[ffi-lib]. 742 If @racket[install-platform] is defined, then the files are copied 743 only if the current platform matches the definition. 744 745 On Mac OS, when a Mach-O file is copied, if the copied file 746 includes a library reference that starts @litchar{@"@"loader_path/}, 747 and if the referenced library exists in a different location among 748 the paths listed by @racket[(get-lib-search-dirs)], then the 749 library reference is updated to an absolute path. 750 751 On Unix, when an ELF file is copied, if the copied file includes an 752 RPATH setting of @litchar{$ORIGIN} and the file is being installed 753 to a user-specific location, then the file's RPATH is adjusted to 754 @litchar{$ORIGIN:} followed by the path to the main installation's 755 library directory as reported by @racket[(find-lib-dir)]. 756 757 On Windows, deleting a previously installed foreign library may be 758 complicated by a lock on the file, if it is in use. To compensate, 759 @exec{raco setup} deletes a foreign-library file by first renaming 760 the file to have the prefix @filepath{raco-setup-delete-}; it then 761 attempts to delete the renamed file and merely issues a warning on 762 a failure to delete the renamed file. Meanwhile, in modes where 763 @exec{raco setup} removes uninstalled libraries, it attempts to 764 delete any file in the foreign-library directory whose name starts 765 with @filepath{raco-setup-delete-} (in an attempt to clean up after 766 previous failures).} 767 768 @item{@indexed-racket[move-foreign-libs] : @racket[(listof (and/c 769 path-string? relative-path?))] --- Like @racket[copy-foreign-libs], 770 but the original file is removed after it is copied (which makes sense 771 for precompiled packages).} 772 773 @item{@indexed-racket[copy-shared-files] : @racket[(listof (and/c 774 path-string? relative-path?))] --- Files to copy into a 775 directory where shared files are found. 776 If @racket[install-platform] is defined, then the files are copied 777 only if the current platform matches the definition. 778 779 On Windows, uninstalled files are deleted in the same way as for 780 @racket[copy-foreign-libs], and the name prefix 781 @filepath{raco-setup-delete-} is similarly special.} 782 783 @item{@indexed-racket[move-shared-files] : @racket[(listof (and/c 784 path-string? relative-path?))] --- Like @racket[copy-shared-files], 785 but the original file is removed after it is copied (which makes sense 786 for precompiled packages).} 787 788 @item{@indexed-racket[copy-man-pages] : @racket[(listof (and/c 789 path-string? relative-path? filename-extension))] --- Files to copy 790 into a @tt{man} directory. The file suffix determines its category; 791 for example, @litchar{.1} should be used for a @tt{man} page 792 describing an executable. 793 794 On Windows, uninstalled files are deleted in the same way as for 795 @racket[copy-foreign-libs], and the name prefix 796 @filepath{raco-setup-delete-} is similarly special.} 797 798 @item{@indexed-racket[move-man-pages] : @racket[(listof (and/c 799 path-string? relative-path? filename-extension))] --- Like 800 @racket[copy-man-pages], but the original file is removed after it 801 is copied (which makes sense for precompiled packages).} 802 803 @item{@indexed-racket[install-platform] : @racket[platform-spec?] 804 --- Determines whether files are copied or moved 805 for @racket[copy-foreign-libs], @racket[move-foreign-libs], 806 @racket[copy-shared-files], or @racket[move-shared-files]. 807 See @racket[matching-platform?] for information on the way that the 808 specification is compared to @racket[(system-type)] 809 and @racket[(system-library-subpath #f)].} 810 811 @item{@indexed-racket[install-collection] : @racket[path-string?] --- 812 A library module relative to the collection that provides 813 @racket[installer]. The @racket[installer] procedure must accept 814 one, two, three, or four arguments: 815 816 @itemlist[ 817 818 @item{The first argument is a directory path to the parent of the 819 Racket installation's @filepath{collects} directory.} 820 821 @item{The second argument, if accepted, is a path to the 822 collection's own directory.} 823 824 @item{The third argument, if accepted, is a boolean indicating 825 whether the collection is installed as user-specific (@racket[#t]) 826 or installation-wide (@racket[#f]).} 827 828 @item{The fourth argument, if accepted, is a boolean indicating 829 whether the collection is installed as installation-wide and should 830 nevertheless avoid modifying the installation; an 831 @racket[installer] procedure that does not accept this argument is 832 never called when the argument would be @racket[#t]. An installer 833 that does accept this argument is called with @racket[#t] to that 834 it can perform user-specific work, even though the collection is 835 installed installation-wide.} 836 837 ]} 838 839 @item{@indexed-racket[pre-install-collection] : @racket[path-string?] --- 840 Like @racket[install-collection], except that the corresponding 841 installer procedures are called @emph{before} the normal @filepath{.zo} build, 842 instead of after. The provided procedure is 843 @racket[pre-installer], so it can be provided by the 844 same file that provides an @racket[installer] procedure.} 845 846 @item{@indexed-racket[post-install-collection] : @racket[path-string?] --- 847 Like @racket[install-collection] for a procedure that is called right after the 848 @racket[install-collection] procedure is executed. The 849 @DFlag{no-install} flag can be provided to @exec{raco setup} 850 to disable @racket[install-collection] and @racket[pre-install-collection], 851 but not @racket[post-install-collection]. The @racket[post-install-collection] 852 function is therefore expected to perform operations that are always needed, 853 even after an installation that contains pre-compiled files. The 854 provided procedure is @racket[post-installer], so it 855 can be provided by the same file that provides an 856 @racket[installer] procedure.} 857 858 @item{@indexed-racket[assume-virtual-sources] : @racket[any/c] --- 859 A true value indicates that bytecode files without a corresponding 860 source file should not be removed from @filepath{compiled} directories, 861 and no files should not be removed when the 862 @DFlag{clean} or @Flag{c} flag is passed to @exec{raco setup}.} 863 864 @item{@indexed-racket[clean] : @racket[(listof path-string?)] --- 865 @elemtag["clean"] A list of pathnames to be deleted when the 866 @DFlag{clean} or @Flag{c} flag is passed to @exec{raco setup}. The 867 pathnames must be relative to the collection. If any path names a 868 directory, each of the files in the directory are deleted, but none 869 of the subdirectories of the directory are checked. If the path 870 names a file, the file is deleted. The default, if this flag is not 871 specified, is to delete all files in the @filepath{compiled} 872 subdirectory, and all of the files in the platform-specific 873 subdirectory of the compiled directory for the current platform. 874 875 Just as compiling @filepath{.zo} files will compile each module 876 used by a compiled module, deleting a module's compiled image will 877 delete the @filepath{.zo} of each module that is used by the 878 module. More specifically, used modules are determined when 879 deleting a @filepath{.dep} file, which would have been created to 880 accompany a @filepath{.zo} file when the @filepath{.zo} was built 881 by @exec{raco setup} or @exec{raco make} (see 882 @secref["Dependency\x20Files"]). If the @filepath{.dep} file 883 indicates another module, that module's @filepath{.zo} is deleted 884 only if it also has an accompanying @filepath{.dep} file. In that 885 case, the @filepath{.dep} file is deleted, and additional used 886 modules are deleted based on the used module's @filepath{.dep} 887 file, etc. Supplying a specific list of collections to @exec{raco 888 setup} disables this dependency-based deletion of compiled files.} 889 890 @item{@racket[compile-omit-paths], @racket[compile-omit-files], and 891 @racket[compile-include-files] --- Used indirectly via 892 @racket[compile-collection-zos].} 893 894@item{@racket[module-suffixes] and @racket[doc-module-suffixes] --- 895 Used indirectly via @racket[get-module-suffixes].} 896 897] 898 899@; ------------------------------------------------------------------------ 900 901@include-section["info.scrbl"] 902 903@; ------------------------------------------------------------------------ 904 905@section[#:tag "setup-check-deps"]{Package Dependency Checking} 906 907When @exec{raco setup} is run with no arguments,@margin-note*{Unless 908@DFlag{check-pkg-deps} is specified, dependency checking is disabled 909if any collection is specified for @exec{raco setup}.} after building 910all collections and documentation, @exec{raco setup} checks package 911dependencies. Specifically, it inspects compiled files and 912documentation to check that references across package boundaries are 913reflected by dependency declarations in each package-level 914@filepath{info.rkt} file (see @secref[#:doc pkg-doc "metadata"]). 915 916Dependency checking in @exec{raco setup} is intended as an aid to 917package developers to help them declare dependencies correctly. The 918@exec{raco setup} process itself does not depend on package dependency 919declarations. Similarly, a package with a missing dependency 920declaration may install successfully for other users, as long as they 921happen to have the dependencies installed already. A missing 922dependency creates trouble for others who install a package without 923having the dependency installed already. 924 925Practically every package depends on the @filepath{base} package, 926which includes the collections that are in a minimal variant of 927Racket. Declaring a dependency on @filepath{base} may seem 928unnecessary, since its collections are always installed. In a future 929version of Racket, however, the minimal collections may change, and 930the new set of minimal collections will then have a package name, such 931as @filepath{base2}. Declaring a dependency on @filepath{base} ensures 932forward compatibility, and @exec{raco setup} complains if the 933declaration is missing. 934 935To accommodate the early stages of package development, missing 936dependencies are not treated as an error for a package that has no 937dependency declarations. 938 939@subsection{Declaring Build-Time Dependencies} 940 941A build-time dependency is one that is not present in a package if it 942is converted to a @tech[#:doc pkg-doc]{binary package} (see 943@secref[#:doc pkg-doc "strip"]). For example, @filepath{tests} and 944@filepath{scribblings} directories are stripped away in a binary 945package by default, so cross-package references from directories with 946those names are treated as build dependencies. Similarly, 947@racketidfont{test} and @racketidfont{doc} submodules are stripped 948away, so references within those submodules create build dependencies. 949 950Build-time-only dependencies can be listed as @racket[build-deps] 951instead of @racket[deps] in a package's @filepath{info.rkt} file. 952Dependencies listed in @racket[deps], meanwhile, are treated as both 953run-time and build-time dependencies. The advantage of using 954@racket[build-deps], instead of listing all dependencies in 955@racket[deps], is that a binary version of the package can install 956with fewer dependencies. 957 958@subsection{How Dependency Checking Works} 959 960Dependency checking uses @filepath{.zo} files, associated 961@filepath{.dep} files (see @secref["Dependency Files"]), and the 962documentation index. Dynamic references, such as through 963@racket[dynamic-require], are not visible to the dependency checker; 964only dependencies via @racket[require], 965@racket[define-runtime-module-path-index], and other forms that 966cooperate with @racket[raco make] are visible for dependency checking. 967 968Dependency checking is sensitive to whether a dependency is needed 969only as a build-time dependency. If @exec{raco setup} detects that a 970missing dependency could be added as a build-time dependency, it will 971suggest the addition, but @exec{raco setup} will not suggest 972converting a normal dependency to a build-time dependency (since every 973normal dependency counts as a build-time dependency, too). 974 975@; ------------------------------------------------------------------------ 976 977@section[#:tag "setup-plt-plt"]{API for Setup} 978 979@defmodule[setup/setup] 980 981@defproc[(setup [#:file file (or/c #f path-string?) #f] 982 [#:collections collections (or/c #f (listof (listof path-string?))) #f] 983 [#:pkgs pkgs (or/c #f (listof string?)) #f] 984 [#:planet-specs planet-specs (or/c #f 985 (listof (list/c string? 986 string? 987 exact-nonnegative-integer? 988 exact-nonnegative-integer?))) 989 #f] 990 [#:make-user? make-user? any/c #t] 991 [#:avoid-main? avoid-main? any/c #f] 992 [#:make-docs? make-docs? any/c #t] 993 [#:make-doc-index? make-doc-index? any/c #f] 994 [#:force-user-docs? force-user-docs? any/c #f] 995 [#:check-pkg-deps? check-pkg-deps? any/c #f] 996 [#:fix-pkg-deps? fix-pkg-deps? any/c #f] 997 [#:unused-pkg-deps? unused-pkg-deps? any/c #f] 998 [#:clean? clean? any/c #f] 999 [#:tidy? tidy? any/c #f] 1000 [#:recompile-only? recompile-only? any/c #f] 1001 [#:jobs jobs exact-nonnegative-integer? #f] 1002 [#:fail-fast? fail-fast? any/c #f] 1003 [#:get-target-dir get-target-dir (or/c #f (-> path-string?)) #f]) 1004 boolean?]{ 1005Runs @exec{raco setup} with various options: 1006 1007@itemlist[ 1008 1009 @item{@racket[file] --- if not @racket[#f], installs @racket[file] as 1010 a @filepath{.plt} archive.} 1011 1012 @item{@racket[collections] --- if not @racket[#f], constrains setup to 1013 the named collections (along with @racket[pkgs] and 1014 @racket[planet-specs], if any)} 1015 1016 @item{@racket[pkgs] --- if not @racket[#f], constrains setup to the 1017 named packages (along with @racket[collections] and 1018 @racket[planet-specs], if any)} 1019 1020 @item{@racket[planet-spec] --- if not @racket[#f], constrains setup to 1021 the named @|PLaneT| packages (along with @racket[collections] and 1022 @racket[pkgs], if any)} 1023 1024 @item{@racket[make-user?] --- if @racket[#f], disables any 1025 user-specific setup actions} 1026 1027 @item{@racket[avoid-main?] --- if true, avoids setup actions that affect 1028 the main installation, as opposed to user directories} 1029 1030 @item{@racket[make-docs?] --- if @racket[#f], disables any 1031 documentation-specific setup actions} 1032 1033 @item{@racket[make-doc-index?] --- if true, builds 1034 documentation index collections in addition to @racket[collections], 1035 assuming that documentation is built} 1036 1037 @item{@racket[force-user-docs?] --- if true, then when building 1038 documentation, creates a user-specific documentation entry point 1039 even if it has the same content as the installation} 1040 1041 @item{@racket[check-pkg-deps?] --- if true, enables 1042 package-dependency checking even when @racket[collections], 1043 @racket[pkgs], or @racket[planet-specs] is non-@racket[#f].} 1044 1045 @item{@racket[fix-pkg-deps?] --- if true, implies 1046 @racket[check-pkg-deps?] and attempts to automatically correct 1047 discovered package-dependency problems} 1048 1049 @item{@racket[unused-pkg-deps?] --- if true, implies 1050 @racket[check-pkg-deps?] and also reports dependencies that 1051 appear to be unused} 1052 1053 @item{@racket[clean?] --- if true, enables cleaning mode instead of setup mode} 1054 1055 @item{@racket[tidy?] --- if true, enables global tidying of 1056 documentation and metadata indexes even when @racket[collections] 1057 or @racket[planet-specs] is non-@racket[#f]} 1058 1059 @item{@racket[recompile-only?] --- if true, disallows compilation 1060 from source, allowing only timestamp adjustments and recompilation 1061 from machine-independent form} 1062 1063 @item{@racket[jobs] --- if not @racket[#f], determines the maximum number of parallel 1064 tasks used for setup} 1065 1066 @item{@racket[fail-fast?] --- if true, breaks the current thread as soon as an 1067 error is discovered} 1068 1069 @item{@racket[get-target-dir] --- if not @racket[#f], treated as a 1070 value for @sigelem[setup-option^ current-target-directory-getter]} 1071 1072] 1073 1074The result is @racket[#t] if @exec{raco setup} completes without error, 1075@racket[#f] otherwise. 1076 1077Instead of using @envvar{PLT_COMPILED_FILE_CHECK}, @racket[setup] is 1078sensitive to the @racket[use-compiled-file-check] parameter. 1079 1080@history[#:changed "6.1" @elem{Added the @racket[fail-fast?] argument.} 1081 #:changed "6.1.1" @elem{Added the @racket[force-user-docs?] argument.} 1082 #:changed "7.2.0.7" @elem{Added the @racket[check-pkg-deps?], 1083 @racket[fix-pkg-deps?] , and @racket[unused-pkg-deps?] 1084 arguments.} 1085 #:changed "7.2.0.8" @elem{Added the @racket[recompile-only?] argument.}]} 1086 1087 1088 1089@subsection{@exec{raco setup} Unit} 1090 1091@defmodule[setup/setup-unit] 1092 1093The @racketmodname[setup/setup-unit] library provides @exec{raco setup} in unit 1094form. The associated @racket[setup/option-sig] and 1095@racket[setup/option-unit] libraries provides the interface for 1096setting options for the run of @exec{raco setup}. 1097 1098For example, to unpack a single @filepath{.plt} archive 1099@filepath{x.plt}, set the @sigelem[setup-option^ archives] parameter 1100to @racket[(list "x.plt")] and leave @sigelem[setup-option^ 1101specific-collections] as @racket[null]. 1102 1103Link the options and setup units so that your option-setting code is 1104initialized between them, e.g.: 1105 1106@racketblock[ 1107(compound-unit 1108 _... 1109 (link _... 1110 [((OPTIONS : setup-option^)) setup:option@] 1111 [() my-init-options@ OPTIONS] 1112 [() setup@ OPTIONS _...]) 1113 _...) 1114] 1115 1116@defthing[setup@ unit?]{ 1117 1118Imports 1119 1120 @itemize[#:style "compact"]{ 1121 @item{@racket[setup-option^]} 1122 @item{@racket[compiler^]} 1123 @item{@racket[compiler:option^]} 1124 @item{@racket[launcher^]} 1125 @item{@racket[dynext:file^]} 1126 } 1127 1128and exports nothing. Invoking @racket[setup@] starts the setup process.} 1129 1130@; ---------------------------------------- 1131 1132@subsection[#:tag "setup-plt-options"]{Options Unit} 1133 1134@defmodule[setup/option-unit] 1135 1136@defthing[setup:option@ unit?]{ 1137 1138Imports nothing and exports @racket[setup-option^].} 1139 1140@; ---------------------------------------- 1141 1142@subsection{Options Signature} 1143 1144@defmodule[setup/option-sig] 1145 1146@defsignature[setup-option^ ()]{ 1147 1148@signature-desc{Provides parameters used to control @exec{raco setup} in unit 1149form.} 1150 1151 @defparam[setup-program-name name string?]{ 1152 The prefix used when printing status messages. 1153 @defaults[@racket["raco setup"]] 1154 } 1155 1156@defparam[setup-compiled-file-paths paths (or/c #f (listof (and/c path? relative-path?)))]{ 1157 If not @racket[#f], supplies a value like the one for @racket[use-compiled-file-paths] 1158 to control operations such as cleaning, where @racket[use-compiled-file-paths] 1159 may have been set to @racket[null] to avoid loading bytecode. 1160 1161 @history[#:added "1.7"]} 1162 1163@defboolparam[verbose on?]{ 1164 If on, prints messages from @exec{make} to @envvar{stderr}. 1165 @defaults[@racket[#f]]} 1166 1167@defboolparam[make-verbose on?]{ 1168 If on, verbose @exec{make}. @defaults[@racket[#f]]} 1169 1170@defboolparam[compiler-verbose on?]{ 1171 If on, verbose @exec{compiler}. @defaults[@racket[#f]]} 1172 1173@defboolparam[clean on?]{ 1174 If on, delete @filepath{.zo} and 1175 @filepath{.so}/@filepath{.dll}/@filepath{.dylib} files in the 1176 specified collections. @defaults[@racket[#f]]} 1177 1178@defparam[compile-mode path (or/c path? #f)]{ 1179 If a @racket[path] is given, use a @filepath{.zo} compiler other than plain 1180 @exec{compile}, and build to @racket[(build-path "compiled" (compile-mode))]. 1181 @defaults[@racket[#f]]} 1182 1183@defboolparam[make-zo on?]{ 1184 If on, compile @filepath{.zo}. @defaults[@racket[#t]]} 1185 1186@defboolparam[make-info-domain on?]{ 1187 If on, update @filepath{info-domain/compiled/cache.rkt} for each 1188 collection path. @defaults[@racket[#t]]} 1189 1190@defboolparam[make-launchers on?]{ 1191 If on, make collection @filepath{info.rkt}-specified launchers and @tt{man} pages. @defaults[@racket[#t]]} 1192 1193@defboolparam[make-foreign-lib on?]{ 1194 If on, install collection @filepath{info.rkt}-specified libraries. @defaults[@racket[#t]]} 1195 1196 @defboolparam[make-docs on?]{ 1197 If on, build documentation. 1198 @defaults[@racket[#t]] 1199 } 1200 1201 @defboolparam[make-user on?]{ 1202 If on, build the user-specific collection tree. 1203 @defaults[@racket[#t]] 1204 } 1205 1206 @defboolparam[make-planet on?]{ 1207 If on, build the planet cache. 1208 @defaults[@racket[#t]] 1209 } 1210 1211@defboolparam[avoid-main-installation on?]{ 1212 If on, avoid building bytecode in the main installation tree when building 1213 other bytecode (e.g., in a user-specific collection). @defaults[@racket[#f]]} 1214 1215@defboolparam[make-tidy on?]{ 1216 If on, remove metadata cache information and 1217 documentation for non-existent collections (to clean up after removal) 1218 even when @racket[specific-collections] or @racket[specific-planet-dirs] 1219 is non-@racket['()] or @racket[make-only] is true. @defaults[@racket[#f]]} 1220 1221@defboolparam[call-install on?]{ 1222 If on, call collection @filepath{info.rkt}-specified setup code. 1223 @defaults[@racket[#t]]} 1224 1225@defboolparam[call-post-install on?]{ 1226 If on, call collection @filepath{info.rkt}-specified post-install code. 1227 @defaults[@racket[#t]]} 1228 1229@defboolparam[pause-on-errors on?]{ 1230 If on, in the event of an error, prints a summary error and waits for 1231 @envvar{stdin} input before terminating. @defaults[@racket[#f]]} 1232 1233 @defparam[parallel-workers num exact-nonnegative-integer?]{ 1234 Determines the number of places to use for compiling bytecode 1235 and for building the documentation. 1236 @defaults[@racket[(min (processor-count) 8)]] 1237 } 1238 1239@defboolparam[fail-fast on?]{ 1240 If on, breaks the original thread as soon as an error is discovered. 1241 @defaults[@racket[#f]] 1242 1243 @history[#:added "1.2"]} 1244 1245@defboolparam[force-unpacks on?]{ 1246 If on, ignore version and already-installed errors when unpacking a 1247 @filepath{.plt} archive. @defaults[@racket[#f]]} 1248 1249@defparam[specific-collections colls (listof (listof path-string?))]{ 1250 A list of collections to set up; the empty list means set-up all 1251 collections if the archives list and @racket[specific-planet-dirs] 1252 is also @racket['()]. @defaults[@racket['()]]} 1253 1254 @defparam[specific-planet-dirs dir (listof (list/c string? 1255 string? 1256 exact-nonnegative-integer? 1257 exact-nonnegative-integer?))]{ 1258 A list of planet package version specs to set up; the empty list means to 1259 set-up all planet collections if the archives list and @racket[specific-collections] 1260 is also @racket['()]. @defaults[@racket['()]] 1261 } 1262 1263@defboolparam[make-only on?]{ 1264 If true, set up no collections if @racket[specific-collections] 1265 and @racket[specific-planet-dirs] are both @racket['()].} 1266 1267@defparam[archives arch (listof path-string?)]{ 1268 A list of @filepath{.plt} archives to unpack; any collections specified 1269 by the archives are set-up in addition to the collections listed in 1270 specific-collections. @defaults[@racket[null]]} 1271 1272@defboolparam[archive-implies-reindex on?]{ 1273 If on, when @racket[archives] has a non-empty list of packages, if any 1274 documentation is built, then suitable documentation start pages, search pages, 1275 and master index pages are rebuilt. @defaults[@racket[#t]]} 1276 1277@defparam[current-target-directory-getter thunk (-> path-string?)]{ 1278 A thunk that returns the target directory for unpacking a relative 1279 @filepath{.plt} archive; when unpacking an archive, either this or 1280 the procedure in @racket[current-target-plt-directory-getter] will 1281 be called. @defaults[@racket[current-directory]]} 1282 1283@defparam[current-target-plt-directory-getter 1284 proc (path-string? 1285 path-string? 1286 (listof path-string?) . -> . path-string?)]{ 1287 A procedure that takes a preferred path, a path to the parent of the main 1288 @filepath{collects} directory, and a list of path choices; it returns 1289 a path for a "plt-relative" install; when unpacking an archive, either 1290 this or the procedure in @racket[current-target-directory-getter] will 1291 be called, and in the former case, this procedure may be called 1292 multiple times. @defaults[@racket[(lambda (preferred main-parent-dir choices) preferred)]]} 1293 1294} 1295 1296@; ---------------------------------------- 1297 1298@subsection{Setup Start Module} 1299 1300@defmodule[setup]{The @racketmodname[setup] library implements 1301@exec{raco setup}, including the part that bootstraps @exec{raco setup} 1302if its own implementation needs to be compiled.} 1303 1304When running @racketmodname[setup] via @exec{racket}, supply the 1305@exec{@Flag{N} raco} to ensure that command-line arguments are parsed 1306the same way as for @exec{raco setup}, as opposed to a legacy 1307command-line mode. 1308 1309@; ------------------------------------------------------------------------ 1310 1311@section[#:tag ".plt-archives"]{API for Installing @filepath{.plt} Archives} 1312 1313The @racketmodname[setup/plt-single-installer] module provides a 1314function for installing a single @filepath{.plt} file. 1315 1316@subsection{Non-GUI Installer} 1317 1318@local-module[setup/plt-single-installer]{ 1319 1320@defmodule[setup/plt-single-installer] 1321 1322@defproc[(run-single-installer 1323 (file path-string?) 1324 (get-dir-proc (-> (or/c path-string? #f))) 1325 [#:show-beginning-of-file? show-beginning-of-file? any/c #f]) 1326 void?]{ 1327 Creates a separate thread and namespace, runs the installer in that 1328 thread with the new namespace, and returns when the thread 1329 completes or dies. It also creates a custodian 1330 (see @secref[#:doc ref-src]{custodians}) to manage the 1331 created thread, sets the exit handler for the thread to shut down 1332 the custodian, and explicitly shuts down the custodian 1333 when the created thread terminates or dies. 1334 1335 The @racket[get-dir-proc] procedure is called if the installer needs a 1336 target directory for installation, and a @racket[#f] result means that 1337 the user canceled the installation. Typically, @racket[get-dir-proc] is 1338 @racket[current-directory]. 1339 1340 If @racket[show-beginning-of-file?] is a true value and the installation 1341 fails, then @racket[run-single-installer] prints the first 1,000 characters 1342 of the file (in an attempt to help debug the cause of failures). 1343} 1344 1345@defproc[(install-planet-package [file path-string?] 1346 [directory path-string?] 1347 [spec (list/c string? string? 1348 (listof string?) 1349 exact-nonnegative-integer? 1350 exact-nonnegative-integer?)]) 1351 void?]{ 1352 1353 Similar to @racket[run-single-installer], but runs the setup process 1354 to install the archive @racket[file] into @racket[directory] as the 1355 @|PLaneT| package described by @racket[spec]. The user-specific 1356 documentation index is not rebuilt, so @racket[reindex-user-documentation] 1357 should be run after a set of @|PLaneT| packages are installed.} 1358 1359@defproc[(reindex-user-documentation) void?]{ 1360 Similar to @racket[run-single-installer], but runs only the part of 1361 the setup process that rebuilds the user-specific documentation 1362 start page, search page, and master index.} 1363 1364@defproc[(clean-planet-package [directory path-string?] 1365 [spec (list/c string? string? 1366 (listof string?) 1367 exact-nonnegative-integer? 1368 exact-nonnegative-integer?)]) 1369 void?]{ 1370 Undoes the work of @racket[install-planet-package]. The user-specific 1371 documentation index is not rebuilt, so @racket[reindex-user-documentation] 1372 should be run after a set of @|PLaneT| packages are removed.}} 1373 1374 1375@; ---------------------------------------------------------- 1376 1377@section[#:tag "dirs"]{API for Finding Installation Directories} 1378 1379@defmodule[setup/dirs]{ The @racketmodname[setup/dirs] library 1380 provides several procedures for locating installation directories. 1381 Many of these paths can be configured through the 1382 @tech{configuration directory} (see @secref["config-file"]).} 1383 1384In cross-platform build mode (see @secref["cross-system"]), the 1385functions provided by @racketmodname[setup/dirs] generally report 1386target-system paths, instead of current-system paths. The exceptions are 1387@racket[get-lib-search-dirs] and @racket[find-dll-dir], which report 1388current-system paths while @racket[get-cross-lib-search-dirs] and 1389@racket[find-cross-dll-dir] report target-system paths. 1390 1391@(define-syntax-rule (see-config id) 1392 @elem{See also @racket['id] in @secref["config-file"].}) 1393 1394@defproc[(find-collects-dir) (or/c path? #f)]{ 1395 Returns a path to the installation's main @filepath{collects} directory, or 1396 @racket[#f] if none can be found. A @racket[#f] result is likely only 1397 in a stand-alone executable that is distributed without libraries.} 1398 1399@(define-syntax user-path 1400 (syntax-rules () 1401 [(_ dir vers) 1402 @list{The user-specific path depends on at least 1403 @racket[(find-system-path 'addon-dir)] and 1404 @racket[vers].}] 1405 [(_ dir) 1406 (user-path dir (get-installation-name))])) 1407 1408@defproc[(find-user-collects-dir) path?]{ 1409 Returns a path to the user-specific @filepath{collects} directory; the 1410 directory indicated by the returned path may or may not exist. 1411 1412 @user-path["collects"]} 1413 1414@defproc[(get-collects-search-dirs) (listof path?)]{ 1415 Returns the same result as @racket[(current-library-collection-paths)], 1416 which means that this result is not sensitive to the value of the 1417 @racket[use-user-specific-search-paths] parameter.} 1418 1419@defproc[(get-main-collects-search-dirs) (listof path?)]{ 1420 Returns a list of paths to installation @filepath{collects} 1421 directories, normally including the result of @racket[find-collects-dir]. 1422 These directories are normally included in the result of 1423 @racket[(current-library-collection-paths)], but a 1424 @envvar{PLTCOLLECTS} setting or change to the parameter may cause 1425 them to be omitted. Any other path in 1426 @racket[(current-library-collection-paths)] is treated as 1427 user-specific. The directories indicated by the returned paths may 1428 or may not exist. 1429 1430 The main-collections search path can be configured via 1431 @racket['collects-search-dirs] in @filepath{config.rktd} (see 1432 @secref["config-file"]).} 1433 1434@defproc[(find-config-dir) (or/c path? #f)]{ 1435 Returns a path to the installation's @filepath{etc} directory, which 1436 contains configuration and package information---including 1437 configuration of some of the other directories (see @secref["config-file"]). 1438 A @racket[#f] result indicates that no configuration directory 1439 is available.} 1440 1441@defproc[(find-links-file) (or/c path? #f)]{ 1442 Returns a path to the installation's @tech[#:doc 1443 reference-doc]{collection links file}. The file indicated by the 1444 returned path may or may not exist. A @racket[#f] result indicates 1445 that no links file is available. 1446 1447 @see-config[links-file]} 1448 1449@defproc[(find-user-links-file [vers string? (get-installation-name)]) path?]{ 1450 Returns a path to the user's @tech[#:doc reference-doc]{collection 1451 links file}. The file indicated by the returned path may or may not 1452 exist. 1453 1454 @user-path["links.rktd" vers]} 1455 1456@defproc[(get-links-search-files) (listof path?)]{ 1457 Returns a list of paths to installation @tech[#:doc 1458 reference-doc]{collection links files} to search in 1459 order. (Normally, the result includes the result of 1460 @racket[(find-links-file)], which is where new installation-wide 1461 links are installed by @exec{raco link} or @racket[links].) The 1462 result of @racket[find-user-links-file] 1463 is @emph{not} added to the returned list. The 1464 files indicated by the returned paths may or may not exist. 1465 1466 @see-config[links-search-files]} 1467 1468@defproc[(find-pkgs-dir) (or/c path? #f)]{ 1469 Returns a path to the directory containing packages with 1470 installation scope; the directory indicated by the returned path may 1471 or may not exist. A @racket[#f] result indicates that no package-installation 1472 directory is available. 1473 1474 @see-config[pkgs-dir]} 1475 1476@defproc[(find-user-pkgs-dir [vers string? (get-installation-name)]) path?]{ 1477 Returns a path to the directory containing packages with 1478 user-specific scope for installation name @racket[vers]; the directory indicated by 1479 the returned path may or may not exist. 1480 1481 @user-path["pkgs" vers]} 1482 1483@defproc[(get-pkgs-search-dirs) (listof path?)]{ 1484 Returns a list of paths to the directories containing packages in 1485 installation scope. (Normally, the result includes the result of 1486 @racket[(find-pkgs-dir)], which is where new packages are installed 1487 by @exec{raco pkg install}.) The result of @racket[find-user-pkgs-dir] 1488 is @emph{not} added to the returned list. The directories indicated by the returned 1489 paths may or may not exist. 1490 1491 @see-config[pkgs-search-dirs]} 1492 1493@defproc[(find-doc-dir) (or/c path? #f)]{ 1494 Returns a path to the installation's @filepath{doc} directory. 1495 The result is @racket[#f] if no such directory is available. 1496 1497 @see-config[doc-dir]} 1498 1499@defproc[(find-user-doc-dir) path?]{ 1500 Returns a path to a user-specific @filepath{doc} directory. The directory 1501 indicated by the returned path may or may not exist. 1502 1503 @user-path["doc"]} 1504 1505@defproc[(get-doc-search-dirs) (listof path?)]{ 1506 Returns a list of paths to search for documentation, not including 1507 documentation stored in individual collections. Unless it is 1508 configured otherwise, the result includes any non-@racket[#f] result of 1509 @racket[(find-doc-dir)] and @racket[(find-user-doc-dir)]---but the latter is 1510 included only if the value of the @racket[use-user-specific-search-paths] 1511 parameter is @racket[#t]. 1512 1513 @see-config[doc-search-dirs]} 1514 1515@defproc[(get-doc-extra-search-dirs) (listof path?)]{ 1516 Like @racket[get-doc-search-dirs], but refrains from adding 1517 @racket[(find-doc-dir)] and @racket[(find-user-doc-dir)] to the 1518 underlying @racket['doc-search-dirs] configuration. 1519 1520 @history[#:added "8.1.0.6"]} 1521 1522@defproc[(find-lib-dir) (or/c path? #f)]{ 1523 Returns a path to the installation's @filepath{lib} directory, which contains 1524 libraries and other build information. The result is @racket[#f] if no such 1525 directory is available. 1526 1527 @see-config[lib-dir]} 1528 1529@defproc[(find-user-lib-dir) path?]{ 1530 Returns a path to a user-specific @filepath{lib} directory; the directory 1531 indicated by the returned path may or may not exist. 1532 1533 @user-path["lib"]} 1534 1535@defproc[(get-lib-search-dirs) (listof path?)]{ 1536 Returns a list of paths to search for foreign libraries. 1537 1538 Unless it is configured otherwise, and except in cross-platform 1539 build mode, the result includes any non-@racket[#f] result of 1540 @racket[(find-lib-dir)] and @racket[(find-user-lib-dir)]---but the 1541 latter is included only if the value of the 1542 @racket[use-user-specific-search-paths] parameter is @racket[#t]. 1543 1544 In cross-platform build mode (see @secref["cross-system"]), 1545 @racket[get-lib-search-dirs] reports a result suitable for the 1546 current system, instead of the target system. See also 1547 @racket[get-cross-lib-search-dirs]. 1548 1549 @see-config[lib-search-dirs] 1550 1551 @history[#:changed "6.1.1.4" @elem{Dropped @racket[(find-dll-dir)] 1552 from the set of paths to 1553 explicitly include in the 1554 default.} 1555 #:changed "6.9.0.1" @elem{Changed behavior in cross-platform build mode.}]} 1556 1557@defproc[(get-cross-lib-search-dirs) (listof path?)]{ 1558 Like @racket[get-lib-search-dirs], but in cross-platform build mode, 1559 reports directories for the target system (including any 1560 non-@racket[#f] result of @racket[(find-lib-dir)], etc.) 1561 instead of the current system. 1562 1563 @history[#:added "6.9.0.1"]} 1564 1565@defproc[(get-cross-lib-extra-search-dirs) (listof path?)]{ 1566 Like @racket[get-cross-lib-search-dirs], but refrains from adding 1567 @racket[(find-lib-dir)] and @racket[(find-user-lib-dir)] to the 1568 underlying @racket['lib-search-dirs] configuration. 1569 1570 @history[#:added "8.1.0.6"]} 1571 1572@defproc[(find-dll-dir) (or/c path? #f)]{ 1573 Returns a path to the directory that contains DLLs for use with the 1574 current executable (e.g., @filepath{libracket.dll} on Windows). 1575 The result is @racket[#f] if no such directory is available, or if no 1576 specific directory is available (i.e., other than the platform's normal 1577 search path). 1578 1579 In cross-platform build mode (see @secref["cross-system"]), 1580 @racket[find-dll-dir] reports a result suitable for the current 1581 system, instead of the target system. See also 1582 @racket[find-cross-dll-dir]. 1583 1584 @history[#:changed "6.9.0.1" @elem{Changed behavior in cross-platform build mode.}]} 1585 1586@defproc[(find-cross-dll-dir) (or/c path? #f)]{ 1587 Like @racket[find-dll-dir], but in cross-platform build mode, 1588 reports a directory for the target system 1589 instead of the current system. 1590 1591 @history[#:added "6.9.0.1"]} 1592 1593@defproc[(find-share-dir) (or/c path? #f)]{ Returns a path to the 1594 installation's @filepath{share} directory, which contains installed 1595 packages and other platform-independent files. The result is 1596 @racket[#f] if no such directory is available. 1597 1598 @see-config[share-dir]} 1599 1600@defproc[(find-user-share-dir) path?]{ 1601 Returns a path to a user-specific @filepath{share} directory; the directory 1602 indicated by the returned path may or may not exist. 1603 1604 @user-path["share"]} 1605 1606@defproc[(get-share-search-dirs) (listof path?)]{ 1607 Returns a list of paths to search for files that are normally in a 1608 @filepath{share} directory. 1609 1610 Unless it is configured otherwise, the result includes any 1611 non-@racket[#f] result of @racket[(find-share-dir)] and 1612 @racket[(find-user-share-dir)]---but the latter is included only if 1613 the value of the @racket[use-user-specific-search-paths] parameter 1614 is @racket[#t]. 1615 1616 @see-config[share-search-dirs] 1617 1618 @history[#:added "8.1.0.6"]} 1619 1620@defproc[(get-share-extra-search-dirs) (listof path?)]{ 1621 Like @racket[get-share-search-dirs], but refrains from adding 1622 @racket[(find-share-dir)] and @racket[(find-user-share-dir)] to the 1623 underlying @racket['share-search-dirs] configuration. 1624 1625 @history[#:added "8.1.0.6"]} 1626 1627@defproc[(find-include-dir) (or/c path? #f)]{ 1628 Returns a path to the installation's @filepath{include} directory, which 1629 contains @filepath{.h} files for building Racket extensions and embedding 1630 programs. The result is @racket[#f] if no such directory is available. 1631 1632 @see-config[include-dir]} 1633 1634@defproc[(find-user-include-dir) path?]{ 1635 Returns a path to a user-specific @filepath{include} directory; the 1636 directory indicated by the returned path may or may not exist. 1637 1638 @user-path["include"]} 1639 1640@defproc[(get-include-search-dirs) (listof path?)]{ 1641 Returns a list of paths to search for @filepath{.h} files. Unless it is 1642 configured otherwise, the result includes any non-@racket[#f] result of 1643 @racket[(find-include-dir)] and @racket[(find-user-include-dir)]---but the 1644 latter is included only if the value of the 1645 @racket[use-user-specific-search-paths] parameter is @racket[#t]. 1646 1647 @see-config[include-search-dirs]} 1648 1649@defproc[(find-console-bin-dir) (or/c path? #f)]{ 1650 Returns a path to the installation's executable directory, where the 1651 stand-alone Racket executable resides. The result is @racket[#f] if no 1652 such directory is available. 1653 1654 @see-config[bin-dir]} 1655 1656@defproc[(find-gui-bin-dir) (or/c path? #f)]{ 1657 Returns a path to the installation's executable directory, where the 1658 stand-alone GRacket executable resides. The result is @racket[#f] if no such 1659 directory is available. 1660 1661 @see-config[gui-bin-dir]} 1662 1663@defproc[(find-user-console-bin-dir) path?]{ 1664 Returns a path to the user's executable directory; the directory 1665 indicated by the returned path may or may not exist. 1666 1667 @user-path[#f]} 1668 1669@defproc[(find-user-gui-bin-dir) path?]{ 1670 Returns a path to the user's executable directory for graphical 1671 programs; the directory indicated by the returned path may or may 1672 not exist. 1673 1674 @user-path[#f]} 1675 1676@defproc[(get-console-bin-search-dirs) (listof path?)]{ 1677 Analogous to @racket[get-share-search-dirs], but for paths to search 1678 for executables such as @exec{racket}. 1679 1680 @see-config[bin-search-dirs] 1681 1682 @history[#:added "8.1.0.6"]} 1683 1684@defproc[(get-console-bin-extra-search-dirs) (listof path?)]{ 1685 Analogous to @racket[get-share-extra-search-dirs] for the underlying 1686 @racket['bin-search-dirs] configuration. 1687 1688 @history[#:added "8.1.0.6"]} 1689 1690@defproc[(get-gui-bin-search-dirs) (listof path?)]{ 1691 Analogous to @racket[get-share-search-dirs], but for paths to search 1692 for executables such as @exec{gracket}. 1693 1694 @see-config[gui-bin-search-dirs] 1695 1696 @history[#:added "8.1.0.6"]} 1697 1698@defproc[(get-gui-bin-extra-search-dirs) (listof path?)]{ 1699 Analogous to @racket[get-share-extra-search-dirs] for the underlying 1700 @racket['gui-bin-search-dirs] configuration. 1701 1702 @history[#:added "8.1.0.6"]} 1703 1704@defproc[(find-apps-dir) (or/c path? #f)]{ 1705 Returns a path to the installation's directory @filepath{.desktop} 1706 files (for Unix). The result is @racket[#f] if no such directory 1707 exists. 1708 1709 @see-config[apps-dir]} 1710 1711@defproc[(find-user-apps-dir) path?]{ 1712 Returns a path to the user's directory for @filepath{.desktop} files 1713 (for Unix); the directory indicated by the returned path may or may 1714 not exist. 1715 1716 @user-path[#f]} 1717 1718@defproc[(find-man-dir) (or/c path? #f)]{ 1719 Returns a path to the installation's man-page directory. The result is 1720 @racket[#f] if no such directory exists. @see-config[man-dir]} 1721 1722@defproc[(find-user-man-dir) path?]{ 1723 Returns a path to the user's man-page directory; the directory 1724 indicated by the returned path may or may not exist. 1725 1726 @user-path["man"]} 1727 1728@defproc[(get-man-search-dirs) (listof path?)]{ 1729 Analogous to @racket[get-share-search-dirs], but for paths to search 1730 for man pages. 1731 1732 @see-config[man-search-dirs] 1733 1734 @history[#:added "8.1.0.6"]} 1735 1736@defproc[(get-man-extra-search-dirs) (listof path?)]{ 1737 Analogous to @racket[get-share-extra-search-dirs] for the underlying 1738 @racket['man-search-dirs] configuration. 1739 1740 @history[#:added "8.1.0.6"]} 1741 1742@defproc[(get-doc-search-url) string?]{ 1743 Returns a string that is used by the documentation system, augmented 1744 with a version and search-key query, for remote documentation links. 1745 1746 @see-config[doc-search-url]} 1747 1748@defproc[(get-doc-open-url) (or/c string? #f)]{ 1749 Returns @racket[#f] or a string for a root URL to be used as an 1750 alternative to opening a local file for documentation. A 1751 non-@racket[#f] configuration means that DrRacket, for example, 1752 performs keyword searches for documentation via the specified URL 1753 instead of from locally installed documentation. 1754 1755 @see-config[doc-open-url] 1756 1757 @history[#:added "6.0.1.6"]} 1758 1759@defproc[(get-installation-name) string?]{ Returns the current 1760 installation's name, which is often @racket[(version)] but can be 1761 configured via @racket['installation-name] in @filepath{config.rktd} 1762 (see @secref["config-file"]).} 1763 1764@defproc[(get-build-stamp) (or/c #f string?)]{ Returns a string 1765 that identifies an installation build, which can be used to augment 1766 the Racket version number to more specifically identify the 1767 build. An empty string is normally produced for a release build. 1768 The result is @racket[#f] if no build stamp is available.} 1769 1770@defproc[(get-absolute-installation?) boolean?]{ 1771 Returns @racket[#t] if this installation uses 1772 absolute path names for executable and library references, 1773 @racket[#f] otherwise.} 1774 1775@deftogether[( 1776@defproc[(find-addon-tethered-console-bin-dir) (or/c #f path?)] 1777@defproc[(find-addon-tethered-gui-bin-dir) (or/c #f path?)] 1778)]{ 1779 Returns a path to a user-specific directory to hold an extra copy of 1780 each installed executable, where the extra copy is created by 1781 @exec{raco setup} and tethered to a particular result for 1782 @racket[(find-system-path 'addon-dir)] and 1783 @racket[(find-config-dir)]. 1784 1785 Unlike other directories, which are configured via 1786 @filepath{config.rktd} in the @racket[(find-config-dir)] directory 1787 (see @secref["config-file"]), these paths are configured via 1788 @racket['addon-tethered-console-bin-dir] and 1789 @racket['addon-tethered-gui-bin-dir] entries in 1790 @filepath{config.rktd} in @racket[(build-path (find-system-path 1791 'addon-dir) "etc")]. If no configuration is present, the result from 1792 the corresponding function, 1793 @racket[find-addon-tethered-console-bin-dir] or 1794 @racket[find-addon-tethered-gui-bin-dir], is @racket[#f] instead of 1795 a path. 1796 1797 See @secref["tethered-install"] for more information. 1798 1799 @history[#:added "6.5.0.2"]} 1800 1801 1802@deftogether[( 1803@defproc[(find-config-tethered-console-bin-dir) (or/c #f path?)] 1804@defproc[(find-config-tethered-gui-bin-dir) (or/c #f path?)] 1805)]{ 1806 Similar to @racket[find-addon-tethered-console-bin-dir] and 1807 @racket[find-addon-tethered-gui-bin-dir], but configured via 1808 @filepath{config.rktd} in the @racket[(find-config-dir)] directory 1809 (see @secref["config-file"]) and triggers executables that are 1810 tethered only to a particular value of @racket[(find-config-dir)]. 1811 1812 See @secref["tethered-install"] for more information. 1813 1814 @history[#:added "6.5.0.2"]} 1815 1816@; ------------------------------------------------------------------------ 1817 1818@section[#:tag "getinfo"]{API for Reading @filepath{info.rkt} Files} 1819 1820@defmodule[setup/getinfo]{ The @racketmodname[setup/getinfo] library 1821 provides functions for accessing fields in @filepath{info.rkt} 1822 files. The file format for @filepath{info.rkt} files is documented 1823 in @secref["info.rkt" #:doc '(lib "scribblings/raco/raco.scrbl")]. 1824} 1825 1826@defproc[(get-info [collection-names (listof string?)] 1827 [#:namespace namespace (or/c namespace? #f) #f] 1828 [#:bootstrap? bootstrap? any/c #f]) 1829 (or/c 1830 (symbol? [(-> any)] . -> . any) 1831 #f)]{ 1832 Accepts a list of strings naming a collection or sub-collection, 1833 and calls @racket[get-info/full] with the full path corresponding to the 1834 named collection and the @racket[namespace] argument.} 1835 1836@defproc[(get-info/full [path path-string?] 1837 [#:namespace namespace (or/c namespace? #f) #f] 1838 [#:bootstrap? bootstrap? any/c #f]) 1839 (or/c (->* (symbol?) ((-> any)) any) 1840 #f)]{ 1841 1842 Accepts a path to a directory. If it finds either a well-formed 1843 @filepath{info.rkt} file or an @filepath{info.ss} file (with 1844 preference for the @filepath{info.rkt} file), 1845 it returns an info procedure that accepts either one 1846 or two arguments. The first argument to the info procedure is 1847 always a symbolic name, and the result is the value of the name in 1848 the @filepath{info.rkt} file, if the name is defined. The optional 1849 second argument, @racket[_thunk], is a procedure that takes no 1850 arguments to be called when the name is not defined; the result of 1851 the info procedure is the result of the @racket[_thunk] in that 1852 case. If the name is not defined and no @racket[_thunk] is 1853 provided, then an exception is raised. 1854 1855 The @racket[get-info/full] function returns @racket[#f] if there is 1856 no @filepath{info.rkt} (or @filepath{info.ss}) file in the directory. If there is a 1857 @filepath{info.rkt} (or @filepath{info.ss}) file that has the wrong shape (i.e., not a module 1858 using @racketmodname[info] or @racketmodname[setup/infotab]), 1859 or if the @filepath{info.rkt} file fails to load, then an exception 1860 is raised. If the @filepath{info.rkt} file loaded, @racket[get-info/full] 1861 returns the @racket[get-info] file. If the @filepath{info.rkt} file does not exist, 1862 then @racket[get-info/full] does 1863 the same checks for the @filepath{info.ss} file, either raising an exception 1864 or returning the @racket[get-info] function from the @filepath{info.ss} file. 1865 1866 The @filepath{info.rkt} (or @filepath{info.ss}) module is loaded 1867 into @racket[namespace] if it is not @racket[#f], or a private, 1868 weakly-held namespace otherwise. 1869 1870 If @racket[bootstrap?] is true, then 1871 @racket[use-compiled-file-paths] is set to @racket['()] while 1872 reading @filepath{info.rkt} (or @filepath{info.ss}), in case an 1873 existing compiled file is broken. Furthermore, the 1874 @racketmodname[info] and @racketmodname[setup/infotab] modules are 1875 attached to @racket[namespace] from the namespace of 1876 @racket[get-info/full] before attempting to load 1877 @filepath{info.rkt} (or @filepath{info.ss}). 1878 1879 As the module is loaded, the @tech[#:doc reference-doc]{environment variable set} 1880 is pruned to contain only environment variables that are listed in the 1881 @envvar{PLT_INFO_ALLOW_VARS} environment variable, which contains a 1882 @litchar{;}-separated list of names. By default, the list of allowed 1883 variable names is empty. 1884 1885 @history[#:changed "6.5.0.2" @elem{Added environment-variable 1886 pruning and @envvar{PLT_INFO_ALLOW_VARS} support.}]} 1887 1888@defproc[(find-relevant-directories 1889 (syms (listof symbol?)) 1890 (mode (or/c 'preferred 'all-available 'no-planet 'no-user) 'preferred)) 1891 (listof path?)]{ 1892 1893 Returns a list of paths identifying 1894 collections and installed @|PLaneT| packages whose 1895 @filepath{info.rkt} file defines one or more of the given 1896 symbols. The result is based on a cache that is computed by 1897 @exec{raco setup}. 1898 1899 Note that the cache may be out of date by the time you call 1900 @racket[get-info/full], so do not assume that every returned 1901 directory's @filepath{info.rkt} file will supply one of the 1902 requested symbols. 1903 1904 The result is in a canonical order (sorted lexicographically by 1905 directory name), and the paths it returns are suitable for 1906 providing to @racket[get-info/full]. 1907 1908 If @racket[mode] is specified, it must be either 1909 @racket['preferred] (the default), @racket['all-available], 1910 @racket['no-planet], or @racket['no-user]. If @racket[mode] is 1911 @racket['all-available], @racket[find-relevant-directories] returns 1912 all installed directories whose info files contain the specified 1913 symbols---for instance, all versions of all installed PLaneT 1914 packages will be searched if @racket['all-available] is 1915 specified. If @racket[mode] is @racket['preferred], then only a 1916 subset of ``preferred'' packages will be searched: only the 1917 directory containing the most recent version of any PLaneT package 1918 will be returned. If @racket[mode] is @racket['no-planet], then 1919 PLaneT packages are not included in the search. If @racket[mode] is 1920 @racket['no-user], then only installation-wide directories are 1921 searched, which means omitting @|PLaneT| package directories. 1922 1923 Collection links from the installation-wide @tech[#:doc 1924 reference-doc]{collection links file} or packages with installation 1925 scope are cached with the installation's main @filepath{lib} 1926 directory, and links from the user-specific @tech[#:doc 1927 reference-doc]{collection links file} and packages are cached with 1928 the user-specific directory @racket[(build-path (find-system-path 1929 'addon-dir) "collects")] for all-version cases, and in @racket[(build-path 1930 (find-system-path 'addon-dir) (version) "collects")] for 1931 version-specific cases.} 1932 1933@defproc[(find-relevant-directory-records 1934 [syms (listof symbol?)] 1935 [key (or/c 'preferred 'all-available 'no-planet 'no-user)]) 1936 (listof directory-record?)]{ 1937 Like @racket[find-relevant-directories], but returns @racket[directory-record] structs 1938 instead of @racket[path?]s. 1939} 1940 1941@defstruct[directory-record ([maj integer?] 1942 [min integer?] 1943 [spec any/c] 1944 [path path?] 1945 [syms (listof symbol?)])]{ 1946 A struct that records information about a collection or a @PLaneT package that has been installed. 1947 Collections will have the major version being @racket[1] and the minor version being @racket[0]. 1948 The @racket[spec] field is a quoted module spec; the @racket[path] field is where the @tt{info.rkt} 1949 file for this collection or @PLaneT package exists on the filesystem; the @racket[syms] field holds the 1950 identifiers defined in that file. 1951} 1952 1953@defproc[(reset-relevant-directories-state!) void?]{ 1954 Resets the cache used by @racket[find-relevant-directories].} 1955 1956@; ------------------------------------------------------------------------ 1957 1958@section[#:tag "relative-paths"]{API for Relative Paths} 1959 1960The Racket installation tree can usually be moved around the filesystem. 1961To support this, care must be taken to avoid absolute paths. The 1962following two APIs cover two aspects of this: a way to convert a path to 1963a value that is relative to the @filepath{collects} tree, and a way to 1964display such paths (e.g., in error messages). 1965 1966@subsection{Representing Collection-Based Paths} 1967 1968@defmodule[setup/collects] 1969 1970@defproc[(path->collects-relative [path path-string?] 1971 [#:cache cache (or/c #f (and/c hash? (not/c immutable?)))]) 1972 (or/c path-string? 1973 (cons/c 'collects 1974 (cons/c bytes? (non-empty-listof bytes?))))]{ 1975 1976Checks whether @racket[path] (normalized by 1977@racket[path->complete-path] and @racket[simplify-path] with 1978@racket[#f] as its second argument) matches the result of 1979@racket[collection-file-path]. If so, the result is a list starting 1980with @racket['collects] and containing the relevant path elements as 1981byte strings. If not, the path is returned as-is. 1982 1983The @racket[cache] argument is used with @racket[path->pkg], if needed.} 1984 1985@defproc[(collects-relative->path 1986 [rel (or/c path-string? 1987 (cons/c 'collects 1988 (cons/c bytes? (non-empty-listof bytes?))))]) 1989 path-string?]{ 1990 1991The inverse of @racket[path->collects-relative]: if @racket[rel] 1992is a pair that starts with @racket['collects], then it is converted 1993back to a path using @racket[collection-file-path].} 1994 1995@defproc[(path->module-path [path path-string?] 1996 [#:cache cache (or/c #f (and/c hash? (not/c immutable?)))]) 1997 (or/c path-string? module-path?)]{ 1998 1999Like @racket[path->collects-relative], but the result is either 2000@racket[path] or a normalized (in the sense of 2001@racket[collapse-module-path]) module path.} 2002 2003@subsection{Representing Paths Relative to @filepath{collects}} 2004 2005@defmodule[setup/main-collects] 2006 2007@defproc[(path->main-collects-relative [path (or/c bytes? path-string?)]) 2008 (or/c path? (cons/c 'collects (non-empty-listof bytes?)))]{ 2009 2010Checks whether @racket[path] has a prefix that matches the prefix to 2011the main @filepath{collects} directory as determined by 2012@racket[(find-collects-dir)]. If so, the result is a list starting 2013with @racket['collects] and containing the remaining path elements as 2014byte strings. If not, the path is returned as-is. 2015 2016The @racket[path] argument should be a complete path. Applying 2017@racket[simplify-path] before @racket[path->main-collects-relative] is 2018usually a good idea. 2019 2020For historical reasons, @racket[path] can be a byte string, which is 2021converted to a path using @racket[bytes->path]. 2022 2023See also @racket[collects-relative->path].} 2024 2025@defproc[(main-collects-relative->path 2026 [rel (or/c bytes? 2027 path-string? 2028 (cons/c 'collects (non-empty-listof bytes?)))]) 2029 path>]{ 2030 2031The inverse of @racket[path->main-collects-relative]: if @racket[rel] 2032is a pair that starts with @racket['collects], then it is converted 2033back to a path relative to @racket[(find-collects-dir)].} 2034 2035@subsection{Representing Paths Relative to the Documentation} 2036 2037@defmodule[setup/main-doc] 2038 2039@defproc[(path->main-doc-relative [path (or/c bytes? path-string?)]) 2040 (or/c path? (cons/c 'doc (non-empty-listof bytes?)))]{ 2041 Like @racket[path->main-collects-relative], except that it checks 2042 for a prefix relative to @racket[(find-doc-dir)] and returns a list 2043 starting with @racket['doc] if so. 2044} 2045 2046@defproc[(main-doc-relative->path 2047 [rel (or/c bytes? 2048 path-string? 2049 (cons/c 'doc (non-empty-listof bytes?)))]) 2050 path>]{ 2051 2052 Like @racket[path->main-collects-relative], except it is the inverse 2053 of @racket[path->main-doc-relative]. 2054} 2055 2056 2057@subsection{Displaying Paths Relative to a Common Root} 2058 2059@defmodule[setup/path-to-relative] 2060 2061@defproc[(path->relative-string/library 2062 [path path-string?] 2063 [default (or/c (-> path-string? any/c) any/c) 2064 (lambda (x) (if (path? x) (path->string x) x))] 2065 [#:cache cache (or/c #f (and/c hash? (not/c immutable?))) #f]) 2066 any/c]{ 2067 Produces a string suitable for display in error messages. If the path 2068 is an absolute one that is inside a package, the 2069 result is a string that begins with @racket["<pkgs>/"]. If the path 2070 is an absolute one that is inside the @filepath{collects} tree, the 2071 result is a string that begins with @racket["<collects>/"]. 2072 Similarly, a path in the user-specific collects results in a prefix of 2073 @racket["<user-collects>/"], a @PLaneT path results in 2074 @racket["<planet>/"], and a path into documentation results in 2075 @racket["<doc>/"] or @racket["<user-doc>/"]. 2076 2077 If @racket[cache] is not @racket[#f], it is used as a cache argument 2078 for @racket[pkg->path] to speed up detection and conversion of 2079 package paths. 2080 2081 If the path is not absolute, or if it is not in any of these, it is 2082 returned as-is (converted to a string if needed). If @racket[default] 2083 is given, it specifies the return value instead: it can be a procedure 2084 that is applied onto the path to get the result, or the result 2085 itself. 2086 2087 Note that this function can return a non-string only if 2088 @racket[default] is given and it does not return a string. 2089} 2090 2091@defproc[(path->relative-string/setup 2092 [path path-string?] 2093 [default (or/c (-> path-string? any/c) any/c) 2094 (lambda (x) (if (path? x) (path->string x) x))] 2095 [#:cache cache (or/c #f (and/c hash? (not/c immutable?))) #f]) 2096 any/c]{ 2097 2098The same as @racket[path->relative-string/library], for backward 2099compatibility.} 2100 2101 2102@defproc[(make-path->relative-string 2103 [dirs (listof (cons (-> path?) string?))] 2104 [default (or/c (-> path-string? any/c) any/c) 2105 (lambda (x) (if (path? x) (path->string x) x))]) 2106 (path-string? any/c . -> . any)]{ 2107 This function produces functions like 2108 @racket[path->relative-string/library] and 2109 @racket[path->relative-string/setup]. 2110 2111 The @racket[dirs] argument determines the prefix substitutions. It must be an 2112 association list mapping a path-producing thunk to a prefix string for 2113 paths in the specified path. 2114 2115 @racket[default] determines the default for the resulting function 2116 (which can always be overridden by an additional argument to this 2117 function). 2118} 2119 2120@; ------------------------------------------------------------------------ 2121 2122@section[#:tag "collection-names"]{API for Collection Names} 2123 2124@defmodule[setup/collection-name] 2125 2126@defproc[(collection-name? [v any/c]) boolean?]{ 2127 2128Returns @racket[#t] if @racket[v] is a string that is syntactically 2129valid as a collection name, which means that it is one or more 2130@litchar{/}-separated strings for which 2131@racket[collection-name-element?] returns true.} 2132 2133 2134@defproc[(collection-name-element? [v any/c]) boolean?]{ 2135 2136Returns @racket[#t] if @racket[v] is a string that is syntactically 2137valid as a top-level collection name or as a part of a collection 2138name, which means that it is non-empty and contains only ASCII 2139letters, ASCII digits, @litchar{-}, @litchar{+}, @litchar{_}, and 2140@litchar{%}, where a @litchar{%} is allowed only when followed by two 2141lowercase hexadecimal digits, and the digits must form a number that 2142is not the ASCII value of a letter, digit, @litchar{-}, @litchar{+}, 2143or @litchar{_}.} 2144 2145 2146@; ------------------------------------------------------------------------ 2147 2148@section[#:tag "collection-search"]{API for Collection Searches} 2149 2150@defmodule[setup/collection-search] 2151 2152@history[#:added "6.3"] 2153 2154@defproc[(collection-search [mod-path normalized-lib-module-path?] 2155 [#:init result any/c #f] 2156 [#:combine combine (any/c (and/c path? complete-path?) . -> . any/c) (lambda (r v) v)] 2157 [#:break? break? (any/c . -> . any/c) (lambda (r) #f)] 2158 [#:all-possible-roots? all-possible-roots? any/c #f]) 2159 any/c]{ 2160 2161Generalizes @racket[collection-file-path] to support folding over all 2162possible locations of a collection-based file in the current 2163configuration. Unlike @racket[collection-file-path], 2164@racket[collection-search] takes the file to location in module-path 2165form, but always as a @racket['lib] path. 2166 2167Each possible path for the file (not counting a @filepath{.ss} to/from 2168@filepath{.rkt} conversion) is provided as a second argument to the 2169@racket[combine] function, where the first argument is the current 2170result, and the value produced by @racket[combine] becomes the new 2171result. The @racket[#:init] argument provides the initial result. 2172 2173The @racket[break?] function short-circuits a search based on the 2174current value. For example, it could be used to short-circuit a search 2175after a suitable path is found. 2176 2177If @racket[all-possible-roots?] is @racket[#f], then @racket[combine] 2178is called only on paths within @filepath{collects}-like directories 2179(for the current configuration) where at least a matching collection 2180directory exists.} 2181 2182 2183@defproc[(normalized-lib-module-path? [v any/c]) boolean?]{ 2184 2185Returns @racket[#t] if @racket[v] is a module path (in the sense of 2186@racket[module-path?]) of the form @racket['(lib _str)] where 2187@racket[_str] contains at least one slash. The 2188@racket[collapse-module-path] function produces such module paths for 2189collection-based module references.} 2190 2191@; ------------------------------------------------------------------------ 2192 2193@section[#:tag "matching-platform"]{API for Platform Specifications} 2194 2195@defmodule[setup/matching-platform] 2196 2197@history[#:added "6.0.1.13"] 2198 2199@defproc[(platform-spec? [v any/c]) boolean?]{ 2200 2201Returns @racket[#t] if @racket[v] is a symbol, string, or regexp value 2202(in the sense of @racket[regexp?]), @racket[#f] otherwise.} 2203 2204@defproc[(matching-platform? [spec platform-spec?] 2205 [#:cross? cross? any/c #f] 2206 [#:system-type sys-type (or/c #f symbol?) (if cross? 2207 (cross-system-type) 2208 (system-type))] 2209 [#:system-library-subpath sys-lib-subpath (or/c #f path-for-some-system?) 2210 (if cross? 2211 (cross-system-library-subpath #f) 2212 (system-library-subpath #f))]) 2213 boolean?]{ 2214 2215Reports whether @racket[spec] matches @racket[sys-type] or 2216@racket[sys-lib-subpath], where @racket[#f] values for the latter are 2217replaced with the default values. 2218 2219If @racket[spec] is a symbol, then the result is @racket[#t] if 2220@racket[sys-type] is the same symbol, @racket[#f] otherwise. 2221 2222If @racket[spec] is a string, then the result is @racket[#t] if 2223@racket[(path->string sys-lib-subpath)] is the same string, 2224@racket[#f] otherwise. 2225 2226If @racket[spec] is a regexp value, then the result is @racket[#t] if 2227the regexp matches @racket[(path->string sys-lib-subpath)], 2228@racket[#f] otherwise. 2229 2230@history[#:changed "6.3" @elem{Added @racket[#:cross?] argument and 2231 changed the contract on @racket[sys-lib-subpath] 2232 to accept @racket[path-for-some-system?] 2233 instead of just @racket[path?].}]} 2234 2235@; ------------------------------------------------------------------------ 2236 2237@section[#:tag "cross-system"]{API for Cross-Platform Configuration} 2238 2239See @other-doc[#:indirect @exec{raco cross} '(lib 2240"raco/private/cross/raco-cross.scrbl")] for information about 2241@exec{raco cross}, a tool that is provided by the 2242@filepath{raco-cross} package as a convenient interface to 2243cross-compilation for Racket. The underlying API documented here 2244supports @exec{raco cross} and other tools. 2245 2246@defmodule[setup/cross-system]{The @racketmodname[setup/cross-system] 2247library provides functions for querying the system properties of a 2248destination platform, which can be different than the current platform 2249in cross-installation modes.} 2250 2251A Racket installation includes a @filepath{system.rktd} file in the 2252directory reported by @racket[(find-lib-dir)]. When the information in that file 2253does not match the running Racket's information, then the 2254@racketmodname[setup/cross-system] module infers that Racket is being 2255run in cross-installation mode. 2256 2257For example, if an in-place Racket @BC 2258installation for a different platform resides at @nonterm{cross-dir}, 2259then running Racket BC as 2260 2261@commandline{racket -C -G @nonterm{cross-dir}/etc -X @nonterm{cross-dir}/collects -l- raco pkg} 2262 2263runs @exec{raco pkg} using the current platform's @exec{racket} 2264executable, but using the collections and other configuration 2265information of @nonterm{cross-dir}, as well as modifying the packages 2266of @nonterm{cross-dir}. That can work as long as no platform-specific 2267libraries need to run to perform the requested @exec{raco pkg} action 2268(e.g., when installing built packages), or as long as the current 2269platform's installation already includes those libraries. 2270 2271For Racket @CS, cross compilation is more 2272complicated, because Racket CS @filepath{.zo} files are 2273platform-specific: 2274 2275@itemlist[ 2276 2277 @item{A target installation @nonterm{cross-dir} is needed that 2278 includes cross-compilation support for the host platform as 2279 plug-in within the installation's 2280 @filepath{@nonterm{cross-dir}/lib} directory. That installation 2281 might be created by compiling from source on the host platform. 2282 Only Racket CS can use a CS cross-compilation plug-in. 2283 2284 When running @exec{racket} in cross mode, use the 2285 @DFlag{cross-compiler} flag to specify the target machine and 2286 path to the @filepath{@nonterm{cross-dir}/lib} directory.} 2287 2288 @item{A flag combination @Flag{MCR} with argument 2289 @filepath{@nonterm{absolute-zo-dir}:} is needed to enable 2290 @filepath{.zo} file creation for both the host platform (which 2291 uses the directory before a @litchar{:}) and the target 2292 platform (which uses the normal compiled-file subdirectory when 2293 the path after the @litchar{:} is empty). 2294 2295 The @nonterm{absolute-zo-dir} can be any absolute path. It 2296 generally should be populated by running @exec{raco setup} in 2297 cross mode before commands like @exec{raco pkg}.} 2298 2299] 2300 2301For example, the @exec{raco pkg} example for Racket CS is 2302 2303@verbatim[#:indent 2]{ 2304 racket --cross-compiler @nonterm{target-machine} @nonterm{cross-dir}/lib \ 2305 -MCR @nonterm{absolute-zo-dir}: \ 2306 -G @nonterm{cross-dir}/etc -X @nonterm{cross-dir}/collects -l- raco pkg 2307} 2308 2309The @nonterm{target-machine} provided to @DFlag{cross-compiler} should 2310be the same as the @racketidfont{target-machine} entry in 2311@filepath{@nonterm{cross-dir}/lib/systemd.rktd}. 2312 2313The @Flag{C} flag is shorthand for @DFlag{cross}, @Flag{M} is short 2314for @DFlag{compile-any}, @Flag{R} is short for @DFlag{compiled}, 2315@Flag{G} is short for @DFlag{config}, @Flag{X} is short for 2316@DFlag{collects}, and @Flag{MCR} is short for @exec{@Flag{M} @Flag{C} 2317@Flag{R}}. 2318 2319@history[#:added "6.3"] 2320 2321@defproc[(cross-system-type [mode (or/c 'os 'word 'gc 'vm 'link 'machine 2322 'so-suffix 'so-mode 'fs-change) 2323 'os]) 2324 (or/c symbol? string? bytes? exact-positive-integer? vector?)]{ 2325 2326Like @racket[system-type], but for the target platform instead of the 2327current platform in cross-installation mode. When not in 2328cross-installation mode, the results are the same as for 2329@racket[system-type]. 2330 2331See also @racket['cross] mode for @racket[system-type].} 2332 2333 2334@defproc[(cross-system-library-subpath [mode (or/c 'cgc '3m 'cs #f) 2335 (system-type 'gc)]) 2336 path-for-some-system?]{ 2337 2338Like @racket[system-library-subpath], but for the target platform 2339instead of the current platform in cross-installation mode. When not 2340in cross-installation mode, the results are the same as for 2341@racket[system-library-subpath]. 2342 2343In cross-installation mode, the target platform may have a different 2344path convention than the current platform, so the result is 2345@racket[path-for-some-system?] instead of @racket[path?].} 2346 2347 2348@defproc[(cross-installation?) boolean?]{ 2349 2350Returns @racket[#t] if cross-installation mode has been detected, 2351@racket[#f] otherwise.} 2352 2353 2354@; ------------------------------------------------------------------------ 2355 2356@section[#:tag "xref"]{API for Cross-References for Installed Manuals} 2357 2358@defmodule[setup/xref] 2359 2360@defproc[(load-collections-xref [on-load (-> any/c) (lambda () (void))]) 2361 xref?]{ 2362 2363Either creates and caches or returns a cached cross-reference record 2364created with @racket[make-collections-xref]. The @racket[on-load] 2365function is called only when a previously cached record is not 2366returned.} 2367 2368 2369@defproc[(make-collections-xref [#:no-user? no-user? any/c #f] 2370 [#:no-main? no-main? any/c #f] 2371 [#:doc-db db-path (or/c #f path?) #f] 2372 [#:quiet-fail? quiet-fail? any/c #f] 2373 [#:register-shutdown! register-shutdown! ((-> any) . -> . any) void]) 2374 xref?]{ 2375 2376Like @racket[load-xref], but automatically finds all cross-reference 2377files for manuals that have been installed with @exec{raco setup}. 2378The resulting cross-reference record takes advantage of a 2379cross-reference database @racket[db-path], when support is available, 2380to delay the loading of cross-reference details until needed. 2381 2382Cross-reference information is skipped when it is installed in the 2383main installation or in a user-specific location, respectively, if 2384@racket[no-main?] or @racket[no-user?] is @racket[#t]. 2385 2386If @racket[quiet-fail?] is true, then errors are suppressed while 2387loading cross-reference information. 2388 2389The @racket[register-shutdown!] callback may be called to register a 2390function that closes database connections when the result of 2391@racket[make-collections-xref] is no longer needed. If 2392@racket[register-shutdown!] is not supplied or if a function sent to 2393@racket[register-shutdown!] is never called, database connections will 2394be closed only though a @tech[#:doc reference-doc]{custodian}.} 2395 2396 2397@defproc[(get-rendered-doc-directories [no-user? any/c] 2398 [no-main? any/c]) 2399 (listof path?)]{ 2400 2401Returns a list of directories for all documentation for all installed 2402collections, omitting documentation that is installed in the main 2403installation or in a user-specific location, respectively, if 2404@racket[no-main?] or @racket[no-user?] is @racket[#t].} 2405 2406 2407@defproc[(get-current-doc-state) doc-state?]{ 2408 Records the time stamps of files that are touched whenever the 2409 documentation is changed. 2410 2411 @history[#:added "1.2"] 2412} 2413 2414@defproc[(doc-state-changed? [doc-state doc-state?]) boolean?]{ 2415 Returns @racket[#t] when the time stamps of the files in 2416 @racket[doc-state] changed (or new files appeared) and @racket[#f] otherwise. 2417 2418 If the result is @racket[#t], then the documentation in this installation of 2419 Racket has changed and otherwise it hasn't. 2420 2421 @history[#:added "1.2"] 2422} 2423@defproc[(doc-state? [v any/c]) boolean?]{ 2424 A predicate to recognize the result of @racket[get-current-doc-state]. 2425 2426 @history[#:added "1.2"] 2427} 2428 2429@; ------------------------------------------------------------------------ 2430 2431@section[#:tag "materialize-user-docs"]{API for Materializing User-Specific Documentation} 2432 2433@defmodule[setup/materialize-user-docs] 2434 2435@history[#:added "1.1"] 2436 2437@defproc[(materialize-user-docs [on-setup ((-> boolean?) -> any) (lambda (setup) (setup))] 2438 [#:skip-user-doc-check? skip-user-doc-check? any/c #f]) 2439 void?]{ 2440 2441Checks whether a user-specific documentation entry point already 2442exists in @racket[(find-user-doc-dir)], and if not, runs @exec{raco 2443setup} in a mode that will create the entry point (to have the same 2444content as the installation's documentation entry point.) If 2445@racket[skip-user-doc-check?] is not @racket[#f], then skips the 2446check for the user-specific documentation entry point. 2447 2448The run of @exec{raco setup} is packaged in a thunk that is provided to 2449@racket[on-setup], which can adjust the current output and error ports 2450as appropriate and check the thunk's result for success. 2451 2452The @racket[on-setup] argument is not called if the documentation entry 2453point already exists in @racket[(find-user-doc-dir)]. 2454 2455@history[#:changed "1.1" @list{Added the @racket[skip-user-doc-check?] argument.}] 2456} 2457 2458@; ------------------------------------------------------------------------ 2459 2460@section[#:tag "layered-install"]{Layered Installations} 2461 2462A typical Racket configuration includes two layers: an 2463@defterm{installation} layer and a @defterm{user} layer. The intent is 2464that the @defterm{installation} layer is read-only to all users of a 2465system, while the @defterm{user} layer allows each individual user to 2466install additional packages that extend the @defterm{installation} 2467layer. The @defterm{installation} layer is intended not only to be 2468read-only, but to not change after users start installing in their own 2469layers. 2470 2471In an environment where Racket itself is under development, the 2472@defterm{installation} layer will change. In that setting, if the 2473@defterm{user} layer is used at all, care must be taken to not create 2474conflicts for the user layer when modifying the installation 2475layer---or else the user layer must be repaired on occasion. 2476 2477By default, @exec{raco setup} updates both layers whenever it is run; 2478if a user does not have write permission the installation, @exec{raco 2479setup} with no arguments is all but certain to report permission 2480errors. The actions of @exec{raco setup} can be constrained to the 2481@defterm{user} layer by supplying the @DFlag{avoid-main} argument, or 2482@exec{raco setup} can be constrained to the @defterm{installation} 2483layer by using the @DFlag{no-user} argument. When @exec{raco pkg} 2484performs setup actions, it effectively supplies one of the other of 2485those based on the package's scope (and @exec{raco pkg} refuses to 2486operate on both scopes/layers at once). 2487 2488The @defterm{user} layer is always both user- and version-specific. 2489More precisely, it is specific to the user and an installation's name, 2490where the installation's name is typically its version number. 2491However, the name of an installation can be changed through the 2492@racket['installation] setting in @filepath{config.rktd} (see 2493@secref["config-file"]). Setting an installation name changes the 2494directory where packages and executables reside within 2495@racket[(find-system-path 'addon-dir)]. The result of 2496@racket[(find-system-path 'addon-dir)] itself can be changed through 2497@racket['addon-dir] in @filepath{config.rktd}. 2498 2499The @defterm{installation} and @defterm{user} configuration layers can 2500be generalized to multiple layers by setting search paths in 2501@filepath{config.rktd}. These search paths essentially treat the layer 2502closest to @defterm{user} as the @defterm{installation} layer that 2503might be adjusted by @exec{raco setup} and @exec{raco pkg}, but search 2504paths can chain to an existing (unchanging) implementation in much the 2505same way that @defterm{user} chains to @defterm{installation}. To 2506build a new layer, create new @filepath{config.rktd} that is like the 2507underlying layer's @filepath{config.rktd}, but 2508@; 2509@itemlist[ 2510 2511 @item{each of @racket['lib-dir], @racket['share-dir], 2512 @racket['links-file], @racket['pkgs-dir], @racket['bin-dir], 2513 @racket['gui-bin-dir], @racket['apps-dir], @racket['doc-dir], 2514 and @racket['man-dir] is a new directory or file; and} 2515 2516 @item{the corresponding search lists @racket['lib-search-dirs], 2517 @racket['share-search-dirs], @racket['links-search-files], 2518 @racket['pkgs-search-dirs], @racket['bin-search-dirs], 2519 @racket['gui-bin-search-dirs], (no @racket['apps-dir] search 2520 needed), @racket['doc-search-dirs], and 2521 @racket['man-search-dirs] each add the old directory or file to 2522 the search list just after @racket[#f]; note that the default 2523 for each search list is @racket[(list #f)].} 2524 2525] 2526@; 2527There is no argument to @exec{raco setup} that is analogous to 2528@DFlag{avoid-main} to avoid modifying nested layer; instead, nested 2529layers are expected to be fully set up so that @exec{raco setup} 2530need not change them. When @exec{raco setup} would otherwise install 2531an executable into the directory configured as @racket['bin-dir], it 2532consults the @racket['bin-search-dirs] list to check whether the 2533executable is already installed in one of those directories, and if so, 2534it will refrain from creating a copy in the new layer. The same 2535search-list check also applies to native libraries, shared files, and 2536man pages, but with the additional check that the file to install matches 2537the one that is already installed. 2538 2539The default path to @filepath{config.rktd} is hardwired within a 2540@exec{racket} executable. In some cases, it can make sense for the 2541innermost layer's configuration to point to another layer, perhaps 2542because the filesystem provides an indirection. For example, on Unix, 2543a Racket installation in @filepath{/usr} might reasonably configure 2544the @defterm{installation} layer's directories to be in 2545@filepath{/usr/local} with @filepath{/usr} directories included in the 2546search lists. 2547 2548To use @exec{racket} with a new @filepath{config.rktd}, you can supply 2549the @DFlag{config} or @DFlag{G} flag to @exec{racket} or set the 2550@envvar{PLTCONFIGDIR} environment variable to point to the directory 2551containing @filepath{config.rktd}. Alternatively, you can create a 2552@tech{tethered} layer that creates replacement executables like 2553@exec{racket} that are hardwired to the layer's configuration 2554directory. 2555 2556@; ------------------------------------------------------------------------ 2557 2558@section[#:tag "tethered-install"]{Tethered Installations} 2559 2560A @deftech{tethered} installation of Racket is a layer (see 2561@secref["layered-install"]) that includes a wrapper executable for 2562every executable across the installation's layers. Each wrapper 2563executable points back to the new layer's @filepath{config.rktd} (see 2564@secref["config-file"]) without the use of a @envvar{PLTCONFIGDIR} 2565environment variable or @DFlag{config} flag. In other words, a 2566tethered installation provides executables such as @exec{racket}, 2567@exec{raco}, and @exec{drracket} that are tied to the layer. Tethering 2568thus helps to create a layer of installation that behaves in a more 2569self-contained way, but with minimal duplication of the underlying 2570layers. 2571 2572Tethering works at either a @defterm{user} or @defterm{installation} 2573layer: 2574 2575@itemlist[ 2576 2577 @item{A @defterm{user} layer with tethering is represented by a fresh 2578 directory @nonterm{addon-dir} and a 2579 @filepath{@nonterm{addon-dir}/etc/config.rktd} file that maps 2580 @racket['addon-tethered-console-bin-dir] to 2581 @nonterm{tethered-bin-dir} and 2582 @racket['addon-tethered-gui-bin-dir] to 2583 @nonterm{tethered-gui-bin-dir}. Initialize the tethered layer 2584 with 2585 2586 @commandline{racket -A @nonterm{addon-dir} -l- raco setup --avoid-main}} 2587 2588 @item{An @defterm{installation} layer with tethering is like a one 2589 without tethering (see @secref["layered-install"]), but where 2590 the layer's @filepath{@nonterm{layer-dir}/etc/config.rktd} file 2591 that maps @racket['config-tethered-console-bin-dir] to 2592 @nonterm{tethered-bin-dir} and 2593 @racket['config-tethered-gui-bin-dir] to 2594 @nonterm{tethered-gui-bin-dir}. The @racket['bin-dir] and 2595 @racket['gui-bin-dir] configurations can point to the same 2596 directories, but executables are not specifically created there by 2597 @exec{raco setup}. Initialize the tethered layer with 2598 2599 @commandline{racket -G @nonterm{layer-dir}/etc -l- raco setup}} 2600 2601] 2602 2603In either case, initialization creates tethered executables in the 2604directories @nonterm{tethered-bin-dir} and 2605@nonterm{tethered-gui-bin-dir}. Thereafter, tethered executables like 2606@exec{@nonterm{tethered-bin-dir}/racket} and 2607@exec{@nonterm{tethered-bin-dir}/raco} can be used to work with the 2608tethered layer. 2609