123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277 |
- This document
- =============
- This document is a guide how to develop GNU Midnight Commander. It's
- quite incomplete, but may be worth reading anyway.
- The document was written by Miguel de Icaza and reworked by Pavel
- Roskin. Some parts were taken from the messages posted in the mailing
- lists.
- Compiling from CVS
- ==================
- To compile GNU Midnight commander from CVS, the following software is
- required:
- Autoconf 2.52 and above (latest is recommended)
- Automake 1.5 and above (latest is recommended)
- Gettext 0.11.5 and above
- Glib 1.2.6 and above (2.x is recommended)
- It is recommended that all those tools are installed with the same
- prefix. Make sure that the tools with the right version are first in
- PATH.
- Once you have the right tools, run `autogen.sh' - it will generate
- everything necessary for the build and run `configure'. Arguments given
- to `autogen.sh' are passed to `configure'. Then run `make' as usually.
- The distribution tarball is created by the command `make distcheck'.
- This command can take a while.
- Currently snapshots are made on Debian unstable and use the versions of
- the tools from the unstable repository. Yes, the rpm packages are made
- on Debian too.
- Note that the version of gettext doesn't affect the snapshot because the
- distributed files are installed by gettext from archives for the version
- used in the AM_GNU_GETTEXT_VERSION macro, which is 0.11.5.
- Working with GNU Midnight Commander
- ===================================
- Please use the CVS version. It may be quite different from the released
- versions. A lot of cleanup is going on. The CVS version may be easier
- to understand, in addition to the obvious fact that the merging is
- easier with the CVS version.
- There are some tools in the maint directory on CVS. They are not
- included with releases or snapshots. You may be interested to look at
- them if you are going to work on the project for an extended period of
- time. In particular, the release procedure is described there.
- In order to compile GNU Midnight Commander from a clean CVS checkout you
- should use autogen.sh instead of configure. Arguments passed to
- autogen.sh are passed to configure after it's generated.
- GNU Midnight Commander uses Autoconf and Automake, with make it fairly
- portable. However, GNU Make is strongly recommended for development
- because other versions of make may not track dependencies properly.
- This is very important for correct compilation, especially if you change
- any header files.
- If you add or remove any files, please change Makefile.am in the same
- directory accordingly. When doing significant changes in the tree
- structure, "make distcheck" is strongly recommended.
- If you have etags installed, you can run "make tags" and use tags in
- emacs to find functions or variables. But you can also use the internal
- editor and the "Find File" command to find any text in the source tree.
- GNU Autoconf allows you to test several different configurations are
- once. To do so, use the so called out-of-tree (or VPATH) compilation.
- Create separate empty directories and run configure with full path from
- those directories, like this:
- cd /usr/local/src
- mkdir mc-slang
- mkdir mc-ncurses
- cd mc-slang
- /usr/local/src/mc/configure && make all
- cd ../mc-ncurses
- /usr/local/src/mc/configure --with-screen=ncurses && make all
- Please use the same indentation as other developers. To indent a block,
- select in the internal editor and use Shift-F9 to call the external
- indent. For historic reasons, GNU Midnight Commander used formatting
- that is not default for GNU Indent. Please put following text to your
- ~/.indent.pro file to make GNU Indent follow the style used in GNU
- Midnight Commander:
- -kr -i4 -pcs -psl --ignore-newlines
- It's OK to indent the whole function if you edit it. However, please
- refrain from it if you are posting your patch for review. In this case
- you would save time of other developers if you only include significant
- changes. The developer applying your patch can format the code for you.
- Please keep in mind that the VFS subsystem is licensed under LGPL, while
- the rest of the code uses GPL.
- Code structure - outline
- ========================
- The code is located in following directories.
- vfs - Virtual File System.
- This library provides filesystem-like access to various data, such are
- archives and remote filesystems. To use VFS, you should use wrappers
- around POSIX calls. The wrappers have names composed from "mc_" and the
- standard name of the function. For example, to open a file on VFS, use
- mc_open() instead.
- edit - the internal editor.
- This code has been contributed by Paul Sheer, the author of Cooledit.
- The internal editor shares some code with Cooledit, but now it's
- developed as part of GNU Midnight Commander.
- src - the main part of the code.
- This code includes the dialog manager written by Radek Doulik and source
- code of the main application.
- slang - stripped down S-Lang library.
- It's provided to allow compilation that don't have the S-Lang library
- with complete headers or the library is broken. Please avoid changing
- this code. If you do change it, please consider contributing your
- changes to the maintainers of S-Lang.
- Code structure - details
- ========================
- GNU Midnight Commander uses extensively the dialog manager written by
- Radek Doulik. To understand how the dialog manager works, please read
- the dialog.c. You will find the basic widgets in the files widget.c.
- Some more high-level functions, e.g. to display a message box, are
- located in wtools.c. This file also contains the Quick Dialog code,
- which makes it easier to create complex dialogs.
- Files findme.c, popt.c, poptconfig.c, popthelp.c and poptparse.c come
- from the popt library used to parse the command line. They should not
- be modified unless absolutely necessary.
- The files util.c and utilunix.c have a lot of utility functions. Get
- familiar with them, they are very simple.
- glib is used for memory allocation and for some utility functions, such
- as manipulation with lists and trees. gmodule (part of the glib
- distribution) is used to load some libraries dynamically at the run
- time.
- Thanks to glib, the code has almost no hardcoded limits, since there are
- many ways to avoid them. For example, when you want to concatenate
- strings, use the g_strconcat() function:
- new_text = g_strconcat (username, " ", password, NULL);
- This allocates new memory for the string, so you should use g_free() on
- the result.
- The parent of all dialogs is called midnight_dlg. Both panels are
- widgets in that dialog. Other widgets include the menu, the command
- line and the button bar.
- Input handling
- ==============
- The routines for input handling on the Midnight Commander are:
- getch, get_key_code, mi_getch and get_event.
- getch is an interface to the low level system input mechanism. It
- does not deal with the mouse.
- In the case of ncurses, this is a function implemented in the
- ncurses library that translates key sequences to key codes (\E[A to
- something like KEY_UP and so on).
- In the case of S-Lang there is no such conversion, that's why we
- load a set of extra definitions.
- The get_key_code routine converts the data from getch to the
- constants the Midnight Commander uses.
- In the case of S-Lang, it will actually do all the jobs that getch
- does for curses. In the case of curses it patches a couple of
- sequences that are not available on some terminal databases. This
- routine is the one you want to use if you want a character without
- the mouse support.
- get_event is the routine you want to use if you want to handle mouse
- events, it will return 0 on a mouse event, -1 if no input is available
- or a key code if there is some input available. This routine in turn
- uses get_key_code to decode the input stream and convert it to useful
- constants.
- mi_getch is just a wrapper around get_event that ignores all the mouse
- events. It's used only in a couple of places, this routine may return
- -1 if no input is available (if you have set the nodelay option of
- ncurses or S-Lang with nodelay) or a character code if no such option is
- available.
- Mouse support
- =============
- The mouse support in the Midnight Commander is based on the get_event
- routine. The core of the mouse event dispatching is in the
- dlg.c:run_dlg routine.
- ncurses
- =======
- Although S-Lang is now used by default, we still support ncurses. We
- basically are using a small subset of ncurses because we want to be
- compatible with Slang.
- The Dialog manager and the Widgets
- ==================================
- The Dialog manager and the Widget structure are implemented in
- src/dialog.c. Everything shown on screen is a dialog. Dialogs contain
- widgets, but not everything on screen is a widget. Dialogs can draw
- themselves.
- Dialogs are connected into a singly linked list using "parent" field.
- Currently active dialog is saved in current_dlg variable. The toplevel
- dialog has parent NULL. Usually it's midnight_dlg.
- parent parent
- current_dlg ------->another dialog-- ... -->midnight_dlg
- When the screen needs to be refreshed, every dialog asks its parent to
- refresh first, and then refreshes itself.
- A dialog is created by create_dlg(). Then it's populated by widgets
- using add_widget(). Then the dialog is run by calling run_dlg(), which
- returns the id of the button selected by the user. Finally, the dialog
- is destroyed by calling destroy_dlg().
- Widgets are placed to a doubly linked circular list. Each widget has
- previous and next widget.
- prev next prev next
- widget1 <---------> widget2 <---------> widget3
- ^ ^
- -----------------------------------------
- next prev
- Pressing Tab moves focus to the "next" widget, pressing Shift-Tab moves
- focus to "prev". The tab order is equal to the add order except some
- old code that use the reverse order by setting DLG_REVERSE flag in
- create_dlg() call. Please don't use reverse order in the new code.
- The initial widget to get focus can be selected by calling
- dlg_select_widget().
- When creating a dialog, you may want to use a callback that would
- intercept some dialog events. However, many widgets will do the right
- thing by default, so some dialogs can work just fine without callbacks.
- There are also widget events, which are sent by the dialog to individual
- widgets. Some widgets also have user callbacks.
- To create your own widget, use init_widget(). In this case, you must
- provide a callback function. Please note that it's not the same as the
- user callback in some widgets.
|