HACKING 13 KB
Newer Older
1
Notes for Developers on contributing to Anjuta:
Naba Kumar's avatar
Naba Kumar committed
2
----------------------------------------------
Naba Kumar's avatar
Naba Kumar committed
3
(To be expanded over time. Please post submissions to the Anjuta 
4
Development mailing list or the project maintainer)
Naba Kumar's avatar
Naba Kumar committed
5

6 7
Getting Started:
---------------
Johannes Schmid's avatar
Johannes Schmid committed
8

9 10 11 12
First thing to do is to get a build working. Anjuta can be built using jhbuild,
which is the recommended way to build GNOME 2.x and Anjuta. It is advisable to
use '--enable-warnings --enable-debug' with configure while building anjuta if
you want to hack on it. Anjuta can be used to hack on Anjuta, and there is a
13
anjuta.anjuta project file in git for this purpose.
14 15 16 17

Once you have got anjuta built and loaded in itself, the most important thing
is to decide what to work on (the TODO, as you say). There are many directions
you can take. I'm listing some of the more common ones in order of difficulty.
18 19 20 21 22 23

0. Use it, test it, report bug, request features, etc. In short, become
an active user. That is how most people become anjuta developers.

1. Documentation and translation. While this might not be a very
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 28 29 30 31 32 33 34 35
that are supplied with the source.

2. Scratch your itch. This is probably the most attractive option for a
reasonably experienced developer. Find something which does not work for
you, or some feature that you want but is missing. Then report it on the
devel list saying that you'd want to work on it (this is essential to
avoid duplication). Then send us patches !

3. Fixing bugs and implementing feature requests. You can find our bug
Naba Kumar's avatar
Naba Kumar committed
36 37 38
and RFE database at http://bugzilla.gnome.org (the module is called anjuta).
You can also have a look at the reasonably up-to-date TODO file we maintain
in the source code or view it with Task Manager in Anjuta.
39

40 41
Resources:
----------
42 43
- Homepage: http://www.anjuta.org/
- Project details page: http://sourceforge.net/projects/anjuta/
44 45
- git: http://git.gnome.org/cgit/
- Anonymous CVS Access: git clone git://git.gnome.org/anjuta
46
- Mailing Lists: http://sourceforge.net/mail/?group_id=14222
Johannes Schmid's avatar
Johannes Schmid committed
47 48
- Bug database: http://bugzilla.gnome.org (the module is called anjuta)
- Feature Requests: See Bug database above
49 50 51
- Forums: http://sourceforge.net/forum/?group_id=14222
- IRC: irc.gnome.org (Channel: #anjuta and #devel-apps)

52 53 54 55
Log messages:
-------------
Log messages for git should have the following format:

56
"[Plugin/module name]: A short summary of the changes (should contain bug number)
57 58 59 60
(empty line)
[optional] A more detailed description of the changes made. Can have multiple
lines and should contain patch contributer, etc."

61 62 63 64 65 66
As an example, a typical commit against the Subversion plugin looks like this:
 
    Subversion: Don't show a commit number in the info pane if no files are given
    
    When no files are selected, the commit isn't done and the commit number is just uninitialized junk.

67
Tools:
Naba Kumar's avatar
Naba Kumar committed
68
-----
69
Anjuta is written using a mixture of C and C++. You will require
70
the standard GNU tool chain and current stable GNOME libraries to 
71
build and work with the Anjuta sources.
Johannes Schmid's avatar
Johannes Schmid committed
72 73 74
New code should be in C as long as it does not touch the scintilla
editing component. C++ code is only allowed in the editor or if you 
need a library which is only availible in C++.
75

76
Submitting patches:
77
------------------
78 79 80
Patches are good, and patches are always welcome! Small, self-contained 
patches are preferred - larger patches which touch on a large number 
of areas of the source tree are more complex to apply and test. 
81

82 83
Patches may be submitted to the to the mailing lists of preferable to GNOME
bugzilla.
84

85
The six-step plan to patching happiness is as follows:
86
------------------------------------------------------
87 88
1) Create your patches directly using the git features -> don't write
patches against the tarball.
89

