Preface

Author: $Author: maroy $
Version: $Revision: 1.2 $
Location: $Source: /home/cvs/livesupport/doc/developmentEnvironment/makefileConventions.html,v $

Scope

This document describes the Makefile file conventions for the LiveSupport project. See also the generic description of the file conventions in the LiveSupport project. This document does not describe the mandatory targets for Makefiles, see the build environment description for such details.

Introduction

Makefiles are text-based files processed by GNU make. As text based files, they should adhere to the generic text-based conventions.

Naming

Makefiles are always named Makefile. In case they are input files for automake or autoconf, they can be named Makefile.in or Makefile.am.

Structure

Makefiles are partitioned by using the following 80 column wide partitioning comment:

#-------------------------------------------------------------------------------
# This is the title of the partition
#-------------------------------------------------------------------------------

The file has the following mandatory structure:

Header
General command definitions
Basic directory and file definitions
Configuration parameters
Dependencies
Targets
Specific targets
Pattern rules

Header

The header holds all information mandated by the generic guidelines, but starting with the Makefile comment character #. Note the 80 column wide partitioning delimiter enclosing the header.

#-------------------------------------------------------------------------------
#   Copyright (c) 2004 Media Development Loan Fund
#
#   This file is part of the LiveSupport project.
#   http://livesupport.campware.org/
#   To report bugs, send an e-mail to bugs@campware.org
#
#   LiveSupport is free software; you can redistribute it and/or modify
#   it under the terms of the GNU General Public License as published by
#   the Free Software Foundation; either version 2 of the License, or
#   (at your option) any later version.
#
#   LiveSupport is distributed in the hope that it will be useful,
#   but WITHOUT ANY WARRANTY; without even the implied warranty of
#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#   GNU General Public License for more details.
#
#   You should have received a copy of the GNU General Public License
#   along with LiveSupport; if not, write to the Free Software
#   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
#
#
#   Author   : $Author: maroy $
#   Version  : $Revision: 1.2 $
#   Location : $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/makefileConventions.html,v $
#-------------------------------------------------------------------------------

General command definitions

This section contains definitions to commands used when executing the make targets within this Makefile. All the commands should be collected here, and a variable defined for them. This insures easy overview of the commands the Makefile uses, and also makes it easy to migrate to new commands, or the same commands in different locations.

No external commands may be directly referenced outside this section.

Sample

A sample general command definitions section follows.

#-------------------------------------------------------------------------------
#   General command definitions
#-------------------------------------------------------------------------------
MKDIR   = mkdir -p
RM      = rm -f
RMDIR   = rm -rf
DOXYGEN = doxygen

Basic directory and file definitions

This section contains definitions for the directories and files referenced in this Makefile. All directories referenced from the Makefile, and all external files referenced by the Makefile should be collected here. This insures easy adoption in case some external directories or files change.

No directories or external files may be directory referenced outside this section.

When referencing other LiveSupport modules, typically the following variables are defined for them:

MODULEX_DIR         = ${MODULES_DIR}/moduleX
MODULEX_INCLUDE_DIR = ${MODULEX_DIR}/include
MODULEX_LIB_DIR     = ${MODULEX_DIR}/lib
MODULEX_LIB         = livesupport_modulex

Sample

A sample directory and file definition section follows.

#-------------------------------------------------------------------------------
#   Basic directory and file definitions
#-------------------------------------------------------------------------------
BASE_DIR    = .
DOC_DIR     = ${BASE_DIR}/doc
DOXYGEN_DIR = ${DOC_DIR}/doxygen
ETC_DIR     = ${BASE_DIR}/etc
SRC_DIR     = ${BASE_DIR}/src
TMP_DIR     = ${BASE_DIR}/tmp


USR_DIR         = ${BASE_DIR}/../../usr
USR_INCLUDE_DIR = ${USR_DIR}/include
USR_LIB_DIR     = ${USR_DIR}/lib
BOOST_INCLUDE_DIR    = ${USR_INCLUDE_DIR}/boost-1_31
LIBXMLPP_INCLUDE_DIR = ${USR_INCLUDE_DIR}/libxml++-1.0

