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

expand docs on package dependencies and checking

Browse Source
This commit is contained in:
Matthew Flatt 2015-01-03 07:37:58 -07:00
parent 513cee5e20
commit 9010eb5d19
2 changed files with 55 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
pkgs/racket-doc/pkg/scribblings/pkg.scrbl
View File

@ -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

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

@ -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).
@; ------------------------------------------------------------------------