<?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>