| Authors | +Authors | Sean Evoy | ||||||||||||||||||||||||||||||||
| Mikhail Sennikovsky | ||||||||||||||||||||||||||||||||||
| Chris Recoskie | +||||||||||||||||||||||||||||||||||
| Revision Date | 10/21/2003 - Version: 0.1.0 | @@ -133,8 +136,8 @@ managed build system and how to extend it.
+|
+ Attribute + |
+
+ Description + |
+
+ Required? + |
+
|
+ Id + |
+
+ A unique identifier for + the page which will be used to reference the page + |
+
+ Yes + |
+
|
+ pageClass + |
+
+ Specifies the Java class + which implements the added page. + This class must implement the org.eclipse.jface.wizard.IWizardPage + interface + |
+
+ Yes + |
+
|
+ operationClass + |
+
+ Specifies the Java class + which implements the operations associated with this page. The class must implement the + + java.lang.Runnable interface + |
+
+ No + |
+
7.14.1.1.2 projectType element
+This is an optional child element of wizardPage +which specifies a projectType for which the additional pages should +apply. One instance of this +element is provided per toolchain supported by the page.
+If no projectType elements are specified, then it +is assumed that the page potentially applies to all projectTypes, +although it may still be excluded based on toolchain (§7.14.1.1.3) or project nature (§4.1.1.1.4).
+projectType Element Schema:
+|
+ Attribute + |
+
+ Description + |
+
+ Required? + |
+
|
+ projectTypeID + |
+
+ The unique ID of a + projectType for which this page should appear. + |
+
+ Yes + |
+
7.14.1.1.3 toolchain Element
+This is an optional child element of wizardPage +which specifies a toolchain for which the additional pages should apply. One instance of this element is +provided per toolchain supported by the page.
+ ++ + + + + + + + + + + + + + + + + + + + + + + + + +toolchain +Element Schema
+|
+ Attribute + |
+
+ Description + |
+
+ Required? + |
+
|
+ toolchainID + |
+
+ The unique ID of a + toolchain for which this page should appear. + |
+
+ Yes + |
+
|
+ versionsSupported + |
+
+ A comma separated list of + specific versions of the toolchain that are supported by the page. If not specified, it is + assumed that this page supports the toolchain regardless of version. + |
+
+ No + |
+
This optional child element of wizardPage specifies +the project nature(s) for which the additional pages should apply. One +instance of this element is provided per nature supported.
+This +would for example allow one to add pages to the New Managed C Project +wizard but not the New Managed C++ project wizard, or other hypothetical +natures that might be supported by MBS in the future (e.g. someday there +might be a Fortran nature).
+If no natureID elements are specified, then it is +assumed that the page potentially applies to all project natures, +although it may still be excluded based on project type (§7.14.1.1.2) or toolchain (§4.1.1.1.3)
+natureID element Schema:
+|
+ Attribute + |
+
+ Description + |
+
+ Required? + |
+
|
+ natureID + |
+
+ The unique ID of a nature + (org.eclipse.core.resources.natures) for which this page should + appear. + |
+
+ Yes + |
+
+
7.14.2 High-Level Architecture
+
7.14.2.1 System Overview
+
The custom wizard pages subsystem in MBS is responsible for managing:
-
+
- Which pages exist in the system, and their associated attributes +
- + + Whether pages should be shown in a given + wizard based upon what options the user has selected in previous pages + (i.e. project nature, toolchain, project type). +
- What order pages are shown in as the user navigates the wizard +
- + + What operations should be executed in + association to the page during the wizard?s doRunEpilogue() method. + +
The main entry point to the system is a central manager class calledl MBSCustomPageManager. This
+class is responsible for managing classes which handle the
+aggregation of page data (MBSCustomPageData).
For convenience sake, an abstract base class for wizard pages exists (MBSCustomPage) which ISVs can subclass to implement the default behaviour of +allowing the page manager to completely control the ordering of pages.
+The following class diagram shows how these
+new classes fit into the existing wizard system in MBS in terms of class
+hierarchies and associations.
+
+
Figure 12: High level view of MBS wizard system
+
+As you can see in Figure 12, there are two MBS wizards, one for C projects and one for C++. These
+wizards ultimately inherit some of their behaviour from the generic
+wizards provided by the CDT's core UI. There are several wizard pages that always appear in the MBS wizard, which allow the user to select the project name, project location, and MBS project type for their project. The wizards defer to the MBSCustomPageManager to handle any custom pages that might be present in the system.
7.14.3 Low-Level Architecture
+
Drilling down into the custom wizard page system itself, we see the following:
+
+
+
Figure 12: High level view of custom wizard system
+
The MBSCustomPageManager class is the main entry point to the system. It is responsible for loading all of the extensions which provide custom wizard pages, and storing that data for later use by the wizard. It keeps a list of records of these pages (MBSCustomPageData) which act as a repository for everything that needs to be known about the page, including what circumstances it should be shown under, and what actual IWizardPage should be shown when the page is displayed.
+
For convenience, there is an abstract base class (MBSCustomPage) which ISVs can subclass to get the most commonly desired behaviour from their pages. Most notably, the provided implementation contained in this class consults the MBSCustomPageManager to determine what wizard pages appear before and after the page, which is necessary to ensure that all custom pages in the system are displayed when they should be.
+
7.14.3.1 MBSCustomPageManager
This class is responsible +for:
+-
+
- Maintaining the set of custom pages as +discovered by the wizard and allowing them to be referenced by string ID +
- Managing the published data which pages wish to +make available to other pages +
- + Managing + the visibility and ordering of custom pages within the wizard as the + user navigates between pages. +
This class is a singleton.
+All non-constructor methods are static.
When the wizard is initialized, it +makes a call to MBSCustomPageManager.loadExtensions(). This method looks contributions to the org.eclipse.cdt.managedbuilder.ui.newWizardPages +extension point. The loaded data is used to +instantiate and populate an MBSCustomPageData object for each page +discovered.
+As the user manipulates the wizard, each page can +publish data they wish to export for use by other pages. This is done via the +addPageProperty() method, which allows for the storage of string data by +string key, using the string ID of the page as a sort of namespace. The data can be +retrieved by other pages via the getPageProperty() method, and this is the standard way for pages to interface to eachother.
+Individual pages are expected to somehow consult
+the getNextPage() and getPreviousPage() methods of the manager when
+their own getNextPage() and getPreviousPage() methods are called by the
+wizard. This allows the
+pages to properly navigate amongst eachother while taking into account
+user choices such as project nature, toolchain, and project type. It should be noted that the
+manager can only do so much as it fills the role of an advisor. Custom pages are still
+theoretically free to ignore its existence, although this is strongly
+discouraged.
+
+
+
+
+
+
+
7.14.3.2 MBSCustomPageData +
+This class provides data aggregation capabilities
+for the page manager to store information on a custom wizard page. On startup, the page manager
+loads all contributions to the newWizardPages extension point, and
+stores the loaded data in these records for later use. There is a nested class, ToochainData, which is used to maintain information on each individual toolchain a given custom page supports. The MBSCustomPage manager calls various methods on this class (e.g. MBSCustomPageData.shouldBeVisibleForNature()) to determine when a given page should be visible in the wizard.
+
+
+
+7.14.3.3
+
+MBSCustomPage
+
+
This abstract class provides a convenient, partial
+implementation of the IWizardPage interface. This class provides
+implementations of the getNextPage() and getPreviousPage() methods which
+consult with the page manager to determine which pages are to be
+displayed. If an ISV?s
+custom pages do not subclass MBSCustomPage then their page
+implementation must be carefully coded to function properly while still
+respecting the rules laid out by the page manager.
+
+
+
+
7.14.4 Limitations
+
+
+
+Currently there is no way for ISVs to
+intermingle their wizard pages amidst the ones defined in MBS, or amidst
+the ones created by other plugins in general. In the future it might be
+possible to provide an extension point which would allow an ISV to
+customize this ordering for their product.
This would +be problematic though as it would be possible for multiple ISVs to +attempt to specify such an ordering within the same installation of +Eclipse/CDT.
+It would +also be problematic as certain custom pages would rely on the selected +project type or toolchain, and with a reordering mechanism, ISVs would +have to be careful to not try to put such pages ahead of the page on +which that data is selected. If +a developer were reordering pages that they themselves did not create, +they would have to tread extremely carefully to properly manage these +and other ordering constraints.
+7.15 Defining Startup Behavior for Configuration Loading
Tool integrators may require that a plugin contain all the build configurations before projects are loaded. Use of this interface insures that a plugin will have access to build configurations before project inforamation is loaded in the workbench. Two methods can be used to access configuration information just after build definitions have been loaded and then again after the build definitions have been resolved. Added as enhancement to bug 123275.
public interface IManagedBuildDefinitionsStartup {
diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/classdiagram.jpeg b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/classdiagram.jpeg new file mode 100644 index 00000000000..03f6d25a7de Binary files /dev/null and b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/classdiagram.jpeg differ diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/classdiagram2.jpeg b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/classdiagram2.jpeg new file mode 100644 index 00000000000..aabe897c1db Binary files /dev/null and b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/classdiagram2.jpeg differ diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/clip_image001.jpg b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/clip_image001.jpg new file mode 100644 index 00000000000..89d7786fbdf Binary files /dev/null and b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/clip_image001.jpg differ -- cgit v1.2.3