Elego ComPact Manual Set Version 1.2
Prev	Chapter 7. Package Management using the Graphical User Interface	Next

7.2. Package Description Files

A package description file named PkgDesc is used to declare

the source elements of a package, their type, and export status
the target elements of a package, their type, and export status
the imported packages together with an acceptable version range
test program sections for the package
platform dependent package contents and definitions
additional definitions needed for the package

We will first have a look at an example, and then examine the general syntax and semantics of the mentioned elements.

The package description file resides in the root directory of the packages. It is not mandatory for every kind of package, but it must be present for the ComPact build system to work. In any case it is a good idea to keep an up-to-date package description file, as the package manager can then perform some more checks, for example, before changes are committed or released. If you don't have a project description file, the command pkgm -populate will usually provide a good start or extend the existing one by missing declarations. See also Section 7.4 for a description of this command.

Figure 7-5. A sample PkgDesc file

import("cvs-config", "dx.x.x")
import("cvs-error", "dx.x.x")

add_define("-DHAVE_CONFIG_H")

c_header("fnmatch", exported)
c_header("getline", exported)
c_header("getopt", exported)
c_header("md5", exported)
c_header("regex", exported)
c_header("savecwd", exported)
c_header("system", exported)
c_header("wait", exported)

c_source("argmatch")
c_source("getline")
c_source("getopt")
c_source("getopt1")
c_source("md5")
c_source("regex")
c_source("savecwd")
c_source("sighandle")
c_source("stripslash")
c_source("xgetwd")
c_source("yesno")

main:
  library("cvs-lib")

; stuff for Windows 32 platform
target ".*-win32-.*":
  add_include("..\..\inc\win32", exported)

  c_header("inc\win32\ndir", exported)
  c_header("inc\win32\pwd", exported)

  c_source("fncase")
  c_source("fnmatch")
  c_source("valloc")
  c_source("vasprintf")

  c_source("src\win32\ndir")
  c_source("src\win32\pwd")
  c_source("src\win32\sockerror")
  c_source("src\win32\stripslash")
  c_source("src\win32\waitpid")
  c_source("src\win32\win32")

  c_source("src\win32\getdate")

; use yacc on all other platforms
other targets:
  yacc_c_source("getdate")

Figure 7-5 shows the project description file of the cvs-lib package, which is shipped with Elego ComPact as part of the GNU CVS example project. Every line contains at most one declaration. Lines starting with a `;' or a `#' character are comment lines. You will also note that some declarations are grouped together to special sections under a section declaration ending with a colon (`:').

Source File Declarations . Most of the lines in the above PkgDesc file declare source files of a certain type or kind, like

c_header("savecwd", exported)
c_source("argmatch")

declaring a C header file named savecwd, which is exported and thus can be used by other packages, and a C source code file argmatch (which is hidden by default). Some of the file kinds known to ComPact as shipped are

document_file	depfile	code_object_file	perl_source
python_source	shell_script	c_source	c_header
c_generic_header	c_generic_source	c_module	c_generic_module
cc_source	cc_header	cc_generic_header	cc_generic_source
cc_module	cc_generic_module	lex_c_source	lex_cc_source
yacc_c_source	yacc_cc_source	autoconf_c_header	tex_source
latex_source	texinfo_source	sgml_source	html_source
man_page	doc_source

The complete actual declarations can always be found in the pkgconf.cbcl resource file, which defines all kinds of elements, derivations, and actions used by the build system of ComPact. All file declarations have a default prefix, a default suffix (or a default extension), and a default location, which are used to complete the names of the declared files. These too are defined in the pkgconf.cbcl resource.

Target Declarations . There is exactly one target declaration in this example, namely

  library("cvs-lib")

This declares a library file (which contains the object code of all compiled sources) named cvs-lib. A non-exhaustive list of possible targets is

program	library	dummy_target	java_archive_file
java_start_script	ps_file	dvi_file	html_file
ascii_file

General Syntax of Declarations . A declaration of a file of any kind has the form

  Kind ( Filename [ , ExportStatus ] )

where Kind is the name of a file kind defined in the backend configuration file pkgconf.cbcl, or one of the predefined file kinds known to ComPact, Filename is the name of the file included in double quotes, and ExportStatus is "exported" or "hidden".

Import Declarations . The two import declarations

import("cvs-config", "dx.x.x")
import("cvs-error", "dx.x.x")

make all exported elements of the packages cvs-config and cvs-error visible and usable in this package. For the import to succeed, those packages must have been successfully built and shipped to one of the package pools used by the ComPact build system. The above statements result in the import of the latest development version, as the version range for the import is given as "dx.x.x". Some more examples of version ranges are:

d2.3.x	d2.3.4-d2.4.2	r1.0.0
1.x.x	2.0.2-2.1.99

General Syntax of Import Declarations . An import declaration has the form

  import ( PackageName, VersionRange )

where VersionRange may be given as one of

  [ a | b | d | r ] Num . Num . x
  [ a | b | d | r ] Num . x . x
  [ a | b | d | r ] x . x . x
  [ a | b | d | r ] Num . Num . Num - [ a | b | d | r ] Num . Num . Num

The latter `x' denotes any decimal number, and is always matched with the highest available version from the available pools. The prefixes `a', `b', `d', `r' are used to denote alpha, beta, development, and release status of a version. Currently only `d' and `r' are used by ComPact. If no prefix is given, a release version is assumed.

Target-Platform-Dependent Sections . The example shows two platform specific sections, which are introduced by the declarations

target ".*-win32-.*":

other targets:

The first one begins a section for declarations specific to the Windows 32 bit operating system. The string after the keyword target contains a regular expression which is matched against the target-platform-configuration that is in effect during the build. The elements of the section are only evaluated if the match yields true. The second section declaration is the else-part of all target-specific section declarations. The elements of this section are only evaluated if no other target-platform-specific section applies.

Additional Declarations . There are various kinds of information that the build system might need in addition to the already described types of declarations, which are usually not read from a file. These types of information are specified in package description files via so-called virtual kinds, of which here is a short list:

add_define	add_include	add_libpath	add_library	java_package_name
c_header_ext	c_source_ext	cc_header_ext	cc_source_ext

The first four examples are used to pass additional C preprocessor definitions, include paths, library paths, and library names to be used for the build, while the last four are used to define default extensions of certain file kinds.

Prev	Home	Next
Package Management using the Graphical User Interface	Up	Building and Shipping Packages