<concept id="GUID-301E5FAA-A1C3-4FD7-9D84-DAA61C66981B" xml:lang="en"><title>Symbian C++ Quick Start</title><shortdesc>This Quick Start is relevant if you want to create Symbian

C++ applications that run on Symbian devices - i.e. "on top" of the

Symbian platform. Typically this will include: professional application

and games developers, professional service companies, hobbyist developers

and students. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The tutorial shows you how to get the development tools (e.g. IDE)

and set up your development environment. It then shows you how to

create a skeleton application using Carbide.c++ and UI designer, and

how to get it up and running on both the <xref href="http://developer.symbian.org/wiki/index.php/Symbian_Emulator" scope="external">Symbian Emulator</xref> and on the device; the whole

process takes just a few minutes! </p>

<section id="GUID-84D52EE3-58BD-4C55-B07C-52D08CEC42D8">       <title>  Set up the development environment</title>       <p>Assuming your

computer meets the <xref href="http://developer.symbian.org/wiki/index.php/What_are_the_developer_environment_system_requirements%3F" scope="external">System Requirements</xref> then setting up your PC

for Symbian C++ development is as simple as downloading and installing

(do so in this order): </p><ol>

<li id="GUID-1ADD0E23-A910-4FE5-9CC7-3ABE186CDFFC"><p>Perl. See the <xref href="http://developer.symbian.org/wiki/index.php/Kits_Q%26As#How_do_I_install_Perl_on_my_C.2B.2B_development_PC.3F" scope="external">Kits Q&amp;As</xref> for notes on the recommended

version.</p></li>

</ol><p>For help installing the SDK please refer to the <xref href="http://developer.symbian.org/wiki/index.php/Symbian%5E1_SDK_Installation_Guide" scope="external">Symbian^1 SDK Installation Guide</xref>.</p><p>You

can now create your first application using the Carbide.c++ project

wizard, as the following sections will describe. </p>     </section>

<section id="GUID-4B542973-8F52-41B5-884E-273BB222B783"><title>Starting

Carbide.c++</title><p>The Carbide.c++ IDE is installed as part of

the free <xref href="http://developer.symbian.org/main/tools_and_kits/downloads/download.php?id=2&amp;cid=6&amp;iid=22" scope="external">Application Developer Toolkit (ADT)</xref> (step

2 in the section above). It is the only supported/official IDE for

Symbian C++ development.  </p><p>Carbide.c++ is launched from the

Windows <b>Start</b> button: <b>All Programs | Symbian Foundation

ADT v</b><i>&lt;ADTVersion&gt;</i> <b>| Carbide.c++ | Carbide.++ v</b><i>&lt;CarbideVersion&gt;</i>.</p><p> On start, you will be prompted

to select a workspace directory. The workspace directory contains

any projects you’ve already created in the workspace and their common

settings - such as code-formatting options (you can define multiple

workspaces in order to separate completely different tasks). If this

is the first time you've run Carbide.c++ the workspace will be empty.</p><note> Your Symbian projects must be on the drive where you installed

your SDK. You must also ensure that the path name of the workspace

does not contain non-alphanumeric characters or spaces. This is because

the Symbian toolchain uses command line tools that cannot read special

path names.</note><p>If you installed the SDK to drive <codeph>C:\</codeph>, an example of a correct workspace path is: <codeph>C:\Symbian\development\</codeph>. </p><fig id="GUID-8E6698A1-7410-40FA-A109-E92481EE5E9D">

<image href="GUID-37042E73-123B-437B-8EC4-8FC6C3AD6D47_d0e4585_href.png" placement="inline"/>

</fig><p>Once Carbide.c++ has started, close the <i>Welcome tab</i> (by clicking the cross shown circled in red below) to see the default

workspace.</p><fig id="GUID-F379FA98-BCA3-47BB-851E-8E976A0B194F">

<image href="GUID-329833DA-CB6E-4715-A8E6-AD838DD5A909_d0e4594_href.png" placement="inline"/>

a Project</title><p>To launch the Carbide.c++ <i>Create New Project

Wizard</i> select: <b>File | New | Symbian OS C++ Project</b>. </p><p>Choose the <b>GUI Application with UI Designer</b> application

template (see S60 section). This template creates a runnable GUI application

with the <i>UI Designer</i> tool enabled (the <i>UI Designer</i> allows

views to be created "visually" by drag & dropping standard UI

components). </p><fig id="GUID-2859E9EC-2EAC-4E99-9993-8AC91944A952">

<image href="GUID-5E7FB4BD-DF3B-4F97-8394-5E1A6FF8D11B_d0e4621_href.png" placement="inline"/>

