2.2. Basic Package Usage

2.2.1. Creating Collections and Packages

Package collections, collections for short, facilitate the handling of large numbers of packages. There is, in fact, never any package that does not belong to a collection. So you must get hold of a collection before you can create a package. There are two possibilities of doing that:

1. Checking out an existing one from the version control repository.

2. Creating a new one.

We postpone taking account of the first option to the beginning of Chapter 7, where the entire version control mechanism is described in detail. As for the second option, there is creation command, which has the format ( -newcollection | -newcol | -newc ) <collection_name> We suggest you use it to create a new, empty collection. The name does not matter unless ComPact informs you that it is already in use. Moreover, the version control system will ask you for a log message, possibly by invoking an editor. Once this process is finished, you should see the following confirmation:

   !!! warning: undefined package: no package root
   new collection <collection name> created and put under
   version control

The collection, then, should appear as a sub-directory, and its being under version control should reveal itself by the presence of a sub-sub-directory. This directory's name should be the same as that of the version control system your installation works with. The system known as CVS is currently the only supported one.

We continue with the command used for creating new packages. Its format is ( -newpackage | -newpkg | -newp ) <package_name> and it must be given so that the current working directory is a collection directory. The new member of that collection, then, appears as a new sub-directory. We suggest you add a package to the collection from the preceding step. You might want to choose the name MessageUtil, since it fits one of the two packages making up the example to be considered in the remainder of this section.

2.2.2. Package Structure

The directory structure of the newly created package is shown below, as is the purpose of each individual package element. Obviously, it is assumed that CVS is the underlying version control system. You might also note that the package description file is always called PkgDesc. Further still, the sub-directories inc and src are to contain header and source code files, and the sub-directory doc is the place where documentation is to be kept. The top-level is called the package root directory.

A package comprises everything that is needed to build one or more libraries and/or programs with the exception of any imported libraries, header files, and defines. Moreover, it contains the libraries and/or programs itself once they have been built. As for the package MessageUtil, this one is intended to export a library messageutil, which contains a simple procedure that can be used to print simple text messages. C/C++ necessitates a header and a source code file for such purposes. So you may create a messageutil.h and a messageutil.c according to the scheme below.

• inc / messageutil.h:

  void message ( char* );
  

  
  
  

• src / messageutil.c:

  #include <stdio.h> 
  void message (char* string ) 
  { printf("%s\n", string);}
  

  
  
  

It remains to edit the package description file so that ComPact is able to recognize what is in the package and, at the same time, what is to be built. In this case the scheme is

• PkgDesc:

  c_header("messageutil", exported)
  c_source("messageutil") library("messageutil") #
  exported by default
  

  
  
  

2.2.3. Building

You might instantly proceed with typing pkgm -build which is the command to compile and link a target, that is, a library or program. Like many other commands, it determines the package in question from the current working directory.

The ensuing directory structure should have the appearance shown below. It exhibits three automatically generated objects, namely the files PkgDep and PkgImp, and the directory whose name is that of the current TPC. For the moment, only the directory is of immediate interest because it contains the target.

2.2.4. Shipping

We suggest you create a local pool in your work space and declare it in a personal ~/.compactrc or ~compact/compactrc (cf. Section 2.1.2). Afterward, you could proceed with typing pkgm -ship local which is the command to ship a target to the local pool. It must be given in the same fashion as pkgm -build. ComPact will then ask whether you want the shipment be tagged as d0.0.0, the current development version. The version control system actually demands a version, so the easiest thing to do is answering with typing yes.

2.2.5. Importing

We conclude this section with a second package, which imports MessageUtil. You may add it to the same collection, choosing the name MessageUtilTest since it contains a test program. The scheme for filling it in is

• src / messageutiltest.c:

  #include <messageutil.h> main ()
                    { message("hello world"); }
  

  
  
  

• PkgDesc:

  import("messageutil", "d0.0.0")
  c_source("messageutiltest")
  program("messageutiltest")
  

  
  
  

the program messageutiltest is built as soon as you type pkgm -build, and can then be found in the automatically created sub-directory whose name is the same as that of the current TPC. Note that one must state the version of the library messageutil that is to be imported. Moreover, we would like to point out that a test program does not normally deserve its own package. It would have been more in line with standard practice if we had suggested that messageutiltest.c be made part of MessageUtil. This approach would have meant that the package has more than one target, namely the library and the program. Yet, multiple targets are supported by ComPact. We have suggested a two-package approach because of didactical reasons.