As mentioned earlier, the package description language, PDL, defines the format of the PkgDesc. This section describes PDL except for those aspects of it that are related to TPC-management and ComPact's built-in template mechanism.
On a preliminary note, the following pkgm command can be used for obtaining an online grammar of PDL: -syntax | -syn. Its explanation is in English. For obtaining an online grammar with German explanations, one can use the command -gsyntax | -gsyn
Please note that this will display only the default grammar for ComPact C/C++ packages. The concrete syntax depends on the package kind and the definitions for this kind found in the configuration file pkgconf.cbcl.
As for the grammar itself, the following conventions apply:
Table 4-2.
| Comments within the PkgDesc | are begun by # or ;, and ended by newline, |
| non-terminals | are enclosed by ', |
| alternatives | are indicated by|, |
| options for arbitrarily many repetitions | are indicated by+, |
| entirely optional parts | are enclosed by angular brackets, and |
| whenever a clause ends with NL (newline) | then its instances must |
| respectively occupy exactly one line. |
Next,tokens and strings are sequences such as abcde or "abcde", respectively. Tokens may basically be understood as unquoted strings. A token can be used instead of a string whenever it cannot disturb the parsing process. A string, in turn, may contain every printable character except for ".
You will use tokens and strings mostly for denoting file names and path names:
TokenOrString ::= Token | String FileParam ::= TokenOrString PathParam ::= TokenOrString
where each instance of FileParam or PathParam must be a relative file name or a relative or absolute path name, respectively. For both file parameters and path parameters, standard POSIX notation is required. Default extensions, however, may be omitted.
The top-level syntax, then, is essentially as follows:
PkgDesc ::= ( Decl + ) [ TargetDecl + ] [TestSection + ]
meaning that a package description file consists of one or more declarations followed by zero or more target declarations followed be zero or more test sections. There is only one top-level aspect not covered by this production. More specifically, you may use the keyword `main' for dividing the list of declarations --
( Decl + )
-- so that there is a general part and a main section. By default, all declarations contained in this list are assumed to be of general nature, meaning that they are to be considered whenever any arbitrary target is built. The presence of `main' indicates that all subsequent declarations are to be considered only if a program from the list of target declarations is built. You will have to use this feature in case there is more than one program target. Such a situation occurs if a main program and, at the same time, one or more test programs belong to the package.To begin with, all C/C++ header files, C/C++ source code files, C++ template files, and assembler source code files to be considered by ComPact must be declared as shown below. Please note that there is a possibility of grouping a header file and a source code file into a C/C++ module, given that both of them share the same name. Moreover, you may use the optional export declaration for assigning an explicit export status to a file or module.
Decl ::= C-HeaderDecl
| C-SourceDecl
| C-ModuleDecl
| CC-HeaderDecl
| CC-SourceDecl
| CC-ModuleDecl
| CC-TemplateDecl
| ASM-SourceDecl
C-HeaderDecl ::= 'c_header' '(' PathParam [ ExpDecl ] ')' NL
C-SourceDecl ::= 'c_source' '(' PathParam [ ExpDecl ] ')' NL
C-ModuleDecl ::= 'c_module' '(' FileParam [ ExpDecl ] ')' NL
CC-HeaderDecl ::= 'cc_header' '(' PathParam [ ExpDecl ] ')' NL
CC-SourceDecl ::= 'cc_source' '(' PathParam [ ExpDecl ] ')' NL
CC-ModuleDecl ::= 'cc_module' '(' FileParam [ ExpDecl ] ')' NL
CC-TemplateDecl ::= 'cc_template' '(' PathParam [ ExpDecl ] ')' NL
ASM-SourceDecl ::= 'asm_source' '(' PathParam [ ExpDecl] ')' NL
We continue with the possibility of adding external C/C++ defines to the compilation process. The syntax is simply as follows:
Decl ::= AddDefineDecl
AddDefineDecl ::= 'add_define' '(' OptionParam [ ExpDecl ] ')' NL
OptionParam :: TokenOrString # the name of the option to be defined
You may use it to add the contents of the token or string as an external define to all dependency analyses and compilations taking place within the package.
Documentation files may be declared as shown below.
Decl ::= TexSourceDecl
| LatexSourceDecl
| TexInfoSourceDecl
| HtmlSourceDecl
| ManPageSourceDecl
| SgmlSourceDecl
| DocSourceDecl
TexSourceDecl ::= 'tex_source' '(' PathParam [ExpDecl] ')' NL
LatexSourceDecl ::= 'latex_source' '(' PathParam [ ExpDecl ] ')' NL
TexInfoSourceDecl ::= 'texinfo_source' '(' PathParam [ ExpDecl ] ')' NL
HtmlSourceDecl ::= 'html_source' '(' PathParam [ExpDecl ] ')' NL
ManPageSourceDecl ::= 'man_source' '(' PathParam [ ExpDecl ] ')' NL
SgmlSourceDecl ::= 'sgml_source' '(' Fileparam [ ExpDecl ] ')' NL
DocSourceDecl ::= 'doc_source' '(' PathParam [ ExpDecl ] ')' NL
Obviously, ComPact supports the following kinds of documentation: TeX, LaTeX, Texinfo, HTML, Unix manual pages, SGML, and Word documents.
Disregarding TPC-dependencies, library and program targets may be declared as follows:
TargetDecl ::= LibraryTargetDecl | ProgramTargetDecl
LibraryTargetDecl ::= 'library' '(' FileParam ')' NL
ProgramTargetDec ::= 'program' '(' FileParam ')' NL
Note: A package may contain more than one target.
It is possible to declare both a library and a program though, as usual, a program can be built only if there is exactly one main procedure. The pkgm command -build has an optional list of parameters, which may be used to specify what targets are to be built (cf. Chapter 5).
Indeed, the package concept would not make any sense if there was not a possibility of specifying package imports. Such references are always by package name; ComPact retrieves defines, files, and libraries to be included in the compilation and linkage process automatically. The syntax is shown below. In each case an admissible (range of) package version(s) must be specified. If you do not work with version control, however, each installation to be found in some pool is tagged d0.0.0. The corresponding specification should have the same form. Chapter 7, the chapter on version control, contains the general format.
Decl ::= PkgImportDecl
PkgImportDecl ::= 'import' '(' PkgParam ','VersionRange ')' NL
PkgParam ::= TokenOrString # the name of the imported package
VersionRange ::= 'd0.0.0'
ComPact lets you know how it resolves each package import declaration in the PkgDesc if you use the pkgm command -showimports | -imports
Moreover, arbitrary include paths, library paths, and libraries may be added to the target building process:
Decl ::= AddIncludeDecl
| AddLibPathDecl
| AddLibraryDecl
AddIncludeDecl ::= 'add_include' '(' PathParam ')' NL
AddLibPathDecl ::= 'add_libpath' '(' PathParam ')' NL
AddLibraryDecl ::= 'add_library' '(' FileParam ')' NL
This feature is extremely important. The reason is that it allows you to use all your installations that existed before you began to work with ComPact.
Complementary to specifying package imports, you may declare a file exported or hidden by using the syntax below. The semantics is as expected. In particular, a package element may be accompanied by a redundant export declaration, which merely makes its default export status explicit.
ExpDecl ::= ',' 'exported' | ',' 'hidden'
Mostly, a package contains one or more test programs and the corresponding source code. Test sections serve for distinguishing these package elements, so that they can be compiled and linked separately. Their syntax is as follows:
TestSection ::= 'test' TestSectionName ( Decl + ) ( TargetDecl + ) TestSectionName ::= TokenOrString
The pragmatics is such that all source and target files that make up a particular test suite are grouped together.
As an example, assume you wanted to include the test program messageutiltest from Chapter 2 in the package MessageUtil. You could achieve that simply by copying the source code file messageutiltest.c to MessageUtil / src, and at the same time, modifying the PkgDesc of MessageUtil as follows:
c_header("messageutil", exported)
c_source("messageutil")
library("messageutil") # exported by default test "message procedure"
# you may choose any other name here
c_source("messageutiltest")
program("messageutiltest")
If you type pkgm then both the library and the program are built.
Finally, you may use the syntax below for overriding ComPact's file extension defaults. This feature is, of course, useful if you have your own defaults.
Decl ::= FileExtensionDecl
FileExtensionDecl ::= C-HeaderExtDecl
| C-SourceExtDecl
| CC-HeaderExtDecl
| CC-SourceExtDecl
| C-GenericHeaderExtDecl
| C-GenericSourceExtDecl
| CC-GenericHeaderExtDecl
| CC-GenericSourceExtDecl
| CC-TemplateExtDecl
| ASM-SourceExtDecl
C-HeaderExtDecl ::= 'c_header_ext' '(' ExtensionParam ')' NL
C-SourceExtDecl ::= 'c_source_ext' '(' ExtensionParam ')' NL
CC-HeaderExtDecl ::= 'cc_header_ext' '(' ExtensionParam ')' NL
CC-SourceExtDecl ::= 'cc_source_ext' '(' ExtensionParam ')' NL
C-GenericHeaderExtDecl ::= 'c-generic_header_ext' '(' ExtensionParam ')' NL
C-GenericSourceExtDecl ::= 'c_generic_source_ext' '(' ExtensionParam ')' NL
CC-GenericHeaderExtDecl ::= 'cc_generic_header_extension' '(' ExtensionParam ')' NL
CC-GenericSourceExtDecl ::= 'cc_generic_source_extension' '(' ExtensionParam ')' NL
CC-TemplateExtDecl ::= 'cc_template_ext' '(' ExtensionParam ')' NL
ASM-SourceExtDecl ::= 'asm_source_ext' '(' ExtensionParam ')' NL
ExtensionParam ::= TokenOrString # the new default extension