# Bluefish kézikönyv - 4. fejezet: Fejlesztői segédlet

előző | tartalom | következő

# 4. fejezet: Fejlesztői segédlet

(Ezt a fejezetet nem fordítom le. Aki be szeretne kapcsolódni a Bluefish feljesztésébe, az remélhetőleg nálam jobban érti azokat a szakkifejezéseket, amik a szövegben előfordulnak. Szívesen veszem viszont, ha valaki segít a fordításban.)

This document describes the conventions to use when coding in the Bluefish project. Please suggest improvements or additions.

this is _not_ meant to stop you from coding, but meant to structure the coding a bit. Bluefish isn't very well structured at the moment, and I'm trying to improve this a bit.

happy coding!
Olivier Sessink
http://bluefish.openoffice.nl/

### Debugging Bluefish

#### Crashes - the backtrace

To do a useful backtrace, and you have no idea where the crash is in the program, go to the source tree and run the following command:`make distclean ./configure --with-debugging-output make gdb src/bluefish` This will start the debugger with the freshly compiled binary. If you do have an idea, open that file and add `#define DEBUG` to the top, and run`make distclean ./configure make gdb src/bluefish` Once the debugger is started, you type `r<enter>`, if it stops, saying it is not allowd to read memory, type `c<enter>`. Just run the program till it crashes, then run `bt<enter>`. Send the output (say the last 50 lines) to the development mailinglist. This will give some debug info, and tells exactly where the crash was located in the program

### Indenting and formatting style

just be lazy and use`cd src indent -kr -ts4 *.c *.h` This is the Kernighan & Ritchie coding style, with tabsize 4

Do not use C++ style comments but use plain C /* and */. gcc does things right, but other C compilers might complain about it.

### Naming

use void name_cb() for a callback that can be used global, like the callback to start a dialog (can be something else then a void)

use static void name_lcb() for a local callback, like the OK click in a dialog (can also be something else then a void)

try to have the name explaining what the function does, e.g. doc_do_replace() would do a replace in a specific doc etc.

In document.c we really have a standard now. All functions starting with doc_...() have a Tdocument parameter. All functions without it, are either old (and should be renamed) or are function which work on the main_v->current_document (a pointer to the current visible document).

### Declaring procedures

always declare those functions static that need not be visible outside the current file static. Reason: Avoid polluting the global namespace. static functions will be linked only within the same fle. All procedures that are used in other files (public) should be in the .h file declared.

All variables that are used in other files (public) should be in the .h with an extern before it. But try to avoid global variables. Most of the time you can avoid them by creating a typedef struct.

Don't put any extern bla() in the top of a .c file, use #include otherfile.h in there instead. So if you change a function you only have to change that particular .h file. In other words: Declare global functions in the .h file but nowhere else.

### Header files

if you include header files like `#include <string.h>` please add a comment why this header is needed, like `#include <string.h> /* strlen() */`

### New files

If you are writing a new .c file, write a .h file for it too and include the .h file in the .c file. Use include guards in all .h files like in bluefish.h

    #ifdef __BLUEFISH_H
    #define __BLUEFISH_H
    ... all the declarations here ...
    #endif

Reason: allow the compiler to check consistency between the .c and the .h

### Which files

Alphabetically listed:

- bflib.c - non-GUI general functions, like some string functions and more
- bluefish.c - start and exit, message queue handling
- callbacks.c - general callbacks like weblint functions
- cap.c - caps or non caps HTML
- char_table.c - a character table and special entities
- coloursel.c - colorselection dialog
- configure.c - configuration dialog
- document.c - all functions that handle the Tdocument, cut, copy and paste and other functions that work on documents
- gtk_easy.c - easy GTK shortcuts to reduce repeating code, used in lots of other files
- highlight.c -the syntax highlighting code
- html.c - html dialogs and callbacks
- html_diag.c - the functions that are used to build the html dialogs
- html_table.c - html tables dialogs and callbacks
- html_form.c - html forms dialogs and callbacks
- images.c - image and thumbnail dialogs
- init.c - parse rcfile and commandline to load options, set defaults for all variables, check if the needed directories exist etc.
- interface.c - the main GUI itself, and the splash screen
- javascript.c - ??
- network.c - open from web code, a dead link check can be added here as well
- menu.c - the main menu and the custom menu, including the custom menu editor
- project.c - all functions that handle the Tproject
- pixmaps.c - loading of xpm files into a GTK widget
- ref_dialog.c - the reference dialog code
- rpopup.c - right click menu and parsing of the HTML into a GList
- snr2.c - search and replace, link management (using regex)
- spell.c - spell checking
- spell_gui.c - spell checking GUI
- stringlist.c - stringlist (GList with strings) handling functionality inc. GUI, and arraylist handling with GUI
  - stringlist: a GList (see glib docs) containing only gchar * content
  - arraylist: a GList containing a NULL terminated array of gchar *