90
2) Use an up-to-date copy for the diffs
Johannes Schmid's avatar
Johannes Schmid committed
91

Johannes Schmid's avatar
Johannes Schmid committed
92
3) If the patch is big or is not high priority (i.e. things other than 
93
stability patches), then either send it to the lead developers directly 
94
(cc-ing them together is a nice idea), or file it at bugzilla.gnome.org. 
95 96 97 98
*Never* post big patches to the mailing lists, since they will annoy 
subscribers and are liable to be rejected by the list server. Send
a reference email to the list mentioning that you have sent a patch.

99
4) Include a good log message to the patch.
100

101 102 103 104
5) Name the patch with a useful filename. For example:
 * 123456-foo-feature.patch or
 * 987654-fixed-editor-crash
It's ok to include the 000x that git puts in front of the patch name
105

Johannes Schmid's avatar
Johannes Schmid committed
106 107
Coding style:
--------------
Naba Kumar's avatar
Naba Kumar committed
108 109 110
Tab size = 4, Indentation = 4, Use tabs for indentation.
Autoformat style: Anjuta coding style.
Example code:
111
<pre>
Naba Kumar's avatar
Naba Kumar committed
112 113 114 115 116
/* Use only C comments. Multiple line comments can be written as shown
 * in this particular example. Avoid writting redundant and balantly
 * obvious comments. Always put comments for tricky and hacky situations.
 * Also notice the space before parenthesis.
 */
Naba Kumar's avatar
Naba Kumar committed
117
gchar*
118 119
function (gchar *arg1, gint arg2, gint arg3, gpointer arg4, GHashTable *arg5,
          gint arg7, gpointer arg7)
Johannes Schmid's avatar
Johannes Schmid committed
120
{
Naba Kumar's avatar
Naba Kumar committed
121 122 123 124 125 126 127 128 129 130 131 132 133
    gchar *str;
    gint x = 23; /* Only the trailing variables could be default initialized */
    gint y = function_call (); /* This is another trailing variable decl */
    
    /* There should be a blank line between declarations and code */
    if (x == y || some_long_comparision == another_long_variable ||
        (ultra_long_function_call_that_does_not_fit_well (which_has_arguments,
                                                          and_more_args,
                                                          yet_more_args) &&
         ((yet_another_conditional & ENUM_ITEM_1) == TRUE) ||
         ((yet_another_conditional & ENUM_ITEM_2) == TRUE) ||
         and_some_more_conditionals != MACRO_NAME) &&
        notice_how_the_parenthesis_are_aligned_in_the_nest == TRUE)
134 135 136 137 138
    {
        switch (a)
        {
        case 1:
            printf ("Hello World");
Naba Kumar's avatar
Naba Kumar committed
139
        case 2:
140
            printf ("Welcome to Anjuta");
Naba Kumar's avatar
Naba Kumar committed
141
        default:
142 143
            printf ("Welcome");
        }
Naba Kumar's avatar
Naba Kumar committed
144
    }
Naba Kumar's avatar
Naba Kumar committed
145 146 147 148 149
    
    /* No inline declarations of variables */
    str = function_call (gchar *arg1, gint arg2, gint arg3, gpointer arg4,
                         GHashTable *arg5, gint arg7, gpointer arg7,
                         last_arg);
Naba Kumar's avatar
Naba Kumar committed
150
    return str;
Johannes Schmid's avatar
Johannes Schmid committed
151
}
152
</pre>
Johannes Schmid's avatar
Johannes Schmid committed
153

