Anjuta DevStudio: GNOME Integrated Development Environment

Notes for Developers on contributing to Anjuta

(To be expanded over time. Please post submissions to the Anjuta Development mailing list or the project maintainer)

Getting Started

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 anjuta.anjuta project file in CVS for this purpose.

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.

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 to know the code and feature set better, and learn the way GNOME projects are developed. Also, you will be helping a lot of people to use Anjuta better. You can use the wiki or update the manuals, DAQ, etc. 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 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.

4. Working on the porting anjuta 1.2 features to anjuta2. This is a noble undertaking but likely to be hard work, and probably not suitable for newbie developers. Note that this is most code and plugins are ported but they might not yet be as good as in anjuta 1.2.

Resources

- Homepage: http://www.anjuta.org/
- Project details page: http://sourceforge.net/projects/anjuta/
- CVS snapshots: http://www.anjuta.org/cvs/
- Anonymous CVS Access: cvs -z3 -d:pserver:anonymous@anoncvs.gnome.org:/cvs/gnome co anjuta
- Mailing Lists: http://sourceforge.net/mail/?group_id=14222
- Bug database: http://bugzilla.gnome.org (the module is called anjuta)
- Feature Requests: See Bug database above
- Forums: http://sourceforge.net/forum/?group_id=14222
- IRC: irc.gnome.org (Channel: #anjuta and #devel-apps)

Tools

Anjuta is written using a mixture of C and C++. You will require the standard GNU tool chain and current stable GNOME libraries to build and work with the Anjuta sources. 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++.

Submitting patches

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.

Patches may be submitted to the project website, to the mailing lists, or directly to the project maintainer.

The six-step plan to patching happiness is as follows

1) All patches should be submitted in *unified* form, i.e. created with the command "diff -u" or "cvs diff -u").

Make your changes in all files (including the ChangeLog file) and run "cvs diff -u > patch.diff" in the top level anjuta/ directory. This diff file will contain patches for all of the files together.

Remember to run the cvs diff for the *top* project directory. It will automatically recurse into the subdirectories and generate the patches.

We ask for patches in this format because:
- more often then not, patches are out of sync with current CVS. This can happen because someone is submitting a patch taken against an old version of Anjuta, or against anonymous CVS (which is usually out of sync for 24 hours). Therefore, the maintainers have to review patches manually.
- if a patch file is opened in Anjuta (or editors such as Nedit) in "Diff" mode, *unified* formats are more readable and errors and mis-syncs are easily detected. Non-unified formats are hard to read.
- unified patches are more intelligent in recognizing changed lines (because by default there is a 3-line context buffer).

2) Diffs taken against CVS should be preceded by "cvs -z3 up" in
- all* cases.

(Note: You can of course use the cvs plugin for all this stuff)

3) If the patch is big or is not high priority (i.e. things other than stability patches), then either send it to the lead developers directly (cc-ing them together is a nice idea), or file it at bugzilla.gnome.org.
- 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.

4) *Always* include a ChangeLog entry as part of the diff to ensure that your entry is also committed directly with your name mentioned.

5) Name the patch with a useful filename. e.g. avoid calling your patch patch.diff, anjuta.diff or something like that. It is easier to manage a queue of patches named things like biswa-print-20020605.diff and bug-544912.diff as the names are more meaningful. Include the bug number or your name and the date in the name of the file. Thanks!

Coding style

Tab size = 4, Indentation = 4, Use tabs for indentation. Autoformat style: Anjuta coding style. Example code:

/* 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.
- /
gchar*
function (gchar *arg1, gint arg2, gint arg3, gpointer arg4, GHashTable *arg5,
          gint arg7, gpointer arg7)
{
    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)
    {
        switch (a)
        {
        case 1:
            printf ("Hello World");
        case 2:
            printf ("Welcome to Anjuta");
        default:
            printf ("Welcome");
        }
    }
    
    /* No inline declarations of variables */
    str = function_call (gchar *arg1, gint arg2, gint arg3, gpointer arg4,
                         GHashTable *arg5, gint arg7, gpointer arg7,
                         last_arg);
    return str;
}

- 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.
- 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.

General source structure

When editing the code, adding new classes or methods, etc. please conform with the style already followed in the source files.

If a section of code will require further work, please add helpful comments of the form /* FIXME: ... */, so that an external tool (such as grep) can be used to identify them.

Separator in filename: You should always use - instead of _, meaning anjuta-plugin.h insted of anjuta_plugin.h

Key elements:
- libanjuta/ - Anjuta IDE framework
- scintilla/ - the scintilla editing component
- launcher/ - launcher wrapper used by the debugger
- tagmanager/ - the tagmanager library
- libegg/ - extra widgets
- plugins/ - plugin components (see the sample for more information)
- 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).

Scintilla

The editing component in Anjuta is Scintilla (www.scintilla.org). The Scintilla sources are imported to the scintilla/ directory in the Anjuta source tree - some reorganization is required:

Scintilla		Anjuta
- --------		------
src/		->	scintilla/
gtk/		->	scintilla/
include/	->	scintilla/include

These are used to compile libscintilla.a, the library which provides the bulk of Anjuta's editing functions.

The interface into Scintilla is in src/aneditor-*.cxx. This is based on SciTE and a lot of care needs to be taken when merging code, since it combines several different files from the SciTE source tree and is quite flexible in the ways that they are used. Also, note that lexer objects from Scintilla must be referenced in src/Makefile.am in order to get linked into Anjuta.

Messages and translations

There are a few rules we ask contributors to follow when adding new message strings and labels to Anjuta.

1. BE CONSISTENT!!
- refer to the standard GNOME Word List in the GNOME Style Guide (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.
- make sure that mixed case is only used where it makes sense to do so.

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 is no reason for the words "start" and "module" to start with an uppercase 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"! :-)

Documentation

The documentation is stored in the manuals/ directory, and consists of a set of SGML sources conforming to the GNOME Documentation Project's 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.

Translations of application messages are stored in the standard po/ directory structure at the top level of the source tree.

Graphics

PNG format is preferred for application graphics.

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.

ARCHITECTURE

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

1) Event Driven

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

For details how to use the anjuta-launcher consult AnjutaLauncher reference documentation in libanjuta.

2) How to add new menu/toolbar items in the Main Menu

Anjuta uses GtkUIManager for creating it's UI. Libanjuta does provide some wrapper functions in anjuta-ui.h. Take a look at the *.ui files in the plugins, the Plugin docs in the reference and read the GtkUIManager docs for details.

4) Dialogs and Windows

Dialogs and Windows should be build using libglade. They should be HIG compliant (http://developer.gnome.org/projects/gup/hig/)

- All dialogs should be closable by 'ESC'
- All dialogs should have default action.

5) Property/Config management

Anjuta has a very powerful preferece management. You can read the docs of AnjutaPreferences in the reference.

7) How to add a new project type

FIXME: For no take a look at the project types in plugins/project-wizard/templates

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

New contributors must always be credited in AUTHORS file

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