</fig><p>The <b>Next</b> page of the wizard is "<b>New Symbian OS

C++ Project</b>". Define the project name - in this case "HelloWorld".

Once again, make sure the project directory is on the same drive as

the SDK and does not contain spaces or other special characters.  </p><fig id="GUID-969415CB-A861-4E36-A4A5-504C3580A3ED">

<image href="GUID-57CC6419-2800-4E54-8DF6-36EC2617D2FD_d0e4633_href.png" placement="inline"/>

</fig><p>The <b>Next</b> page of the wizard is "<b>Symbian OS SDKs</b>". Choose the SDK(s) you want to use for building the project from

among those installed to your PC (You can add more SDKs to your project

later on). This should include a <xref href="http://developer.symbian.org/wiki/index.php/What_are_the_Kits%3F#Application_Development_SDK" scope="external">Symbian platform SDK</xref>. At time of writing the

only C++ Application Development SDK is the Symbian^1 SDK (<b>Note</b>: this is a copy of the S60 5th Edition SDK v1.0).  </p><fig id="GUID-0275D0D6-5E8E-4795-A887-F0F21EE509D9">

<image href="GUID-E544A944-5A65-40BD-A3B4-EF14E6132130_d0e4651_href.png" placement="inline"/>

</fig><p>By default all build configurations will be selected:   

  </p><ul>

<li><p><b>Phone Debug | Release (GCCE)</b> builds binaries for the

phone using the (free) GCCE compiler that was installed with the <xref href="http://developer.symbian.org/wiki/index.php/What_are_the_Kits%3F#Application_Development_SDK" scope="external">SDK</xref>.  </p></li>

<li><p><b>Phone Debug | Release (ARMV5)</b> builds binaries for the

phone using the <xref href="http://developer.symbian.org/wiki/index.php/ARM_Real_View_Compilation_Tools_(RVCT)_Quick_Start" scope="external">ARM RealView Compiler (RVCT)</xref>. RVCT produces

code that is a few percent smaller and faster than the current versions

of GCCE supported for Symbian C++ development, but must be separately

licensed from ARM. RVCT is primarily used by phone manufacturers to

build binaries for device ROM.</p></li>

</ul><p>Most developers should simply de-select the ARMV5 options

above as shown (the Emulator is needed by all developers, and GCCE

is sufficient for most third-party development).  </p><p>The <b>Next</b> page of the wizard sets the "<b>Application properties</b>".  </p><fig id="GUID-3BD8C48E-AFA5-4D34-9E66-9B374E514635">

<image href="GUID-6CEE397C-78E3-40AE-8D39-3DC0980A932A_d0e4693_href.png" placement="inline"/>

</fig><p>Keep the default values. The <b>Baseline SDK</b> defines

the common compatibility level of your application. For example, if

set to the <b>S60 5th Edition SDK</b>, the UI designer doesn’t let

you add elements that are only available in later S60 5th Edition,

Feature Pack 1+ SDKs and devices.  </p><p>The <b>Next</b> page of

the wizard allows you to choose an S60 UI design. Keep the <b>Empty</b> user interface variant.  </p><p>The <b>Next</b> page of the wizard

"<b>Container Name and Type</b>" has default values that are usually

acceptable.  </p><note/><p>The <b>Finish</b> button is active

in this page. The next page is optional but for the purposes of this

tutorial you should click <b>Next</b>, rather than <b>Finish</b>.

 </p><fig id="GUID-0F3EA856-F629-47BF-88ED-76F355EED12F">

<image href="GUID-A331AA9C-ECEC-4497-B45A-7C08845DE0A4_d0e4733_href.png" placement="inline"/>

</fig><p>Even though our application will only use one view, it’s

usually better to check "Support View Switching", in order to make

the application easier to extend later on.  </p><p>The <b>Next</b> page of the wizard "<b>Basic Settings</b>" can be used to customize

the project with your name and a copyright notice for every human-readable

file. It also allows you to specify the application unique identifier

(<xref href="http://developer.symbian.org/wiki/index.php/UID_Q%26As_(Symbian_Signed)" scope="external">UID</xref>).  </p><fig id="GUID-7D8B9AD4-F90C-4001-8449-DC282774B4E9">

<image href="GUID-B2B34DFF-6EBE-424A-9480-C9F1CB6E2D56_d0e4750_href.png" placement="inline"/>

</fig><p>The UID (actually the <xref href="http://developer.symbian.org/wiki/index.php/UID_Q%26As_(Symbian_Signed)#What_are_SIDs.3F" scope="external">SID</xref>, but for the moment we can ignore the

distinction) defines the private area in the file system in which

