<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-7A52BD40-E1C1-5C67-AAA0-1B79A34CF24C" xml:lang="en"><title>Template

extension makefiles</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>A template extension makefile is a makefile which is integrated into the

Symbian platform build system, such that it can be re-used by providing different

input values as parameters. This facility allows extension makefiles to separate

behaviour of the makefile from its input data. For example, you might want

to copy files from one location to another using a template extension makefile

which represents the required behaviour. The location from where these files

have to be copied is represented by the input data, which can be specified

in the <filepath>bld.inf</filepath> file using <xref href="GUID-2910AB26-CA7C-50B9-A187-0C8406C1ED1F.dita">prj_extensions</xref>. </p>

<p> <i>Note that it is recommended to follow GNU make syntax to define template

extension makefiles. For more details on GNU make syntax, refer </i> <xref href="http://www.gnu.org" scope="external">http://www.gnu.org</xref>. </p>

<p>The template extension makefiles are invoked by the build system which

defines a set of standard makefile variables. These variables can have well

defined values and help the makefile writer to locate common directories,

configurations and so on. The proper usage of these variables may result in

achieving platform independence to a certain extent. It is highly recommended

to use these variables wherever it is necessary. </p>

<p>The following is a list of the variables defined: </p>

<table id="GUID-FB51BFC4-5BB2-54C9-ACAA-A14F725C2706">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>Variable name</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <codeph>$(EPOCROOT)</codeph>  </p> </entry>

<entry><p>Location of the <codeph>epoc32</codeph> tree. </p> </entry>

</row>

<row>

<entry><p> <codeph>$(PLATFORM)</codeph>  </p> </entry>

<entry><p>The current platform which can be <codeph>TOOLS</codeph>, <codeph>ARMV5</codeph>, <codeph>WINSCW</codeph> etc. </p> </entry>

</row>

<row>

<entry><p> <codeph>$(CFG)</codeph>  </p> </entry>

<entry><p>The current configuration either <codeph>UREL</codeph> or <codeph>UDEB</codeph>. </p> </entry>

</row>

<row>

<entry><p> <codeph>$(TO_ROOT)</codeph>  </p> </entry>

<entry><p>Relative path to <codeph>EPOCROOT</codeph>. </p> </entry>

</row>

<row>

<entry><p> <codeph>$(TO_BLDINF)</codeph>  </p> </entry>

<entry><p>The path to the top-level <filepath>bld.inf</filepath>. </p> <p> <i>Note:

if a bld.inf file #includes another bld.inf, this variable will always contain

the directory of that top-level file. If you require the directory of the

bld.inf which actually references the makefile, use $(EXTENSION_ROOT) instead.</i>  </p> </entry>

</row>

<row>

<entry><p> <codeph>$(EPOCBLD)</codeph>  </p> </entry>

<entry><p>The project’s “working” build directory under <codeph>\epoc32\build\…</codeph>. </p> </entry>

</row>

<row>

<entry><p> <codeph>$(EXTENSION_ROOT)</codeph>  </p> </entry>

<entry><p>The path to the directory containing the <filepath>bld.inf</filepath> in

which the extension makefile was called. </p> </entry>

</row>

<row>

<entry><p> <codeph>$(HOST_SHELL) </codeph>  </p> </entry>

<entry><p>The path of the host-platform specific (i.e. the shell) makefile

containing the above definitions. </p> </entry>

</row>

<row>

<entry><p> <codeph>$/</codeph>  </p> </entry>

<entry><p>Path element separator. </p> </entry>

</row>

<row>

<entry><p> <codeph>$;</codeph>  </p> </entry>

<entry><p> <codeph>PATH</codeph> environment variable separator. </p> </entry>

</row>

<row>

<entry><p> <codeph>$(RMDIR)</codeph>  </p> </entry>

<entry><p>Command for directory removal. </p> </entry>

</row>

<row>

<entry><p> <codeph>$(RM)</codeph>  </p> </entry>

<entry><p>Command for file deletion. </p> </entry>

</row>

<row>

<entry><p> <codeph>$(ERASE)</codeph>  </p> </entry>