- toolbars.c - the main and html toolbars
- undo.c - undo/redo old
- undo2.c - rewritten from scratch, the default now
- wizards.c - wizards, like html*.c, but inserting multiple tags at a time
- wml.c - WML support

### Patches

Antti-Juhani Kaijanaho wrote:

1. I keep two code trees of bluefish, one untouched (an official pre unpacked) and one where I do my work. For every unrelated change I make a new tree for my changes.
2. Before making a patch, run "make distclean".
3. When I want to make a patch, I cd to the parent dir of the two trees. I then run "diff -Naur official-pre-tree my-changed-tree | bzip2 -9c > patchbla.diff.bz2" (where official-pre-tree and my-changed-tree are the two code trees.

### CVS - usage

Olivier wrote:
Using bash (fill in your own username):

    CVSROOT=:pserver:USERNAME@cvs1.openave.net:/home/cvsroot/bluefish1
    export CVSROOT
    cvs login
    cvs checkout bluefish

this will download the most current bluefish development version. If you did this before you can run

    cvs update -dP

to update your local files with new changes. To send files:

    cvs commit

will send your new changes to the CVS repository. Please always update directly before you do a commit, to check if other people are working on the same source!

Some other commands might come in useful:

- cvs log src/document.c will show the log for this file, showing all revisions
- cvs diff -c -r 1.2 -r 1.3 src/document.c will return a patch with the differences between revision 1.2 and 1.3 of document.c (-c = humen readable output)
- cvs annotate src/document.c shows a complete annotation of every patch and it's comments for this file

### CVS - guidelines

Antti-Juhani wrote:

- Committing to the trunk is always allowed, as long as you don't break the build. If you add significant new features, discuss it first on the mailing list. The trunk is the "unstable" series. The trunk is what you get using

      cvs checkout

- When we want to freeze for release, a "frozen" branch is created (with the name, say, rel_0_5_branch for the 0.5 frozen release). Committing to the frozen branch is allowed only if:
  - you don't break the build
  - you add no new features
  - your commit is necessary for the upcoming release (bug fixes, po updates etc)
  You get this using

      cvs checkout -r branch_name

- When a frozen branch is ready to release, the most recent set of files in the frozen branch is tagged as, say, "rel_0_5" (for the 0.5 release). The branch is declared "stable". Tarballs and debs and rpms are made. No commits are allowed in a stable branch. After the release, the stable branch is merged with the trunk.

This three-stage release plan, modeled after the Debian release cycle, allows for unstable developments in parallel with release preparation.

To create a branch:

    cvs tag -b name_of_branch

Note that the tree where you did the cvs tag is still the trunk, not the branch. You need then to check out a new copy from the branch:

    cd somewhere_else
    cvs checkout -r name_of_branch

Committing to this working copy commits to the branch, and the trunk is left untouched. Other people can access the branch by doing the same

    cvs checkout -r.

When you want to merge your changes to the trunk, do

    cvs update -j name_of_branch

in the old tree (the trunk). Fix any conflicts and commit.

### Translations

Roland Steinbach (roland@ratisbona.com)wrote:
if you would start lets say the greek translation (gr) you would have to:

- copy bluefish.pot to gr.po
- the msgid-lines have the text to translate, the msgtxt-lines hold the translation
- send the .po-file to me or to the list

in future version if you need to update the .po-file you have to:

- look for lines containing the word "fuzzy" (except for line 6, here it is right). These are raw guesses of translations, delete the line containig "fuzzy" and correct the translation
- look for lines without translations (search for 'msgtxt ""') and translate them.

that's it!

### Some tips

- if you want to add a property, add it to Tproperty (in bluefish.h) and set the initialisation line in main_v_props_init() in init.c, that will do. If you want it in the GUI you have to edit configure.c, this should be a line in configure_cb() and a line in apply_config(). Could be more lines for more advanced properties.
- gtk_easy.c contains a lot of easy-to-use gtk functions for creating dialogs and setting a lot of variables
- The macro DEBUG_MSG() works like the printf() function, if #define DEBUG is in the top of the file, or --with-debug is used with ./configure, else it will be removed by the preprocessor.

### Releases

Things to do when releasing:

- remove #define DEVELOPMENT from default_header.h
- comment the include .depends from the Makefile (is broken on HP-UX)
- use cvs export

... I gotta finish this

### Useful links

- glib reference, check the string utility functions and double linked lists
- gdk reference, fonts and colormaps
- gtk reference, the rest, all widgets, callback prototypes etc.
- C preprocessor
- autoconf/automake, or the GNU configure build system
- Programming in C, a very good tutorial
- CVS book, a good book on CVS usage
- cvs2cl, CVS-ChangeLog generator

prev | contents | next