Importing a Symbian SDK project

alpha version, October 2000

In principle, you just need to specify the MMP file of the original project, and the (new, non-existing) target directory where the project is to be placed to. There are absolutely no limitations of naming and placement of the XSdk projects: any folder, any level deep, will do. You can use any name for the project folder, and you can copy/move/rename it any time (it should be all quite obvious, but we are pointing it out since in the Symbian SDK it is not so).

ProjectBuilder

When developing in ProjectBuilder, just call the menu item "Import Symbian project..." from the menu "Project/XSdk":

ImportMenu

A standard file selector is immediately launched; use it to find and select the MMP file of the project you want to import. Then, another selector is launched so as you can specify the target folder: select any place in the file system, and enter a new name; the folder will be made automatically for you. By default the MMP file name without the MMP suffix is offered.

When you have set the original file and the target folder, the import process is launched. It tries to import the Symbian project to the new folder; among others it

copies all the Symbian project files to the new folder. Note that quite often are many of them good for nothing: for example, you'll no more need any generated .marm or .wins file there may be... Though, since the MMP format does not list all the project files, there is no way to exclude automatically those which are no more needed;
all the copied file names are lowercased. Again, it is not entirely and always proper; though, there is no way to know which case the letters should have, and keeping them unchanged brings quite more problems than lowercasing them: in Windows, almost any project contains some files with uppercase names, included or used other way, and referenced by lowercase!
some standard files are made: primarily, the PB.project project file, and a standard Makefile as well, so as the project can be immediately built;
since the Symbian SDK has no subproject support, there are quite often external references: an application project includes header from an altogether different project, which happens to contain the appropriate engine library! The import system tries to solve such external links whenever possible, and makes automatically XSdk subprojects for them.

Example

For example, let's import the standard example project Boss. In the first file selector, we choose the MMP file from the Boss/EIK9 folder:

ImportOpeningBoss

In the next file selector we specify the target folder which does not exist yet, let us say, "/tmp/Boss9". The import process makes the folder, populates it by the imported files, and automatically opens the project:

ImportBoss9

Note that the ENG1 and VIEW3 projects were referenced from the imported project, and thus they were automatically imported as two subprojects (one of them, the ENG1, named by its "TARGET" from the MMP file as "bosseng" with the standard extension ".engine", used for DLL subprojects, is shown on the last picture).

All the information from the MMP file was imported properly, including the reference to the resource file or the linked libraries (those of the engine project you see at the last picture). The only thing not imported is the UNICODE_UID, generally good for nothing.

What was not imported

There is, though, some information of the project, which could not be imported since the Symbian's MMP format does not support it, and there is no way to determine it programmatically! Thus, you must finish the import process manually--the very same way you would have manually finish an application build, had you use the simple Symbian SDK:

in the EIK9, there is no application help file, but let's for a moment pretend there is (since it does exist for a majority of application projects). In this example, we shall use the boss.mmp file instead.
Well, the Symbian project can not specify that the application help file should be automatically included in the built application. With the XSdk, you no more need to do so manually after each build: just double-click the "Other Resources" group in the browser, and select it:

Once this is done, the makefile system will automatically copy the file to the built application whenever needed. Of course, you can place any other file to this group: a document template, a 3rd-party library or plug-in... just anything which should be placed into the application folder.
even worse it is with the AIF file: not only that is is not mentioned in the project anyhow; its sources (the .rss file and the application icon bitmaps) are even stored in a quite different folder than the project itself!
Therefore, it is plain impossible to import the AIF characteristics automatically. You have to use the application inspector, and set there the application capabilites, and import the application icon there as well--the inspector is described here. Of course, once it is done, you can forget the AIF sources: the XSdk naturally makes the AIF file automatically for you.

How comes there are errors?!?

Now, you can try to build the application: just open the build panel, and click the build button (the build process and all its options is in more details described here). It is quite probable the build might end by reporting errors--like it really does with the Boss EIK9 application:

ImportError

How is it possible with a thousand times built and compiled application? Well, the compiler used in the Symbian SDK is a pretty old one, and it ignores many errors and violations of the C++ language standard. Unfortunately, the Epoc API is not designed by a particularly clean way; especially the descriptors are quite messed-up.

The result is than there is a number of constructions, which were used to be valid in the old Symbian enviroment, but which are refused by the more recent and more proper compiler. This particular one is that the copy constructors are not properly defined; to correct the problem we have to replace the copy constructor by a normal one:

TFileName searchPath(KSearchPath); // this way's all right

You can encounter more errors in imported files; as already mentioned, the most often ones will be

mixed-up letter case, generally in include names;
omitted type in const declaration (just add int or TInt between the const and the identifier);
omitted keyword class in the friend declarations (just add it).

Happily there are no more problems in the Boss EIK9 application: as soon as we have corrected the error, the application was built properly. The application was built into a subfolder "XBuiltFiles/XReleaseDir/marm" in the project folder, where the XBuiltFiles is a common folder for all genertaed files, the XReleaseDir contains all the releases, and marm is the target which we were building for.

Note: the alpha version does not support the install service, which would directly install the result to a selected folder, or--if possible--directly to an attached Epoc machine. The service will be available in the next XSdk release.

