Appendix A - Using Makefiles

Appendix A - Using Makefiles

The IRIS Explorer product provides UNIX tools to simplify the automatic building of modules after the Module Builder has created the module resources. This section describes the tools, their use in the creation of a single module, and their integration with the make utility in building a source tree that has several modules. It is not necessary to be an expert on make to understand this section, although a little knowledge is helpful.

While it is convenient to create the executable image for a module from the Module Builder, it is often necessary to create or modify modules from the UNIX shell without using a graphically based tool. This need is most common in connection with automatic compilation of entire source trees, most often with the make utility.

The structure assumed in presenting these tools is that the sources and module resources for one or more modules are kept together in a directory with no other user programs. The Module Builder handles all the necessary features of creating the Makefile to govern module building within this directory. It is also possible to have several sibling directories, each containing module programs and resources. The Module Builder tools provide the Makefile ingredients necessary to govern the building of all modules in all subdirectories with minimal user intervention.

Creating a Module

For purposes of illustration, consider the Contour module supplied with IRIS Explorer. The source for Contour can be found in directory /usr/explorer/src/Contour. The same description applies equally to any other IRIS Explorer module.

The general procedure for creating modules is:

Once the module has been built, you can rebuild the module from the UNIX shell (within the Contour module directory) by typing: 

make Contour

Do this whenever you change the source files of the Contour module. Running make does not result in any change in the interfaces to the Module Data Wrapper or Module Control Wrapper.

Note: When these interfaces do change, for example, when you add or delete a function argument or a port, or change widget types, you must run the Module Builder to update the module resources.

Installing a Module

When running IRIS Explorer, it is useful to keep the key components of all modules, their executables, resources, documentation, and credits files in one directory. This simplifies module selection with the Module Librarian. Each module's Makefile (generated by the Module Builder) has an action called install, which copies the mentioned files to a definable installation directory. install also causes the module to be built, if necessary. To build and install the module, type:

make install

Note: make install builds and installs all modules within the current directory; there is no command to allow installation of only a single module from within a multi-module directory.

Build and Installation Options

In some implementations IRIS Explorer can use shared libraries for the Module Control Wrapper and the API library. You can enable this feature by setting the CXBUILDSHARED environment variable and remaking the module Makefile, as follows. 

setenv CXBUILDSHARED 1
make Makefile
make all

Setting the CXINSTALLSYMBOLIC variable when the module's Makefile is created causes a module to be installed with a symbolic link from the installation directory back to the module directory. For example, this sequence causes symbolic installation of the module: 

setenv CXINSTALLSYMBOLIC 1
make Makefile
make install

Symbolic installation can save a large amount of disk space, as many modules are half a megabyte or more in size.

The CXINSTALLSTRIPPED environment variable controls the stripping of the module's symbol table to save disk space (at the expense of debugging information). Setting CXINSTALLSTRIPPED before the module is installed causes the installed module to be stripped. This removes symbol table information and reduces module size significantly.

By default, make install installs modules in $EXPLORERUSERHOME/modules. Normally, you cannot write directly into that directory. To change the directory where modules are installed, define EXPLORERUSERHOME to contain the directory name where modules should be installed. They will be installed in a subdirectory under $EXPLORERUSERHOME named modules. You can override this on a per-module directory basis with the Module Builder's User Makefile option. Choose a filename, such as myMakefile, enter its name in the User Makefile slot on the Module Builder main window, and insert the following line in that file: 

CXMODULES_INST = <pathname>

where <pathname> is the actual pathname where modules in this directory should be installed.

Generating Makefiles

In most cases, you do not need to recreate a module's Makefile from the UNIX shell. The Makefile is saved whenever you select Save Resources from the File menu or Build or Build & Install from the Build menu on the Module Builder's main window. However, it is also possible to recreate the Makefile from the UNIX shell, in case you accidentally delete it or change the environment variables discussed above.

The cxmkmf command is a shell script located in the /usr/explorer/bin directory. If you don't have this directory in your path, you must specify the full command name: 

/usr/explorer/bin/cxmkmf

Make Clean

The module Makefile also performs another useful action, cleaning automatically generated files out of the directory. To do this, type: 

make clean

This command removes all automatically generated files except the module's Makefile and the related Imakefile. Cleaning also removes the module executable so that a new build will force recompilation and linking.

The MODULES File

