One of a typical issue when developing a Symbian application, is to adapt it to several platforms.

Until last year, things were clear:
  Developers targeting the Nokia devices had to use the Nokia Series 60 v1.x SDK and any Symbian enabled IDE since they finally all had their own version of the Nokia SDK (Visual Studio, Metrowerks Codewarrior and Borland C++Builder).
  Developers targeting the SonyEricsson device had no choice and must use the SonyEricsson/UIQ 2.0 SDK alongst with Metrowerks CodeWarrior.

Note: I am not mentionning alternatives like Linux based environment since they are (unfortunately) not mainstream environments for Symbian development.

With the arrival of Series 60 v2.0, Series 90 and UIQ 2.1 platforms, things are becoming a little bit more complex since the number of SDKs are increasing rapidly. Not to mention the Siemens SX1 SDK, Sendo SDK,... It now becomes quite common to have several SDKs installed on a single machine (as far as I am concerned, I commonly use Nokia Series 60 v1.2, Nokia Series 60 v2.0 and UIQ v2.1 SDKs).

Furthermore, users of Visual Studio and Borland C++Builder do not have to move to Codewarrior to enjoy UIQ development anymore. So, a proper configuration of all these tools has become a necessity (and -until recently- a real pain).

As a matter of fact, not all the SDKs use the same method to configure themselves:
  Symbian 6.1 based SDKs (all Series 60 v1.x SDKs) use the EPOCROOT environment variable
  Symbian 7.0/7.0s SDKs (UIQ, Series 60 v2.0 and Series 90) rely on the new - and not so easy to use - device command.

The EnvironmentSwitch tool

Happily enough, Nokia delivers with its latest SDKs (NS60 v2.0 and NS90 v1.0beta) a small utility program called EnvironmentSwitch that is really useful to achieve succesful cohabitation of all SDKs (even non-Nokia ones). This tool is located by default in C:\Symbian\7.0s\Series60_v20\Series60Tools\environmentswitch or C:\Symbian\7.0s\Series90_v10b_CW\Series90Tools\environmentswitch

Two files are required to run the tool [1] :
  environmentswitch.exe which is the tool executable
  settings.xml which is the configuration file.

This settings.xml file is the key to configure your system properly. EnvironmentSwitch looks for it in the following places:
  the full path (directory and filename) specified by a single command line argument, else
  the full path (directory and filename) specified by the environment variable ENVSWITCHCONFIG, else
  a file named settings.xml in the directory from which it is launched.

Once started, a small yellow icon will appear on your taskbar waiting for you to select your working SDK.

The EnvironmentSwitch configuration

The configuration file is in a simple attribute-based XML format. An example is shown at the bottom of this page.

The document root element type is settingsfile. It has no attributes.

All child elements of the root are of type environment. Each environment element is typically use to define a new SDK configuration. An environment element has the following attributes:

• name (mandatory) - the menu item caption
• icon (optional) - .ico file for the tray icon when this environment is selected - like old EPOCICON
• tooltip (optional) - tooltip text when this environment is selected - defaults to value of name

Child elements of an environment element are of type env or command.

The env element modifies an environment variable:

• key (mandatory) - the variable to modify
• value (optional) - the value
• action (optional) - how it modifies current value
  • " prepend "
  • " append "
  • " replace " (default) Note: use "replace" with no value to unset a variable.
• registry (optional) - if "yes", modify the current control set in the Registry to affect other processes (default is "no")

The environment variables (including the Registry) are restored this when environment is deselected (or EnvironmentSwitch terminates).

The command element specifies a command to execute:

• value - the command (mandatory)
• directory - (optional) working directory in which to invoke it - extends old PROJECTPATH
• binding - (optional) when to execute, defaults to "entry":
  • " entry " - run when this environment is selected
  • " exit " - run when this environment is deselected (or EnvironmentSwitch terminates)
  • " middlebutton " - run on middle mouse button click
  • " doubleclick " - run on left mouse button double click
  • " menu " - attach to the EnvironmentSwitch (right mouse button) menu
• outputwindow - (optional) if "yes", capture any command output (stdout & stderr) to an error message box - intended to support 'devices -setdefault'
• caption - (optional) menu item caption if binding is "menu", ignored otherwise. Default is to use the value attribute

Example Configuration File

Here is the settings.xml file I use:

This file configures three SDKs [2]:
  a Series 60 v1.2 SDK (located in C:\Symbian\6.1\Series60\)
  a Series 60 v2.0 SDK (located in C:\Symbian\7.0s\Series60_v20)
  a UIQ v2.1 SDK (located in C:\Symbian\UIQ_21)

For each SDK, I use the following command set:
  a command that opens a shell to the root of the SDK
  a command that opens a shell to my projects root directory
  a command that starts the selected SDK EPOC emulator
  a command that starts Visual C++ 6 IDE
  a command that starts Borland C++BuilderX IDE

[1] You may also need to update your system by installing MSXML Core Services 4.0 SP2 to get rid of a warning at program startup.

[2] Note that some of the lines are specific to my french Windows configuration. To reuse the file, you will probably have to modify each path that contain C:\Program Files\Fichiers Communs to something more suitable to your system (probably C:\Program Files\Common Files.