Naba Kumar's avatar
Naba Kumar committed
154 155 156
- Try to limit the lines to 80 characters.
- Please try to write OO-code using GObject (or derived class) as baseclass.
This will lead to better design and clear module separation.
Johannes Schmid's avatar
Johannes Schmid committed
157 158 159 160 161 162 163 164
- If possible gnome-vfs is preferred to standard UNIX IO functions.
- Try to avoid forward declaration of static functions, try to keep them in 
order instead
- Use descriptive variable names like filename instead of f and cur_item instead
of i.
- If you use a "hack" please add a comment and say why this could not be done
cleaner.

165
General source structure:
166
------------------------
Naba Kumar's avatar
Naba Kumar committed
167 168 169
When editing the code, adding new classes or methods, etc. please 
conform with the style already followed in the source files.

Andy Piper's avatar
Andy Piper committed
170
If a section of code will require further work, please add helpful
Naba Kumar's avatar
Naba Kumar committed
171 172
comments of the form /* FIXME: ... */, so that an external tool (such as
grep) can be used to identify them.
Andy Piper's avatar
Andy Piper committed
173

Johannes Schmid's avatar
Johannes Schmid committed
174 175 176
Separator in filename:
You should always use - instead of _, meaning anjuta-plugin.h
insted of anjuta_plugin.h
177

Naba Kumar's avatar
Naba Kumar committed
178
Key elements:
179 180
* libanjuta/ - Anjuta IDE framework
* scintilla/ - the scintilla editing component
181
* launcher/ - launcher wrapper used by the debugger
182
* tagmanager/ - the tagmanager library
183
* libegg/ - extra widgets
184
* plugins/ - plugin components (see the sample for more information)
185 186 187 188 189
* src/ - the main Anjuta IDE sources
* data/ - System data.
* mime/ - Mime related files.
* global-tags/ - System tags.
* manuals/ - All sorts of sgml documents (API and user).
190

191
Messages and translations:
192 193 194 195 196
-------------------------
There are a few rules we ask contributors to follow when adding new
message strings and labels to Anjuta.

1. BE CONSISTENT!! 
197
- refer to the standard GNOME Word List in the GNOME Style Guide 
198 199 200 201
(http://developer.gnome.org/documents/style-guide/) when referencing 
different user interface features, and then use the same terminology 
throughout. Try to ensure that your use of words matches the rest of
the code.
202
- make sure that mixed case is only used where it makes sense to do so.
203 204 205 206

Example: "Unable to Start Plug in Module %s".
This message is not ideal since the standard terminology is "plugin" (so 
please do not use "Plug in", "plug-in", etc.). Also, in this case there 
207
is no reason for the words "start" and "module" to start with an uppercase 
208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230
letter.

There are a few standard terms we use - in particular:
- plugin
- Project (always with an uppercase P)

2. Do not use contractions (don't, can't, etc.). These can make a message 
difficult to translate.

3. Do not use colloquial expressions. They may seem cool or amusing, but 
actually they can be hard to translate into all languages. Also, although as 
developers it is OK to have fun, messages with certain language in them can be 
intimidating for new or inexperienced users, and are not very professional.

Example: "You FOOL! I can not attach to myself." 
This message was originally used in the debugger code, and was removed some 
time ago. It is quite fun, but a new user might be put off. 

4. Do not use the first person "I" for referring to Anjuta in messages 
(again, the previous message is an example of this). This is bad practice in 
technical writing. If you need to refer to Anjuta itself, please use the word
"Anjuta"! :-)

231
Documentation:
Naba Kumar's avatar
Naba Kumar committed
232 233 234
-------------
The documentation is stored in the manuals/ directory, and consists 
of a set of SGML sources conforming to the GNOME Documentation Project's
235 236 237 238 239
Style Guide. Please ensure that all additions also follow these guidelines.

Screenshots used in the manual are processed using The Gimp. Single dialogs
and menus are converted to RGB and the Script-Fu Drop Shadow effect applied 
(with the default settings). All documentation images are in PNG format.
240

