Template +extension makefiles

diff -r 000000000000 -r 89d6a7a84779 Symbian3/SDK/Source/GUID-7A52BD40-E1C1-5C67-AAA0-1B79A34CF24C.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-7A52BD40-E1C1-5C67-AAA0-1B79A34CF24C.dita Thu Jan 21 18:18:20 2010 +0000 @@ -0,0 +1,184 @@ + + + + + +Template +extension makefiles +

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 bld.inf file using prj_extensions.

Note that it is recommended to follow GNU make syntax to define template +extension makefiles. For more details on GNU make syntax, refer http://www.gnu.org.

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.

The following is a list of the variables defined:

+ + + + +Variable name +Description + + + + +

$(EPOCROOT)

Location of the epoc32 tree.

+ + +

$(PLATFORM)

The current platform which can be TOOLS, ARMV5, WINSCW etc.

+ + +

$(CFG)

The current configuration either UREL or UDEB.

+ + +

$(TO_ROOT)

Relative path to EPOCROOT.

+ + +

$(TO_BLDINF)

The path to the top-level bld.inf.

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.

+ + +

$(EPOCBLD)

The project’s “working” build directory under \epoc32\build\….

+ + +

$(EXTENSION_ROOT)

The path to the directory containing the bld.inf in +which the extension makefile was called.

+ + +

$(HOST_SHELL)

The path of the host-platform specific (i.e. the shell) makefile +containing the above definitions.

+ + +

Path element separator.

+ + +

PATH environment variable separator.

+ + +

$(RMDIR)

Command for directory removal.

+ + +

$(RM)

Command for file deletion.

+ + +

$(ERASE)

Command for file deletion.

+ + +

$(MKDIR)

Command for directory creation.

+ + +

$(CP)

Command for file copying.

+ + +

$(PLATFORM_PATH)

The current platform in lower case to be used as part of path names.

+ + +

$(CFG_PATH)

The current configuration in lower case to be used as part of path +names.

+ + + +

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 Extension +makefile targets.

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.

For example, the following will delete the files values.cpp and config.cpp for +the target CLEAN.

+CLEAN : + -$(ERASE) $(MDIR)$/values.cpp + -$(ERASE) $(MDIR)$/config.cpp +

Note that any path within a template extension makefile is recommended +to use the path separator variable $/ as listed in the above table.

A template extension makefile can be referenced in the bld.inf file +using the prj_extensions keyword. For more information on +how to reference a template extension makefile, see prj_extensions.

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 Meta files.

Note that all the template extension makefiles along with their meta +files need to be located under the \epoc32\tools\makefile_templates\ folder.

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.

# 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 : + +

+How to write +an extension makefile template +

\ No newline at end of file