the application can store its data. Among other things the UID can

also be used to programmatically identify and/or <xref href="http://developer.symbian.org/wiki/index.php/How_to_programmatically_start_another_application" scope="external">start the application</xref>.  </p><p>Carbide.c++

generates a random UID value for you starting with ‘0xE’, which is

the range of UIDs reserved for internal development and testing. If

you want to release your application to the public, you need to get

your own unique UID allocated by <xref href="http://www.symbiansigned.com/" scope="external">Symbian Signed</xref>.  </p><p>As we do not intend to release our Hello World application

to the public, we’ll simply continue to use the value Carbide.c++

assigned us from the development range (you can change the UID later

on, although you must be careful to change every instance of it found

within your project - see <xref href="http://developer.symbian.org/wiki/index.php/UID_Q%26As_(Symbian_Signed)#How_do_I_change_the_UID_of_my_application.3F" scope="external">How to change your application's UID</xref>).  </p><p>Select <b>Finish</b> to close the wizard and create your application

(there is no need to go to the <b>Next</b> (last) page of the wizard

as the default values are always acceptable).  </p><p>That's it, your

workspace should look similar to the screenshot below. </p><fig id="GUID-4E47F468-590F-4608-9608-D026956B6B23">

<image href="GUID-967F99EC-0C6E-468F-BB2D-C175C7F69B67_d0e4782_href.png" placement="inline"/>

you can use the emulator for most of your development work (it is

possible to access the Internet through the emulator, and even simulate

GPS). </p><p/><p><b>Building for the Emulator</b></p><ul>

<li><p>First set the active build configuration. You can do this by

clicking the <b>Manage configurations for the current project</b> icon <image href="GUID-9F4C948B-7A6B-4E90-BBB7-A6CC6F4A6769_d0e4802_href.png" placement="inline"/> in the toolbar

or by selecting menu: <b>Project | Build Configurations | Set Active</b> and select <b>Emulator Debug</b>. </p></li>

<image href="GUID-379D9401-04A2-4A32-A3BF-C6F127E8F074_d0e4813_href.png" placement="inline"/>

<li><p>Then build the current configuration using the <b>Build</b> icon <image href="GUID-CBE1CE3A-5C8B-475D-9F5E-8ACD839EB7E6_d0e4823_href.png" placement="inline"/> in the toolbar or through the menu: <b>Project | Build Project</b> (You can also select a particular configuration to build from the

Build icon selector).</p></li>

</ul><p><i>Warning: If you get an error message similar to "WARNING:

EPOCROOT does not specify an existing directory", you did not place

your workspace/project on the same drive as the application development

SDK (which is installed by default to C:\). Delete the project and

start again. The diagram shows how this might appear in Carbide.c++:</i> </p><fig id="GUID-724EE45B-5DEF-40D5-8AA0-1D84C6DBD7A7">

<image href="GUID-1319CEA4-56D7-45DF-9C22-45291017992E_d0e4835_href.png" placement="inline"/>

</fig><p/><p><b>Running on the Emulator</b></p><p>If your application

built successfully, click on the <b>Run</b> button <image href="GUID-B574CC84-342C-4613-A628-B32B7876D595_d0e4846_href.png" placement="inline"/> (Ctrl +

F11). Upon the first launch of your project, Carbide.c++ will ask

you which executable you want to launch: </p><fig id="GUID-66C413F8-7482-47FC-A37F-1BFC83A7550E">

<image href="GUID-DCFF3240-F1CD-41FF-B832-990ADF101674_d0e4850_href.png" placement="inline"/>

and your application started automatically. The emulator will close

once you exit your application. </p></li>

<li><p>If you choose <i>Emulator</i> the emulator (epoc.exe) will

be launched and you will need to navigate to the application and start

it by clicking on the icon (just as you do when starting an application

on a device). We’ll explain how to find the application shortly.</p></li>

</ul><p>It may sound more difficult to choose the second method, but

it has some advantages. You can leave the emulator running if you

are only doing small edits in your source code – simply close your

application in the emulator, recompile and restart your app through

the emulator’s menu. You’ll also see any error messages that may be

shown when you exit the application, because the emulator will not

shut down instantly after you exit Hello World in the emulator. Those

error messages are also visible in Carbide.c++’s console window.  </p><p>When the emulator starts for the first time you might have to

wait for several minutes before it is completely ready for use. Successive

starts will be a lot faster, because Windows caches most of the emulator

DLLs. </p><fig id="GUID-A0A0A882-BC03-401B-A701-8EBEBC6D7BCE">

<image href="GUID-3FFF726B-D158-4EDF-B950-4B58467F210B_d0e4874_href.png" placement="inline"/>

</fig><p><i>If you decide to launch the emulator and navigate to your

application:</i> First, open the menu through the <b>S60</b> menu

symbol on the bottom left of the screen. Your own application will

be located at the bottom of the <b>Applications</b> folder; use your

mouse to navigate in the emulator’s menus.  </p><p>When you launch

your application, the main pane will be empty. As you can see, the

example application the wizard has created already supports a full

user interface and handles input from the left and right softkeys

at the bottom of the screen. </p><fig id="GUID-B81BC36D-7EA2-4B2A-9610-4A7F12684802">

<image href="GUID-E5962E2D-C2D1-40EC-96FB-79CA6D10417F_d0e4890_href.png" placement="inline"/>

</fig><p/><p><b>Debugging on the Emulator</b></p><p>The Emulator

is the default debug target - you simply click the Debug button <image href="GUID-4C6B9697-B69C-49D5-AD23-D7C0053BED3A_d0e4898_href.png" placement="inline"/>.  </p><p>Debugging on the Emulator is not covered further in this tutorial.

See <b>Carbide.c++ User Guide &gt; Debugging projects</b> for extensive

<section id="GUID-8ADA0364-18BF-4392-A448-3C5513B3C49B"><title>Targeting

the Device</title><p>The emulator can be used for most of your development

work. However, some situations still require a real device – for example,

when you want to use the camera or the acceleration sensor.</p><p><i><b>Tip</b>: You should test your applications on the phone from

time to time, even if it is fully supported by the emulator.</i></p><p>When you've finished development, you'll also want to build a

release version; stripping out debug code and symbol information to

make your binaries smaller and more efficient. </p><p/><p><b>Building

for the Device</b></p><p>To tell the IDE that you want to build for

the device, change the active build configuration to a phone-release

configuration for GCCE (unless you have the <xref href="http://developer.symbian.org/wiki/index.php/ARM_Real_View_Compilation_Tools_(RVCT)_Quick_Start" scope="external">RVCT compiler</xref>). As before, use the <b>Manage

configurations for current project</b> toolbar icon (<image href="GUID-9F4C948B-7A6B-4E90-BBB7-A6CC6F4A6769_d0e4930_href.png" placement="inline"/>) to select

the active-build configuration.  </p><fig id="GUID-0B5929C0-6DAC-4859-8B2A-BC3225507685">

<image href="GUID-BD1DBD2B-A4C1-4769-B454-2A9B4D056446_d0e4934_href.png" placement="inline"/>

</fig><p>Next, choose to build the current configuration using the

toolbar <b>Build</b> icon <image href="GUID-CBE1CE3A-5C8B-475D-9F5E-8ACD839EB7E6_d0e4941_href.png" placement="inline"/>(or in the

menu: <b>Project | Build Project</b>).  </p><p>This will automatically

compile the project using the GCCE compiler and create an installation

package – a file called <codeph>HelloWorld.sisx</codeph> in your project's <codeph>\HelloWorld\sis\</codeph> directory. You now need to transfer this

file to your phone to install it. 	</p><p><i><b>Tip</b>: Use Carbide.c++

to find the file on your PC. Navigate to the file in the project view,

then right-click on it and select <b>Show in Explorer</b>.</i>  </p><p>Don’t forget to switch back to the <b>Emulator Debug</b> build

configuration when you continue development! </p><p/><p><b>Installing

on the Device</b></p><p>  You can use the PC Suite that came with

your phone to install the application on your device</p><ul>

<li><p>Connect your device to the PC via Bluetooth or USB and add

the phone to the known devices in the PC Suite (if necessary).</p></li>

<li><p>Double-click the <codeph>.sisx</codeph> file in Windows Explorer

or the Project Explorer window of Carbide.c++.</p></li>

</ul><p>If the PC Suite is not installed on your PC, you can send

the file to the phone via Bluetooth or IrDA (if available):      </p><ul>

</ul><p>You will be prompted to install the application when you open

the message. 	</p><p/><p><i><b>Warning</b>: If you get a </i><keyword>Certificate Error</keyword> <i>message when you try to install the

application, then your phone has been configured to prevent installation

of self-signed sis files. To change this behavior, go to <b>Settings

- Application manager - Installation settings - Software installation</b> and change the setting from <b>Signed Only</b> to <b>All</b>. For

other errors received upon installation, consult the <xref href="http://developer.symbian.org/wiki/index.php/Getting_Started_with_Debugging_on_the_Device" scope="external">installation error troubleshooting guide</xref>.</i></p><p/><p><b>Debugging on the Device</b></p><p>  Debugging on

a production phone is covered in the topic: <xref href="http://developer.symbian.org/wiki/index.php/Getting_Started_with_Debugging_on_the_Device" scope="external">Getting Started with Debugging on the Device</xref>. </p></section>

<section id="GUID-832FBA52-70D7-47B8-AA09-76CD10F75B15"><title>Building

on the Command Line</title><p>It is also possible to build your applications

using the command-line based Symbian toolchain. If you've never done

so before you will first need to set up the environment using the

tool provided:  </p><ul>

<li><p>Select the windows start button and select: <b>Start | All

Programs | Symbian Foundation ADT v1.0 | Carbide.c++ | Configure environment

for WINSCW command line</b></p></li>

</ul><p>   Open a command prompt in your project's /group/ folder

(where the bld.inf project file is located) and do:  </p><codeblock xml:space="preserve">bldmake bldfiles 

abld build</codeblock><p>  The command <codeph>bldmake bldfiles</codeph> creates a batch file <codeph>abld.bat</codeph> based on the component-definition

file (<codeph>bld.inf</codeph>) and the project-definition file(s)

(<codeph>.mmp</codeph>). The <codeph>abld build</codeph> command uses

the batch file to build <i>all</i> the default targets (i.e. for gcce

and Emulator).  </p><p>You can build just one target using  </p><p><codeblock xml:space="preserve">abld build &lt;target&gt;</codeblock></p><p>For example,

"<codeph>abld build winscw udeb</codeph>" builds just the emulator

debug variant.  </p><p>You can start the emulator by selecting its

executable in your file system (it will be located at <codeph>SDK

DIRECTORY\epoc32\release\winscw\udeb\epoc.exe</codeph>).  </p><p>An

overview of the commands and the generated outputs is shown below.

<image href="GUID-358412B8-8B98-419F-99E6-28A01ED99B79_d0e5103_href.png" placement="inline"/>

<section id="GUID-1E8CC146-B76A-476D-BF65-DFBB6B31D183"><title>Troubleshooting</title><p>  For the vast majority of users the preceding instructions can

be followed through without issue. If however you have any build issues,

then please follow the following instructions to check that your <xref href="http://developer.symbian.org/wiki/index.php/How_do_I_test_that_my_development_environment_is_set_up_correctly%3F" scope="external">environment is set up correctly</xref> and <xref href="http://developer.symbian.org/wiki/index.php/Development_Environment_Troubleshooting_Guide" scope="external">troubleshoot</xref> any problems that may arise.</p></section>

<section id="GUID-A303EA17-F198-42A2-B41C-5C43B4D88B9E"><title>Summary</title><p>In this tutorial you set up your development environment, learned

how to create a skeleton application using Carbide.c++ <i>UI Designer</i>, and how to get it up and running on both the Symbian platform emulator

and on the device.  </p><p>In <xref href="GUID-0C814ED6-3F64-4E0E-9C47-654AEDADBA90.dita">Going Beyond Hello:

A Tutorial for Symbian C++ Applications</xref> we will extend the

basic skeleton to create a small paint application, along the way

learning more about the application frameworks (e.g. defining menus,

how to handle touch-screen events, drawing to the screen etc.).</p></section>

<section id="GUID-478AF935-A7FB-4F58-A1F4-E17FE57DDF72"><title>Related

Info</title><p>  Further reading: </p><ul>

<li><p><xref href="GUID-0C814ED6-3F64-4E0E-9C47-654AEDADBA90.dita">Going

Beyond Hello: A Tutorial for Symbian C++ Applications</xref> provides

a step by step guide to creating your first "real application", covering

the key elements of the application framework. </p></li>

<li><p><xref href="http://developer.symbian.org/wiki/index.php/Fundamentals_of_Symbian_C%2B%2B" scope="external">Fundamentals of Symbian C++</xref> provides all the

essential information you need to understand Symbian C++.</p></li>

<li><p><xref href="http://developer.symbian.org/wiki/index.php/What_are_the_Kits%3F" scope="external">What are the Kits?</xref> explains the <xref href="http://developer.symbian.org/main/tools_and_kits/downloads/download.php?id=2&amp;cid=6&amp;iid=22" scope="external">ADT</xref> and <xref href="http://developer.symbian.org/main/tools_and_kits/downloads/download.php?id=3&amp;cid=7&amp;iid=26" scope="external">SDK</xref>.</p></li>