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.
This is the main makefile of a project. It is here where all subparts come together and is the specific part of your Makefiles.
This is a generic Makefile that does a lot of work and predefines several make targets that can be reused in Makefile.
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.
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.
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.
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:
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
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:
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
incinst expects a variable
bininst expects a variable
libinst expects a variable
docinst will install all
files to the documentation installation directory.
PREFIX, PREFIX_BIN, PREFIX_INC, PREFIX_LIB, PREFIX_DOC
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
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
For more information on SPOD look here.
DOC_SOURCES is used to give the source files that need processing by
POD_CSS is used to give an alternative Cascading Style Sheet to the POD to HTML generator.
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, default value:
WEB_INDEX, if given a value, the document indicated by this variable will be copied to
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
This last option 'check' will configure the variables
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'.
### 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
harray<T> template class library is installed.
The same applies for
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
config.h contains all configured prerequisites, in terms of
#defines. E.g., if one configured
config.h will contain '
#define HAVE_PTHREAD 1. If one configured
optional), and pthreads are not there,
config.h will not contain
#define HAVE_PTHREAD ....
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.
#define EXE_EXT ...,
The same applies for the extension for executabels (
EXE_EXT), the extension for object files (
and the extension for static libraries (
'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"', will not evaluate to
"1"="1", but to
See there the problem. Fix it by removing any whitespace in the variable assignments.
config.h in your program and use the
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.