Merge commit 'git-svn'
[anjuta-git-plugin.git] / HACKING
blob9bf949fadd17fbbaedc4cd56f6f7f662990345b7
1 Notes for Developers on contributing to Anjuta:
2 ----------------------------------------------
3 (To be expanded over time. Please post submissions to the Anjuta 
4 Development mailing list or the project maintainer)
6 Getting Started:
7 ---------------
9 First thing to do is to get a build working. Anjuta can be built using jhbuild,
10 which is the recommended way to build GNOME 2.x and Anjuta. It is advisable to
11 use '--enable-warnings --enable-debug' with configure while building anjuta if
12 you want to hack on it. Anjuta can be used to hack on Anjuta, and there is a
13 anjuta.anjuta project file in CVS for this purpose.
15 Once you have got anjuta built and loaded in itself, the most important thing
16 is to decide what to work on (the TODO, as you say). There are many directions
17 you can take. I'm listing some of the more common ones in order of difficulty.
19 0. Use it, test it, report bug, request features, etc. In short, become
20 an active user. That is how most people become anjuta developers.
22 1. Documentation and translation. While this might not be a very
23 attractive option, it has many benefits for newbie developers. You get
24 to know the code and feature set better, and learn the way GNOME
25 projects are developed. Also, you will be helping a lot of people to use
26 Anjuta better. You can use the wiki or update the manuals, DAQ, etc.
27 that are supplied with the source.
29 2. Scratch your itch. This is probably the most attractive option for a
30 reasonably experienced developer. Find something which does not work for
31 you, or some feature that you want but is missing. Then report it on the
32 devel list saying that you'd want to work on it (this is essential to
33 avoid duplication). Then send us patches !
35 3. Fixing bugs and implementing feature requests. You can find our bug
36 and RFE database at http://bugzilla.gnome.org (the module is called anjuta).
37 You can also have a look at the reasonably up-to-date TODO file we maintain
38 in the source code or view it with Task Manager in Anjuta.
40 4. Working on the porting anjuta 1.2 features to anjuta2. This is a noble
41 undertaking but likely to be hard work, and probably not suitable for
42 newbie developers. Note that this is most code and plugins are ported but 
43 they might not yet be as good as in anjuta 1.2.
45 Resources:
46 ----------
47 - Homepage: http://www.anjuta.org/
48 - Project details page: http://sourceforge.net/projects/anjuta/
49 - CVS snapshots: http://www.anjuta.org/cvs/
50 - Anonymous CVS Access: cvs -z3 -d:pserver:anonymous@anoncvs.gnome.org:/cvs/gnome co anjuta
51 - Mailing Lists: http://sourceforge.net/mail/?group_id=14222
52 - Bug database: http://bugzilla.gnome.org (the module is called anjuta)
53 - Feature Requests: See Bug database above
54 - Forums: http://sourceforge.net/forum/?group_id=14222
55 - IRC: irc.gnome.org (Channel: #anjuta and #devel-apps)
57 Tools:
58 -----
59 Anjuta is written using a mixture of C and C++. You will require
60 the standard GNU tool chain and current stable GNOME libraries to 
61 build and work with the Anjuta sources.
62 New code should be in C as long as it does not touch the scintilla
63 editing component. C++ code is only allowed in the editor or if you 
64 need a library which is only availible in C++.
66 Submitting patches:
67 ------------------
68 Patches are good, and patches are always welcome! Small, self-contained 
69 patches are preferred - larger patches which touch on a large number 
70 of areas of the source tree are more complex to apply and test. 
72 Patches may be submitted to the project website, to the mailing lists, 
73 or directly to the project maintainer.
75 The six-step plan to patching happiness is as follows:
76 ------------------------------------------------------
77 1) All patches should be submitted in *unified* form, i.e. created 
78 with the command "diff -u" or "cvs diff -u"). 
80 Make your changes in all files (including the ChangeLog file) and run
81 "cvs diff -u > patch.diff" in the top level anjuta/ directory. This diff
82 file will contain patches for all of the files together.
84 Remember to run the cvs diff for the *top* project directory. It will
85 automatically recurse into the subdirectories and generate the patches.
87 We ask for patches in this format because:
88 - more often then not, patches are out of sync with current CVS. This 
89 can happen because someone is submitting a patch taken against an old 
90 version of Anjuta, or against anonymous CVS (which is usually out of 
91 sync for 24 hours). Therefore, the maintainers have to review patches 
92 manually.
93 - if a patch file is opened in Anjuta (or editors such as Nedit) in 
94 "Diff" mode, *unified* formats are more readable and errors and 
95 mis-syncs are easily detected. Non-unified formats are hard to read.
96 - unified patches are more intelligent in recognizing changed lines
97 (because by default there is a 3-line context buffer).
99 2) Diffs taken against CVS should be preceded by "cvs -z3 up" in 
100 *all* cases.
102 (Note: You can of course use the cvs plugin for all this stuff)
104 3) If the patch is big or is not high priority (i.e. things other than 
105 stability patches), then either send it to the lead developers directly 
106 (cc-ing them together is a nice idea), or file it at bugzilla.gnome.org. 
107 *Never* post big patches to the mailing lists, since they will annoy 
108 subscribers and are liable to be rejected by the list server. Send
109 a reference email to the list mentioning that you have sent a patch.
111 4) *Always* include a ChangeLog entry as part of the diff to ensure that
112 your entry is also committed directly with your name mentioned.
114 5) Name the patch with a useful filename. e.g. avoid calling your patch
115 patch.diff, anjuta.diff or something like that. It is easier to manage
116 a queue of patches named things like biswa-print-20020605.diff and 
117 bug-544912.diff as the names are more meaningful. Include the bug number
118 or your name and the date in the name of the file. Thanks!
120 Coding style:
121 --------------
122 Tab size = 4, Indentation = 4, Use tabs for indentation.
123 Autoformat style: Anjuta coding style.
124 Example code:
125 <pre>
126 /* Use only C comments. Multiple line comments can be written as shown
127  * in this particular example. Avoid writting redundant and balantly
128  * obvious comments. Always put comments for tricky and hacky situations.
129  * Also notice the space before parenthesis.
130  */
131 gchar*
132 function (gchar *arg1, gint arg2, gint arg3, gpointer arg4, GHashTable *arg5,
133           gint arg7, gpointer arg7)
135     gchar *str;
136     gint x = 23; /* Only the trailing variables could be default initialized */
137     gint y = function_call (); /* This is another trailing variable decl */
138     
139     /* There should be a blank line between declarations and code */
140     if (x == y || some_long_comparision == another_long_variable ||
141         (ultra_long_function_call_that_does_not_fit_well (which_has_arguments,
142                                                           and_more_args,
143                                                           yet_more_args) &&
144          ((yet_another_conditional & ENUM_ITEM_1) == TRUE) ||
145          ((yet_another_conditional & ENUM_ITEM_2) == TRUE) ||
146          and_some_more_conditionals != MACRO_NAME) &&
147         notice_how_the_parenthesis_are_aligned_in_the_nest == TRUE)
148     {
149         switch (a)
150         {
151         case 1:
152             printf ("Hello World");
153         case 2:
154             printf ("Welcome to Anjuta");
155         default:
156             printf ("Welcome");
157         }
158     }
159     
160     /* No inline declarations of variables */
161     str = function_call (gchar *arg1, gint arg2, gint arg3, gpointer arg4,
162                          GHashTable *arg5, gint arg7, gpointer arg7,
163                          last_arg);
164     return str;
166 </pre>
168 - Try to limit the lines to 80 characters.
169 - Please try to write OO-code using GObject (or derived class) as baseclass.
170 This will lead to better design and clear module separation.
171 - If possible gnome-vfs is preferred to standard UNIX IO functions.
172 - Try to avoid forward declaration of static functions, try to keep them in 
173 order instead
174 - Use descriptive variable names like filename instead of f and cur_item instead
175 of i.
176 - If you use a "hack" please add a comment and say why this could not be done
177 cleaner.
179 General source structure:
180 ------------------------
181 When editing the code, adding new classes or methods, etc. please 
182 conform with the style already followed in the source files.
184 If a section of code will require further work, please add helpful
185 comments of the form /* FIXME: ... */, so that an external tool (such as
186 grep) can be used to identify them.
188 Separator in filename:
189 You should always use - instead of _, meaning anjuta-plugin.h
190 insted of anjuta_plugin.h
192 Key elements:
193 * libanjuta/ - Anjuta IDE framework
194 * scintilla/ - the scintilla editing component
195 * launcher/ - launcher wrapper used by the debugger
196 * tagmanager/ - the tagmanager library
197 * libegg/ - extra widgets
198 * plugins/ - plugin components (see the sample for more information)
199 * src/ - the main Anjuta IDE sources
200 * data/ - System data.
201 * mime/ - Mime related files.
202 * global-tags/ - System tags.
203 * manuals/ - All sorts of sgml documents (API and user).
205 Scintilla:
206 ---------
207 The editing component in Anjuta is Scintilla (www.scintilla.org). 
208 The Scintilla sources are imported to the scintilla/ directory in the
209 Anjuta source tree - some reorganization is required:
211 <pre>
212 Scintilla               Anjuta
213 ---------               ------
214 src/            ->      scintilla/
215 gtk/            ->      scintilla/
216 include/        ->      scintilla/include
217 </pre>
219 These are used to compile libscintilla.a, the library which provides
220 the bulk of Anjuta's editing functions.
222 The interface into Scintilla is in src/aneditor-*.cxx. This is based on
223 SciTE and a lot of care needs to be taken when merging code, since it
224 combines several different files from the SciTE source tree and is
225 quite flexible in the ways that they are used. Also, note that lexer
226 objects from Scintilla must be referenced in src/Makefile.am in order 
227 to get linked into Anjuta.
229 Messages and translations:
230 -------------------------
231 There are a few rules we ask contributors to follow when adding new
232 message strings and labels to Anjuta.
234 1. BE CONSISTENT!! 
235 - refer to the standard GNOME Word List in the GNOME Style Guide 
236 (http://developer.gnome.org/documents/style-guide/) when referencing 
237 different user interface features, and then use the same terminology 
238 throughout. Try to ensure that your use of words matches the rest of
239 the code.
240 - make sure that mixed case is only used where it makes sense to do so.
242 Example: "Unable to Start Plug in Module %s".
243 This message is not ideal since the standard terminology is "plugin" (so 
244 please do not use "Plug in", "plug-in", etc.). Also, in this case there 
245 is no reason for the words "start" and "module" to start with an uppercase 
246 letter.
248 There are a few standard terms we use - in particular:
249 - plugin
250 - Project (always with an uppercase P)
252 2. Do not use contractions (don't, can't, etc.). These can make a message 
253 difficult to translate.
255 3. Do not use colloquial expressions. They may seem cool or amusing, but 
256 actually they can be hard to translate into all languages. Also, although as 
257 developers it is OK to have fun, messages with certain language in them can be 
258 intimidating for new or inexperienced users, and are not very professional.
260 Example: "You FOOL! I can not attach to myself." 
261 This message was originally used in the debugger code, and was removed some 
262 time ago. It is quite fun, but a new user might be put off. 
264 4. Do not use the first person "I" for referring to Anjuta in messages 
265 (again, the previous message is an example of this). This is bad practice in 
266 technical writing. If you need to refer to Anjuta itself, please use the word
267 "Anjuta"! :-)
269 Documentation:
270 -------------
271 The documentation is stored in the manuals/ directory, and consists 
272 of a set of SGML sources conforming to the GNOME Documentation Project's
273 Style Guide. Please ensure that all additions also follow these guidelines.
275 Screenshots used in the manual are processed using The Gimp. Single dialogs
276 and menus are converted to RGB and the Script-Fu Drop Shadow effect applied 
277 (with the default settings). All documentation images are in PNG format.
279 Translations of application messages are stored in the standard po/ 
280 directory structure at the top level of the source tree.
282 Graphics:
283 --------
284 PNG format is preferred for application graphics.
286 The image filenames are mapped in the file src/pixmaps.h, with helper functions
287 for manipulating them in src/resources.c. Please use this method for including
288 graphics and do not use the filenames directly.
290 ARCHITECTURE:
291 -------------
293 You can find the API documentation of anjuta in the 
294 "Anjuta Developers Reference Manual" devhelp book!
296 1) Event Driven:
297 ----------------
298 When Anjuta was first designed, the primary goal was to enable the use of 
299 external unix commands in a more productive and intuitive way. Therefore,
300 anjuta follows non-blocking input/output operations aggressively. This means
301 that anjuta UI will not freeze while it performs a lengthy task. All such
302 jobs are event-driven (I am not referring to the gtk-events here) and works
303 on asynchronous basis. The example jobs are compilation, debugging, file search,
304 class updates etc. While asynchronous event-driven implementation is more
305 complex than it's synchronous counter part, it gives a smooth and non frustrative
306 operation. :-)
308 For details how to use the anjuta-launcher consult AnjutaLauncher reference
309 documentation in libanjuta.
311 2) How to add new menu/toolbar items in the Main Menu:
312 ----------------------------------------------
314 Anjuta uses GtkUIManager for creating it's UI. Libanjuta does provide
315 some wrapper functions in anjuta-ui.h. Take a look at the *.ui files in the 
316 plugins, the Plugin docs in the reference and read the GtkUIManager docs for
317 details.
319 4) Dialogs and Windows:
320 -----------------------
322 Dialogs and Windows should be build using libglade. They should be HIG compliant
323 (http://developer.gnome.org/projects/gup/hig/)
325 - All dialogs should be closable by 'ESC'
326 - All dialogs should have default action.
328 5) Property/Config management:
329 ------------------------------
331 Anjuta has a very powerful preferece management. You can read the docs of
332 AnjutaPreferences in the reference.
334 7) How to add a new project type:
335 ---------------------------------
337 FIXME: For no take a look at the project types in 
338 plugins/project-wizard/templates
340 8) Debug messages
341 ---------------------------------
343 Do not use g_message/g_warning for debug messages. Use DEBUG_PRINT instead which
344 is defined in libanjuta/anjuta-debug.h. This will assure that debug messages
345 are only presented to developers and not to normal users. Debug messages will
346 only be shown if --enable-debug is passed to configure/autogen which means that
347 DEBUG is defined.
350 9) How to correctly credit people:
351 ----------------------------------
353 New contributors must always be credited in AUTHORS file
355 You should also ensure that you submit headed ChangeLog entries with a 
356 name and e-mail address when you submit a patch.