USDA ARS

Implementing IPW Commands as C Programs

Implementing an IPW command as a program is the most common approach to implementation -- over 85% of IPW's commands are programs. Currently, every IPW program is written in the C programming language (ANSI/ISO Standard C).

Makefile

The format of a program's Makefile is very similar to the Makefile for a script. A sample Makefile is provided in the file "$IPW/src/samples/command/Makefile.program". The basic Makefile for most IPW programs looks like this:

     PGM := foo
     DESCRIPTION := blah blah blah

     SRCS := main.c globals.c headers.c foo.c

     include $(IPW)/make/command

The PGM macro specifies the name of the program, and the SRCS macro lists all the C source-code files that make up the program.

Organization of source files

The source code for an IPW program is divided among several files according to a convention to ensure uniformity across all programs. The function and general format of each file is discussed below. Samples of these files are located in the directory refered to previously: "$IPW/src/samples/command". Note that some programs do not require all of these files.

IPWmacros.h
This C header file is automatically generated for each program. It defines C preprocessor macros that correspond to the IPW macros defined in the automatically-generated file "IPWmacros". For example,

IPW_NAME
the program's name -- used for making names of temporary files.

IPW_DESCRIPTION
used as an argument to the function "ipwenter()" -- see the file "main.c" below.

pgm.h
Every program must have this C header file. Every source-code file should include this header file. The general format for this header file is

main.c
This source-code file contains the program's "main()" function. The purpose of this function is to perform the setup prior to the actual processing of the input data. This setup includes

For small programs, e.g., those that perform simple operations on text data files, the actual processing of the input data is done in the "main()" function. For larger programs, i.e., those that work with image files, the "main()" function opens input, output and mask files, and then calls the two other functions to process image headers and pixel data in order (see the source-code files "headers.c" and "foo.c" below).

After the data is processed, the "main()" function performs any necessary cleanup, which always concludes with a call to the function "ipwexit()".

globals.c
This file contains the definitions for all the global variables shared by the various functions that constitute the program.

headers.c
A program that works with image files typically has this file which contains a function called "headers()". This function processes all the image headers, reading the headers of the input images, and using them to construct the headers for the output images.

foo.c
Typically, large programs do not process input data, e.g., pixel data, in the "main()" function, but rather use a separate function which is defined in this source-code file, and named after the program.

Linking with Libraries

By default, an IPW program is linked with the standard C library ("libc"), the math library ("libm"), and the standard IPW library ("libipw"). Additional libraries may be specified using the optional macro EXTRA_LIBS in the program's Makefile:

     PGM := foo
     DESCRIPTION := ...

     SRCS := ...

     EXTRA_LIBS := snobal model

     include $(IPW)/make/command

The order that the libraries are listed is important. If the functions in one library (e.g., "libA") call the functions in another library (e.g., "libB"), then the former ("libA") must be first in the list to ensure the linking phase of compilation is successful.


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