alpha version, October 2000
The XSdk system offers a number of easy-to-use visual tools for proper maintaining the project. Many convenient task ensures the ProjectBuilder itself: check its standard documentation.
The ProjectBuilder offers a number of extremely powerful functions, like one of the best source editors available, project-wide indexing and searching, regular expression replacement service, and much more. The description of them is not in scope of this documentation; read please the standard ProjectBuilder help and tutorial pages in the operating system.
Here we shall describe only those ProjectBuilder features which are directly used by the XSdk system:
You can set or change the project name through the standard Project inspector of the ProjectBuilder: just open the inspector using the "Tools / Inspector" menu command or the Inspector button, and through the pop-up menu in its upper part select the Project Attributes pane:
The project name can be set to any name, which is a valid filename. The XSdk will use the project name as a name for the result executable--for example, the application from the last picture will be built into an "newaa.app", its main resource will be named "newaa.rsc", its AIF file "newaa.aif", and so on.
Note that the project name can differ from the name of the folder where the project is placed: the folder name is an internal thing of the project, and needs not to be reflected anyhow in the result executable.
Note also that for Epoc applications, the project name can differ from the application caption (set through the Application Inspector): the project name determines the name of the application files, whilst the caption is the name presented to the user (ie. through the Extras Bar). Unlike the project name, the caption needs not to be a valid filename.
There are three groups where the ProjectBuilder keeps its source files: "Headers" for header files, and "Classes" and "Other Sources" for the C, C++, Objective C, or Fortran (and in near future also Java) sources.
The XSdk treats the "Classes" and "Other Sources" groups exactly the same way; therefore, you can decide yourself which file to place where. Generally, the "Classes" group should contain class implementations (the interfaces are, naturally, placed to "Headers"), whilst the "Other Sources" should contain other, non-class-related sources.
To add a file to the project, you can use a plethora of different services in the ProjectBuilder: the file can be dragged'n'dropped to the group icon (shown at the ProjectBuilder window top right corner when a group is selected), or you can use the "Project / Add Files" menu command, or just double-click the appropriate group in the browser.
When creating new file (using the menu command "File / New in Project"), the ProjectBuilder automatically prepares the new file contents using the appripriate template from the project folder: cpp.template is used for .cpp files, h.template for the headers. In case you are not satisfied by the standard templates, you can edit them. Should you make a number of Objective C or Fortran files, you can add your own m.template and f.template files to the project folder; they will be used automatically. See the cpp.template and h.template contents for how to write the file templates.
Note that the ProjectBuilder default file type for classes is the Objective C, with a .m extension. Do therefore not ask the Projectbuilder to make new class sources without a suffix, for it would automatically add the .m suffix. If you use explicitly a name with the .cpp sufix, ProjectBuilder will properly create an empty C++ source.
To remove a file or files from the project, select them in the browser, and use the menu command "Project / Remove Files". You can decide whether the file is to be erased from disk entirely, or just removed from the project file list (stored in the PB.project file): if the latter, the file will not be used when the project is built, but remains in the project directory for future reference.
You can rename any file in project through the standard File inspector of the ProjectBuilder: just select the file to be renamed, and open the inspector using the "Tools / Inspector" menu command or the Inspector button, and through the pop-up menu in its upper part select the File Attributes pane. Or, you can get directly there using the "Rename" command from the "File" menu:
Type the new name into the name field, and press Enter. The ProjectBuilder will both rename the file on disk and inside its list of project files (stored in the PB.project file).
For adding and removing subprojects use the standard commands from the "Project" menu. The only caveat is that the alpha XSdk release does not support subprojects at arbitrary level: currently, you can use only a root project and any number of first-level subprojects. That will change in future releases.
Sometimes, you might need to state that one subproject depends on another: for example, the view library would probably depend on the engine library. So as to specify this kind of dependance, just open the Makefile.preamble file of the project which depends on others (it is placed in the ProjectBuilder's "Supporting Files" group), and add there a variable DEPENDS_ON; as its value list all the subprojects this subproject depends on, space-delimited, this way:
DEPENDS_ON:=Main.engine Supplementar.engine CommonServices.engine
The build system will take this setting into account, and (a) automatically build all projects this one depends on before it starts building this one, and (b) adds their interface libraries automatically into the list of libraries this project will be linked against.
In future XSdk releases this service will be available through a GUI interface; probably it will be added to the Generic subproject inspector.
Note that there is no need to specify that the main project depends on its subprojects--it is presumed automatically.
Place any file which has to be placed into the buiilt result "as is" into the "Other Resources" group. The XSdk will--after a successful build--just copy all files from this group to the result.
In case you want to have an Epoc resource file (ie. not a generic file which serves as some resource for the application, but a file in a specific Epoc "resource" format) translated and the .rsc result placed between the built files, add its name to an array in the PB.project file with a "XSdkPlainResources" key (see the Makefiles for a general format of the PB.project file)--for example, with three resource source files "xxx.rss", "yyy.rss" and "zzz.rss", this way:
XSdkPlainResources = (xxx.rss, yyy.rss, zzz.rss);
There is currently no GUI tool to perform this task, for the Epoc resources are used in imported projects only; the native XSdk Extended API projects generate their resource files, instead of forcing the poor programmer to write their sources. Probably in future releases of XSdk we shall add such a tool, though, to make maintaining the imported projects more convenient.
Place all the standard Epoc libraries the project modules are to be linked against into the "Libraries" group: just double-click the group name, and select the appropriate libraries in the file selector. The first time you will have to navigate the file selector to the XSdk Epoc Libraries folder (normally /Local/Developer/XSdk/EpocSDK/Libraries/marm, see the Where Is It? document); next time the ProjectBuilder will remember the path and open it directly.
In the alpha version there is no automated service to find the Epoc library to be used when some symbols are missed. Since there is a vast number of Epoc libraries and their names are no way intelligible (the Symbian guys seemingly still use the ancient MS DOS with its grave file name limitations), there is a real need of such tool, and it will be available in future XSdk versions.
Just like the libraries, select the frameworks the project uses in the "Frameworks" group. Again, for the first time you'll have to navigate to the XSdk Frameworks folder (normally /Local/Developer/XSdk/Frameworks, see the Where Is It? document); next time the ProjectBuilder will remember the path and open it directly. Read the XSdk Frameworks document to learn about the differences between XSdk frameworks and plain Epoc static DLL libraries.
When creating a framework, you have to tell the project system which of the headers should be exported to the framework as public ones (since they are to be available to all projects, which will use the framework), and which ones are to be kept internal in the project.
By default, all headers are considered internal. For changes, use the standard File inspector of the ProjectBuilder: just select the header file to be made public, and open the inspector using the "Tools / Inspector" menu command or the Inspector button, and through the pop-up menu in its upper part select the File Attributes pane:
Check or uncheck the "Public Header" check box, and do not forget to click the "Apply" button at the bottom of the inspector window.
The XSdk suite extends the services of the ProjectBuilder by a number of its own features. Generally, there are three types of them: system-wide tools, installed to the "Project / XSdk" menu (eg. the UID pool management is placed here), the loadable project types, which support making and building of the Epoc executables, and the dynamically loadable inspectors, shown in the "Tools / XSdk Tools" menu. Here we will describe the last ones.
The contents of the "Tools / XSdk Tools" menu is determined dynamically. Each of the XSdk ProjectBuilder extensions (there is one generic bundle, and a number of loadable project types) can register a menu item for a specific root project type, for a specific subproject type, or for a number of generic subproject types.
The ProjectBuilder then checks whether there is a menu item for the root project of the current project window, and if so, it will be the very first item in the menu. Then, menu items for the currently selected subproject are checked, and if there is one, added. Finally, under a menu separator all the generic menu items for the currently selected subprojects are shown--like this:
The picture shows one root project item ("App Inspector"), one specific subproject item ("Generic Subproject Inspector"), and three generic subproject items.
In the alpha XSdk release, there are the following registered menu items:
There is no ProjectBuilder application and no GUI inspectors in the command-line XSdk releases. In future, there will be a suite of command-line tools to automate all these services; currently, you have to maintain the information stored in the PB.project file manually (just like you manually maintained the information stored in the Symbian MMP file).
The description of general PB.project format is to be found in the Makefiles help page; there are described also the main keys and values (like those describing the project source files). The special keys and values related to particular inspectors are described in the appropriate inspector help page (see the links in the XSdk Concrete Inspectors paragraph).
Copyright © 1999-2000 X.soft, all rights reserved