Fix no newlines warnings. Patch by Peter Oberndorfer
[kdevelopdvcssupport.git] / Architecture.dox
1 /** \file  Architecture.dox
2   * \brief KDevelop architecture
3   */
5 /** \page architecture KDevelop 4 Architecture
7 \section source_overview Platform Source Overview
9 \subsection what_is_platform Platform VS Others
11 The idea is that kdevplatform contains:
12 - everything to create platform plugins
13 - everything to create platform applications
14 - commonly used/important plugins
17 \subsection platform_code Platform Code Layout
19 Platform consists of
20 - interfaces
21   -  interfaces that expose everything necessary for plugins
22   .
23 - shell
24   -  implements interfaces and basically provides a ready-to-use and extend application.
25   .
26 - sublime
27   -  the user interface library
28   .
29 - project and language
30   -  additional libraries for project managers and language supports (usable for other plugins as well)
31   .
32 - plugins
33   -  common plugins, ie those that could be useful for other applications than just KDevelop
34   .
35 - outputview
36   -  allows plugins to easily implement toolviews that show line-by-line output. for example make build output.
37   .
38 - vcs
39   -  central & distributed version control library
40   .
41 - veritas
42   -  generic unit test runner library
45 \subsection platform_for_plugins What to Use in Plugins
47 - plugins need to link to interfaces
48 - plugins shall never link to shell
49 - plugins need not to link to sublime library
50 - plugins can optionally link to other helper libraries in platform when necessary
53 \subsection platform_coding_conventions Current Platform Coding Conventions
55 - preferred coding style is
56 - all platform classes shall be in KDevelop namespace
57 - all files have to be named without kdev* prefix
58 - all files have to be installed in subdirectories under ${INCLUDE_INSTALL_DIR}/kdevplatform/
59 - all interfaces are named KDevelop::IFoo and their files ifoo.h/cpp
60 - all interface implementations are named KDevelop::Foo and their files foo.h/cpp
64 \section code_overview Platform Code Overview
66 \subsection core ICore/Core
68 Core is the central class, it provides access to all shell functionality.
69 There's a KDevelop::ICore interface and KDevelop::Core implementation. KDevelop::ICore interface gives
70 access to all controllers exposed via interfaces. Each plugin is initialized with ICore pointer so it
71 always has access to core via \ref KDevelop::IPlugin::core method. There's no need for something like KDevelop3's
72 KDevAPI class anymore.
74 Core is a singleton that needs to be manually initialized by platform application using
75 \ref KDevelop::Core::initialize right after the KApplication object is created and ShellExtension is initialized.
76 KDevelop::ShellExtension is the same thing as in KDevelop3 - the way to platform application to tell
77 which UI configuration files are used and what is the default profile. KDevelop4 shell extension's
78 only difference is defaultArea() method which shall return the name of default UI area
79 (see below for more information about areas).
81 \subsection plugin IPlugin
83 All concrete plugins must inherit from KDevelop::IPlugin.
84 Extension Interfaces can be used to handle groups of similar plugins in a generic fashion, see below.
85 Each plugin must have an associated .desktop file, as described in KPluginInfo class documentation.
87 \subsection extensions Extension Interfaces and Plugins
89 The idea behind extension interfaces is to provide following features:
90 - To allow plugins to expose their functionality via abstract interfaces
91   and at the same time do not care about BC and do not force other plugins to link with them.\n
92   Documentation plugin would be a good example of non-core but still sometimes useful functionality
93   that might be exported via IDocumentation extension interface with methods like
94   lookupInDocumentation(const QString &) and others.
95   KDevelop4's outputview plugin with IOutputView interface is also a good and actually working
96   example of such use-case.
98 - To have implementations of important functionality not in a shell, but in plugins.\n
99   Good examples are buildsystem managers, builders and language supports in KDevelop4.
100   When a project is opened, a buildsystem manager plugin (that implements either
101   IBuildSystemManager interface or IProjectFileManager) is looked for by the shell an loaded.
103 - To forget about BC issues of dependent plugins. In case the plugin has something new to expose,
104   the new version of extension interface has to be defined. All other plugins will either
105   continue using old interface or ask for the new one.
108 The extension interfaces framework is implemented with QExtensionManager and Co. See the Qt
109 documentation for reference.
111 KDevelop::IBuildSystemManager is an example of an extension interface.
112 Plugins that implement this provide build and/or compile functionality.
113 An other example is KDevelop::ILanguageSupport which abstracts away language specific details from shell.
116 \subsubsection declare_extension To declare extension interface:
117 - Create an abstract class
118 - Include <iextension.h>
119 - Add following macros to the header file with a class (if you use namespace):
120     \code
121     KDEV_DECLARE_EXTENSION_INTERFACE_NS( KDevelop, IMyInterface, "org.kdevelop.IMyInterface")
122     Q_DECLARE_INTERFACE( KDevelop::IMyInterface, "org.kdevelop.IMyInterface" )
123     \endcode
124 - Or use (when the interface is not in namespace)
125     \code
126     KDEV_DECLARE_EXTENSION_INTERFACE( IMyInterface, "org.kdevelop.IMyInterface" )
127     Q_DECLARE_INTERFACE( IMyInterface, "org.kdevelop.IMyInterface" )
128     \endcode
131 \subsubsection implement_extension To implement extension interface:
132 - Create a plugin as usual
133 - Subclass it from your interface
134 - Use Q_INTERFACES macro in class declaration
135 - use KDEV_USE_EXTENSION_INTERFACE macro in the constructor of the plugin:
136     \code
138     \endcode
139 - declare in plugin's .desktop file:
140     \code
141     X-KDevelop-Interfaces=IMyInterface
142     \endcode
143   Code Example:
144     \code
145     class MyPlugin: public KDevelop::IPlugin, public KDevelop::IMyInterface {
146         Q_OBJECT
147         Q_INTERFACES(KDevelop::IMyInterface)
148     public:
149         MyPlugin(QObject* parent) : IPlugin( parent )
150         {
151             KDEV_USE_EXTENSION_INTERFACE( KDevelop::IMyInterface )
152         }
153     };
154     \endcode
157 \subsubsection load_extension To load a plugin that supports extension interface:
158 - Use \ref KDevelop::IPluginController::pluginForExtension method if you have only one possible
159   plugin implementing the extension interface
160 - Or use \ref KDevelop::IPluginController::allPluginsForExtension method to return a list of plugins.\n
161   Note, that those methods will load plugins if they are not yet loaded
162 - Once IPlugin pointer is returned by one of two methods above, it can be asked for an
163   extension using \ref KDevelop::IPlugin::extension method ( like plugin->extension<IMyInterface>() )
165 \subsubsection interplugin_dependency To set a dependency between plugins:
166 - Set the list of required interfaces in plugin's .desktop file
167     \code
168     X-KDevelop-IRequired=IMyInterface,IMyOtherInterface
169     \endcode
170 It is not possible to set direct inter-plugin dependencies. The plugin shall never depend on another
171 plugin, it shall only depend on something that implements the interface.
174 \subsection project IProject, IProjectController and Project Management Infrastructure
176 KDevelop4 can have multiple projects open at any given time.
178 project management structure:
179 \code
180                                         |--------------------|       |-------------------------------|
181                                   |---->| KDevelop::IProject |------>| KDevelop::IProjectFileManager |
182                                   |     |--------------------|       |-------------------------------|
183                                   |                 |
184 |------------------------------|  |     |------------------------|
185 | KDevelop::IProjectController |------->| KDevelop::ProjectModel |
186 |------------------------------|  |     |------------------------|
187                                   |                 |
188                                   |     |--------------------|       |-------------------------------|
189                                   |---->| KDevelop::IProject |------>| KDevelop::IBuildSystemManager |
190                                         |--------------------|       |-------------------------------|
191 \endcode
192 ProjectController is a container for projects (\ref KDevelop::IProject interface). Each project contributes
193 its contents (files, folders, targets, etc.) to the \ref KDevelop::ProjectModel. Each project also has
194 a file manager plugin associated with it.\n
195 Project file manager is the plugin which implements either KDevelop::IProjectFileManager or
196 \ref KDevelop::IBuildSystemManager and provides all actual project management facilities.\n
197 This way KDevelop4 is able to load as many projects as desired and each of the project can
198 have different build system. Plugins access project contents through classes defined in 
199 \ref KDevelop::ProjectModel. Examples include ProjectFolderItem, ProjectFileItem, ProjectTargetItem etc.
201 %KDevelop currently supports the notion of "current project" (the one which is currently selected) in the
202 project management view). But plugins are encouraged to not depend on it. The selection might be
203 empty or project management view might be closed at any time.
205 %KDevelop Platform provides by default "GenericProjectManager" which just threats all files and
206 subdirectories under project directory as project items and currently provides no building facilities.
208 The project file (&lt;projectname&gt.kdev4) controls which project file manager will be loaded.
209 For example, this .kdev4 file will load Generic manager:
210 \code
211     [General Options]
212     Manager=KDevGenericManager
213 \endcode
216 \subsection language ILanguage, ILanguageController and Language Support Infrastructure
218 The language support infrastructure is designed to be similar to project management.
219 Its goals are:
220 - use as many language supports as necessary at the same time
221 - be able to load several language supports for one source file
222   good examples are mixed-source files like .php (php+html), .rhtml (ruby + html)
223 - be not dependent on projects
226 language support structure:
227 \code
228                                                                           |----------------------------|
229                                                                     |---->| KDevelop::ILanguageSupport |
230                                          |---------------------|    |     |----------------------------|
231                                    |---->| KDevelop::ILanguage |----|
232                                    |     |---------------------|    |     |----------------------------|
233                                    |                                |---->| KDevelop::BackgroundParser |
234 |-------------------------------|  |                                      |----------------------------|
235 | KDevelop::ILanguageController |--|
236 |-------------------------------|  |                                      |----------------------------|
237                                    |                                |---->| KDevelop::ILanguageSupport |
238                                    |     |---------------------|    |     |----------------------------|
239                                    |---->| KDevelop::ILanguage |----|
240                                          |---------------------|    |     |----------------------------|
241                                                                     |---->| KDevelop::BackgroundParser |
242                                                                           |----------------------------|
243 \endcode
244 Language controller holds the set of already loaded languages and provides means to load more.
245 For each language (defined by its "name") Language object exists. Each such language has
246 a background parser and a actual support plugin that implements KDevelop::ILanguageSupport.
247 This way the basic shell functionality (like language loading algorithm and background parser)
248 is separated from language-specific stuff (like parsing).
250 Unlike KDevelop3, language support plugin is loaded not among with a project. Instead, when the
251 source file is opened, the language controller asks plugin controller whether there are
252 any language plugins (those that implement KDevelop::ILanguageSupport) that support a mime type
253 of the file (those who set X-KDevelop-SupportedMimeTypes=...).
255 For each language support plugin found, the KDevelop::Language object (that implements KDevelop::ILanguage interface)
256 is created and language support plugin is associated with it. Then each language is asked to return
257 a KDevelop::ParseJob to process the file. This way several language supports are able to parse one file.
259 If KDevelop::Language object for given mimetype already exists, it is used and no plugin loading is performed.
262 \subsection uicontroller IUiController
264 KDevelop::UiController is closely connected to the Sublime UI and basically is an subclass of
265 \ref Sublime::Controller which will be explained later.
267 The main job of UiController is to allow plugins to manager their views and toolviews. Currently only
268 toolviews can be added and removed.
270 Sublime UI wants plugins to add and remove not actual toolviews, but factories to create them.
271 This is because user can request from Sublime UI to show a new toolview at any time. For example,
272 it is possible to have more than one Konsole toolviews. The user just have to ask for them.
273 Automatically factory will be used only once, when UI controller is asked to add a toolview.
274 This means for example that only one Konsole toolview will be opened automatically.
276 To create a factory, a plugin needs to subclass KDevelop::IToolViewFactory and implement two methods:
277 - virtual QWidget* KDevelop::IToolViewFactory::create(QWidget *parent = 0)
278   where the actual toolview widget will be created
279 - virtual Qt::DockWidgetArea KDevelop::IToolViewFactory::defaultPosition(const QString &areaName)
280   which will give the UI a hint on where to place the toolview
283 Once the factory is ready, it has to be added to the UiController using IUiController::addToolView() method.
284 It is not absolutely necessary for a plugin to remove or delete toolview factory. UiController will
285 delete them all upon unload.
287 NOTE: temporarily IUiController has KDevelop::IUiController::openUrl() method which is the only
288 way to open files in KDevelop until DocumentController is ported.
292 \section sublime Sublime UI
294 \subsection sublime_operation Modus Operandi
296 - UI provides support for "areas" (alike Eclipse's perspectives)
297 - The basic set of areas is:
298   - code editing area with splitted editor windows \n
299     (with kate/konqueror-like splitting)
300   - debugging area \n
301     (Xcode-like debugger window with only one editor view by default but with possiblility to show more)
302   - profiling area \n
303     (like KCacheGrind)
304   - user interface design area \n
305     (like Qt designer)
306 - Area configuration includes code editor windows (unlike eclipse)
307 - Each area can be displayed in usual Qt mainwindow with toolviews in dockwidgets
308 - Areas are shown in separate mainwindows so that multiple-monitor setups become the best supported
309 - One area can be shown in two and more mainwindows by "cloning" the area \n
310   (unlike Eclipse that pretends that two mainwindows show the same area)
311 - Optionally areas can be switched inside the same mainwindow without opening new ones
312   (like in Eclipse), but this mode of operation is currently not implemented. \n
313   Also Sublime was not optimized for this use-case. See wiki pages for a detailed discussion and
314   explanation of possible problems.
315 - It is possible to open as many similar toolviews as necessary (for example, several konsole's)
316 - It is possible to open several views for the same file in code editor view (unlike KDevelop 3.x)
317 - Instead of tabs for editor windows a "switcher" is provided. \n
318   Currently the switcher is a combobox but that will change for sure.
321 \subsection sublime_architecture Brief Architecture Overview
323 Sublime::Controller is the central point of the whole Sublime infrastructure. It contains areas,
324 documents and controlls mainwindows. \n
325 Sublime::Controller::showArea() is the only way to show an area in the mainwindow.
327 Sublime::MainWindow is just a KParts::MainWindow which just knows how to "reconstruct" the area,
328 react on area changes. Additionally it knows which view and toolview is "active" (i.e. last focused).
330 Sublime::Area is the object that controls views, toolviews and defines their placement
331 inside the mainwindow. Provides varous view management (e.g. add/remove/etc.) methods and signals.
332 Also Area is responsible to store/restore view layout (on-disk storage is not implemented currently).
334 Area is identified by its name. Each KDevelop platform application, for example, has to define
335 a concept of "default area" in ShellExtension so that UiController can load it by default.
337 While areas operate on views, the Sublime Controller deals with \ref Sublime::Document 's only.
338 Sublime::View is only a thin wrapper around actual QWidget.
340 Document is what provides views. Sublime::Document::createView() is the only way to get a view.
341 When createView() is called, the protected Sublime::Document::createViewWidget() is called to
342 return the actual widget for a view.
344 There is an abstract Sublime::Document class with no createViewWidget() implementation and
345 there's a convenience class Sublime::ToolDocument that can create widgets of user-specified type.
347 KDevelop currently uses Sublime::PartDocument which is subclassed by KDevelop::PartDocument.
348 This PartDocument creates a view by loading a part and then asking a part about its widget.