HACKING 14 KB

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