Wiley.Developing.Software.for.Symbian.OS.2nd.Edition.Dec.2007 (779887), страница 26
Текст из файла (страница 26)
However, remember that the code couldleave if instantiation does not succeed.• Always declare a heap class (indicated by the C prefix) as a pointeronly, and create it via new (or NewL()/NewLC()); never declare orinstantiate it on the stack.•If you call a function that ends in LC, you need to pop the pointerreturned by that function from the cleanup stack (at a suitable place)before you exit the last TRAP harness created before that function call.•Only use CleanupStack::PushL() for CBase -derived pointers,or for simple heap-based objects that have no destructors.•Use the correct ‘cleanup stack’ push functions, to ensure safe cleanupof objects other than those derived from CBase; for example, Robjects pushed using CleanupClosePushL(). For non-CBasedeleted heap objects, use CleanupDeletePushL() (and others,CleanupReleasePushL(), etc.).•When writing a shared library DLL, place IMPORT C in the h filebefore the declaration of each function that you want accessible to theDLL user and place EXPORT C in the CPP file before each functionimplementation.•Do not use global writable data in your DLLs, if at all possible.Read-only global variables (type const) is fine.•Follow the naming standards for functions, member variables, arguments, enums, constants, and macros.•When creating an object that will be instantiated on the heap, deriveit from CBase (or a class already derived from it) and prefix a C toyour class name (e.g., CMyClass).5Symbian OS Build EnvironmentThis chapter examines the Symbian OS Software Development Kit (SDK),the overall build process and tools, and how to create the various buildconfiguration files required to build and install your program successfully.I’ll also cover other key topics, such as using the emulator, and buildingand freezing DLLs.I’ll mainly use the command line in this chapter – even if you’re usingan IDE, it’s helpful to have a basic understanding of what goes on in thebackground.5.1 SDK Directory StructureSection 2.1.3 explains how to get the correct SDK to work with yourchosen smartphone model.
You will typically download it as a zip file,which is then installed. By default, the SDK installs to a directory calledsymbian in the root of the installation drive you have chosen (e.g.,c:\symbian). UIQ SDKs are placed in subdirectories of \symbian,which specify the product name. For example, the UIQ Version 3 SDKis installed at \symbian\UIQ3SDK. The Nokia S60 SDKs are placedin \symbian, using subdirectories that specify the Symbian OS versionnumber and the product name.
For example, the S60 3rd Edition FP1SDK is installed by default to \symbian\9.2\S60 3rd FP1.Let’s look at some of the key directories found in the SDK installation.5.1.1The epoc32 DirectoryThis directory is common to all Symbian OS SDKs (although the veryearly Nokia SDKs separated this into two epoc32 directories – Sharedand NokiaCPP). Let’s look at the epoc32 subdirectories.124SYMBIAN OS BUILD ENVIRONMENTepoc32\includeThis directory contains the system include files (.h and .inl files) neededfor your software, stored either in this directory or in one of its subdirectories, such as \epoc32\include\ICL for the multimedia imageconversion library header files. The files e32std.h and e32cmn.h aregood ones to skim through because they contain a number of the commonsystem API class declarations (although others are distributed through anumber of include files in this directory).
If you’re not sure which filethe header file for the class you want to use is located in, you can eitheruse your favorite search technique or look in the Symbian OS Librarydocumentation within the SDK. The class reference documentation specifies the header file, and library to link against, at the top of the pageassociated with the class.epoc32\buildThis directory is where the build tools place their intermediate files. Asbuilds occur, you will see directories being created in \epoc32\buildthat mirror your project’s location where you executed the build. Forexample, a command line build performed for a project located inc:\myProject\group will create an epoc32\build\myProject\group directory. There is also a subdirectory for each component inthe build – and under that are subdirectories for every platform you havebuilt, each containing the object files generated for that platform.If you are curious, you can explore this directory and examine themakefiles generated for each platform – but you’ll find that normally youdo not need to worry about this directory.epoc32\toolsThis directory contains the Windows-based tools used in the SDK.
You’llsee a mixture of batch files, Perl scripts, Windows and DOS executables,and Java executables.epoc32\releaseThe \epoc32\release directory contains the executables for all supported target platforms. This is where the final executables (e.g., EXEand DLL files) are placed when you build your software. Directory\epoc32\release has subdirectories for each platform supported bythe SDK (e.g., WINSCW, GCCE, and ARMV5). These platforms – known asbuild targets – in turn contain UDEB and UREL directories. These directories contain the actual executables – UDEB contains versions of theexecutables built with debug symbols, while UREL has no debug symbolsand is used for production code.SDK DIRECTORY STRUCTURE125On emulator build targets (WINSCW), under both UDEB and UREL,there is a subdirectory called \z that contains (together with the contentsof \epoc32\data\z) the contents of the simulated ROM (Z) drive forthe emulator.For smartphone build targets (e.g., GCCE), the release directory is usedmainly for storing executables before they are packaged to an installfile for installation to the smartphone.
However, the emulator buildtargets contain the emulator executable itself, all the Symbian OS systemcomponents built for the emulator, and the executables produced by yourprogram builds.epoc32\data\zThe files in this directory are combined with the build target’s Z directoryto make up the simulated Z drive of the emulated smartphone. Thisdirectory also contains the emulator configuration file, epoc.ini, whichis discussed further in section 5.6.1.epoc32\winscwThis is the default location for the writable emulator memory drivesfor SDKs that support Carbide and Code Warrior. Pre-Symbian OS v9versions of the SDK that supported Microsoft tools created these drivesunder a different directory: epoc32\wins.5.1.2 Example DirectoriesEach SDK has a set of standard Symbian OS examples that are commonbetween all platforms.
These examples cover a variety of different areasof Symbian OS.In addition to the generic Symbian examples, the SDKs containexamples specific to the platform. The directories for these vary, andyou’ll need to browse to find them for your particular SDK. For example,the S60 3rd Edition SDK examples are in a directory named S60Ex.UIQ Version 3 SDKs have a directory called UIQ under the Examplesdirectory that contains UIQ-specific examples.If you are compiling GUI application examples, use the ones inyour platform-specific examples directory instead of the generic Symbianexamples. This is because the common examples do not use the vendorspecific API classes and sometimes do not work properly.5.1.3 Documentation DirectoriesThe SDKs contain documentation that provides a reference for the systemAPIs and the build tools, as well as other general information, examples,126SYMBIAN OS BUILD ENVIRONMENTand tutorials for building.
The organization of the documentation filesvaries between SDKs. On UIQ 3, the documentation is stored in\UIQ3SDK\Documentation, while for S60 3rd Edition, the documentation directory is S60Doc.SDK documentation typically exists as compiled HTML help files(.chm), but can also be presented in PDF and HTML.5.2 Build System OverviewThe Symbian OS build system is platform-independent; therefore, makefiles are not used directly.
After all, different development systems havedifferent make, compiler, and linker tools and these are invoked differently. For example, the compiler is invoked as mvccsym2 for theMetrowerks compiler used to build emulator binaries and gcc for buildsto run on a smartphone. There are also different makefile formats (i.e.,nmake and make). You would not want to keep track of separate makefiles when compiling your software application for both the emulator andsmartphone.If you don’t write makefiles, how do you define your build? SymbianOS has its own build file format that you must use to specify how yourprogram is built.
It contains information similar to that in a makefile, butit is platform-independent – it contains no specific platform or development tool commands. The build command takes the target platform asan argument, generates the necessary makefiles for that platform, andexecutes them.5.3 Basic Build FlowTo build a Symbian OS program, you need two build files:•Component description file (always named bld.inf).•Project definition file (suffixed by .mmp).The component description file is a text file that, in its simplest form,lists the project definition files to be included in an overall build. In mostcases, bld.inf will only list a single component. An example bld.infis shown below:PRJ_MMPFILESsimpleEx.mmpThe project definition file (known as an MMP file) specifies the information needed to build a specific program. This includes a list of theBASIC BUILD FLOW127program’s source files, the paths to the program’s include files, andthe libraries your program needs to link to.
This is the key definition file for the build and its format will be discussed in more detailshortly.As shown in Chapter 2, once these two files are created, you usethe commands bldmake and abld to perform a build based on thebld.inf and MMP files. For example, you would type:bldmake bldfilesabld build winscw udebto perform a winscw debug emulator build. bldmake actually generatesthe abld.bat file (it’s a batch file that ends up calling a Perl program).You only need to invoke it when you build your project for the firsttime, or if you modify bld.inf or move your project directory toanother location. From then on you can build by just using the abldcommand.Figure 5.1 shows the basic flow of the build.CommandsFilesbldmake bldfiles(Generates abld.bat)bld.inf<project>.mmpabld build <build_target> <build_type>(Invokes development tool makefile and toolsfor make target.)Intermediate files in\epoc32\buildBinary output inepoc32\release\build_target\build_variantFigure 5.1Build Flow128SYMBIAN OS BUILD ENVIRONMENT5.3.1 A Closer Look at abld.batabld can be invoked with other arguments besides build.
The moredetailed syntax of abld is:abld [test] command [options] build_target build_typeAs you can see, build is just one of the commands you can usewith abld. See the SDK documentation for a complete list. For the mostpart there are only two commands besides build that you are likelyto need: clean and freeze. The abld clean command performs theequivalent of a make clean, where all binary files are removed so thesoftware can be completely rebuilt (e.g., abld clean gcce urel). Thereis also a abld reallyclean, which will remove additional files suchas the generated makefiles and can be used to help resolve build issues.The freeze command is used to freeze the interfaces to DLLs andwill be discussed in detail later in this chapter.Normally, the options are left blank, but sometimes it’s useful toadd -v.
![](https://s.studizba.com/z.php?f=/templates/si/i/noavatar.png&w=100&h=100&t=1"){kind=avatar}
