Contents

NAME
Description
Scope
Prerequisites
Components of pconf
Prerequisites
How it works
PConf in depth
Package name and version
Installing
Generating documentation
Web Documentation
Configurable items
config.h
FAQ
Author
License & copyright
Version
Downloading

pconf - A Makefile skeleton that includes configuring

PConf, formaly known as for the Perl Configure System doesn't use Perl anymore. It has been rewritten to be a simple, self configuring Makefile skeleton to use with GNU Make.

PConf is commonly used for C/C++ projects. It can however also be used for other projects.

You will need GNU Make and a good shell environment with UNIX commands. For Windows, MSYS will do fine.

Makefile

This is the main makefile of a project. It is here where all subparts come together and is the specific part of your Makefiles.

Makefile.in

This is a generic Makefile that does a lot of work and predefines several make targets that can be reused in Makefile.

Makefile.local

This is a specific Makefile, that is included by Makefile.in. In this Makefile, all the to be checked dependencies are given. And extra fields can be given a value, to be used in the configure process.

Makefile.conf

This is a generic Makefile, that is used to configure a project and check all the needed dependencies. It determines the operating system used and all the flags, variables, etc. to be configured. This configuration is written to 'config/config.inn'. With help of Makefile.unify, it next writes out 'config/config.in', which is used by future instantiations of 'make' as the to be used Makefile include.

Makefile.unify

This is a generic Makefile, that is used to unify the flags that have been outputted by Makefile.conf to 'config/config.inn'. It compiles 'pconf_unify.c' and feeds the variables in 'config/config.inn' to them. Output is 'config/config.in'. All flags will be there in the variables in 'config/config.in' only ones and will have been ordered in the most prefered order.

pconf_unify.c

This is a generic C program, that is used to unify flags that are fed to it. It works in different modes: '--cflags', '--ldflags' and '--libs'. It orders its arguments according to the mode. '--cflags' and '--ldflags' order the flags in order of appearence and leave out flags that follow a flag and are equal to it. '--libs' orders the library references in order of appearence, but leaves out all library references that equal the last one. Examples:

pconf_unify --libs -lpthread -lutest -lcritsec -lpthread -lwx -lpthread'

will be output:

-lutest -lcritsec -lwx -lpthread

PConf expects following programs:

  • GNU Make.

  • Currently GNU CC/C++, maybe more compiler environments will be added later.

  • pod2html (from perl) or spod2html (a scheme variant of pod2html) to generate documentation. Although optional, this is the way documentation is generated in pconf.

  • Bourne Shell, preferably bash.

Notably MSYS+MinGW on Windows and bash+gcc on Linux/BSD variants will get you working.

PConf has two stages. The first stage is the configure stage. In this stage, pconf tries to get the name of the operating system, and tries to configure the given dependencies. Description of these configurable dependencies are given below (chapter 'Configurable options').

The needed dependencies are given by the programmer in 'Makefile.local'. 'Makefile.conf' contains all the code to resolve the dependencies and assemble the right CFLAGS, LDFLAGS and LIBS variables.

After stage one, there will be a file 'config/os.cfg', a file './config.h' and a file 'config/config.in'. If 'config/config.in' exists, no more configuration will be done, so the next time 'make' is invoced, 'config/config.in' will be included in Makefile.in, and that will be it.

'./config.h' contains a list of #defines that can be used by a program to create #ifdef ... #endif blocks. Also, if existent, './config.h.in' will be included in './config.h'.

In stage two, the actual make process is done. Stage two is the stage that is used after configuration has been done, either by running all the code in 'Makefile.conf', or by including 'config/config.in'.

If you want to rerun stage1, try 'make config' or 'make configure' or 'make distclean;make'.

In the PConf Makefile you always give 'VERSION' and 'PACKAGE' name. Example:

        PACKAGE:=pconf
        VERSION:=0.1

PConf can be used to install programs, libraries, header files and documentation for you. Note: Documentation will be placed in $(PREFIX_DOC)/$(PACKAGE). PREFIX_BIN, PREFIX_INC, PREFIX_LIB and PREFIX_DOC are normally derived from PREFIX in Makefile.in, but can be overridden in the Makefile.

The installation process is normally programmed out in Makefile. The install: target can be made dependend on docinst, bininst, libinst and incinst.