In case you happen to forget the particular release path, just have a look at the bottom part of the build window--the last thing written there is an information where the application was placed to:

ImportBuiltOK

Command line

You always can, and in the "Projectbuilderless" environments must, import projects from the command line. The appropriate tool is a shell script convert_project.sh, placed in the mmp_conversion subfolder of the standard tools folder (see the "Where Is It?" document). Just call it with two arguments: the first a path of the imported MMP file, the second the name of a target folder (which would be automatically created).

Let's import this time the Boss/EIK8 application, using the command line interface (note that in the Mac OS X Server, where the example was run, the NEXT_ROOT is a real root, so we start directly with the Local folder):

19 ~\> /Local/Developer/XSdk/Tools/mmp_conversion/convert_project.sh /tmp/Boss/EIK8/BOSS.MMP /tmp/Boss8 20 ~\>

The project was imported properly (otherwise the import tool would report error or warning). Here are all the files:

20 ~\> ls -R /tmp/Boss8 Makefile PB.project boss.hrh bosssnd.cpp ding.wav Makefile.postamble boss.aif boss.mmp bosssnd.h ding.wve Makefile.preamble boss.cpp boss.rss bossview.engine/ doebld.bat Makefile.xsdk boss.h bosseng.engine/ ding ebld.bat /tmp/Boss8/bosseng.engine: Makefile Makefile.preamble PB.project bosseng.h doebld.bat Makefile.postamble Makefile.xsdk bosseng.cpp bosseng.mmp ebld.bat /tmp/Boss8/bossview.engine: Makefile Makefile.preamble PB.project bossview.h doebld.bat Makefile.postamble Makefile.xsdk bossview.cpp bossview.mmp ebld.bat 21 ~\>

The rest is the same as above, only we have to use some plain text editor to use the "Other Resources" group in the PB.project, and to set the application icon and capabilities for an automatic generation of the AIF file (the contents of the PB.project file and information how to maintain it in systems without ProjectBuilder are described here). When it is finished, we just start make; its output is quite comprehensive, so we shall show only small part of it here:

24 /tmp/Boss8\> make debug ## ## Project boss, Epoc Application ## marm build: app -> /private/tmp/Boss8/XBuiltFiles/XReleaseDir/marm ## ## making the DLL subprojects (engines, views) ## ## Subproject bosseng, Epoc Engine at boss/bosseng.engine ## marm build: dll ## ## making the DLL subprojects (engines, views) ## making other subprojects (linked in) ## preparing header bosseng.h ## no command file ## ## Building subproject bosseng, Epoc Engine at boss/bosseng.engine ## marm build: dll ## #-@ /bin/rm /private/tmp/Boss8/XBuiltFiles/marm/boss/bosseng.engine/bosseng.in ## preparing c++ source bosseng.cpp ## compiling c++ source /private/tmp/Boss8/XBuiltFiles/XPreprocessedSources/boss/bosseng.engine/_bosseng.cpp /Local/Developer/XSdk/Tools/XPBReporter /Local/Developer/XSdk/GNU/bin/arm-epoc-pe-gcc -c -fmessage-length=0 -Wall -Wno-unused-value -Wno-unused-variable -Wno-switch -O -DNDEBUG -D__XSDK__ -DXSdkUID1=268435577 -DXSdkUID2=268435597 -DXSdkUID3=268436049 -DXSdkVMajor=1 -DXSdkVMinor=0 -DXSdkVBuild=0 -D__XSDK_PLATFORM_MACOSX__ -D__XSDKDEBUG__ -D__DLL__ -I- -I/private/tmp/Boss8/XBuiltFiles/XProjectHeaders -I/Local/Developer/XSdk/EpocSDK/Headers -I/Local/Developer/XSdk/EpocSDK/Headers/libc /private/tmp/Boss8/XBuiltFiles/XPreprocessedSources/boss/bosseng.engine/_bosseng.cpp -o /private/tmp/Boss8/XBuiltFiles/marm/boss/bosseng.engine/bosseng.cpp.o ... /Local/Developer/XSdk/Tools/XPeTran /private/tmp/Boss8/XBuiltFiles/marm/boss/_boss.app /private/tmp/Boss8/XBuiltFiles/XReleaseDir/marm/boss.app -nocall -uid1 0x10000079 -uid2 0x1000006c -uid3 0x10000253 > /private/tmp/Boss8/XBuiltFiles/marm/boss/petranlog.txt ## ## Project boss, Epoc Application ## DONE, result was placed to /private/tmp/Boss8/XBuiltFiles/XReleaseDir/marm/boss ## 25 /tmp/Boss8\>

You can see how the subprojects are scanned and--if needed--built (just the compilation of the first source file from the first subproject is shown). The results of all the subprojects, the main project, the generated RSC, all the files from the "Other Resources" group, and the AIF file (if generated), are all automatically placed to the release folder.

Release notes

The current release of the import tool does not make a subproject in case the referenced files are in the same folder as the main project (ie. there are two MMP files in one folder, and all the sources are mixed up there: suppose you merged the ENG, VIEW and EIK folders contents into one common folder).

This problem will be fixed in the next release.