USDA ARS

IPW Libraries

Library Documentation

The documentation for an IPW library consists of a description file (like those above), the man pages for the function categories, and the man pages for the functions themselves.

A library's description file has two sections:

  1. narrative text explaining the purpose and use of the library, and
  2. a list of categories and their functions.

The contents of the first section are stored in a file called "Description.html" in the library's source directory. The second section is generated automatically from the Makefiles within the library's source directory.

Man pages

The man pages for each category and its functions are stored in a subdirectory called "Man" located in the category's source directory. The source file for the category's man page is located in the subdirectory "Man/Category". This man page typically describes the header file associated with the category.

The source file for each function's man page resides in a separate subdirectory named after the function. For example, the source file for the function "foo"'s man page would be located in the subdirectory "Man/foo".

Makefiles

There are three levels of Makefiles within a library's source directory:

  1. top-level Makefile for the library itself,
  2. Makefile for each category, and
  3. individual Makefile for each man page.

The Makefile format for the top two levels is the same; they simply list the categories in the library, and the functions in each category.

     ---  library Makefile  ---

     LIB := name
     DESCRIPTION := ...

     DIRS := cat1 cat2 ...

     include $(IPW)/make/library


     ---  category Makefile  ---

     CATEGORY := name
     DESCRIPTION := ...

     FUNCS := func1 func2 ...

     include $(IPW)/make/funcCategory

The categories and functions appear in the library's description file is the order specified. Each function has its own source file with the extension ".c". In the example above, the source files would be "func1.c", "func2.c", etc. Note that the extensions are not specified with the FUNCS macro.

If a category has additional private functions that are called only by the category's public functions and not from outside the category, then the source files for these private functions are specified using the optional PRIVATE_SRCS macro:

     FUNCS := ...

     PRIVATE_SRCS := _init.c _globals.c _newItem.c

     include $(IPW)/make/funcCategory

The Makefiles for the man pages for the category and its functions have the same format, differing only in the include file that's referenced:

     NAME := foo
     DESCRIPTION := blah blah blah

     include $(IPW)/make/funcCatManpg

       or

     include $(IPW)/make/funcManpage


IPW documentation / Last revised 21 May 2009 / IPW web site