incinst expects a variable $(HEADERS), bininst expects a variable $(PROGRAMS), libinst expects a variable $(LIBRARIES). docinst will install all $(OS)/*.html files to the documentation installation directory.

PREFIX, PREFIX_BIN, PREFIX_INC, PREFIX_LIB, PREFIX_DOC

In Makefile:

        PREFIX=c:/local
        PREFIX_DOC=c:/documentation

This will install programs in $(PREFIX)/bin, libraries in $(PREFIX)/lib, documentation in 'c:/documentation/$(PACKAGE)' and header files in $(PREFIX)/include.

PConf uses 'POD' format for documentation. You can give the sources for documentation in the DOC_SOURCES variable. The files in this document are processed by 'pod2html' or 'spod2html'. This means that source files can be documented by using 'POD' directives.

While generating documentation, all patterns @PACKAGE@ and @VERSION@ will be replaced by the $(PACKAGE) and $(VERSION) variables.

For more information on SPOD look here.

DOC_SOURCES

DOC_SOURCES is used to give the source files that need processing by $(pod2html).

POD_CSS

POD_CSS is used to give an alternative Cascading Style Sheet to the POD to HTML generator.

Use variable WEB_DOC_PLACE to setup te place to put generated documentation on the web. Also all files ending on .css will be uploaded. make uploaddocs uploads documentation using SSH's secure copy SCP. The WEB_DOC_PLACE must contain a valid scp location string, e,g. in Makefile.local:

WEB_DOC_PLACE:=webdoc@sqlhuge.org:/var/www/htdocs

WEB_DOC_PLACE, default value: hnmdijkema@shell.sf.net:/home/groups/e/el/elementals/htdocs. WEB_INDEX, if given a value, the document indicated by this variable will be copied to index.html.

A configurable item normally has syntax of 'NEED_XYZ:=0, 1, 2 or 3'. All configurable items have default value '0'. A value of '1' means 'mandatory'. If this prerequisite is not there give up making this project. A value of '2' means 'optional'. If this prerequisite is not there, we can cope with it; but if it is there, configure it in. A value of '3' means 'check'. Only check for this prerequiste. If it is not there, we can cope, otherwise, only give us variable 'HAVE_xyz' in the Makefile and in 'config.h'; but don't configure any flags.

This last option 'check' will configure the variables xyz_CFLAGS, xyz_LDFLAGS and xyz_LIBS, which will give the possibility to conditionally use these flags in specific compilations. E.g. when compiling modules that depend on specific libraries, where the main program or library does not. NB! Not all configurable items support the '3' option.

NEED_PTHREADS:=1/2 will try to configure the CFLAGS, LDFLAGS en LIBS needed for the POSIX Threads library. PTHREAD_CXX_EXCEPTIONS triggers gives additional information needed by the POSIX Threads configuration process, PTHREAD_CXX_EXCEPTIONS defaults to '0'. Example:

        ### Threading
        ifeq ("$(OS)","WIN32")
        # C++ EXCEPTION HANDLING NEEDED!
        NEED_PTHREADS:=1
        PTHREAD_CXX_EXCEPTIONS:=1
        else
        NEED_PTHREADS:=1
        endif

NEED_CRITSEC:=1/2 will try to configure CFLAGS, LDFLAGS and LIBS for the libcritsec critical section library.

NEED_RVECTOR:=1/2 will try to configure CFLAGS, LDFLAGS and LIBS for the std::rvector<T, _Alloc> template class library for automatically resizing vectors. Needs STL installed. Also the backward compatible harray<T> template class library is installed.

The same applies for NEED_STL_RVECTOR, NEED_HARRAY and NEED_HSTACK.

NEED_UTEST:=1/2 will try to configure CFLAGS, LDFLAGS and LIBS for the utest C++ unit test library.

NEED_WXWIDGETS:=1/2 will try to configure CFLAGS, LDFLAGS and LIBS for wxWidgets.

NEED_SQLITE:=1/2 will try to configure CFLAGS, LDFLAGS and LIBS for the SQLite library.

NEED_LIBPQ:=1/2 will try to configure CFLAGS, LDFLAGS and LIBS for the PostgreSQL libpq library.

NEED_LTDL:=1/2 will try to configure CFLAGS, LDFLAGS and LIBS to use the libtool portable dynamic loading library (libltdl).

config.h contains all configured prerequisites, in terms of HAVE_... #defines. E.g., if one configured NEED_PTHREAD:=1, config.h will contain '#define HAVE_PTHREAD 1. If one configured NEED_PTHREAD:=2 (i.e. optional), and pthreads are not there, config.h will not contain #define HAVE_PTHREAD ....

Besides the HAVE_... macros, config.h contains the following macros:

#define SHL_EXT ...

Is a character string that contains the extension used for shared libraries and loadable modules, e.g. ".so" or ".dll".

#define EXE_EXT ..., OBJ_EXT and LIB_EXT

The same applies for the extension for executabels (EXE_EXT), the extension for object files (OBJ_EXT) and the extension for static libraries (LIB_EXT).

I configured 'NEED_XYZ:=1' and the dependency isn't there, but the configure process doesn't stop. What's wrong?

You did the right thing. You configured 'NEED_XYZ:=1'. But you might have run into a whitespace problem. If you configured 'NEED_XYZ:=1  ', '"$(NEED_XYZ)"="1"', will not evaluate to "1"="1", but to "1  "="1". See there the problem. Fix it by removing any whitespace in the variable assignments.

I want to know the extension for shared libraries used on the platform I'm compiling on.

Include config.h in your program and use the #defines SHL_EXT, EXE_EXT, OBJ_EXT and LIB_EXT.

Hans Oesterholt-Dijkema <hdnews -at- gawab.com>

(c) Hans Oesterholt-Dijkema 7-2004, License: Artistic.

This document is part of the 'pconf' package, v0.22.

Latest releases of all packages can be found here.