1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-7A52BD40-E1C1-5C67-AAA0-1B79A34CF24C" xml:lang="en"><title>Template |
|
13 extension makefiles</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>A template extension makefile is a makefile which is integrated into the |
|
15 Symbian platform build system, such that it can be re-used by providing different |
|
16 input values as parameters. This facility allows extension makefiles to separate |
|
17 behaviour of the makefile from its input data. For example, you might want |
|
18 to copy files from one location to another using a template extension makefile |
|
19 which represents the required behaviour. The location from where these files |
|
20 have to be copied is represented by the input data, which can be specified |
|
21 in the <filepath>bld.inf</filepath> file using <xref href="GUID-2910AB26-CA7C-50B9-A187-0C8406C1ED1F.dita">prj_extensions</xref>. </p> |
|
22 <p> <i>Note that it is recommended to follow GNU make syntax to define template |
|
23 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> |
|
24 <p>The template extension makefiles are invoked by the build system which |
|
25 defines a set of standard makefile variables. These variables can have well |
|
26 defined values and help the makefile writer to locate common directories, |
|
27 configurations and so on. The proper usage of these variables may result in |
|
28 achieving platform independence to a certain extent. It is highly recommended |
|
29 to use these variables wherever it is necessary. </p> |
|
30 <p>The following is a list of the variables defined: </p> |
|
31 <table id="GUID-FB51BFC4-5BB2-54C9-ACAA-A14F725C2706"> |
|
32 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
33 <thead> |
|
34 <row> |
|
35 <entry>Variable name</entry> |
|
36 <entry>Description</entry> |
|
37 </row> |
|
38 </thead> |
|
39 <tbody> |
|
40 <row> |
|
41 <entry><p> <codeph>$(EPOCROOT)</codeph> </p> </entry> |
|
42 <entry><p>Location of the <codeph>epoc32</codeph> tree. </p> </entry> |
|
43 </row> |
|
44 <row> |
|
45 <entry><p> <codeph>$(PLATFORM)</codeph> </p> </entry> |
|
46 <entry><p>The current platform which can be <codeph>TOOLS</codeph>, <codeph>ARMV5</codeph>, <codeph>WINSCW</codeph> etc. </p> </entry> |
|
47 </row> |
|
48 <row> |
|
49 <entry><p> <codeph>$(CFG)</codeph> </p> </entry> |
|
50 <entry><p>The current configuration either <codeph>UREL</codeph> or <codeph>UDEB</codeph>. </p> </entry> |
|
51 </row> |
|
52 <row> |
|
53 <entry><p> <codeph>$(TO_ROOT)</codeph> </p> </entry> |
|
54 <entry><p>Relative path to <codeph>EPOCROOT</codeph>. </p> </entry> |
|
55 </row> |
|
56 <row> |
|
57 <entry><p> <codeph>$(TO_BLDINF)</codeph> </p> </entry> |
|
58 <entry><p>The path to the top-level <filepath>bld.inf</filepath>. </p> <p> <i>Note: |
|
59 if a bld.inf file #includes another bld.inf, this variable will always contain |
|
60 the directory of that top-level file. If you require the directory of the |
|
61 bld.inf which actually references the makefile, use $(EXTENSION_ROOT) instead.</i> </p> </entry> |
|
62 </row> |
|
63 <row> |
|
64 <entry><p> <codeph>$(EPOCBLD)</codeph> </p> </entry> |
|
65 <entry><p>The project’s “working” build directory under <codeph>\epoc32\build\…</codeph>. </p> </entry> |
|
66 </row> |
|
67 <row> |
|
68 <entry><p> <codeph>$(EXTENSION_ROOT)</codeph> </p> </entry> |
|
69 <entry><p>The path to the directory containing the <filepath>bld.inf</filepath> in |
|
70 which the extension makefile was called. </p> </entry> |
|
71 </row> |
|
72 <row> |
|
73 <entry><p> <codeph>$(HOST_SHELL) </codeph> </p> </entry> |
|
74 <entry><p>The path of the host-platform specific (i.e. the shell) makefile |
|
75 containing the above definitions. </p> </entry> |
|
76 </row> |
|
77 <row> |
|
78 <entry><p> <codeph>$/</codeph> </p> </entry> |
|
79 <entry><p>Path element separator. </p> </entry> |
|
80 </row> |
|
81 <row> |
|
82 <entry><p> <codeph>$;</codeph> </p> </entry> |
|
83 <entry><p> <codeph>PATH</codeph> environment variable separator. </p> </entry> |
|
84 </row> |
|
85 <row> |
|
86 <entry><p> <codeph>$(RMDIR)</codeph> </p> </entry> |
|
87 <entry><p>Command for directory removal. </p> </entry> |
|
88 </row> |
|
89 <row> |
|
90 <entry><p> <codeph>$(RM)</codeph> </p> </entry> |
|
91 <entry><p>Command for file deletion. </p> </entry> |
|
92 </row> |
|
93 <row> |
|
94 <entry><p> <codeph>$(ERASE)</codeph> </p> </entry> |
|
95 <entry><p>Command for file deletion. </p> </entry> |
|
96 </row> |
|
97 <row> |
|
98 <entry><p> <codeph>$(MKDIR)</codeph> </p> </entry> |
|
99 <entry><p>Command for directory creation. </p> </entry> |
|
100 </row> |
|
101 <row> |
|
102 <entry><p> <codeph>$(CP)</codeph> </p> </entry> |
|
103 <entry><p>Command for file copying. </p> </entry> |
|
104 </row> |
|
105 <row> |
|
106 <entry><p> <codeph>$(PLATFORM_PATH)</codeph> </p> </entry> |
|
107 <entry><p>The current platform in lower case to be used as part of path names. </p> </entry> |
|
108 </row> |
|
109 <row> |
|
110 <entry><p> <codeph>$(CFG_PATH)</codeph> </p> </entry> |
|
111 <entry><p>The current configuration in lower case to be used as part of path |
|
112 names. </p> </entry> |
|
113 </row> |
|
114 </tbody> |
|
115 </tgroup> |
|
116 </table> |
|
117 <p>The extension makefiles integrated into the build system should support |
|
118 a number of phony targets which correspond to different phases of the Symbian |
|
119 platform build process. These phony targets are labels representing a set |
|
120 of commands to be executed to perform a task. For more information on these |
|
121 phony targets, refer to <xref href="GUID-60B98AFE-6DE6-5086-B70C-F377562E60D9.dita">Extension |
|
122 makefile targets</xref>. </p> |
|
123 <p>The commands for a phony target can be platform specific operations such |
|
124 as creating a directory, removing a directory, copying a file and so on. It |
|
125 is recommended to use the above listed variables to perform these platform |
|
126 specific operations, instead of invoking the command directly. </p> |
|
127 <p>For example, the following will delete the files <filepath>values.cpp</filepath> and <filepath>config.cpp</filepath> for |
|
128 the target CLEAN. </p> |
|
129 <codeblock id="GUID-13E04491-476A-5DC0-B487-5E711051B7A2" xml:space="preserve">CLEAN : |
|
130 -$(ERASE) $(MDIR)$/values.cpp |
|
131 -$(ERASE) $(MDIR)$/config.cpp</codeblock> |
|
132 <p> <i>Note that any path within a template extension makefile is recommended |
|
133 to use the path separator variable $/ as listed in the above table.</i> </p> |
|
134 <p>A template extension makefile can be referenced in the <filepath>bld.inf</filepath> file |
|
135 using the <codeph>prj_extensions</codeph> keyword. For more information on |
|
136 how to reference a template extension makefile, see <xref href="GUID-2910AB26-CA7C-50B9-A187-0C8406C1ED1F.dita">prj_extensions</xref>. </p> |
|
137 <p>Each template extension makefile has an associated meta file which provides |
|
138 additional information such as the template makefile type, the platform for |
|
139 which the template can be applied and so on. It is mandatory to have a meta |
|
140 file with each template extension makefile. For information on meta file syntax, |
|
141 refer to <xref href="GUID-E6CB4891-AFC8-50BB-A2C8-057DB1269DA9.dita">Meta files</xref>. </p> |
|
142 <p> <i>Note that all the template extension makefiles along with their meta |
|
143 files need to be located under the \epoc32\tools\makefile_templates\ folder.</i> </p> |
|
144 <example><p>This example will copy the source files to a target |
|
145 path, build the component using the target copy of the source files, and finally |
|
146 delete the target copy of the source files. </p><codeblock id="GUID-94E381AB-129C-5D62-AAEC-54432DFAE786" xml:space="preserve"># copy_default.mk |
|
147 # |
|
148 |
|
149 SOURCE_COPY=$(EPOCROOT)epoc32$/release$/$(PLATFORM_PATH)$/$(CFG_PATH)$/$(SOURCES) |
|
150 |
|
151 TARGET_COPY=$(EPOCROOT)epoc32$/release$/$(PLATFORM_PATH)$/$(CFG_PATH)$/$(TARGET) |
|
152 |
|
153 $(TARGET_COPY) : $(SOURCE_COPY) |
|
154 $(CP) "$?" "$@" |
|
155 |
|
156 DO_NOTHING : |
|
157 @rem do nothing |
|
158 |
|
159 MAKMAKE : |
|
160 |
|
161 BLD : $(TARGET_COPY) |
|
162 |
|
163 SAVESPACE : BLD |
|
164 |
|
165 FREEZE : DO_NOTHING |
|
166 |
|
167 LIB : DO_NOTHING |
|
168 |
|
169 CLEANLIB : DO_NOTHING |
|
170 |
|
171 RESOURCE : DO_NOTHING |
|
172 |
|
173 CLEAN : |
|
174 -$(ERASE) $(TARGET_COPY) |
|
175 |
|
176 RELEASABLES : |
|
177 @echo $(TARGET_COPY) |
|
178 |
|
179 FINAL : |
|
180 </codeblock></example> |
|
181 </conbody><related-links> |
|
182 <link href="GUID-C07B506E-A1C8-537C-A7BF-DD7F449DF8A5.dita"><linktext>How to write |
|
183 an extension makefile template</linktext></link> |
|
184 </related-links></concept> |
|