NAME

veda-new-package - Create a new skeleton package

SYNOPSIS

veda new-package pkg-name [--language skill|scheme] [--prefix prefix]

DESCRIPTION

Creates a new package pkg-name following the Veda guidelines (cf. PACKAGE FORMAT below).

The main skeleton file is populated with bogus information and a basic example to be updated/edited out; each of these locations is marked with a TODO note.

A simple, basic test suite is also generated. It includes three tiny test cases, one of which is failing for demonstration purposes.

OPTIONS

--language skill|scheme

Specify main language for the package, either skill for SKILL or scheme for SKILL++. Other languages and file types can still be used, but this initial choice determines the file extension of the package's titular file (.il or .ils).

--prefix prefix

Specify prefix as the global namespace prefix for exported symbols. Cadence recommends the use of a capitalized prefix to avoid clashes with built-in identifiers, which have all-lowercase prefixes; e.g. AcmeRocket for Acme Corporation's rocket package.

Defaults to My followed by the capitalized "words" in package, e.g. MyFooBar for package foo-bar.

PACKAGE FORMAT

A package is a directory which contains a SKILL or SKILL++ file with the same base name (<directory>.{il,ils}, the "titular" file), which in turn begins with a comment header formatted in a specific way. A minimal package foo would consist in a single file:

foo/foo.il

with a single-line header:

;;; foo.il --- Minimal package

More complex packages may contain @-prefixed metadata tags in the header comment, each beginning with:

;; @<tag-name>

The following tags are recognized:

;; @author   A.U.Thor <author@example.com>
;; @requires bar, baz
;; @load     a.il, b.ils, ...
@author

States the name and email address of an author of the package. If there are multiple authors, repeat the tag for each of them.

@requires

Specifies a list of other packages required by this package. Defaults to no dependencies. E.g.:

@requires bar, baz
@load

Specifies the load order of package source files. @load directives can take two forms:

@load foo.il, bar.ils

or

@load foo.il, bar.ils, ...

where the ellipsis means that any other source file found in the package's directory is to be loaded after foo.il and bar.ils (in an undefined order).

Defaults to @load ... which means all source files, in an undefined order.

Only the toplevel directory of a package is searched for source and test files; these are classified according to their suffix:

*-test.il, *-test.ils

Classified as test files;

*-il, *-ils

Files ending in .ils or .il which are not considered test files are classified as source files.

Other files and directories are ignored, but pkg/ and testing-* are reserved.

Packages are normally searched for in two locations relative to the execution directory: pkg/ and ../, in that order.

Implementation

The package system is implemented as a SKILL++ package (named package, using the VedaPackage global namespace prefix) which is distributed with Veda. The normal and recommended mechanism for accessing its API is a @requires directive:

@requires package

but as a special case, package.ils can also be loaded directly from SKILL for bootstrapping purposes. That is, assuming an installation prefix of /opt/crosstwine/veda/0.7.0:

(load "/opt/crosstwine/veda/0.7.0/share/veda/0.7.0/pkg/package/package.ils")

would make the VedaPackage* functions available. Its documentation should be browsable using e.g.:

firefox file:///opt/crosstwine/veda/0.7.0/share/doc/veda/0.7.0/pkg/package/index.html

ENVIRONMENT

This commands uses information from the following variables, if present, during template expansion:

They can be set from the shell or via one of the configuration files (cf. veda help, section ENVIRONMENT).

EXAMPLES

Basic package creation:

$ veda new-package rocket --language scheme --prefix AcmeRocket
    Create rocket
    Create rocket/rocket.ils
    Create rocket/rocket-test.ils

Examining the TODO notes:

$ grep -nr TODO rocket/
rocket/rocket.ils:1:;;; rocket.ils --- TODO: Short package description
rocket/rocket.ils:3:;; Copyright (C) 2013  TODO: Copyright notice.
rocket/rocket.ils:5:;; @author TODO: Firstname Lastname <email@example.com>
rocket/rocket.ils:7:;; TODO: Standard license banner.
rocket/rocket.ils:11:;; TODO: Long package description/commentary.
rocket/rocket.ils:34:  ;; TODO: Remove/replace by real code.
rocket/rocket.ils:44:  ;; TODO: Remove/replace by real export.

SEE ALSO

Crosstwine Veda on the Web