How configure.exe works Craig Southeren Last updated 25 November 2004

Contents

1. Introduction

One of the great challenges in maintaining a multi-platform software library like PWLib is that developers can configure there their systems in many, many different ways. The Unix community has solved this problem using the GNU autoconf program, and while that solution uses a somewhat arcane syntax, and is very convoluted in function (like many  Unix utiilties) it does work and  has become the de-facto standard for the Unix platform.

Unfortunately there is no such standard for Windows, which means autoconf only solves half the problem. So, we developed a configure program for Windows that attempts to reproduce many of the similar functions as autoconf, but in a way that makes it work for Windows. This program is usually referred to as "configure.exe" and it lives in the pwlib/tools/configure directory. A Windows executable is provided with both PWLib and OpenH323 and is invoked automatically as part of the build process.

This document described how configure.exe works so that developers can use it's features to add new modules to PWLib and OpenH323. 

2. Theory of operation

There are three principles behind configure.exe:

1. Information about packages is stored in special comment fields in the configure.ac (or configure.in) file for the project. Most (but not all) of the non-comment lines in configure.ac are ignored. This allows all of the configuration information for Unix and Windows to be located in the same file
    
2. configure.exe scans every directory on the local filesystem looking for installed packages. Packages are identified using filename hints that are provided by the comments in the configure.ac file. Once a package has been identified, further hints specify symbols that can be defined
   
3. Once all of the installed packages have been located, the files named in AC_CONFIG_HEADERS directives will be loaded and processed. This will create output files that reflect the correct configuration

3. MSWIN comment lines

configure.exe derives information about packages from comment lines in the input file that has the following format:

dnl MSWIN_command feature , arguments

The feature string is used to group all of the directives associated with one feature together. While it is normal for lines associated with one feature to be on consecutive lines, this is not required and can lead to mysterious problems if a "cut & paste" error causes directives for one feature to be in different parts of the same file.

Features can also be disabled by name using command line parameters.

The command string specifies the action to be taken. The possible command strings are:

The best way to learn more about how these commands are used is to look in the configure.ac file for PWLib or OpenH323

4. Directory scanning

The directory scanning process will consider a package to be installed if it meets the CHECK_FILE and CHECK_DIR requirements. Directories will be excluded from scanning if they are listed in the PWLIB_CONFIGURE_EXCLUDE_DIRS environment variable, or can be excluded using command line options.

5. Rewriting files

When all directories have be scanned, each of the file specified in AC_CONFIG_HEADERS directives will be loaded and rewritten to a new file without the ".in" suffix. The rewriting is performed by doing the following replacements:

• Lines of the form
  
      #undef symbol 
  
  where symbol corresponds to a symbol defined by a MSWIN_DEFINE directive for a installed feature will be replaced by:
  
      #define symbol value
  
• Any occurence of the string
  
      @symbol@
  
  where symbol corresponds to a symbol defined in a MSWIN_DIR_DEFINE directive for an installed feature will be replaced with the directory in which the feature is installed

6. Using Windows pragmas for configure.exe

The effective use of configure.exe is dramatically simplified by the use of two Windows-specific #pragma directives that allow preprocess directives to affect include directives, and to add libraries to the link set. These directives described below:

#pragma include_alias

This directive provides a method to silently translate the argument to #include directives, which is very useful as it allows "normalised" directives in the source to have the full pathname added. For example, the following directive ensures that all instances of "#include <avcodec.h>" in the source code will be changed to include the full pathname. 

#pragma include_alias(<avcodec.h>, <@H323_RFC2190_AVCODEC_DIR@/avcodec.h>)

Note that the symbol @H323_RFC2190_AVCODEC_DIR@ will be rewritten by configure.exe to be the name of the directory in which the appropriate module is installed

#pragma comment(lib, libname)

This directive specifies that libname should be included into the link set for the final program. This pragma, if suitably guarded by ifdefs, allows required libraries to be added for features without requiring the developer to manually edit their project files  

Change History

Copyright © 2003-2007 by Post Increment A.B.N 95 856 785 279
All Rights Reserved
All trademarks and copyrights on this page are owned by their respective owners.