#lang scribble/manual @(require (planet cce/scheme:6:0/scribble) scribble/eval (for-label scheme (this-package-in package))) @(define make-my-eval (make-eval-factory '(scheme (planet orseau/lazy-doc:1:5/package)))) @(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} @(defmodule/this-package package) 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. They are also relative to some parameters. Either set them to correct values directly or use @scheme[set-planet-env]. If you only need to use @scheme[planet-build], then you can call it with the parameters values, which will be set temporarily. @defparam[package-name name string?]{ A parameter controlling the name of the package. 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-owner owner string?]{ A parameter controlling the owner name of the current package. By default it is the username of the OS environment or @scheme["my-username"] if none is found. } @defproc[(set-planet-env [ owner 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-owner], @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[(planet-inject) void?]{ Launches the @filepath{planet} executable with the "file-inject" option on the current package file in the parent directory of the @scheme[current-directory]. The package file must exist. } @defproc[(planet-remove-package) void?]{ Calls @scheme[remove-pkg] on the current package environment settings. } @;NOT-PROVIDED[this-package-in-string] @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]) and adding header information. } @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. Does not (yet) deletes @filepath{~} files under Unix. } @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 [ owner string? (package-owner)] [ major number? (major-version)] [ minor number? (minor-version)] [#: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. }