Building a XSdk project

alpha version, October 2000

Ususally, the bulding of a XSdk project is as easy as clicking the "Build" button in the ProjectBuilder, or writing the "make marm" command in the command-line XSdk release. Though, there are some informations you should be aware of.

Contents

• How to build shortly sums how to build the project in the ProjectBuilder;
• Build targets describe the different build targets, which you can use to modify the building process;
• In Programming languages and file types you can learn how the XSdk determines which compiler to use on which source;
• Headers and include directories informs how and where the included files are found;
• the list of linked-in libraries is made according to a set of rules, described in Which libraries?
• Resources and other tasks describes what is done by the make system beside the compilation and linking of the executables;
• the placement of all the generated files is described in the Generated and built files placement;
• Command line shows the differences for command line XSdk releases.

How to build

So as to build a project, open the build panel using the menu item "Tools / Project Build / Build..." (with an ellipsis), or the Build button of the project window toolbar. Then click the leftmost icon there to start the build:

Or, you can use the menu item "Tools / Project Build / Build" (without an ellipsis) to open the window and immedialy start the build.

The middle button serves to clean the project, ie. to remove all the generated files. Using the rightmost button you can open a panel to select the build target and arguments:

Build targets and arguments

The build targets and arguments give you some control over the build process. In the alpha version, there are the following targets:

• debug: all the files are built the same way as it the marm target was selected, but for compilation of all the files the __XSDKDEBUG__ macro is defined. With the XSdk Extended API it means that the code for logging any message sent is added; with plain Symbian API the macro has no special meaning, and you can use it yourself (in future probably the DEBUG macro will be set as well, to enable all the asserts, but in the alpha release it is not so)
• marm: all the files are built, and, if possible, the project target is generated for the ARM architecture (which currently means for any Epoc machine);
• clean: all the generated files are removed (the "Clean" button, shown in the previous paragraph, just performs a build with the target clean);
• export: the XSdk project is exported to a Symbian project or set of projects. This is described in an extra document.

So as to select the target, click the rightmost button in the build panel (see the previous picture), and use the "Target:" pop-up menu in the panel:

The "Host", "Build for" , and "Build Frameworks" options you can ignore: they serve for different environments (in future, when there will be more Epoc architectures than just the ARM, and when Epoc will support multi-architecture binaries, which is up to Symbian, we shall use the "Build for" one).

Check the "Continue after error" box in case you want the build process not to stop after the first file which cannot be properly translated. If this box is checked, the build process tries to build all files (finding there potentially as many errors as possible in one run).

Into the "Arguments" field you can enter special arguments for the make process. The XSdk currently supports two arguments, none of which you probably will want to use: "ASMONLY=YES" makes the build process translate all the source files to assembler sources (instead of the linkable modules); "OPTIMALIZE={NO|<number>}" changes the optimalization level.

Programming languages and file types

Unlike vast majority of other development environments, the XSdk supports free mixing of, in principle, any programming languages in one project. The language of a source file--and thus the compiler which is to be called to translate it into a linkable module--is determined by the file's suffix:

There are some limitations: since the Objective C runtime needs static variables, in Epoc it can not be used for DLL or application projects. Quite similar problems, incidentally, are the reason the compiled Java is not available yet (the lacking support of some ANSI services in the Symbian estlib ANSI library is another).

The OPL support will be available soon. The reason of delay is that the XSdk aims to integrate all the languages seamlessly; that means a non-trivial amount of pre-processing must be done (including an automatic making of some glue OPX libraries), and non-trivial libraries must be linked-in to support cross-calling the functions and methods between the interpreted OPL and compiled modules.

Preprocessing

The C++ language was designed so poorly it is next to unuseable for serious programming (it is a shame the Symbian, or, rather, at those times, Psion, selected the terrible rot as the foundation of the Epoc32!). Therefore, so as to add at least some half-baked support for decent writing, the C++ sources have to be pre-processed before compilation; the pre-processor adds many services the C++ lacks (like the true class support, or dynamic method calling, needed for a GUI integration).

For the description of the preprocessor details see the XPreprocessor documentation page; here we shall focus on which files and how get preprocessed.

