Warning, /kdevelop/kdevelop/kdevplatform/Architecture.dox is written in an unsupported language. File is not indexed.
0001 /** \file Architecture.dox 0002 * \brief KDevelop architecture 0003 */ 0004 0005 /** \page architecture KDevelop Architecture 0006 0007 \section source_overview Platform Source Overview 0008 0009 \subsection what_is_platform Platform Vs. Others 0010 0011 The idea is that kdevplatform contains: 0012 - Everything to create platform plugins 0013 - Everything to create platform applications 0014 - Commonly used/important plugins 0015 . 0016 0017 \subsection platform_code Platform Code Layout 0018 0019 Platform consists of 0020 - interfaces 0021 - interfaces that expose everything necessary for plugins 0022 . 0023 - shell 0024 - implements interfaces and basically provides a ready-to-use and extend application. 0025 . 0026 - sublime 0027 - the user interface library 0028 . 0029 - project and language 0030 - additional libraries for project managers and language supports (usable for other plugins as well) 0031 . 0032 - plugins 0033 - common plugins, ie those that could be useful for other applications than just KDevelop 0034 . 0035 - outputview 0036 - allows plugins to easily implement tool views that show line-by-line output. for example make build output. 0037 . 0038 - vcs 0039 - central & distributed version control library 0040 . 0041 . 0042 0043 \subsection platform_for_plugins What to Use in Plugins 0044 0045 - Plugins need to link to the interfaces 0046 - Plugins should never link to the shell 0047 - Plugins should not need to link to the sublime library 0048 - Plugins can optionally link to other helper libraries in platform when necessary 0049 . 0050 0051 \subsection platform_coding_conventions Current Platform Coding Conventions 0052 0053 - All platform classes shall be in the KDevelop namespace 0054 - All files should be named without a kdev prefix 0055 - All files have to be installed in subdirectories under ${INCLUDE_INSTALL_DIR}/kdevplatform/ 0056 - All interface names should start with an I (e.g. KDevelop::IFoo) and the files should be named ifoo.h and ifoo.cpp 0057 - All interface implementations are named KDevelop::Foo and their files foo.h/cpp 0058 . 0059 0060 0061 \section code_overview Platform Code Overview 0062 0063 \subsection core ICore/Core 0064 0065 Core is the central class. It provides access to all shell functionality. 0066 There's a KDevelop::ICore interface and a KDevelop::Core implementation. 0067 The KDevelop::ICore interface gives access to all controllers exposed via 0068 interfaces. Each plugin is initialized with an KDevelop::ICore pointer so 0069 it always has access to the core via the KDevelop::IPlugin::core method. 0070 0071 Core is a singleton that needs to be manually initialized by platform 0072 applications using \ref KDevelop::Core::initialize right after the KApplication 0073 object is created and ShellExtension is initialized. KDevelop::ShellExtension 0074 the mechanism platform applications define which UI configuration files are 0075 used and what the default profile is. Use KDevelop::ShellExtension::defaultArea 0076 to define the name of default UI area (see below for more information about areas). 0077 0078 \subsection plugin IPlugin 0079 0080 All concrete plugins must inherit from KDevelop::IPlugin. Extension interfaces 0081 can be used to handle groups of similar plugins in a generic fashion, see below. 0082 Each plugin must have an associated .desktop file, as described in the 0083 KPluginInfo class documentation. 0084 0085 \subsection extensions Extension Interfaces and Plugins 0086 0087 The idea behind extension interfaces is to provide following features: 0088 - To allow plugins to expose their functionality via abstract interfaces 0089 and at the same time allow them to not care about binary compatibility 0090 and to not force a plugin to link against another plugin.\n \n The documentation 0091 plugin would be a good example of a piece of non-core functionality 0092 that could be exported via an IDocumentation extension interface with methods like 0093 lookupInDocumentation(const QString &) and others. The outputview plugin with 0094 has an IOutputView interface which is another example of such a use-case. The 0095 IOutputView interface provided by the outputview plugin can be used by other 0096 plugins to display information to the user with the other plugin not caring 0097 about the specific implementation details of the outputview plugin 0098 0099 - To provide implementations of important functionality in plugins.\n \n 0100 Good examples are buildsystem managers, builders, and language supports in 0101 KDevelop4. When a project is opened, a buildsystem manager plugin (that 0102 implements either IBuildSystemManager interface or IProjectFileManager) is 0103 looked for by the shell and loaded. 0104 0105 - To forget about binary compatibility issues of dependent plugins.\n \n 0106 In case the plugin has something new to expose, a new version of the 0107 extension interface has to be defined. All other plugins will either continue 0108 using the old interface or ask for the new one. 0109 . 0110 0111 The extension interfaces framework is implemented with QExtensionManager and 0112 company. See the Qt documentation for more information. 0113 0114 KDevelop::IBuildSystemManager is an example of an extension interface. 0115 Plugins that implement this provide build and/or compile functionality. 0116 An other example is KDevelop::ILanguageSupport which abstracts away language 0117 specific details from shell. 0118 0119 0120 \subsubsection declare_extension To declare an extension interface: 0121 - Create an abstract class 0122 - Add macros declaring the interface to your abstract class' header file 0123 - If your abstract class is in a namespace use the following: 0124 \code 0125 Q_DECLARE_INTERFACE( KDevelop::IMyInterface, "org.kdevelop.IMyInterface" ) 0126 \endcode 0127 - Otherwise use: 0128 \code 0129 Q_DECLARE_INTERFACE( IMyInterface, "org.kdevelop.IMyInterface" ) 0130 \endcode 0131 . 0132 \note The use of nested namespaces is not supported. 0133 . 0134 0135 \subsubsection implement_extension To implement an extension interface: 0136 - Create a class that inherits from KDevelop::IPlugin 0137 - Add the interface you wish to implement to the inheritance chain for your 0138 new plugin class (use multiple inheritance here) 0139 - Add a Q_INTERFACES macro to your class declaration. \n \n It should be in the 0140 same section as the Q_OBJECT macro. The argument to the Q_INTERFACES macro 0141 should be the name of the interface you're inheriting from. \n \n For 0142 example, if one is using the IMyInterface interface, one would add 0143 \code 0144 Q_INTERFACES( IMyInterface ) 0145 \endcode 0146 to one's class declaration. 0147 - Add the following to the plugin's .desktop file: 0148 \code 0149 X-KDevelop-Interfaces=IMyInterface 0150 \endcode 0151 Replacing IMyInterface which the class name of one's interface. 0152 . 0153 0154 Here's an example putting all of the above together: 0155 \code 0156 class MyPlugin: public KDevelop::IPlugin, public KDevelop::IMyInterface 0157 { 0158 Q_OBJECT 0159 Q_INTERFACES(KDevelop::IMyInterface) 0160 public: 0161 MyPlugin(QObject* parent) : IPlugin( parent ) 0162 { 0163 } 0164 }; 0165 \endcode 0166 0167 0168 \subsubsection load_extension To load a plugin that supports a certain extension interface: 0169 - Use KDevelop::IPluginController::pluginForExtension if you have only one 0170 possible plugin implementing the extension interface 0171 - Or use KDevelop::IPluginController::allPluginsForExtension to return a list 0172 of plugins. \n \note The above methods will load plugins to verify they implement the 0173 extension being asked for if needed. 0174 - Once an KDevelop::IPlugin pointer is returned by one of two methods above, 0175 it can be asked for an extension using KDevelop::IPlugin::extension 0176 0177 . 0178 \subsubsection interplugin_dependency To set a dependency between interfaces: 0179 - Set the list of required interfaces in plugin's .desktop file 0180 \code 0181 X-KDevelop-IRequired=IMyInterface,IMyOtherInterface 0182 \endcode 0183 . 0184 It is not possible to set direct inter-plugin dependencies. One plugin shall 0185 never depend on another plugin, it shall only depend on something that 0186 implements an interface. 0187 0188 \subsection project Project Management Infrastructure 0189 0190 KDevelop4 can have multiple projects open at any given time. 0191 0192 Project management structure: 0193 \code 0194 |--------------------| |-------------------------------| 0195 |---->| KDevelop::IProject |------>| KDevelop::IProjectFileManager | 0196 | |--------------------| |-------------------------------| 0197 | | 0198 |------------------------------| | |------------------------| 0199 | KDevelop::IProjectController |------->| KDevelop::ProjectModel | 0200 |------------------------------| | |------------------------| 0201 | | 0202 | |--------------------| |-------------------------------| 0203 |---->| KDevelop::IProject |------>| KDevelop::IBuildSystemManager | 0204 |--------------------| |-------------------------------| 0205 \endcode 0206 ProjectController is a container for projects (KDevelop::IProject interface). Each project contributes 0207 its contents (files, folders, targets, etc.) to the KDevelop::ProjectModel. Each project also has 0208 a file manager plugin associated with it. 0209 0210 A project file manager is the plugin which implements either one of two 0211 interfaces: KDevelop::IProjectFileManager or KDevelop::IBuildSystemManager. The 0212 project file manager provides the actual project management facilities. 0213 0214 Plugins access project contents through classes defined in 0215 KDevelop::ProjectModel. Examples include ProjectFolderItem, ProjectFileItem, 0216 ProjectTargetItem, etc. 0217 0218 %KDevelop currently supports the notion of "current project" (the one which is 0219 currently selected in the project management view). But plugins are encouraged 0220 to not depend on the notion of a current project. The selection might be empty 0221 or the project management view might be closed at any time. 0222 0223 %KDevelop Platform provides by default a generic project manager. This project 0224 manager treats all files and subdirectories under the project directory as 0225 project items and currently provides no building facilities. 0226 0227 The project file (<projectname>.kdev4) controls which project file 0228 manager will be loaded. For example, this .kdev4 file will load the generic 0229 manager: 0230 \code 0231 [General Options] 0232 Manager=KDevGenericManager 0233 \endcode 0234 0235 0236 \subsection language Language Support Infrastructure 0237 0238 The language support infrastructure is designed to be similar to project management. 0239 Its goals are: 0240 - use as many language supports as necessary at the same time 0241 - be able to load several language supports for one source file 0242 good examples are mixed-source files like .php (php+html), .rhtml (ruby + html) 0243 - be not dependent on projects 0244 . 0245 0246 language support structure: 0247 \code 0248 |----------------------------| 0249 |---->| KDevelop::ILanguageSupport | 0250 |---------------------| | |----------------------------| 0251 |---->| KDevelop::ILanguage |----| 0252 | |---------------------| | |----------------------------| 0253 | |---->| KDevelop::BackgroundParser | 0254 |-------------------------------| | |----------------------------| 0255 | KDevelop::ILanguageController |--| 0256 |-------------------------------| | |----------------------------| 0257 | |---->| KDevelop::ILanguageSupport | 0258 | |---------------------| | |----------------------------| 0259 |---->| KDevelop::ILanguage |----| 0260 |---------------------| | |----------------------------| 0261 |---->| KDevelop::BackgroundParser | 0262 |----------------------------| 0263 \endcode 0264 Language controller holds the set of already loaded languages and provides means to load more. 0265 For each language (defined by its "name") Language object exists. Each such language has 0266 a background parser and a actual support plugin that implements KDevelop::ILanguageSupport. 0267 This way the basic shell functionality (like language loading algorithm and background parser) 0268 is separated from language-specific stuff (like parsing). 0269 0270 Unlike KDevelop3, language support plugin is loaded not among with a project. Instead, when the 0271 source file is opened, the language controller asks plugin controller whether there are 0272 any language plugins (those that implement KDevelop::ILanguageSupport) that support a mime type 0273 of the file (those who set X-KDevelop-SupportedMimeTypes=...). 0274 0275 For each language support plugin found, the KDevelop::Language object (that implements KDevelop::ILanguage interface) 0276 is created and language support plugin is associated with it. Then each language is asked to return 0277 a KDevelop::ParseJob to process the file. This way several language supports are able to parse one file. 0278 0279 If KDevelop::Language object for given mimetype already exists, it is used and no plugin loading is performed. 0280 0281 0282 \subsection uicontroller IUiController 0283 0284 KDevelop::UiController is closely connected to the Sublime UI and basically is an subclass of 0285 \ref Sublime::Controller which will be explained later. 0286 0287 The main job of UiController is to allow plugins to manager their views and tool views. Currently only 0288 tool views can be added and removed. 0289 0290 Sublime UI wants plugins to add and remove not actual tool views, but factories to create them. 0291 This is because user can request from Sublime UI to show a new tool view at any time. For example, 0292 it is possible to have more than one Konsole tool views. The user just have to ask for them. 0293 Automatically factory will be used only once, when UI controller is asked to add a tool view. 0294 This means for example that only one Konsole tool view will be opened automatically. 0295 0296 To create a factory, a plugin needs to subclass KDevelop::IToolViewFactory and implement two methods: 0297 - virtual QWidget* KDevelop::IToolViewFactory::create(QWidget *parent = 0) 0298 where the actual tool view widget will be created 0299 - virtual Qt::DockWidgetArea KDevelop::IToolViewFactory::defaultPosition(const QString &areaName) 0300 which will give the UI a hint on where to place the tool view 0301 . 0302 0303 Once the factory is ready, it has to be added to the UiController using IUiController::addToolView() method. 0304 It is not absolutely necessary for a plugin to remove or delete the tool view factory. UiController will 0305 delete them all upon unload. 0306 0307 NOTE: temporarily IUiController has KDevelop::IUiController::openUrl() method which is the only 0308 way to open files in KDevelop until DocumentController is ported. 0309 0310 0311 \subsection launch Launch Framework 0312 0313 - Launch Configuration (\ref KDevelop::ILaunchConfiguration)<br /> 0314 one entry created by the user in Configure Launches 0315 (ie an executable) 0316 - has one Launch Configuration Type 0317 - has a Launcher for every possible Launch Mode 0318 0319 - Launch Configuration Type (\ref KDevelop::LaunchConfigurationType)<br /> 0320 native application / script 0321 - has possible Launchers 0322 0323 - Launcher (\ref KDevelop::ILauncher)<br /> 0324 creates the KJob for launching 0325 - has LaunchConfigurationPageFactories 0326 - supports a number of Launch Modes 0327 0328 - Launch Mode: execute / debug / profile 0329 0330 - Launch Configuration Page Factory (\ref KDevelop::LaunchConfigurationPageFactory)<br /> 0331 creates Widget used in Configure Launches 0332 0333 - Launch Configuration Page (\ref KDevelop::LaunchConfigurationPage)<br /> 0334 Widget that configures a LaunchConfiguration 0335 0336 - RunController (\ref KDevelop::IRunController) 0337 - has possible Launch Configuration Types 0338 0339 0340 \section sublime Sublime UI 0341 0342 \subsection sublime_operation Modus Operandi 0343 0344 - UI provides support for "areas" (alike Eclipse's perspectives) 0345 - The basic set of areas is: 0346 - code editing area with split editor windows \n 0347 (with kate/konqueror-like splitting) 0348 - debugging area \n 0349 (Xcode-like debugger window with only one editor view by default but with possibility to show more) 0350 - profiling area \n 0351 (like KCacheGrind) 0352 - user interface design area \n 0353 (like Qt designer) 0354 - Area configuration includes code editor windows (unlike eclipse) 0355 - Each area can be displayed in usual Qt mainwindow with tool views in dockwidgets 0356 - Areas are shown in separate mainwindows so that multiple-monitor setups become the best supported 0357 - One area can be shown in two and more mainwindows by "cloning" the area \n 0358 (unlike Eclipse that pretends that two mainwindows show the same area) 0359 - Optionally areas can be switched inside the same mainwindow without opening new ones 0360 (like in Eclipse), but this mode of operation is currently not implemented. \n 0361 Also Sublime was not optimized for this use-case. See wiki pages for a detailed discussion and 0362 explanation of possible problems. 0363 - It is possible to open as many similar tool views as necessary (for example, several konsole's) 0364 - It is possible to open several views for the same file in code editor view (unlike KDevelop 3.x) 0365 - Instead of tabs for editor windows a "switcher" is provided. \n 0366 Currently the switcher is a combobox but that will change for sure. 0367 . 0368 0369 \subsection sublime_architecture Brief Architecture Overview 0370 0371 Sublime::Controller is the central point of the whole Sublime infrastructure. It contains areas, 0372 documents, and controls mainwindows. \n 0373 Sublime::Controller::showArea() is the only way to show an area in the mainwindow. 0374 0375 Sublime::MainWindow is just a KParts::MainWindow which knows how to "reconstruct" the area 0376 and react on area changes. Additionally it knows which view and tool view is "active" (i.e. last focused). 0377 0378 Sublime::Area is the object that controls views, tool views, and defines their placement 0379 inside the mainwindow. Provides various view management (e.g. add/remove/etc.) methods and signals. 0380 Also Area is responsible for storing and restoring the view layout (on-disk storage is not 0381 implemented currently). 0382 0383 An area is identified by its name. Each KDevelop platform application, for example, has to define 0384 a concept of a "default area" in ShellExtension so that the UiController can load it by default. 0385 0386 While areas operate on views, the Sublime Controller deals with Sublime::Document objects only. 0387 Sublime::View is only a thin wrapper around QWidget. 0388 0389 Document is what provides views. Sublime::Document::createView() is the only way to get a view. 0390 When createView() is called, the protected Sublime::Document::createViewWidget() is called to 0391 return the actual widget for a view. 0392 0393 There is an abstract Sublime::Document class with no createViewWidget() implementation and 0394 there's a convenience class Sublime::ToolDocument that can create widgets of user-specified type. 0395 0396 KDevelop currently uses Sublime::PartDocument which is subclassed by KDevelop::PartDocument. 0397 This PartDocument creates a view by loading a part and then asking a part about its widget. 0398 0399 0400 0401 */