From RTSC-Pedia

[printable version]  [offline version]

offline version generated on 04-Aug-2010 21:08 UTC

XDCspec - package-specification

Package specification syntax

Within the realm of XDCspec, a package is a programmatic element that logically contains modules and interfaces -- collectively termed units -- within its scope. Besides introducing its own public name, a package specification may identify other named packages upon which the current package in some way depends. The specification may also declare its (in)compatibility with earlier versions of the same package, as well as further constrain the level of compatibility required of any dependent packages. Specially-formatted comments embedded in package-specification source file are processed by the xdoc utility when generating HTML documentation for a set of packages.

package-specification

requires-statement*

//! @xdoc
package qualified-package-name compatibility-key?
{
   unit-declaration-list*
}[;]?
//! @xdoc

requires-statement

requires internal? qualified-package-name compatibility-key? ;

qualified-package-name

dirname [.dirname]*

compatibility-key

[ number [,number]* ]

unit-declaration-list

unit-category UnitName [,UnitName]* ;

unit-category

module | interface

• A qualified-package-name should in general be globally-unique. Packages are located in a directory with a matching name found along the system package path.
• A package-specification resides in a distinguished source file named package.xdc, found in the corresponding package directory.
• Each unit-declaration-list introduces individual modules and interfaces within the scope of the current package, all of which must be uniquely named. Units with the same name may only appear in different packages.
• Each requires-statement designates another package upon which the current package in someway unconditionally depends. The requires-relation among packages cannot contain cycles. The optional internal qualifier allows you to distinguish between packages that are required to "use the package" verses package required to "build the package"; use internal for package only required to build the package. Bundles, for example, require other packages in order to create the repositories they provide. On the other hand, the bundle certainly does not require these packages when the bundle is being used (it provides them!).
• A compatibility-key is generally interpreted as an numeric array of the form [m,s,r,p] where m denotes major functionality, s denotes source level, r denotes specification radius, and p denotes a particular patch. A new release of a package is source-compatible with any predecessor in which m is the same, and is binary-compatible with that predecessor if s is the same as well.
• By convention, package names are composed of lowercase identifiers whereas units (modules or interfaces) are named with TitleCase identifiers.

[printable version]  [offline version]

offline version generated on 04-Aug-2010 21:08 UTC