From 9010eb5d192383e6fdc18410aa35f80387e5bf4d Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Sat, 3 Jan 2015 07:37:58 -0700 Subject: [PATCH] expand docs on package dependencies and checking --- pkgs/racket-doc/pkg/scribblings/pkg.scrbl | 13 +++-- pkgs/racket-doc/scribblings/raco/setup.scrbl | 60 +++++++++++++++----- 2 files changed, 55 insertions(+), 18 deletions(-) diff --git a/pkgs/racket-doc/pkg/scribblings/pkg.scrbl b/pkgs/racket-doc/pkg/scribblings/pkg.scrbl index bd3e5171fa..f44d1308d9 100644 --- a/pkgs/racket-doc/pkg/scribblings/pkg.scrbl +++ b/pkgs/racket-doc/pkg/scribblings/pkg.scrbl @@ -15,6 +15,8 @@ @litchar{0} through @litchar{9}, @litchar{_}, and @litchar{-}}) +@(define raco-doc '(lib "scribblings/raco/raco.scrbl")) + @(define (gtech s) @tech[#:doc '(lib "scribblings/guide/guide.scrbl") s]) @@ -388,7 +390,7 @@ A directory path can be used as a @tech{package scope}, in which case package operations affect the set of packages installations in the directory. An installation can be configured to include the directory in its search path for installed packages (see -@secref["config-file" #:doc '(lib "scribblings/raco/raco.scrbl")]). +@secref["config-file" #:doc raco-doc]). Conflict checking disallows installation of the same or conflicting package in different scopes, but if such a configuration is forced, @@ -1039,7 +1041,7 @@ The following @filepath{info.rkt} fields are used by the package manager: When a package is a @tech{single collection package}, its @filepath{info.rkt} file may specify additional fields that are used for the Scribble documentation system or other tools. Many of these fields are described - in @secref["setup-info" #:doc '(lib "scribblings/raco/raco.scrbl")]. + in @secref["setup-info" #:doc raco-doc]. } @(define (definfofield s) @as-index{@racketidfont{@s}}) @@ -1115,11 +1117,14 @@ The following @filepath{info.rkt} fields are used by the package manager: on the Racket run-time system, which is potentially useful when a version is included in the dependency. For most purposes, it's better to specify a versioned dependency on - @racket["base"], instead.} + @racket["base"], instead. + + See also @secref["setup-check-deps" #:doc raco-doc].} @item{@definfofield{build-deps} --- like @racketidfont{deps}, but for dependencies that can be dropped in a @tech{binary package}, - which does not include sources; see @secref["strip"]. The + which does not include sources; see @secref["strip"] and + @secref["setup-check-deps" #:doc raco-doc]. The @racketidfont{build-deps} and @racketidfont{deps} lists are appended, while @command-ref["create"] strips away @racketidfont{build-deps} when converting a package for diff --git a/pkgs/racket-doc/scribblings/raco/setup.scrbl b/pkgs/racket-doc/scribblings/raco/setup.scrbl index 10c9c69edd..7fb1276789 100644 --- a/pkgs/racket-doc/scribblings/raco/setup.scrbl +++ b/pkgs/racket-doc/scribblings/raco/setup.scrbl @@ -770,13 +770,50 @@ dependencies. Specifically, it inspects compiled files and documentation to check that references across package boundaries are reflected by dependency declarations in each package-level @filepath{info.rkt} file (see @secref[#:doc pkg-doc "metadata"]). + Dependency checking in @exec{raco setup} is intended as an aid to package developers to help them declare dependencies correctly. The @exec{raco setup} process itself does not depend on package dependency -declarations; a missing dependency creates trouble only for others who -later install a package. To accommodate the early stages of package -development, missing dependencies are not treated as an error for a -package that has no dependency declarations. +declarations. Similarly, a package with a missing dependency +declaration may install successfully for other users, as long as they +happen to have the dependencies installed already. A missing +dependency creates trouble for others who install a package without +having the dependency installed already. + +Practically every package depends on the @filepath{base} package, +which includes the collections that are in a minimal variant of +Racket. Declaring a dependency on @filepath{base} may seem +unnecessary, since its collections are always installed. In a future +version of Racket, however, the minimal collections may change, and +the new set of minimal collections will then have a package name, such +as @filepath{base2}. Declaring a dependency on @filepath{base} ensures +forward compatibility, and @exec{raco setup} complains if the +declaration is missing. + +To accommodate the early stages of package development, missing +dependencies are not treated as an error for a package that has no +dependency declarations. + +@subsection{Declaring Build-Time Dependencies} + +A build-time dependency is one that is not present in a package if it +is converted to a @tech[#:doc pkg-doc]{binary package} (see +@secref[#:doc pkg-doc "strip"]). For example, @filepath{tests} and +@filepath{scribblings} directories are stripped away in a binary +package by default, so cross-package references from directories with +those names are treated as build dependencies. Similarly, +@racketidfont{test} and @racketidfont{doc} submodules are stripped +away, so references within those submodules create build dependencies. + +Build-time-only dependencies can be listed as @racket[build-deps] +instead of @racket[deps] in a package's @filepath{info.rkt} file. +Dependencies listed in @racket[deps], meanwhile, are treated as both +run-time and build-time dependencies. The advantage of using +@racket[build-deps], instead of listing all dependencies in +@racket[deps], is that a binary version of the package can install +with fewer dependencies. + +@subsection{How Dependency Checking Works} Dependency checking uses @filepath{.zo} files, associated @filepath{.dep} files, and the documentation index. Dynamic @@ -786,16 +823,11 @@ to the dependency checker; only dependencies via @racket[require], cooperate with @racket[raco make] are visible for dependency checking. Dependency checking is sensitive to whether a dependency is needed -only as a build-time dependency. A build-time dependency is one that -is not present in a package if it is converted to a @tech[#:doc -pkg-doc]{binary package} (see @secref[#:doc pkg-doc "strip"]). For -example, @filepath{tests} and @filepath{scribblings} directories are -stripped away in a binary package by default, so cross-package -references from directories with those names are treated as build -dependencies. Build-time-only dependencies can be listed as -@racket[build-deps] instead of @racket[deps] in a package's -@filepath{info.rkt} file; dependencies listed in @racket[deps], -meanwhile, are treated as both run-time and build-time dependencies. +only as a build-time dependency. If @exec{raco setup} detects that a +missing dependency could be added as a built-time dependency, it will +suggest the addition, but @exec{raco setup} will not suggest +converting a normal dependency to a build-time dependency (since every +normal dependency counts as a build-time dependency, too). @; ------------------------------------------------------------------------