4. fejezet: Fejlesztői segédlet

(egyelőre csak angolul)

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

This is currently the worst structured:

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!

CVS - guidelines

Antti-Juhani wrote:

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:

in future version if you need to update the .po-file you have to: that's it!

Some tips

Releases

Things to do when releasing:

... I gotta finish this

Useful links