It is quite simple: all the headers, plain C, and C++ source files are preprocessed. The preprocessed headers are placed to the XBuiltFiles/XProjectHeaders folder; the preprocessed sources are placed to the XBuiltFiles/XPreprocessedSources folder (see also the generated and built files placement below).

You can disable preprocessing of any file should you want to: just add into the file a comment "//XSdkDoNotPreprocess" on a separate line (though it can be anywhere, it is preferred to place it to the top of the file, perhaps at its very first line). When the preprocessor encounters such a line, it stops preprocessing, and places the file to the target folder unchanged (almost--it precedes it by a "#line" preproceessor directive, to direct the compile errors to be reported over the correct source file).

Headers and include directories

Primarily, all the project headers--preprocessed or not--are placed to the XBuiltFiles/XProjectHeaders folder, which is then used as the first include path given to the compiler. The reason is to allow the main project to include subproject headers, or the subprojects to include each other's headers, without using confusing constructions like "#include "../folder/file.h"". The only small and easily dodgeable drawback is that you cannot have a header of the same name in more subprojects.

After it, the standard Epoc header path is added. There is another trick hidden, which applies for the Windows environment only: in Windows, the alpha XSdk release uses the standard Symbian C compiler, and it is not able--only Symbian and Cygnus know why on earth--to include headers from different disks?!? Therefore, when building project in Windows, and the Epoc headers are on a different disk than the project, they are copied to a local folder XBuiltFiles/XEpocHeaders (which is then added to the compiler's include folders list).

Then, for all frameworks which are used for the project their header folders are added. Again, in case the frameworks are on a different disk in the Windows blasted environment, the headers must be (and automatically are) copied to a local folder XBuiltFiles/XFrameworkHeaders. See the XSdk Frameworks document for general information of XSdk frameworks and their advantages over the Symbian static interface DLLs.

Finally, the makefile system checks whether any Objective C source is part of the project, and if so, the Objective C headers folder (containing, among others, the standard "objc/Object.h" header) is added.

Which libraries are linked in?

The mechanism which determines the set of libraries to be linked in is not utterly different from the one which finds the include directories.

All the Epoc libraries listed in the ProjectBuilder's "Libraries" group, and interface libraries of all the frameworks from the "Frameworks" group, are added (see the libraries in Maintaining a project document). Just like the headers, in the rotten Windows environment it is possible they might have to be copied to local folders XBuiltFiles/XEpocLibs/marm and XBuiltFiles/XFrameworkLibs/marm, respectively.

The build system checks whether the estlib ANSI compatibility library is used; if so, the appropriate startup file (ecrt0.o) is added automatically.

All the result libraries of projects this project "DEPENDS_ON" are added automatically (see the subprojects in Maintaining a project document). For a root project, all its subprojects' interface libraries are added automatically.

Finally, it is checked whether the project contains any Objective C or Fortran sources, and if so, the appropriate standard libraries are added. A XSdk glue library, which solves the C++ interfacing problems, is added automatically.

Resources and other auxiliary tasks

If the project contains menu and toolbar definitions, made by the Menu&Toolbar Inspector, a standard resource file is generated (this will be true for all XSdk Extended API applications, and for some of application views). All the Symbian resource source files specified (see the resources in Maintaining a project document) are translated as well.

The standard project bitmap store, containing the toolbar icons and perhaps more, is made and placed to the result (see the bitmap store in Creating an application document). For application which has an icon, the AIF file is generated as well.

Finally, all the "Other Resources" files are copied to the target folder.

If the project just built is an Epoc Framework, it is currently automatically installed. This behaviour will change in future XSdk releases, when the install target is added.

Generated files and build result placement

All the generated files are placed into the XBuiltFiles subfolder of the root project folder: of course that the XSdk does not clutter any system folder the way the Symbian SDK did!

The build result is currently stored to a XBuiltFiles/XReleaseDir/marm. This is somewhat inconvenient, and thus it probably will be changed in the future XSdk releases.

Command line

All the above information applies for command line builds fully; the only two differences are that

• the build is started by writing the make command on the command line, instead of the "Build" button;
• the build target should be placed as the first make argument (like "make debug", "make marm");
• temporarily for the alpha release only, the build number and build time (see the versioning information) are not updated.

Copyright © 1999-2000 X.soft, all rights reserved