#lang scribble/manual @(require (planet cce/scheme:6:0/scribble) scribble/eval (for-label scheme (this-package-in package))) @(defmodule/this-package package) @(define make-my-eval (make-eval-factory '(scheme "package.ss"))) @(require (for-label scheme/system planet/util (this-package-in common) (this-package-in defs-parser) )) @(require (this-package-in package) (for-label (planet cce/scheme:6:0/scribble))) @(define scrbl @filepath{.scrbl}) @title[#:tag "package"]{Package Utilities} This module provides definitions to easily create PLaneT packages along with their documentation (using the automatic scribble parser, see @secref{defs-parser}). All the functions of this module are meant to be used when @scheme[current-directory] is correctly set to the directory of your package. This is generally true when evaluating a file of your package in DrScheme. @defparam[package-name name string?]{ A parameter controlling the name of the patckage. By default it is the name of the current directory. } @defparam[major-version number number?]{ A parameter controlling the major-version number of the current package (default: 1). } @defparam[minor-version number number?]{ A parameter controlling the minor-version number of the current package (default: 0). } @defparam[package-username username string?]{ A parameter controlling the username number of the current package By default it is the username of the OS environment. } @defproc[(set-planet-env [ username string? ] [ major number? ] [ minor number? ] [ name any/c (package-name)]) void?]{ Creates a environment suitable for calling the functions of this module, by setting the @scheme[package-username], @scheme[major-version], @scheme[minor-version] and @scheme[package-name] parameters to the given values. Call this function before any other if you want to change the default values of the parameters. } @;NOT-PROVIDED[package-dir] @;NOT-PROVIDED[system-debug] @defproc[(planet-create) void?]{ Launches the @filepath{planet} executable with the "create" option. The package file is put in the parent directory of the package. Using the planet executable seems to provide more debug info than @scheme[make-planet-archive]. } @defproc[(parse-module [ package-name string? ] [ filename string? ] [ extension string? "ss"]) string?]{ Creates the whole scribble string associated with @scheme[filename], automatically looking for the provided definitions (using @scheme[quote-require]). } @defproc[(write-doc [ file string? ] [ dir (or/c path-string? 'up 'same) 'same] [#:exists exists (or/c 'error 'append 'update 'replace 'truncate 'truncate/replace) 'error]) void?]{ Writes the @scrbl file associated with @scheme[file] in the directory @scheme[dir]. The @scheme[exists] argument is the same as for @scheme[with-output-to-file], and the @scheme[dir] argument is the same as for @scheme[build-path]. } @defproc[(write-main-src [ main path-string? ] [ files (listof path-string?) ] [#:exists exists (or/c 'error 'append 'update 'replace 'truncate 'truncate/replace) 'replace]) void?]{ (Re)writes the main source file of the package, using @scheme[require-provide] for each file of the package. } @(require (for-label (planet cce/scheme:6:0/require-provide) scheme/require-syntax)) @;NOT-PROVIDED[exn-warning-exists] @defproc[(write-main-doc [ main path-string? ] [ dir (or/c path-string? 'up 'same) ] [ files (listof path-string?) ] [#:exists exists (or/c 'error 'append 'update 'replace 'truncate 'truncate/replace) 'error]) void?]{ Writes the main @scrbl file in the @scheme[dir] directory with a table of contents. If @scheme[exists] is @scheme['error], @scheme[write-main-doc] only displays a warning and does not overwrite the file. If modules have been added to the package since the last execution of @scheme[(planet-build)], either the user should delete the @scheme[main] file so that it will be rewritten, or the user should add the inclusion of the modules himself in the @scheme[main] file. } @defproc[(write-info [ dir (or/c path-string? 'up 'same) ] [ main-src string? ] [ main-doc string? ] [#:exists exists (or/c 'error 'append 'update 'replace 'truncate 'truncate/replace) 'error]) void?]{ Writes a stub of the the @filepath{info.ss} file that ought to be modified by the user. The argument @scheme[dir] is the sub-directory of the documentation. See @scheme[write-main-doc] for information about the @scheme[exists] option. } @defproc[(write-docs [#:dir dir path-string? "reference"] [#:main-src main-src (or/c #f string?) "main.ss"] [#:main-doc main-doc (or/c #f string?) "manual"] [#:info? info? boolean? #t] [#:except except (listof string?) '()]) void?]{ Calls @scheme[write-main-src] on @scheme[main-src], @scheme[write-main-doc] on @scheme[main-doc], if they are provided. Calls @scheme[write-info] if @scheme[info?] is @scheme[#t], and creates the documentation directory @scheme[dir] if it does not already exist. (Re)writes the @scrbl file for all other @filepath{.ss} or @filepath{.scm} file in the directory (but not in sub-directories), without warning. An exception list of files that must not be included in the process can be given through @scheme[except]. } @defproc[(delete-bak-files) void?]{ Deletes all @filepath{.bak} files, in the current directory and its sub-directories, that may have been created by DrScheme. } @defproc[(planet-hard-link) void?]{ Creates a @PLaneT hard link to the current directory so that it is considered as a package. } @defproc[(planet-remove-hard-link) void?]{ Removes the planet hard link of the current package. } @defproc[(planet-build [#:dir dir path-string? "reference"] [#:main-src main-src (or/c #f string?) "main.ss"] [#:main-doc main-doc (or/c #f string?) "manual"] [#:info? info? boolean? #t] [#:except except (listof string?) '()]) void?]{ Creates a hard-link, calls @scheme[write-docs] with the @scheme[except] exception list of files, calls @scheme[delete-bak-files], and then calls @scheme[planet-create]. See @scheme[write-docs] for the description of the keyword options. }