Naba Kumar's avatar
Naba Kumar committed
241 242
Translations of application messages are stored in the standard po/ 
directory structure at the top level of the source tree.
243

244
Graphics:
245 246 247
--------
PNG format is preferred for application graphics.

248 249 250 251
The image filenames are mapped in the file src/pixmaps.h, with helper functions
for manipulating them in src/resources.c. Please use this method for including
graphics and do not use the filenames directly.

252
ARCHITECTURE:
253
-------------
Johannes Schmid's avatar
Johannes Schmid committed
254 255 256

You can find the API documentation of anjuta in the 
"Anjuta Developers Reference Manual" devhelp book!
257 258 259

1) Event Driven:
----------------
260
When Anjuta was first designed, the primary goal was to enable the use of 
261 262
external unix commands in a more productive and intuitive way. Therefore,
anjuta follows non-blocking input/output operations aggressively. This means
263
that anjuta UI will not freeze while it performs a lengthy task. All such
264
jobs are event-driven (I am not referring to the gtk-events here) and works
265
on asynchronous basis. The example jobs are compilation, debugging, file search,
266 267
class updates etc. While asynchronous event-driven implementation is more
complex than it's synchronous counter part, it gives a smooth and non frustrative
268 269
operation. :-)

Naba Kumar's avatar
Naba Kumar committed
270 271
For details how to use the anjuta-launcher consult AnjutaLauncher reference
documentation in libanjuta.
272

Naba Kumar's avatar
Naba Kumar committed
273
2) How to add new menu/toolbar items in the Main Menu:
274
----------------------------------------------
Johannes Schmid's avatar
Johannes Schmid committed
275

Naba Kumar's avatar
Naba Kumar committed
276
Anjuta uses GtkUIManager for creating it's UI. Libanjuta does provide
James Liggett's avatar
James Liggett committed
277
some wrapper functions in anjuta-ui.h. Take a look at the *.xml files in the 
Johannes Schmid's avatar
Johannes Schmid committed
278 279 280
plugins, the Plugin docs in the reference and read the GtkUIManager docs for
details.

281 282 283
4) Dialogs and Windows:
-----------------------

James Liggett's avatar
James Liggett committed
284
Dialogs and Windows should be build using GtkBuilder. They should be HIG compliant
Johannes Schmid's avatar
Johannes Schmid committed
285
(http://developer.gnome.org/projects/gup/hig/)
286

Naba Kumar's avatar
Naba Kumar committed
287 288 289
- All dialogs should be closable by 'ESC'
- All dialogs should have default action.

290 291 292 293 294 295
Glade catalog:
Several Anjuta plugins, including the Subversion and Git plugins, among others,
use custom widgets with a Glade catalog. To be able to edit glade files for these
plugins, pass --enable-glade-catalog to configure to make sure that the glade
catalog is installed. libgladeui development files must be installed.

296
5) Property/Config management:
297 298
------------------------------

Naba Kumar's avatar
Naba Kumar committed
299
Anjuta has a very powerful preferece management. You can read the docs of
Johannes Schmid's avatar
Johannes Schmid committed
300
AnjutaPreferences in the reference.
301 302 303 304

7) How to add a new project type:
---------------------------------

Johannes Schmid's avatar
Johannes Schmid committed
305 306
FIXME: For no take a look at the project types in 
plugins/project-wizard/templates
307

308 309 310 311 312 313 314 315 316 317 318
8) Debug messages
---------------------------------

Do not use g_message/g_warning for debug messages. Use DEBUG_PRINT instead which
is defined in libanjuta/anjuta-debug.h. This will assure that debug messages
are only presented to developers and not to normal users. Debug messages will
only be shown if --enable-debug is passed to configure/autogen which means that
DEBUG is defined.


9) How to correctly credit people:
319 320
----------------------------------

321
New contributors must always be credited in AUTHORS file
322 323 324

You should also ensure that you submit headed ChangeLog entries with a 
name and e-mail address when you submit a patch.