<entry><p>Command for file deletion. </p> </entry>

</row>

<row>

<entry><p> <codeph>$(MKDIR)</codeph>  </p> </entry>

<entry><p>Command for directory creation. </p> </entry>

</row>

<row>

<entry><p> <codeph>$(CP)</codeph>  </p> </entry>

<entry><p>Command for file copying. </p> </entry>

</row>

<row>

<entry><p> <codeph>$(PLATFORM_PATH)</codeph>  </p> </entry>

<entry><p>The current platform in lower case to be used as part of path names. </p> </entry>

</row>

<row>

<entry><p> <codeph>$(CFG_PATH)</codeph>  </p> </entry>

<entry><p>The current configuration in lower case to be used as part of path

names. </p> </entry>

</row>

</tbody>

</tgroup>

</table>

<p>The extension makefiles integrated into the build system should support

a number of phony targets which correspond to different phases of the Symbian

platform build process. These phony targets are labels representing a set

of commands to be executed to perform a task. For more information on these

phony targets, refer to <xref href="GUID-60B98AFE-6DE6-5086-B70C-F377562E60D9.dita">Extension

makefile targets</xref>. </p>

<p>The commands for a phony target can be platform specific operations such

as creating a directory, removing a directory, copying a file and so on. It

is recommended to use the above listed variables to perform these platform

specific operations, instead of invoking the command directly. </p>

<p>For example, the following will delete the files <filepath>values.cpp</filepath> and <filepath>config.cpp</filepath> for

the target CLEAN. </p>

<codeblock id="GUID-13E04491-476A-5DC0-B487-5E711051B7A2" xml:space="preserve">CLEAN : 

  -$(ERASE) $(MDIR)$/values.cpp

  -$(ERASE) $(MDIR)$/config.cpp</codeblock>

<p> <i>Note that any path within a template extension makefile is recommended

to use the path separator variable $/ as listed in the above table.</i>  </p>

<p>A template extension makefile can be referenced in the <filepath>bld.inf</filepath> file

using the <codeph>prj_extensions</codeph> keyword. For more information on

how to reference a template extension makefile, see <xref href="GUID-2910AB26-CA7C-50B9-A187-0C8406C1ED1F.dita">prj_extensions</xref>. </p>

<p>Each template extension makefile has an associated meta file which provides

additional information such as the template makefile type, the platform for

which the template can be applied and so on. It is mandatory to have a meta

file with each template extension makefile. For information on meta file syntax,

refer to <xref href="GUID-E6CB4891-AFC8-50BB-A2C8-057DB1269DA9.dita">Meta files</xref>. </p>

<p> <i>Note that all the template extension makefiles along with their meta

files need to be located under the \epoc32\tools\makefile_templates\ folder.</i>  </p>

<example><p>This example will copy the source files to a target

path, build the component using the target copy of the source files, and finally

delete the target copy of the source files. </p><codeblock id="GUID-94E381AB-129C-5D62-AAEC-54432DFAE786" xml:space="preserve"># copy_default.mk

#

SOURCE_COPY=$(EPOCROOT)epoc32$/release$/$(PLATFORM_PATH)$/$(CFG_PATH)$/$(SOURCES)

TARGET_COPY=$(EPOCROOT)epoc32$/release$/$(PLATFORM_PATH)$/$(CFG_PATH)$/$(TARGET)

$(TARGET_COPY) : $(SOURCE_COPY)

    $(CP) "$?" "$@"

DO_NOTHING :

  @rem do nothing

MAKMAKE : 

BLD : $(TARGET_COPY)

SAVESPACE : BLD

FREEZE : DO_NOTHING

LIB : DO_NOTHING

CLEANLIB : DO_NOTHING

RESOURCE : DO_NOTHING

CLEAN : 

    -$(ERASE) $(TARGET_COPY)

RELEASABLES : 

    @echo $(TARGET_COPY)

FINAL : 

</codeblock></example>

</conbody><related-links>

<link href="GUID-C07B506E-A1C8-537C-A7BF-DD7F449DF8A5.dita"><linktext>How to write

an extension makefile template</linktext></link>

</related-links></concept>