when using parallel builds, make install with kdesudo uses a command string
[kdevelop:kdevelop.git] / README.devel
1 General
2 -------
3 KDevelop 2 could be generally divided into the following categories:
4
5  - The core: Which connects the parts and plug-ins to the user
6    interface
7  - Parts: Which implements various parts of the KDevelop based on
8    Components architecture.
9  - Plug-ins: Which implements some other stuff based on the plug-in
10    architecture. For the difference between Components and plug-ins
11    see bellow.
12
13 The Core
14 --------
15 Resided in kdevelop/, sets up the GUI, loads various components
16 (throug the Component Manager - see bellow), communicates with the
17 components to let them talk to the user interface.
18
19 Components/Component Architecture
20 ---------------------------------
21 Initial functionalities whithin KDevelop are divided into some
22 Parts. These are parts which KDevelop needs to run and function. For
23 instance you can think of the editor, or the class parser. 
24
25 To give the component identities and uniformation, they shold be
26 derived from the class KDevComponent as defined in
27 kdevelop/lib/ComponentManager/kdevcomponent.h. This class defines some
28 minimal functionality needed for instance for communications. Each
29 component can communicate with other components or with the core.
30 KDevComponent defines some virtual methods which could be overrided in
31 each component.
32
33 To let the components communicate with each other, every component
34 should have some minimum access to the component which it's going to
35 communicate with. That's why the communicating components should be
36 divided into a generalization and a specialization.
37
38 The Generalization is directly derived from KDevComponent and provides
39 minimum access for other components which may communicate.  The
40 Specialization is a derived class from the Generalization, and extends
41 the components and implements it fully. The generalizations are
42 resided in kdevelop/lib/ComponentManger/Components/ and the
43 specializations are defined as Parts in kdevelop/parts.
44
45 If a component does not need to communicate with other components, or
46 nobody wants to communicate with it, it does not need to have
47 generalization and it could directly derive from KDevComponent. In
48 this case it is called a global component.
49
50 The Generalizations are identified externally by ServiceTypes of
51 KDE. The Specializations are identified externally by Services.
52 The MUST have these. (See Component Manager)
53
54 The components can communicate also with the core, or the core may
55 want to communicate with them. This happens through the Component
56 Manager (See bellow).
57
58 Plug-ins/ Plug-in architecture
59 ------------------------------
60 Extended specializations of the Parts and also some other
61 functionalities are defined as Plug-ins. Plug-ins are resided in
62 /kdevelop/plugin.
63
64 Component Manager
65 -----------------
66 To give a uniform structure to the Core<->Component communications and
67 to organize the loading/unloading the componens and to register them
68 correctly there is Component Manager.
69
70 Class KDevComponentManager, resided in lib/ComponentManager is
71 responsible for loading the components (using the klibloader and
72 kservice). Everybody (mostly the core) who wants to load a component,
73 loads it using the KDevComponentManager.  KDevComponentManager
74 provides the needed methods. When KDevComponentManager loads a module,
75 registers it as well, so it can give the pointer to the rest, if they
76 ask for it.
77
78 Another aspect of the KDevComponentManager is the Core<->Component
79 communications. It provides some public slots and signals. Send the
80 right signal to it, it distributes the signal over the registerd
81 components. So can the core communicate easily with the components
82 just using the KDevComponentManager to deliver its qt signals.
83
84 Creating a KDevComponent
85 ------------------------
86 A new KDevComponent should have the following characters:
87
88  - It could have a generalization.
89  - It must have a specialization.
90  - The generalization (if exists) must derive from the class
91    KDevComponent.
92  - The specialization must derive from the generalization (if exists,
93    otherwise from the class KDevComponent)
94  - The generalization (if exists) must provide a ServiceType.
95  - The specialization must provide a Service associating with the
96    ServiceType of the generalization (if exists, otherwise the
97    ServiceType of KDevComponent).
98  - The generalization (if exists) must reside in 
99    kdevelop/lib/ComponentManager/Components.
100  - The specialization must reside in kdevelop/parts.
101  - It must have a KInstance and should be able to be loaded with
102    klibloader.
103
104 Note:
105 Not everything should be component. The Component architecture is
106 complex enough and should stay understandable. Take a look, perhaps it
107 is better to make a plug-in out of it.
108
109 KDevNode 
110 --------
111 A KDevNode (lib/general/kdevnodes.h) is a data structure which holds
112 information for an object in KDevelop. This can be used if components
113 want to exchange information about a specific object.  For instance a
114 Projectspace can raise the signal
115 "sigAddedFileToProject(KDevFileNode*)" to inform all other running
116 components that a file was added. The KDevFileNode is a subclass of
117 KDevNode and contains information about Projectspace,Projectname and
118 of course the filenname of this file.
119
120 KDevNodeAction
121 --------------
122 KDevNodeAction is a special KAction which stores a KDevNode and raise
123 it if the action was activated.  In KDevelop 2 it is possible to
124 extend the the popup menus in the treeviews or similar things at
125 'runtime' for every object 'indivual'. For this you will need
126 KDevNodeAction (lib/general/kdevactions.h), the following signal and
127 method :
128
129 void KDevComponent::needKDevNodeActions(KDevNode* pNode, QList<KAction>*pList) 
130 QList<KAction>*KDevComponent::kdevNodeActions(KDevNode* pNode).
131
132 An example: (asking for actions)
133
134 the Projectview need some actions (the user clicked the right
135 mousebutton) for the file "main.cpp" in the project "foobar",
136 projectspace: "foo".
137
138 The Projectview creates now a KDevFileNode (pNode) with these
139 properties and an empty list (pList). After this it raise the signal
140
141 KDevComponent::needKDevNodeActions(KDevNode* pNode,QList<KAction>* pList)
142
143 The list (pList) will be filled with actions (from running components)
144 for these KDevNode. You can use it with:
145
146 +++
147 for(pAction=pList->first();pAction!=0;pAction= pList->next()){
148      pAction->plug(pPopup,-1);// add all available actions to the popupmenu
149 }
150 +++
151
152 An example: (implementing a new action for an KDevNode) An
153 implemention from a ProjectSpace component which add a "Move to"
154 action could look like this:
155
156 +++
157 QList<KAction>* ProjectSpace::kdevNodeActions(KDevNode* pNode){
158   QList<KAction>* pList = new QList<KAction>;
159
160   KDevNodeAction* pAction=0;
161   if(pNode->inherits("KDevFileNode")){
162     pList->append(new KActionSeparator());
163     pAction = new KDevNodeAction(pNode,"Move to..."); // pNode is stored in the Action
164     connect(pAction,SIGNAL(activated(KDevNode*)),this,
165             SLOT(slotMoveFileTo(KDevNode*)));
166     pList->append(pAction);
167 ...
168 return pList;
169 }
170
171 Coding style rules for KDevelop 2
172 ---------------------------------
173 - prefix "m_" for class attributes
174 - prefix "p" for pointers but no further type-prefixes
175 - prefix "m_p" for class attributes which are pointers
176 - upper case letters for each single word in a compound word: e.g.
177   KDevViewHandler instead of Kdevviewhandler.
178 - tab space = 4
179 - tabs replaced by spaces
180 - no prefix "get" at the beginning of a get function.
181
182 How to help
183 -----------
184
185 Please take a look at TODO file (kdevelop/TODO). Perhaps there is
186 something you can do. You can also look for bugs and fix them. You can
187 implement new idea's. You can provide translations. You can add
188 comment and documentations. If you create something, made some pics,
189 provide a patch, etc., you can upload it into our anonymous ftp site.
190 (please visit: http://www.kdevelop.org/index.html?filename=upload.html).
191 And please don't fprget to inform us per email.
192
193 Is there any question? Is there something unclear? Do you need
194 additional information? Just ask! There will be someone at the
195 mailinglist to answer your question.
196
197
198 28-02-2001
199 KDevelop Team
200 Omid Givi, omid@kdevelop.org
201
202
203
204