Preface

This document is part of the Campcaster project, Copyright © 2004 Media Development Loan Fund, under the GNU GPL.

Scope

This document describes the Makefile file conventions for the Campcaster project. See also the generic description of the file conventions in the Campcaster 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

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 Campcaster project.
#   https://www.campware.org/
#   To report bugs, send an e-mail to [email protected]
#
#   Campcaster 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.
#
#   Campcaster 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 Campcaster; if not, write to the Free Software
#   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
#
#
#   Author   : $Author: paul $
#   Version  : $Revision: 2373 $
#   Location : $URL: svn://code.campware.org/campcaster/trunk/campcaster/doc/developmentEnvironment/makefileConventions.html $
#-------------------------------------------------------------------------------

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 Campcaster 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         = campcaster_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         = campcaster_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.