Merge branch '2134_am_silent_rules'
[kaloumi3.git] / doc / HACKING
blobb09e518fbbc0129e8d62cbfc7d5bede20330b8e4
1 This document
2 =============
4 This document is a guide how to develop GNU Midnight Commander.  It's
5 quite incomplete, but may be worth reading anyway.
7 The document was written by Miguel de Icaza and reworked by Pavel
8 Roskin and later from Patrick Winnertz.
9  Some parts were taken from the messages posted in the mailing
10 lists.
13 Compiling from GIT
14 ==================
16 To compile GNU Midnight commander from GIT, the following software is
17 required:
19 Autoconf 2.52 and above (latest is recommended)
20 Automake 1.5 and above (latest is recommended)
21 Gettext 0.11.5 and above
22 Glib 2.8 and above (2.14 and higher is recommended)
24 Full list of requirements you can see at:
25 http://www.midnight-commander.org/wiki/doc/buildAndInstall/req
27 It is recommended that all those tools are installed with the same
28 prefix.  Make sure that the tools with the right version are first in
29 PATH.
31 Once you have the right tools, run `autogen.sh' - it will generate
32 everything necessary for the build `configure'. Then run 'configure'
33 and `make' as usually.
35 The distribution tarball is created by the command `make distcheck'. 
36 This command can take a while.
38 Currently snapshots are made on Debian unstable and use the versions of
39 the tools from the unstable repository.  Yes, the rpm packages are made
40 on Debian too.
42 Note that the version of gettext doesn't affect the snapshot because the
43 distributed files are installed by gettext from archives for the version
44 used in the AM_GNU_GETTEXT_VERSION macro, which is 0.11.5.
48 Working with GNU Midnight Commander
49 ===================================
51 Please use the GIT version.  It may be quite different from the released
52 versions.  A lot of cleanup is going on.  The GIT version may be easier
53 to understand, in addition to the obvious fact that the merging is
54 easier with the GIT version.
56 In order to compile GNU Midnight Commander from a clean GIT checkout you
57 should use 'autogen.sh && ./configure' instead of 'configure'.
59 GNU Midnight Commander uses Autoconf and Automake, with make it fairly
60 portable.  However, GNU Make is strongly recommended for development
61 because other versions of make may not track dependencies properly. 
62 This is very important for correct compilation, especially if you change
63 any header files.
65 If you add or remove any files, please change Makefile.am in the same
66 directory accordingly.  When doing significant changes in the tree
67 structure, "make distcheck" is strongly recommended.
69 GNU Autoconf allows you to test several different configurations are
70 once.  To do so, use the so called out-of-tree (or VPATH) compilation. 
71 Create separate empty directories and run configure with full path from
72 those directories, like this:
74 cd /usr/local/src
75 mkdir mc-slang
76 mkdir mc-ncurses
77 cd mc-slang
78 /usr/local/src/mc/configure && make all
79 cd ../mc-ncurses
80 /usr/local/src/mc/configure --with-screen=ncurses && make all
82 Please use the same indentation as other developers.  To indent a block,
83 select in the internal editor and use Shift-F9 to call the external
84 indent.  For historic reasons, GNU Midnight Commander used formatting
85 that is not default for GNU Indent.  Please put following text to your
86 ~/.indent.pro file to make GNU Indent follow the style used in GNU
87 Midnight Commander:
89 --gnu-style
90 --format-first-column-comments
91 --indent-level4
92 --brace-indent0
93 --line-length100
94 --no-tabs
95 --blank-lines-after-procedures
97 or in short notation:
99 indent -gnu -fc1 -i4 -bli0 -nut -bap -l100
101 It's OK to indent the whole function if you edit it.  However, please
102 refrain from it if you are posting your patch for review.  In this case
103 you would save time of other developers if you only include significant
104 changes.  The developer applying your patch can format the code for you.
106 Please keep in mind that the VFS subsystem is licensed under LGPL, while
107 the rest of the code uses GPL.
110 Code structure - outline
111 ========================
113 The code is located in following directories.
115 vfs - Virtual File System.
117 This library provides filesystem-like access to various data, such are
118 archives and remote filesystems.  To use VFS, you should use wrappers
119 around POSIX calls.  The wrappers have names composed from "mc_" and the
120 standard name of the function.  For example, to open a file on VFS, use
121 mc_open() instead.
123 edit - the internal editor.
125 This code has been contributed by Paul Sheer, the author of Cooledit.
126 The internal editor shares some code with Cooledit, but now it's
127 developed as part of GNU Midnight Commander.
129 src - the main part of the code.
131 This code includes the dialog manager written by Radek Doulik and source
132 code of the main application.
134 Code structure - details
135 ========================
137 GNU Midnight Commander uses extensively the dialog manager written by
138 Radek Doulik.  To understand how the dialog manager works, please read
139 the dialog.c.  You will find the basic widgets in the files widget.c.
140 Some more high-level functions, e.g. to display a message box, are
141 located in wtools.c.  This file also contains the Quick Dialog code,
142 which makes it easier to create complex dialogs.
144 The files util.c and utilunix.c have a lot of utility functions.  Get
145 familiar with them, they are very simple.
147 glib is used for memory allocation and for some utility functions, such
148 as manipulation with lists and trees.  gmodule (part of the glib
149 distribution) is used to load some libraries dynamically at the run
150 time.
152 Thanks to glib, the code has almost no hardcoded limits, since there are
153 many ways to avoid them.  For example, when you want to concatenate
154 strings, use the g_strconcat() function:
156         new_text = g_strconcat (username, " ", password, (char *)0);
158 This allocates new memory for the string, so you should use g_free() on
159 the result.
161 The parent of all dialogs is called midnight_dlg.  Both panels are
162 widgets in that dialog.  Other widgets include the menu, the command
163 line and the button bar.
166 Input handling
167 ==============
169 The routines for input handling on the Midnight Commander are:
170 getch, get_key_code, mi_getch and get_event.
172 getch is an interface to the low level system input mechanism.  It
173 does not deal with the mouse.  
175     In the case of ncurses, this is a function implemented in the
176     ncurses library that translates key sequences to key codes (\E[A to
177     something like KEY_UP and so on).
179     In the case of S-Lang there is no such conversion, that's why we
180     load a set of extra definitions.
182 The get_key_code routine converts the data from getch to the
183 constants the Midnight Commander uses.
185     In the case of S-Lang, it will actually do all the jobs that getch
186     does for curses.  In the case of curses it patches a couple of
187     sequences that are not available on some terminal databases.  This
188     routine is the one you want to use if you want a character without
189     the mouse support.
191 get_event is the routine you want to use if you want to handle mouse
192 events, it will return 0 on a mouse event, -1 if no input is available
193 or a key code if there is some input available.  This routine in turn
194 uses get_key_code to decode the input stream and convert it to useful
195 constants.
197 mi_getch is just a wrapper around get_event that ignores all the mouse
198 events.  It's used only in a couple of places, this routine may return
199 -1 if no input is available (if you have set the nodelay option of
200 ncurses or S-Lang with nodelay) or a character code if no such option is
201 available. 
204 Mouse support
205 =============
207 The mouse support in the Midnight Commander is based on the get_event
208 routine.  The core of the mouse event dispatching is in the
209 dlg.c:run_dlg routine.
212 ncurses
213 =======
215 Although S-Lang is now used by default, we still support ncurses.  We
216 basically are using a small subset of ncurses because we want to be
217 compatible with Slang.
220 The Dialog manager and the Widgets
221 ==================================
223 The Dialog manager and the Widget structure are implemented in
224 src/dialog.c.  Everything shown on screen is a dialog.  Dialogs contain
225 widgets, but not everything on screen is a widget.  Dialogs can draw
226 themselves.
228 Dialogs are connected into a singly linked list using "parent" field. 
229 Currently active dialog is saved in current_dlg variable.  The toplevel
230 dialog has parent NULL.  Usually it's midnight_dlg.
232             parent                  parent
233 current_dlg ------->another dialog-- ... -->midnight_dlg
235 When the screen needs to be refreshed, every dialog asks its parent to
236 refresh first, and then refreshes itself.
238 A dialog is created by create_dlg().  Then it's populated by widgets
239 using add_widget().  Then the dialog is run by calling run_dlg(), which
240 returns the id of the button selected by the user.  Finally, the dialog
241 is destroyed by calling destroy_dlg().
243 Widgets are placed to a doubly linked circular list.  Each widget has
244 previous and next widget.
246         prev   next         prev   next
247 widget1 <---------> widget2 <---------> widget3
248    ^                                       ^
249    -----------------------------------------
250    next                                 prev
252 Pressing Tab moves focus to the "next" widget, pressing Shift-Tab moves
253 focus to "prev".  The tab order is equal to the add order except some
254 old code that use the reverse order by setting DLG_REVERSE flag in
255 create_dlg() call.  Please don't use reverse order in the new code.
257 The initial widget to get focus can be selected by calling
258 dlg_select_widget().
260 When creating a dialog, you may want to use a callback that would
261 intercept some dialog events.  However, many widgets will do the right
262 thing by default, so some dialogs can work just fine without callbacks.
264 There are also widget events, which are sent by the dialog to individual
265 widgets.  Some widgets also have user callbacks.
267 To create your own widget, use init_widget().  In this case, you must
268 provide a callback function.  Please note that it's not the same as the
269 user callback in some widgets.
272 Where to Find Bug Reports and Patches
273 =====================================
275 The official place for bug reports is:
277     http://www.midnight-commander.org/
280 There are various unofficial sources where bug reports and patches can
281 be found (NOT maintained by the MC team).
284 http://bugs.debian.org/mc
285         The bug tracking system for Debian, a package collection mainly
286         for GNU/Linux and the Hurd.
288 http://bugzilla.redhat.com/bugzilla/buglist.cgi?component=mc
289         Bugs reported in Redhat Linux.
291 http://www.openbsd.org/cgi-bin/cvsweb/ports/misc/mc/patches/
292         The patches that are applied for the OpenBSD version of MC.
294 http://www.freebsd.org/cgi/cvsweb.cgi/ports/misc/mc/files/
295         The patches that are applied for the FreeBSD version of MC.
297 http://cvsweb.netbsd.org/bsdweb.cgi/pkgsrc/sysutils/mc/patches/
298         The patches that are applied for the NetBSD version of MC.
300 http://www.gentoo.org/cgi-bin/viewcvs.cgi/app-misc/mc/files/?hideattic=1
301         The patches that are applied for the Gentoo Linux version of MC.
304 Programming Tips
305 ================
307 (This list should be sorted alphabetically.)
309 ?: This operator has a precedence that is easy to use the wrong way. You
310         might think that
312                 int right = 25 + have_frame() ? 1 : 0; /* WRONG */
314         results in either 25 or 26. This is not the case. The C compiler
315         sees this as:
317                 int right = (25 + have_frame()) ? 1 : 0; /* WRONG */
319         To avoid this, put the ?: in parentheses, like this
321                 int right = 25 + (have_frame() ? 1 : 0); /* RIGHT */
323         If the condition is more complicated, put it in additional
324         parentheses:
326                 int right = 25 + ((have_frame()) ? 1 : 0); /* RIGHT */
328 const: For every function taking a string argument, decide whether you
329         (as a user of the function) would expect that the string is modi-
330         fied by the function. If not, declare the string argument as
331         "const char *". If your implementation needs to modify the string,
332         use g_strdup to create a local copy.
334 const_cast: Has been replaced by str_unconst.
336 g_free: g_free handles NULL argument too, no need for the comparison.
337         Bad way:
338             if (old_dir) g_free (old_dir);
339         Right way:
340             g_free (old_dir);
342 g_strdup: When you use g_strdup to create a local copy of a string, use
343         the following pattern to keep the reference.
345         char * const pathref = g_strdup(argument);
346         /* ... */
347         g_free (pathref);
349         The "const" will make the pointer unmodifiable (pathref++
350         is not possible), but you can still modify the string contents.
352 NULL: When you pass NULL as an argument of a varargs function, cast the
353         0 to the appropriate data type. If a system #defines NULL to
354         be 0 (at least NetBSD and OpenBSD do), and the sizes of int and
355         a pointer are different, the argument will be passed as int 0,
356         not as a pointer.
358         This tip applies at least to catstrs (edit/edit.h), execl(3),
359         execle(3), execlp(3), g_strconcat (glib), parent_call
360         (src/background.h), parent_call_string (src/background.h),
361         rpc_get (vfs/mcfsutil.h), rpc_send (vfs/mcfsutil.h).
363         example:
364         char *path = g_strconcat("dir", "/", "file", (char *)0);
366 size_t: This data type is suitable for expressing sizes of memory or the
367         length of strings. This type is unsigned, so you need not check
368         if the value is >= 0.
370 strncpy: Don't use this function in newly created code. It is slow, insecure
371         and hard to use. A much better alternative is g_strlcpy (see there).
373 str_unconst: We use many libraries that do not know about "const char *"
374         and thus declare their functions to require "char *". If you
375         know for sure that an external function does not modify the
376         string, you can "unconst" a string using the function
377         str_unconst(). If you are not sure whether the function modifies
378         the string, you should use g_strdup() to pass a copy of a string
379         to the function. Don't forget to call g_free() after work is done.
381 unused: Unused arguments of a function can be marked like this:
383         void do_nothing(int data)
384         {
385             (void) &data;
386         }
388         This tells the GNU C Compiler not to emit a warning, and has no
389         side effects for other compilers.