Makefile generation depends on the file MODULES in the module directory. This file contains a list of the modules to be built in that directory. The generated Makefile contains rules for building, cleaning, and installing all modules listed in the MODULES file. The MODULES file is automatically updated by the Module Builder, so you never need to touch it. However, you can remove a module from the build process by deleting its name from the MODULES file.

Using Imake in Module Building

The IRIS Explorer make environment relies on the X Window System tool imake to provide machine-independent Makefile generation and execution. All Imakefiles and Makefiles in the module directories are generated automatically by the Module Builder, so you never need to edit those files. Any changes you do make are likely to be deleted on the next invocation of the Module Builder.

You can find out more about IRIS Explorer's use of imake by looking at the files in /usr/explorer/config. Most of these files are copies of the standard X Window System imake release with minor changes. They include:

Using Generated Makefiles

The Module Builder automatically creates the Imakefile for you. You can add custom lines into the generated Imakefile by placing them in another file, then entering that filename in the User Makefile slot in the Module Builder main window. You can use this facility to modify the default build and install sequence by defining values for special make variables.

Some make variables can be changed and some cannot. Table A-1 and Table A-2 respectively list the variables.

Table A-1 lists the make variables that you can change in a user Makefile.

Variable Meaning
DEFINES Definitions for cpp use in C, C++, and Fortran compiles, and in make depend.
CDEFINES Passed to the C compiler
C++DEFINES Passed to the C++ compiler
FDEFINES Passed to the Fortran compiler
INCLUDES Include directory specification for cpp use in C, C++, and Fortran, and in make depend.
CINCLUDES Include directory specification for
C++INCLUDES Include directory specification for cpp use in C++ compiles
FINCLUDES Include directory specification for cpp use in Fortran compiles
LOCAL_LDFLAGS Loader flags to be passed when linking modules
LOCAL_LIBRARIES Library filenames relative to the local directory (or fully qualified). Used in linking modules and in calculating dependencies so that the module will re-link if any of these libraries changes.
SYS_LIBRARIES System libraries (given in the -L<dir> -l<lib> form) to be passed to the loader.
Table A-1 User-definable make Variables

Table A-2 lists some of the make variables you should not change. They are used by the built-in configuration:

Compiler Compiler Flags Defines Includes
CC CFLAGS ALLDEFINES ALLINCLUDES
C++ C++FLAGS ALLC++DEFIN ES ALLC++INCLUD ES
FC FCFLAGS ALLFDEFINES ALLFINCLUDES
LDLIBS LDOPTIONS
Table A-2 System-required Variables

Default Makefile Actions

The generated Makefile performs two additional actions when a make install command is given at the UNIX shell, or when you select "Build & Install" from the Build menu. If the modulename.doc and modulename.credit files do not exist, the Makefile creates prototype documentation and credits files with those names.

The creation of prototype module documentation is described in Chapter 2, "Understanding the Module Builder".

Installing Credit Files

In general, IRIS Explorer module credit files are image files in TIFF format, though some implementations support other image formats.

Because credit image files are typically large, IRIS Explorer offers a variety of ways to install them, allowing for symbolic links to existing image files to be created automatically. Understanding this procedure will provide maximum flexibility and control over the image presented when you select the "Credits" item on the module menu. It also reduces the amount of disk space required.

Note: The prototype credits file is a link to UserModule.credit in the /usr/explorer/lib directory.

Sometimes, however, you may want a custom credit image file for modules you create. In this case, you can define an environment variable named CXCREDITS to contain the file name of the credit image file. This variable is consulted when the module Makefile is created and not consulted again when the credit link is installed. If, when the Makefile is made, this variable is defined, it overrides the default location of the credit file given above.

You may want a different credit file for each module development subdirectory. In this case, you need only define a user Makefile in the Module Builder main window and place in that file a line, for example: 

CXCREDITS = filename

where filename is the full name of the credit file for the modules in this directory.

For each module in a module development subdirectory, if there exists a file with the same base name as the module but with the suffix .credit, this file will be installed as the credit file for that module. So, for example, there may be a module named Shape in a development subdirectory. If there were also a file named Shape.credit, it would be installed as the credit file for this module.

In all cases but the last, the installation of the credit file is done with a symbolic link, so very little disk space is taken by the credit files.

Last modified: Fri Aug 2 16:12:02 1996
[ Documentation Home ]
© NAG Ltd. Oxford, UK, 1996