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
16 To compile GNU Midnight commander from GIT, the following software is
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
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
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
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:
78 /usr/local/src/mc/configure && make all
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
90 --format-first-column-comments
95 --blank-lines-after-procedures
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
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
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
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.
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
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
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
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.
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
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.
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.
247 widget1 <---------> widget2 <---------> widget3
249 -----------------------------------------
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
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.
307 (This list should be sorted alphabetically.)
309 ?: This operator has a precedence that is easy to use the wrong way. You
312 int right = 25 + have_frame() ? 1 : 0; /* WRONG */
314 results in either 25 or 26. This is not the case. The C compiler
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
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.
338 if (old_dir) 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);
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,
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).
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)
388 This tells the GNU C Compiler not to emit a warning, and has no
389 side effects for other compilers.