Archived:Carbide.vs Creating and deploying projects on hardware
This article provides a beginner-guide to creating projects and deploying them on hardware, using Carbide.vs (2.0.1). The SDK referenced in this text is the S60 3rd Edition MR SDK .
Creating a project
The first step to create a project is to access the File > New > Project menu, and then choose "Symbian OS Project". Now, you should choose a name for the project and its location. It is important that both the project name and the project directory do not have white spaces, or the build process will not work (the wizard will refuse to continue if you do that). Let's go next.
The next window is named "Create a new Symbian OS Project". This window enables you to choose what kind of project will be created, based on the predefined templates. The "Project Type" combo box indicates whether the project will use Symbian 9 or some previous version ("Classic"). For S60 3rd Edition devices, Symbian 9 should be selected. The "Project Template" combo box enumerates the available project templates. For a traditional Symbian application, please select the "S60 3rd Ed. Hello World Application".
The "Select SDKs section" provides you with a chance to select what SDKs to use when building the project. This list will be populated based on what SDKs you have installed on your machine. The "Enable/Disable SDKs" lets you restrict (or not) what SDKs will appear on that list. Next to the SDK name the available build configurations for that SDK are listed. For example, using the S60 3rd Ed. SDK makes available the "WINSCW" and "GCCE" configurations. The first one is used to build the project for the emulator, whereas the last one is used to build the project for the actual device. Please, select both configurations. Let's go next.
The next window is the project configuration window. There are three sections: Basic settings, other settings, and project directories.
The "Basic settings" section lets you choose the base name for the application and its UID. The wizard will use the base name to create the starting classes for the application. Let's use "HelloSymbian" for this name.
The UID (Universal Identification Number) is a 32 bit number used to identify uniquely the application throughout the system. It is required for all applications, and the Carbide.vs wizard automatically generates ids for new applications. During the development process, it is possible to use any id from 0x01000000 e 0x0fffffff. However, for release applications, a suitable id should be requested from Symbian (through email@example.com).
In the "Project directories" section, it is possible to specify the name of the project directories. Carbide.vs generates the following names, by default:
The data directory stores resource files (.rss) that define strings and user interface elements. The gfx directory stores application image files (icons). The group directory stores the project .mmp file and the bld.inf file. The bld.inf file contains instructions used in the application build process. The .mmp file corresponds to the project makefile. The inc directory contains the application header files (.h). Source files (.cpp) are stored in the src folder. Unit tests source file are stored in the tsrc directory. The sis directory stores the application instalation file (.sis) and the package file, which is used in the .sis file generation.
The "Other settings" section lets you change text and messages that appear on code comments. Then, click on the "Finish" button and the wizard will create the first classes.
The wizard creates four classes: CHelloSymbianApplication, CHelloSymbianDocument, CHelloSymbianAppView, and CHelloSymbianAppUi. These classes derive from the basic Avkon framework classes. Avkon is the S60 user interface framework, based on the MVC (Model-View-Controller) design pattern . Hence, a basic GUI application has the following elements:
- Application View (CHelloSymbianAppView): Corresponds to the main application window, where it can present its contents;
- Application UI (CHelloSymbianAppUi): Responsible for creating the view and handling events generated from the user interface;
- Application Document (CHelloSymbianDocument): Represents the data model of the application. In other words, it owns the application data, storing and retrieving (from disk, for example). In the Symbian OS application model, this class is responsible for creating the application UI.
- Application (CHelloSymbianApplication): Represents the main application, the main component that gets called when the user wants to run it. In the Symbian OS application model, this class is responsible for creating the document class object.
An alternative way to create projects is to import an existing one. Many examples of Symbian OS programming are released for compilation with the command-line tools. Fortunately, Carbide.vs offers a way to import those projects.
The import wizard is invoked through the File > Import Symbian Project menu. Then, the "Import Symbian Project" window is displayed.
The first step is to specify either a bld.inf file or a mmp file in the "Project File" field. The "Project type" field indicates what kind of project is being imported, information that the wizard will try to guess. Let's go next.
If you chose a bld.inf file, the next window will have two sections: "Solution Settings" and "Project Settings". However, if you chose a mmp file the window will have one section named "General Settings". Let's examine both.
The "Project Settings" section has an entry for all projects found in the bld.inf file. You can change the project name, but should left the other field unchanged (it corresponds to the original project root).
The "Solution Settings" window lets you choose the SDKs and build configurations to use in the project. The "Solution root" field can be changed but this action has no practical effect. The project files will be saved in the root directory of the first imported project. It does not copy files.
The "General Settings" is a mix of the two sections presented previously.
Specifying import libraries
Many funcionalities of Symbian OS are implemented in DLLs. Hence, it is necessary to inform the compiler about the import libraries (.lib) to use when building the application.
This task is accomplished by accessing the Project > [project name] Properties menu. Then, go through Linker > Input > Additional Dependencies. There you should put the name of all required libraries.
This procedure works for emulator builds. Device builds use the same libraries specified in the emulator build configuration.
The first step is to build for the device. Under Carbide.vs, the current build configuration can be determined through the Project > SDK Configuration Manager menu. This menu opens a window where you can choose the configuration. Please, choose the "GCCE" option.
From Symbian 9.0 onwards, all applications should be digitally signed in order to install them on the device. Depending on the functionalities required by the application, it is necessary to acquire a certificate from Symbian. However, if the application does not require restricted functionalities, it is possible to "self-sign" the application for test purposes. For information on how to generate a certificate and private key for self-signing, please see Archived:How to sign a .Sis file with Self-Sign Certificate.
Carbide.vs offers a way to sign a .sis file and to automatically sign .sis files after building them.
Signing the .sis file
First, it is necessary to include a certificate in the Carbide.vs certificate list. This can be accomplished through the Tools > Manage Certificates menu. The "Certificate Management" window opens and you should include your certificate and private key.
Then, the .sis file can be signed by right-clicking on it from the IDE, and choosing "SignSis". The "Signsis tool" window opens and you should select a certificate/key pair to use for signing the file. A signed .sis file will be generated in the same directory of the original .sis file.
Automatically signing the .sis file
Go to the Project > Carbide.vs properties menu. Then, choose the "Security Properties" section. In this section it is possible to select a default certificate to use for the project. Check the "Auto signing" option and Carbide.vs will automatically sign the .sis file.
Installing the .sis file
Two alternatives to install applications on the device:
- Using the Nokia PC Suite application
- Copying the file directly to the device and performing the installation through it.
If the Nokia PC Suite application is running, you can click on the signed .sis file (either on the IDE or Windows Explorer) and Nokia PC Suite will ask if you want to install the application. Choose "yes", and Nokia PC Suite will ask you to finish the instalation process on the device.