Symbian学习笔记2 之 mmp file

 Building, debugging and deploying an application in Application development tutorial

Project definition file (mmp) file syntax

Each 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的大小