     ______   ___    ___
    /\  _  \ /\_ \  /\_ \
    \ \ \L\ \\//\ \ \//\ \      __     __   _ __   ___ 
     \ \  __ \ \ \ \  \ \ \   /'__`\ /'_ `\/\`'__\/ __`\
      \ \ \/\ \ \_\ \_ \_\ \_/\  __//\ \L\ \ \ \//\ \L\ \
       \ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
	\/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
				       /\____/
				       \_/__/


		 Linux-specific information.

	 See readme.txt for a more general overview.

   Also see docs/build/unix.txt for general Unix information.



=======================================
============ General notes ============
=======================================

   On Linux you have two different system drivers -- one for running using 
   X, and one for running without X. For information on the X version, and 
   instructions telling how to install Allegro and compile your programs on 
   a Unix system, see docs/build/unix.txt. This file only describes the
   Linux console routines.

   Normally the X version is used in preference to the console version, if 
   an X server is contactable (this means that your programs will use X if 
   you launch them from inside X, and otherwise use the console). You can 
   change this using your config file if you like, or by configuring 
   --without-x.



============================================
============ Installing Allegro ============
============================================

   See docs/build/unix.txt: this process is identical for the console and X
   versions.



=======================================
============ Using Allegro ============
=======================================

   Some parts of Linux console Allegro need root privileges. Others don't. 
   Specifically, the VGA, mode-X and VBE/AF graphics drivers do. The fbcon 
   driver doesn't. Also, if you intend to run a program from something which 
   isn't a VT (e.g. an xterm (but not using the X version), a remote login, 
   a screen session) then you need to either own a (free) console numbered 
   from 1 to 15 or to have root privileges.

   If you want a program to run with privileges even though the user running 
   it is not root, make root own the binary and set the suid bit:

       # chown root.allegro exhello
       # chmod 4770 exhello

   That makes the executable be owned by root and group `allegro'. It's 
   readable, writable and executable by root and people in that group. Also, 
   when it runs, it has root privileges. For that reason, it's not 
   executable by the general public. Put trusted users into group `allegro'.

   You might prefer to use `4750' instead of `4770' -- then people in the 
   group cannot write to the binary.

   Allegro will drop the privileges almost immediately after initialisation, 
   using `seteuid'. This means that you can still get the permissions back 
   later on. Allegro needs to be able to regain the privileges if you intend 
   to call `allegro_init' again in the future. If this isn't the case, you 
   can completely give up the privileges using `setuid(getuid());' -- then 
   they are lost for good.

   Security note: If you don't do this, any buffer overflows are a severe 
   security problem. In any case, you should take great care when allowing 
   random people to execute third-party programs suid root.

   If, as root, you run `make suid', it will do this to all of the programs 
   generated -- the demo game, the examples, the tests, etc.



==========================================
============ Notes on drivers ============
==========================================

   This section contains Linux-specific notes on the drivers available.

   * System:
	On initialisation, Allegro will try to get a certain amount of 
	control over the console. This doesn't generally require root 
	privileges, but if the program isn't being run from a plain VC (e.g. 
	it's running from within X or screen), Allegro must try to allocate 
	a spare VC and move the program to it. This requires a free console 
	we can read from and write to; unless the user has allocated some, 
	we need to be root here.

	Display switching is possible; all of Allegro's modes are supported. 
	The default is SWITCH_PAUSE. SWITCH_BACKGROUND will only work if the 
	application takes special precautions.

   * Graphics:
	Linux Allegro supports standard VGA and mode-X by direct writes to 
	the video card. You need root privileges for this to work.

	It also supports fbcon, for which you do not need privileges, but 
	you do need a recent kernel, correctly configured.

	The VBE/AF system does require root privileges. You also need to get 
	a VBE/AF driver that works in Linux -- the FreeBE/AF project has two 
	at present, but the project itself hasn't been ported to Linux. You 
	can just copy out the driver binaries, though. Put the appropriate 
	driver into `/usr/local/lib', `/usr/lib', `/lib' or `/', filename 
	`vbeaf.drv' -- or put it anywhere you like, specifying the location 
	in the config file as for the DOS version.

	For security reasons, the VBE/AF driver binary must be owned by root
	and only writable by root. You really don't want to load and execute 
	user-specified binary code in a privileged program.

	The SVGAlib driver should be fairly stable and fast now, and can use
	most of the video modes that SVGAlib provides. It requires root
	privileges if your version of SVGAlib requires them.

   * Sound:
	The ALSA drivers currently only support the older (stable) version
	of the ALSA API (0.5.x). The 0.9.x beta series are NOT supported yet.

   * Keyboard:
	The keyboard driver uses the kernel mapping tables to map scancodes 
	to character codes and key functions, so your keyboard mapping 
	should be fine without special configuration in the setup program.

   * Joystick:
	To compile Allegro with joystick support you must have a recent 
	(2.2.* or late 2.1.*) kernel, i.e. with kernel-based joystick 
	support. Look for /usr/src/linux/include/linux/joystick.h. You 
	shouldn't have to actually configure the kernel with joystick 
	support though, you just need that header file.

	Similarly, to run Allegro programs with joystick support you need a 
	recent kernel, and here you must have configured it into the kernel. 
	You also need to create the device file /dev/js0, if it's not 
	already there.

	See /usr/src/linux/Documentation/joystick.txt for details.

   * Mouse:
	Currently Linux Allegro supports PS/2 and Microsoft mice directly, 
	and other mouse types via GPM. To use GPM you must turn on its 
	`repeater' feature, where it copies all mouse activity to the FIFO 
	/dev/gpmdata. Edit your init scripts and add the `-R' option. The 
	GPM driver can also be used with native Mouse Systems mice by 
	changing the `mouse_device' variable in the config file.

	When using the PS/2 Intellimouse protocol, it is necessary to
	explicitly put the mouse into wheel mode, which requires Allegro
	to have write permissions to the device. As this only has to be
	done once (the mouse will remember its state unless you unplug
	it), an alternative to changing device file permissions is to
	initialise the mouse during boot up with GPM. To do this, edit
	your init scripts and use the `-t imps2 -m /dev/psaux' options for
	GPM. If you do not want GPM active, kill it with `gpm -k'.

