Quickstart
• Make sure you have Xcode 2.1 or later (preferably 2.4) installed
• Run the installer.
• Get an SDK from www.symbian.com/developer/sdks.asp. See the supported SDKs section for information on which are supported. The supplied InstallSDK utility should mean you don't need to install the SDK on a PC then copy the installed folder onto your mac.
• Launch Xcode.
• Either:
• a) Create a new project using one of the Symbian OS templates, or
• b) Choose "Import Project" from the File menu and select one of the Symbian OS options.
• The plugin will try and work out your EPOCROOT at this point. If it isn't successful, a window should appear asking you to specify it.
• Go to "Project->Edit active target"
• Click on Build tab, choose configuration "All Configurations".
• Assuming your EPOCROOT is valid, there should now be a new entry in the "Collections" menu called "Symbian GCC compiler". Most of the settings have help text.
• Click the big build button and watch all the compile errors!
• To build a SIS file add your pkg file to the SIS target that should have been created for you ("Project->Add to Project" then choose the file, then tick the SIS target in the next dialog). The bld.inf import assistant may have already added your pkg files to the target for you.
• To have the SIS file automatically beamed to your phone, edit the SIS target settings (click on the target, choose "File->Get Info" then click the Build tab) and enable the option "Send SIS file via Bluetooth".
While this plugin has been tested with a number of different SDKs and projects (and I use it for my "real world" Symbian OS development) there will no doubt be combinations of files and settings that don't work as intended. Any problems should be reported to <xcodeplugin@tomsci.com>. Please include, if possible, whatever files are relevant to the problem you are experiencing. For example if you have an MMP file that won't import, please include that (and whatever files it references). If Xcode crashes, please include the crash log from /Users/username/Library/Logs/CrashReporter/Xcode.crash.log.
Supported SDKs
UIQ 2.1
S60 2.x
S80
Please note that S60 3 is not yet supported.
Feature overview
This section outlines what is possible for each type of target that the plugin supports
General
• You can import bld.inf and MMP files, so setting up a project is very quick (check out File->Import Project). The importer supports almost all bld.inf/MMP syntax except for extension makefiles.
• Almost all customisation is done by editing settings in the target build inspector (click on the target, choose File->Get Info and click on the Build tab). All the Symbian OS-specific settings appear in the collections menu under "Symbian GCC compiler" or "Symbian makesis" etc. All the settings have help text associated with them, and many use the same syntax as MMP files.
• The commands "Preprocess" and "Show Assembly Code" in the Build menu work are supported for C and C++ source files.
• There is no emulator or debugger. That's a bit too much to hope for, don't you think? :-)
• There is no need to convert your source or header files to UNIX-style line endings (if you didn't know this used to be a really annoying issue, count yourself lucky!).
• Building from the command line is supported using xcodebuild. You can import a bld.inf from the command line using the tool /usr/local/bin/importbldinf.
DLLs/APPs/EXEs
• Building binaries is pretty simple - just create a new target using the template appropriate for the type of binary you want to build, and add files to it.
• ARMI is the only architecture supported.
• DEF files are supported for DLLs - everything is specified in the build settings. To perform a freeze, change the "Freeze Settings" to "Freeze during next build" then perform a build. There is no separate command equivalent to "abld freeze", you just do a build with this setting on and it freezes as part of the build process.
• The MMP importer fully supports the most common binary types
• Per-file compilation flags (ie when you do a Get Info on a source file and click on the Build tab) are supported.
Resources
• The simplest way of building a resource is to just add the rss file to the target that's building your binary. If you do this, the build settings pane will include the resource compiler options. You can add multiple resources to one target in this way (provided none of the settings they share needs to be different)
• If you have multiple resources that need different target paths or header settings (for example) then you need to create a separate target for each rss, so that you can change the build settings for each independantly. You do this by creating a new "MBM and RSC" target.
• The MMP importer will handle creating separate targets for each resource if it is necessary.
• If you change a resource file, any changes this causes to RSG files will not be picked up until the next build. This seems to be a limitation of how Xcode's dependency analysis works. Which is also why you see "Copying blah.rsg" appear in the build log of every build, regardless of whether the file has actually changed.
MBMs
• Work in almost exactly the same way as resources, with the exception that you always need to create a separate "MBM and RSC" target for each MBM you want to create.
• You cannot specify colour depth for each bitmap in the MBM separately. However you can specify a colour depth using the comma-separated format (like "c12,8") to indicate that the depth alternates between c12 and 8. This is usually sufficient for most MBM definitions that specify alternating bitmaps and masks.
• All the bmp files must be in the same group (in Xcode's "Groups & Files" view) for the plugin to order the bitmaps correctly.
• The MMP importer supports importing MMPs, but it will not currently handle the case where the bitmaps don't have all the same colour depth. You'll have to go and manually change this setting after the import.
SIS files
• Building SIS files is also fairly straightforward. Just add pkg files to a SIS target (most of the templates include one already, you can add more using the "Symbian OS->sis" target template. Once you've added a pkg file, the build settings inspector will show the makesis-specific settings.
• To automatically send the SIS file via Bluetooth enable the "Send SIS File Via Bluetooth" build setting.
• After beaming a SIS for the first time, you may have to close and reopen the project before it remembers which bluetooth device you selected.
• Pkg files are converted on the fly to work on OS X. This means you shouldn't have to modify your (windows-style) pkg files. For example, the following line:
"\EPOC32\RELEASE\THUMB\UREL\SERVER.EXE"-"!:\system\programs\server.exe"
is converted (on my computer) to
"/Users/tomsci/Documents/Dev/Epoc/UIQ_21/epoc32/release/armi/UREL/SERVER.EXE"-"!:\system\programs\server.exe"
Note how EPOCROOT is substituted, backslashes are converted, and any references to THUMB binaries are changed to ARMI, since THUMB isn't supported. If this doesn't work with your particular pkg file, let me know! Be sure to send me the original pkg file and the converted one (which gets written to the project's temp directory). You must create a target of type "Symbian -> sis" in order to add pkg files to it. Some pkg files based on the Symbian or UIQ samples are non-conformant or unwisely laid out - you can try setting the undocumented build setting SYMBIAN_MUNGE_PKGS to YES to further process the pkg file and try to correct some of the problems I've noticed.
AIF files
• Building AIF files for UIQ 2 SDKs is not supported (and never will be).
• Building AIF files for other SDKs should work.
• In principle though, they work in the same way as MBMs and resources, except you use the AIF target template to build them.
Other issues
• The "Products" group in the "Groups & Files" sidebar is almost always wrong about what your products are and where they are located.
• Cleaning doesn't work as you'd expect. Currently only intermediates are deleted, not products. Probably related to the previous problem. So for certain product types you'll have to resave (ie, update) the input files to ensure that the output files are rebuilt. Fortunately most of the time this isn't needed, since Xcode is pretty smart, and realises that if you change a build setting it needs to recompile everything.
• Technically you can have different EPOCROOTs set for each target, and even mix UIQ and S60 targets in the same project, but be aware that the Symbian Project Assistant dialog (the one that pops up if any target has a missing/invalid EPOCROOT) will try and set the project-global build setting, rather than any target-specific one. Basically if you are going to use multiple EPOCROOTs in one project, you should press cancel whenever the Project Assistant pops up, and change the setting manually. There is currently no way to disable this dialog without removing SymbianPluginUI.pbplugin entirely.
• Some of the Symbian build tools that Xcode can't avoid calling into aren't very intelligent when it comes to file paths. Therefore it is a good idea not to put any of the following characters into the name of any file or directory involved in your project. Some may work for some paths (the resource and MBM compilers are the worst culprits), but it's easier just to always avoid them all:
/ (slash)
\ (backslash)
: (colon)
(space)
" (speech mark)
Anything else non-ASCII.
This last one may be excessively paranoid, but I have my doubts. The same rules should, for now, be observed for target names. This is because Xcode uses them for folder names for temporary build products and thus you hit the same problem. Pester me enough and I may try patching the tools so they are better behaved.
To do
• More file and project templates (app for example)
• Support for SDKs based on Symbian OS 9.x, such as UIQ 3 and S60 3.
Credits
This plugin includes binary versions of most of the tools mentioned in Simon Woodside's excellent article "HOWTO develop Symbian apps using Mac OS X".
The Xcode plugin interface and much of the plugin's structure was taken from the examples and documentation by Damien Bobillot. Without his work this plugin would never have happened.
While this plugin doesn't directly use gnupoc or sdk2unix, many thanks go to the people responsible for both, for the inspiration and for proving it was possible!
class-dump by Steve Nygard was used extensively to figure out some of the less accessible Xcode interfaces.
The rest of the Xcode plugin was written by Tom Sutcliffe.
Finally, thanks to Apple for making such a cool IDE :-)
Tom Sutcliffe, 15-Sep-2006