Building, debugging and deploying an application in Application development tutorial
mmp
) file syntaxEach statement in a mmp
file starts with a keyword. This section describes the syntax of these keywords by using the contents of the mmp
file for the S60 filesystem browser application as an example. You can find more information about mmp
file syntax in the mmp file syntax reference.
// filebrowseapp.mmp
//
// Copyright (c) 2006 Symbian Software Ltd. All rights reserved.
//
TARGET filebrowseapp.exe
TARGETTYPE exe
UID 0x100039CE 0xE80000A6
VENDORID 0
#ifdef __WINSCW__
CAPABILITY AllFiles // AllFiles on emulator since no signing is required
#else
CAPABILITY NONE // No capabilities on hardware - otherwise SIS file signing is required
#endif
SOURCEPATH ../src
SOURCE FileBrowseAppUi.cpp
SOURCE FileBrowseDocument.cpp
SOURCE FileBrowseApplication.cpp
SOURCE FileBrowseBaseView.cpp
SOURCE RFsEngine.cpp
SYSTEMINCLUDE /epoc32/include
USERINCLUDE ../inc
SOURCEPATH ../data
START RESOURCE filebrowseapp.rss
TARGETPATH /resource/apps
HEADER
END
START RESOURCE filebrowseapp_reg.rss
TARGETPATH /private/10003A3F/apps
END
START RESOURCE filebrowseapp_loc.rss
TARGETPATH /resource/apps
LANG SC
HEADER
END
START BITMAP filebrowseapp.mbm
TARGETPATH /resource/apps
HEADER
SOURCEPATH ../gfx
SOURCE C16 folder.bmp
SOURCE C16 file.bmp
SOURCE 8 mask.bmp
END
LIBRARY euser.lib efsrv.lib cone.lib eikcore.lib eikcoctl.lib eikdlg.lib egul.lib eikctl.lib apparc.lib
LIBRARY bafl.lib
LIBRARY avkon.lib CommonEngine.lib
TARGET
This keyword specifies the name of the output file that will be built.
TARGETTYPE
This indicates the type of file generated by the project, in this case an executable. The most common target types are dll
, exe
and plugin
.
UID
The UID keyword specifies two of the target's three Unique Identifiers (UIDs) which identify the component. The target will have three UIDs but the first value (known as UID1) does not need to be specified because it is automatically applied by the build tools. It is a general identifier which is assigned according to the TARGETTYPE
specified.
Thus, the first UID specified here, is actually UID2, which further identifies the component type and can be thought of as an interface identifier. The value (0x100039CE
) identifies the file as an application; the same value is used for all Symbian OS applications.
The next UID specified should be unique to the application. It is also specified in the application registration resource file (which is described in the Resources section) and the applications installation package file (which is described in the pkg file format section).
No two executables may have the same UID3 value, and, to ensure uniqueness, you must request UID values from Symbian which allocates UID values from a central database. The Symbian Signed web site has more information on how to acquire UIDs for your project. There is also a range of test values, such as the value for UID3 used in the filesystem browser application (0xE80000A6
), which can be used to get started but must not be used in your final product.
SECUREID
This is an optional keyword and is not used in the example above. The keyword is used to define the Secure Identifier (SID) for an executable which is used to determine which private directory a process can access and identify it as a caller, for example, when making client-server requests. The SID can be specified by a SECUREID
statement in the project's mmp
file.
If this statement is not specified, as in the example given, the UID3 of the application is used instead. If that value is not set, KNullUID
(=0) is used.
VENDORID
This keyword is new in Symbian OS v9.1. Each executable may contain a vendor ID (VID) which identifies its origin, specified by the VENDORID
keyword. A vendor ID is not mandatory and, in many cases, will be omitted from the mmp file, or included and set to zero, which means that the source of the executable is not required for security checks.
VIDs are allocated to Symbian licensees, partners, operators and Independent Software Vendors through sign-up programs, for instance Symbian Signed. If an application needs a VID its installation package must be signed as described in the Application signing section. Unsigned applications have no vendor ID since without a signature it cannot be verified.
CAPABILITY
This keyword is new in Symbian OS 9.1. A capability is a unit of protection, or privilege and, in Symbian OS 9.1, some Symbian OS APIs now have a capability associated with them. The capability is used to restrict use of the API to callers with at least that same level of privilege.
The capabilities that an executable is assigned are listed following the capability keyword. If the CAPABILITY
keyword is not present in the .mmp
file, the default of CAPABILITY NONE
is used.
In the example above, the application is assigned different capabilities in emulator builds (AllFiles
) to hardware builds (NONE
). This is unusual, but has been done to illustrate the Platform Security concept called "data caging". On the emulator, the filesystem browser code is assigned AllFiles
capabilities, and can view more private areas of the filesystem than when it runs on a phone handset with no capabilities.
It is instructive to run the application on both the emulator and a phone for comparison.
For a process running without AllFiles
capability, nothing in the /sys/
directory is visible, and the only directory under /private/
that can be seen is /private/<SID>/
where <SID>
is the sub-directory named with the Secure Identifier of that process.
For the same process running with AllFiles
capability, the contents of the /sys/
directory is visible, as are all the subdirectories under /private/
.
The AllFiles
capability is one of a group of tightly controlled capabilities called system capabilities, which can only be granted to an executable after certification. Certificates and Symbian Signed are described later in the Application signing section of this tutorial.
SOURCEPATH
, SOURCE
The SOURCEPATH
keyword specifies the location of the source or resource files listed subsequently using the SOURCE
declaration. It can either be used as a location relative to the directory that holds the mmp
file or as a fully qualified path. The keyword can be used to multiple times to specify different directories if necessary. Alternatively, it can be omitted entirely if all source files are located in the same place as the mmp
file, although this is usually not the case for more complex projects, which typically organise their directories as described earlier in the Project directory layout section.
SYSTEMINCLUDE
The SYSTEMINCLUDE
keyword specifies the location in which files included in the code using #include <>
can be found. The /epoc32/include
directory is where the Symbian OS system headers are stored, and a line identical to this should appear in all mmp
files.
USERINCLUDE
This keyword specifies the directory in which files included in code using #include ""
will be located, relative to the directory which holds the mmp file or as a fully qualified path.
Directories specified with USERINCLUDE
are only one of three locations that may be searched of header files; the other directories being that in which the source file which uses the include statement is stored and the SYSTEMINCLUDE
directory.
START RESOURCE…END
Used to specify a resource file, which contains text and specifications of user interface elements.
These keywords replace the RESOURCE
statement used in mmp
files prior to Symbian OS v9.1.
The START RESOURCE
keyword indicates the beginning of a block which provides information about how an application resource file is to be compiled. At least one of these is needed if the application has a UI. The resource file itself should be the same location as the mmp
file itself or in the directory specified by the last preceding SOURCEPATH
declaration.
The end of the information block is indicated by the END
keyword and an application may have several resource files, each of which is specified separately using the START RESOURCE…END
block.
In the example shown here, the second block specifies a registration resource file for the application. This contains non-localisable information to display the application correctly in the application launcher, and includes the application's name, UID and properties. All UI applications must provide a registration file, as described in the Resources section, which should be built to /private/10003a3f/apps
using the TARGETPATH
keyword, described below.
TARGETPATH
TARGETPATH
is used to specify the build location for a compiled resource. In this example, the location of the first compiled resource file is specified as /resource/apps
, which is a public, read-only directory and is the standard location for resource files. The registration file is built to /private/10003a3f/apps
.
Note: The location to which the C++ code buildt used to be specified using the TARGETPATH
keyword in versions of Symbian OS prior to 9.0. However, for reasons of security, in this and future releases of Symbian OS, all executable code must run from the phone's /sys/bin/
directory, which is inaccessible to all but the trusted computing base that forms the heart of Symbian OS. (For the emulator, this is equivalent to the PC's /epoc32/release/winscw/build variant/
directory). The TARGETPATH
keyword is, therefore, only used to build resource files to their appropriate locations.
There is no longer any need to specify a target path for the executable in the mmp
file and it will be ignored except when used within a START RESOURCE…END
block.
HEADER
This is an optional keyword which, when used, causes a resource header file (.rsg
) to be created in the system include directory, /epoc32/include/
. The header provides identifiers that allow C++ code to refer to specific resources.
LIBRARY
This keyword lists the import libraries needed by the application. The build will report link errors (‘unresolved externals’) if you don't specify all the required libraries. The class-level documentation in the Developer Library tells you which library to import for each class.
No path needs to be specified and each library statement may contain several libraries, separated by a space. More than one library statement may also be used.
STATICLIBRARY
STATICLIBRARY
is used to specify statically linked libraries (object code that is built into your application).
All UIQ applications should link against a UIQ-specific heap allocator library, which is designed to be more effective in out of memory situations. This is done as follows in a mmp
file:
STATICLIBRARY qikalloc.lib
LIBRARY qikallocdll.lib
START BITMAP…END
This section contains the bitmaps for application icons and specifies how to compile bitmap (.bmp
) files into a Symbian OS format multi-bitmap (.mbm
) file. Different sizes of source bitmap should be supplied for different view sizes. In UIQ, the most appropriate icon size for the UI's current zoom state is selected to avoid the need for the icon to be dynamically scaled when it is drawn at a different size. Note that the S60 platform also allows icons to be specified in Scalable Vector Graphics - Tiny (SVG-T) format, and has additional tools (mifconv
) to support this.
For each image, an image bitmap and a mask bitmap are needed. The mask should be black for the parts of the image that should be visible, and white for the transparent areas. For more information about these see Application icons and captions.
EPOCSTACKSIZE
This is an optional keyword and is not used in the example above.
In previous versions of Symbian OS, the default stack size was 0x5000 bytes. In v9.1, the default value is 0x2000. To increase the stack size, you can use the EPOCSTACKSIZE
keyword, for example, to increase the stack size of 0x5000:
EPOCSTACKSIZE 0x5000
Note, the stack size setting only applies when building for the phone and is not supported for WINSCW
emulator builds. The stack size is not limited on the emulator since the stack will expand as needed to the much larger limit set by the Windows platform. This may cause programs that overuse the stack to work on the emulator, but fail on hardware with a stack overflow panic (KERN-EXEC 3
). It is one of the differences between phone hardware and the emulator which make hardware testing essential. See "Why test on hardware?" for more details.
EPOCHEAPSIZE
This is an optional keyword and is not used in the example above.
Use the EPOCHEAPSIZE
statement to specify the minimum and maximum sizes of the initial heap for a process. The default sizes are 4KB minimum and 1MB maximum. The minimum size specifies the RAM that is initially mapped for the heap's use. The process can then obtain more heap memory on demand until the maximum value is reached.
以上来自S60帮助文档
TARGET
TARGETTYPE
UID
SECUREID
VENDORID
以上略
CAPABILITY
用来定义在不同特权级别上的程序文件的可见性,比如
#ifdef __WINSCW__
CAPABILITY AllFiles // AllFiles on emulator since no signing is required
#else
CAPABILITY NONE // No capabilities on hardware - otherwise SIS file signing is required
#endif
SOURCEPATH
, SOURCE
用来定义sorce file的 path和 source file的name,并且可以定义多个来自不同目录的源文件,当所有的source file和mmp在同一个路径的时候,SOURCEPATH, SOURCE可以被省略,但是在稍微复杂项目上一般不这样做
SYSMTEMINCLUDE 指定#inlude <>中的文件的library
USERINCLUDE 指定#include "" 中的文件的library
START RESOURCE…END
用于指定资源文件。这个用于替代9,1版本之前的RESOURCE,并且在有UI的程序中必须输入,具体要指定到哪个TAPGETPATH,有待研究
TAGETPATH 指定编译后资源所放的位置,而且这个只在RESOUCE中使用
HEADER 可选的关键字,当被使用的时候,被选择的资源会在
/epoc32/include/中被创建,允许c++去访问指定的资源
LIBRARY、
STATICLIBRARY 提供C++ code中所需要的library
START BITMAP…END 把指定的bmp文件转化为Symbian OS 格式的多位图文件
EPOCSTACKSIZE 可选,指定Stack的大小,PS ,程序在执行的过程中,如果Stack空间不够,就会自动扩展,但当在真机测试的时候,不会自动扩展
EPOCHEAPSIZE
可选,指定HEAP的大小