Ticket #3763: introduce run_listbox_with_data().
[midnight-commander.git] / doc / INSTALL
blob8007c69c72f89f3340d1d3e68ed7a6456918901b
1 This file contains:
3 - Build requirements for GNU Midnight Commander
4 - Installation instructions for GNU Midnight Commander
5 - Where to get more information on GNU Midnight Commander
6 - Notes about GNU Midnight Commander installation
7 - Obtaining related software
9 Build requirements for GNU Midnight Commander
10 ----------------------------------------------------
12 - glibc
13 - gcc
14 - make
15 - autoconf
16 - automake
17 - libtool
18 - glib2
19 - pcre (if glib < 2.14)
20 - slang or ncurses
21 - gettext
22 - cvs (for gettext < 0.18 or if gettext >= 0.18 is built with --with-cvs)
23 - libssh2 >= 1.2.5 is required only for sftp vfs (1.2.7 if you need ssh-agent support)
24 - libaspell to support spell checking in the internal editor
27 Installation instructions for GNU Midnight Commander
28 ----------------------------------------------------
30 The `configure' shell script attempts to guess correct values for
31 various system-dependent variables used during compilation, and creates
32 the makefiles.  It also creates a file `config.status' that you can run
33 in the future to recreate the current configuration.
35 To compile this package:
37 1.  Configure the package for your system.
39 Normally, you just `cd' to the directory containing the package's source
40 code and type `./configure'.  If you're using `csh' on an old version of
41 SystemV, you might need to type `sh configure' instead to prevent `csh'
42 from trying to execute `configure' itself.  Under AIX, you may need to
43 use ksh instead of sh.
45 Running `configure' takes a while.  While it is running, it prints some
46 messages that tell what it is doing.  If you don't want to see any
47 messages, run `configure' with the `--quiet' option.
49 To compile the package in a different directory than the one containing
50 the source code, you must use a version of `make' supporting the `VPATH'
51 variable, such as GNU `make'.  Change to the directory where you want
52 the object files and executables to go and run the `configure' script
53 with the full path.  If for some reason `configure' cannot find the
54 source code directory, run `configure' with the option `--srcdir=DIR',
55 where DIR is the directory that contains the source code.
57 By default, `make install' will install the package's files in
58 `/usr/local/bin', `/usr/local/man', etc.  You can specify an
59 installation prefix other than `/usr/local' by giving `configure' the
60 option `--prefix=PATH'.
62 You can specify separate installation prefixes for architecture specific
63 files and architecture-independent files.  If you give `configure' the
64 option `--exec-prefix=PATH', the package will use PATH as the prefix for
65 installing binary programs and libraries.  Data files and documentation
66 will still use the regular prefix.  Normally, all files are installed
67 using the same prefix.
69 If compiled on GNU/Linux, Midnight Commander detects if you have the gpm
70 library installed.  If you installed the gpm mouse library in a
71 non-standard place, you will need to use the --with-gpm-mouse flag with
72 the directory base where you installed the gpm package.
74 `configure' recognizes the following options (the list may be
75 incomplete, use `configure --help' to get the full list):
77 `--help'
78      Print a summary of the options to `configure' and exit.
80 `--quiet'
81 `--silent'
82      Do not print messages saying which checks are being made.
84 `--version'
85      Print the version of Autoconf used to generate the `configure'
86      script, and exit.
88 `--without-edit'
89      Configure GNU Midnight Commander to be compiled without the
90      built-in file editor.  The built-in editor is compiled in by
91      default.
93 `--enable-aspell'
94      This option adds spell check support in the internal editor using
95      libaspell. Disabled by default.
97 `--without-gpm-mouse'
98      Use this flag to disable gpm mouse support (e.g. if you want to
99      use mouse only on X terminals).
101 `--with-glib-static'
102      Force linking against glib statically.  This option is intended for
103      building binaries for distribution purposes and may not work on
104      some operating systems.
106 `--with-mmap', `--without-mmap'
107      Force using or not using the mmap function.  It is currently used
108      in the internal viewer.  `--with-mmap' may be useful on some
109      versions of AIX where the `configure' script decides that mmap is
110      broken, but it's actually suitable for the internal viewer.
112 `--with-subshell[=optional]', `--without-subshell' 
113      The subshell support is by default turned on, you can disable
114      this by using the --without-subshell option.  If you pass the
115      =optional parameter, then the subshell support is turned off by
116      default.  To turn it on, specify the `-U' option to the program.
118 `--without-x'
119      By default, the Midnight Commander tries to connect to the X Window
120      System events to query the status of the keyboard modifiers, such
121      as Control, Shift and Alt, when invoked in a terminal emulator
122      under X11.  This is necessary (but not always sufficient) to
123      recognize some optional but handy key combinations like Ctrl-Home
124      and Shift-Cursor keys.  Use `--without-x' if the dependency on
125      X11 libraries is not desired.
127 `--disable-largefile'
128      This option disables support for large files (2 gigabytes and more)
129      on the systems where file operations use 32-bit offsets by default,
130      but support for 64-bit offsets is available.  May be useful for
131      slow processors and embedded systems.
133 `--enable-charset'
134      This option adds support for selecting character set of the text in
135      the internal viewer and editor and converting it on the fly.  The
136      implementation of this option is currently incomplete.
138 `--disable-background'
139      This option disables support for background operations.  Background
140      operations allow to perform some tasks such as copying files in a
141      separate background process.  Any messages from the background
142      process are forwarded to the foreground process.  More advanced
143      dialogs cannot be forwarded yet, so the background process uses the
144      default.  Background code is known to be less stable than the rest
145      of the code, so you may want to disable it at the compile time.
147 `--with-homedir'
148      This option allow users  to place user config directories in any
149      place. By default value is 'XDG', this mean, mc will respect XDG
150      standards. If other value is specified, this will used as directory
151      name (relative to $HOME if path is relative, or as is if path is
152      absolute).
154 VFS options:
155 - - - - - -
157 `--disable-vfs'
158      This option disables the Virtual File System switch code in the
159      Midnight Commander and uses the standard file system calls for
160      file access.  If you specify this option, you won't get the
161      transparent access to archives and remote directories.
163 `--enable-vfs-cpio'
164      (on by default)
165      Support for cpio filesystem
167 `--enable-vfs-tar'
168      (on by default)
169      Support for tar filesystem
171 `--enable-vfs-ftp'
172      (on by default)
173      Support for FTP vfs
175 `--enable-vfs-fish'
176      (on by default)
177      Support for FISH vfs
179 `--enable-vfs-sftp'
180      (auto)
181      Support for SFTP vfs
183 `--enable-vfs-extfs'
184      (on by default)
185      Support for extfs
187 `--enable-vfs-sfs`
188      (on by default)
189      Support for sfs
191 `--enable-vfs-undelfs'
192      (off by default)
193      Support for ext2 undelete filesystem.
194      On systems that use the ext2 or ext3 file system and have the
195      libext2fs library available, this option adds support for
196      recovering deleted files (the undel virtual file system).
198 `--enable-vfs-smb'
199      (off by default)
200      This option enables remote VFS over the SMB protocol.  A stripped
201      down version of samba distributed with the sources is compiled and
202      linked with the mc executable.  It is recommended that you install
203      Samba client, since mc uses some files from Samba under certain
204      conditions.  Please visit http://www.samba.org/ to learn more.
207 Screen library:
208 - - - - - - - -
210 You may also tell configure which screen library you want to use with
211 the Midnight Commander.  The configure script will use S-Lang as
212 default, and prefers an already installed S-Lang library over the
213 included one, but you can override this by using the following flag
214 (please note that since S-Lang is default, it is tested better than
215 ncurses):
217 `--with-screen={slang|ncurses}'
218      Choose the library used to manage interaction with the terminal.
219      `slang' means S-Lang library already installed on the system,
220      `ncurses' means ncurses library already installed on the system.
221      The S-Lang library is used by default if found.
223 `--with-slang-includes=[DIR]'
224      Set path to SLANG includes [default=/usr/include]; make sense
225      only if --with-screen=slang is used.
227 `--with-slang-libs=[DIR]'
228      Set path to SLANG library [default=/usr/lib]; mke sense only
229      if --with-screen=slang is used.
231 `--with-ncurses-includes=[DIR]'
232      Set path to ncurses includes [default=/usr/include]; make
233      sense only if --with-screen=ncurses is used;
234      for /usr/local/include/ncurses specify /usr/local/include.
236 `--with-ncurses-libs=[DIR]'
237      Set path to ncurses library [default=/usr/lib]; make sense
238      only if --with-screen=ncurses is used.
240 Compiler options:
241 - - - - - - - - -
243 On systems that require unusual options for compilation or linking that
244 the package's `configure' script does not know about, you can give
245 `configure' initial values for variables by placing them in the command
246 line:
248 ./configure CC='gcc -traditional' LIBS=-lposix
250 Here are the variables that you might want to override when running
251 `configure'.
253  - Variable: CC
254      C compiler program.  The default is `gcc' if found, otherwise `cc'.
256  - Variable: CFLAGS
257      The default flags used to build the program.
259  - Variable: INSTALL
260      Program to use to install files.  The default is `install' if you
261      have it, `cp' otherwise.
263 For these variables, any value given in the command line is added to the
264 value that `configure' decides to use:
266  - Variable: LIBS
267      Libraries to link with, in the form `-lfoo -lbar...'.
269  - Variable: LDFLAGS
270      Linker flags, e.g. -L<lib dir> if you have libraries in a
271      nonstandard directory <lib dir>
273  - Variable: CPPFLAGS
274      C/C++ preprocessor flags, e.g. -I<include dir> if you have
275      headers in a nonstandard directory <include dir>
277 If you need to do unusual things to compile the package, we encourage
278 you to figure out how `configure' could check whether to do them, and
279 mail diffs or instructions to the address given in the README so we can
280 include them in the next release.
282 2.  Type `make' to compile the package.
284 3.  Type `make install' to install programs, data files, and the
285 documentation.  On GNU/Linux the console screen saver is installed as
286 well.
288 4.  You can remove the program binaries and object files from the source
289 directory by typing `make clean'.  If you want to clean the source tree
290 completely, so that it contains only those files that should be packaged
291 in the archive, issue `make distclean'.  If you've run configure in a
292 different directory than the source tree, distclean won't remove your
293 *.o and linked programs in that directory.
295 5.  GNU Midnight Commander allows you to stay in the last current
296 directory after exiting MC.  This is done with a shell function, the man
297 page has more information about this.
299 The file `configure.in' is used to create `configure' by a program
300 called `autoconf'.  You only need it if you want to regenerate
301 `configure' using a newer version of `autoconf'.
304 Where to get more information on GNU Midnight Commander
305 -------------------------------------------------------
307 There are two mailing lists for the program:
309 mc@gnome.org:        Discussion on GNU Midnight Commander file manager.
310 mc-devel@gnome.org:  Discussion between the developers of the program.
312 To subscribe to the mailing lists, visit their respective pages:
314 http://mail.gnome.org/mailman/listinfo/mc/
315 http://mail.gnome.org/mailman/listinfo/mc-devel/
318 Notes about GNU Midnight Commander installation
319 -----------------------------------------------
321 GNU Midnight Commander has been run in the following configurations:
323 i386-*-linux
324 sparc-*-linux
325 alpha-*-linux
326 powerpc-*-linux
327 mips-dec-ultrix4.3
328 mips-dec-{open,net}bsd1.0
329 mips-sgi-irix5.2
330 mips-sgi-irix5.3
331 powerpc-ibm-aix5.3.0.0 (IBM XL C, IBM XL C/C++)
332 sparc-sun-sunos4.1
333 sparc-sun-netbsd1.0
334 sparc-sun-solaris2.3
335 hppa-hp-hpux9
336 hppa-hp-hpux7
337 m68k-apple-aux
338 mc88110-aviion-dgux5.4
339 i386-*-bsdi2
340 i386-*-freebsd4.3
341 i386-*-openbsd2.9
343 Midnight Commander is written in a portable manner and uses GNU Autoconf
344 for configuration, so it is expected to compile without changes on many
345 other operating systems.
347 You will need an ANSI C Compiler (such as GCC) and glib library to
348 compile the source.  GNU Midnight Commander now comes with the S-Lang
349 screen manager, a fast screen manager, but you may want to use the
350 already installed S-Lang or ncurses library.
352 If you insist on using ncurses, it's recommended to use ncurses 4.1 and
353 above, since the older versions don't support resizing in the xterm
354 window.
356 GNU Midnight Commander comes with the mouse support on xterms and in the
357 Linux console.  In order to take advantage of the mouse support on the
358 Linux console you will need the gpm mouse server (see the section
359 "Obtaining related software" in this file).
361 Once you get gpm, compile it and install it, then you will have to
362 specify the `--with-gpm-mouse' flag to the configure program if you
363 installed it in a non-standard directory.  If you installed the gpm
364 package under /usr or /usr/local, you don't need to specify this flag;
365 configure will find gpm for you.  The support for mice on xterms is
366 always compiled in.
368 We are working on further enhancements to the program, but we're not
369 sure which ones must go first.  If you would like to point us in the
370 Right Direction we will be glad to hear from you.
372 If you happen to find a feature that doesn't do what you expect, please
373 write to mc@gnome.org telling as much as you can about the problem
374 you're experiencing.  Please don't send personal messages to the
375 maintainers.
378 Obtaining related software
379 --------------------------
381 glib
382 ----
384 The only "hard" dependency of GNU Midnight Commander is glib.  You can
385 get glib from
387 ftp://ftp.gnome.org/pub/gnome/sources/glib/
389 Minimal version of glib: 2.26.x
390 Recommended version: 2.26.x and higher.
392 Newer versions may work, but haven't been tested.
394 PCRE
395 ----
397 If the version of glib you have installed is older than 2.14.x, then you
398 also need to install PCRE library.
400 You can get PCRE from
402 http://www.pcre.org/
404 Terminal database
405 -----------------
407 There are many incomplete terminal databases out there, however, a
408 complete terminfo is bundled with ncurses.  (It is simple to generate
409 the termcap database using the infocmp utility in ncurses).
411 Some terminfo data are included with the mc distribution (lib/*.ti).
412 Particularly linux, xterm and vt100. Use e.g. ''tic linux.ti'' to use
413 them.
415 If you want to run mc on xterm/color_xterm/ansi_xterm (not rxvt), then
416 you might read lib/README.xterm for further information.
418 Screen libraries
419 ----------------
421 GNU Midnight Commander can use the included version of S-Lang, but you
422 can get the latest version here:
424 http://www.s-lang.org/
426 Alternatively, you can use ncurses:
428 http://www.gnu.org/software/ncurses/ncurses.html
430 Mouse support
431 -------------
433 The general purpose mouse (gpm) daemon is available from
435 http://unix.schottelius.org/gpm/
437 Compiler
438 --------
440 If your C compiler is not powerful enough to compile GNU Midnight
441 Commander, you should report is as a bug to the GNU Midnight Commander
442 team.  Sometimes there is no solution than upgrading to a modern and
443 free compiler - GCC (Compiler Collection):
445 http://gcc.gnu.org/
449 Currently you can not use gcc 4.2.4 (and probably other versions) on
450 AIX to compile the S-Lang version. Please use IBM XL C or IBM XL C/C++
451 instead.
453 If you compile a ncurses version you need to set TERM=dtterm to get
454 working color support. Furthermore it is important to specify the
455 --with-ncurses-includes/--with-ncurses-lib parameters because otherwise
456 mc will pick up term.h from AIX which does not work with the ncurses
457 library.
459 The AIX S-Lang build was tested with S-Lang 2.0.7. Later versions may
460 also work but are not tested yet.
462 Here is an example for S-Lang, it is assumed that the S-Lang library
463 is installed under /user/local and that you also want want to install
464 to /usr/local:
466   export CC=cc_r
467   export CXX=xlC_r
468   export CONFIG_SHELL=/usr/bin/bash (if installed)
469   export SHELL=/usr/bin/bash        (if installed)
471   ./configure \
472      --prefix=/usr/local \
473      --with-screen=slang \
474      --with-slang-includes=/usr/local/include \
475      --with-slang-libs=/usr/local/lib