MODULES_DIR = ${BASE_DIR}/../../modules

HELLOLIB_DIR         = ${MODULES_DIR}/hello
HELLOLIB_INCLUDE_DIR = ${HELLOLIB_DIR}/include
HELLOLIB_LIB_DIR     = ${HELLOLIB_DIR}/lib
HELLOLIB_LIB         = livesupport_hello

VPATH    = ${SRC_DIR}

HELLO_EXE = ${TMP_DIR}/hello

DOXYGEN_CONFIG = ${ETC_DIR}/doxygen.config

Configuration parameters

This section contains the parameters passed to the building tools (compiler, linker, etc.) When invoking building tools, they should be parametrized by the definitions made here.

Sample

A sample configuration parameters section follows.

#-------------------------------------------------------------------------------
#   Configuration parameters
#-------------------------------------------------------------------------------
CPPFLAGS = 
CXXFLAGS = -pedantic -Wall \
           -I${USR_INCLUDE_DIR} -I${HELLOLIB_INCLUDE_DIR} \
           -I${INCLUDE_DIR} -I${TMP_DIR}
LDFLAGS  = -L${USR_LIB_DIR} -L${HELLOLIB_LIB_DIR} -L${LIB_DIR}

Dependencies

The dependencies section lists the objects that are build by implicit rules, and that main targets depend on. This is the place where all object files are listed, basically, for each library or executable.

No object files that are built by this Makefile should be directly referred to outside this section.

Sample

A sample dependencies section follows.

#-------------------------------------------------------------------------------
#   Dependencies
#-------------------------------------------------------------------------------
HELLO_EXE_OBJS = ${TMP_DIR}/main.o

Targets

This section lists all the explicit, external targets for the makefile. For a list of targets required, see the description of the build environment. All targets in this section are marked as .PHONY, as these targets are not building the files they are named after.

No explicit targets should be defined in the Makefile outside this directory.

Sample

A sample targets section follows.

#-------------------------------------------------------------------------------
#   Targets
#-------------------------------------------------------------------------------
.PHONY: all dir_setup doc clean docclean depclean distclean
                                                                                
all: dir_setup ${HELLO_EXE}
                                                                                
dir_setup: ${TMP_DIR} ${DOXYGEN_DIR}
                                                                                
doc:
    ${DOXYGEN} ${DOXYGEN_CONFIG}
                                                                                
clean:
    ${RM} ${HELLO_EXE_OBJS} ${HELLO_EXE}
                                                                                
docclean:
    ${RMDIR} ${DOXYGEN_DIR}/html
                                                                                
depclean: clean
                                                                                
distclean: clean docclean
    ${RMDIR} ${TMP_DIR}/config* ${TMP_DIR}/autom4te*

Specific targets

This section defines the targets for files to be built by the Makefile. These are the targets that specify how files are built, but are not covered by pattern rules.

Sample

A sample specific targets section follows.

#-------------------------------------------------------------------------------
#   Specific targets
#-------------------------------------------------------------------------------
${HELLO_EXE}: ${HELLO_EXE_OBJS}
    ${CXX} ${LDFLAGS} -o $@ $^ -l${HELLOLIB_LIB}
                                                                                
${TMP_DIR}:
    ${MKDIR} ${TMP_DIR}
                                                                                
${DOXYGEN_DIR}:
    ${MKDIR} ${DOXYGEN_DIR}

Pattern rules

Pattern rules are the generic rules to build target files from object files. Define these pattern rules in this section.

No pattern rules should exist outside this section.

Sample

A sample pattern rules section follows.

#-------------------------------------------------------------------------------
#   Pattern rules
#-------------------------------------------------------------------------------
${TMP_DIR}/%.o : ${SRC_DIR}/%.cxx
    ${CXX} ${CPPFLAGS} ${CXXFLAGS} -c -o $@ $<

Template

See a generic template for Makefiles. You may freely copy this template when starting to create a new Makefile.