-- REALLY-QUICK START -------------------------------------------------- If you're in a desperate hurry type: ./configure --enable-drivers=all make And if you start wondering why it doesn't work, come back and read the rest of the file. 8) -- PREREQUISITES ----------------------------------------------------- First read the README if you haven't already. In order to compile LCDproc, you'll need: an ANSI C compiler, we recommend GCC. Most Linux or BSD systems come with GCC. GNU Make. It is available for all major distributions. If you want to compile it yourself, see http://www.gnu.org/software/make/make.html . The GNU autotools, that is automake and autoconf. It is available for all major distributions. If you want to compile it yourself, see http://sources.redhat.com/automake/ and http://sources.redhat.com/autoconf/ . LCDproc is in fact two things, a client (lcdproc) and a server (LCDd). The client gathers informations and sends them to the server. The server displays the informations on an LCD display. The client and the server use a TCP connection to communicate, so it is possible to have a client on a box in Sweden showing its stats on a LCD display in the United States. -- DISPLAYS ----------------------------------------------------------- Many different displays (or better said: output devices) are supported. Some of these devices also support input, for example with a keypad. There are drivers for input-only devices too. For LCDd (the server) to use the device, it needs to load a driver. The drivers are so called 'shared modules', that usually have an extension of .so . The drivers to be loaded should be specified in the config file (by one or more Driver= lines), or on the command line. The command line should only be used to override things in the config file. The drivers should be in a directory that is indicated by the DriverPath= line in the configfile. Depending on what kind of LCD display that you have, there are several sources for informations. If your LCD display came with a manual, this is a great place to start. If you don't have a manual, then you must find out what kind of display this is, and check the related informations: HD44780 and compatible: read docs/hd44780-howto.txt or alternatively see http://www.robijn.net/lcdproc/ STV5730: http://www.adams-online.de/lcd/ SED1520: http://www.adams-online.de/lcd/ Also take a look at the comments in the driver source code in server/drivers. You may have some good indications there. You may want to take a look at LCDproc's hardware page at http://lcdproc.omnipotent.net/hardware.php3 for details. Several different types of displays are now supported. -- BUILDING LCDPROC ------------------------------------------------- --- Configuration --- The simplest way of doing it is with: ./configure But it may not do what you want, so please take a few seconds to type: ./configure --help And read the available options, especially --enable-drivers --- Compilation --- Run make to build the server and all clients make If you only want to compile the clients, you can omit to compile the server: cd shared make cd ../clients make Similarly, if you only want to compile the server, you can omit to compile the clients: cd shared make cd ../server make Depending on your system, LCDproc will build in a few seconds to a few minutes. It's not very big. If you want, you can install it (if you're root) by typing: make install This will install the binaries and the man pages in the directory you specified in configure. -- PLATFORM SPECIFIC ------------------------------------------------ The lcdproc crew has tried to support a number of platforms. Platforms that are very non-standard are not and will probably never be supported. Both server & drivers and clients have their own difficulties in porting. Here's are the prerequistes for both: --- Client --- The client should run on any POSIX compliant system. It has been sucessfully tested on: Linux 2.2.x, Linux 2.4.x, NetBSD 1.5, OpenBSD 3.0 In the future want it to run on Windows, MacOS and others. --- Server --- The server needs to talk with the LCD display. At this time, it works on very little more than on the Intel i386 (PC Compatible) architecture. It has been sucessfully tested on: Linux 2.2.x, Linux 2.4.x, NetBSD 1.5, OpenBSD 3.0 Here are some comments specific to each platform that LCDproc has been tested on. --- Linux --- Nothing special to say, everything should go well. You may not be able to compile all drivers on something else than i386 if your linux installation does not have ioperm, inb and outb commands. I heared that some Alpha do that. You can leave all parallel port drivers out and it should compile again. --- NetBSD --- You need to use GUN Make instead of NetBSD's make. Remember to type gmake instead of make to compile LCDproc. The server will probably only compile on NetBSD/i386. If you try to run LCDd and you get this error: Bus error (core dumped) It is likely that you did not have the right permission to access the ports. Try starting the program as root. --- OpenBSD --- You need to use GUN Make instead of OpenBSD's make. Remember to type gmake instead of make to compile LCDproc. The server will probably only compile on NetBSD/i386. --- FreeBSD --- It will compile fine on i386. --- Other platforms --- If the build process fails, but you do know how to link a loadable module by hand, you can add the appropriate flags etcetera into acinclude.m4. Experience required. Please let us know if you got it working on a previously unsupported system, so we can include it in a next release. -- RUNNING LCDPROC ----------------------------------------------------- --- Configuration file --- The first thing that you need to do is to modify the configuration file for your server. A example file (LCDd.conf) is available in the tarball. The comments present in this file should give you indications on what to do. --- Starting the server --- If you're in the LCDproc source directory, and have just built it, run: server/LCDd -c path/to/config/file For some extra options useful while testing things, try "LCDd -h". For security reasons, LCDd only accept connections from the localhost, it will not accept connections from other computers on the Internet. You can change this behavior in the configuration file. --- Starting the client(s) --- Then, you'll need some clients. LCDproc comes with a few, of which the 'lcdproc' client is the main client: clients/lcdproc/lcdproc C M T X & This will run the LCDproc client, with the [C]pu, [M]emory, [T]ime, and [X]load screens. The ampersand (&) puts it in the background. By default, the client tries to connect to a server located on localhost and listening to port 13666. To change this, use the -s and -p options. -- PUTTING LCDPROC IN SYSTEM STARTUP ----------------------------------- It's nice to have LCDproc start when the computer boots, so here's how to do it: In Slackware or RedHat: Add lines to your /etc/rc.d/rc.local, such as the following: echo "Starting LCDproc..." /usr/local/bin/lcdproc C M X & In Debian: - Make a file "/etc/init.d/lcd" which works the same as the other scripts in that directory. (it should accept "start" and "stop" as parameters...) - To start, run "LCDd" with any necessary parameters. If possible it will put itself in the background as a daemon. - Also in the "start" section, add "lcdproc" with some parameters. Be sure to put a "&" on the end, or the system will get stuck there when you boot. - And, put in any other clients you want to run all the time. - For the "stop" section, simply "kill" all the programs you started in the "start" section. They will shut down and exit. I recommend killing the server after all the clients, but it really doesn't matter much. - Run (as root): update-rc.d lcd defaults This will create symlinks to start and stop the daemon, resp. from /etc/rc[2-5].d/S50lcd to /etc/init.d/lcd, and from /etc/rc[016].d/K50lcd to /etc/init.d/lcd. That's all the distributions we've actually done this with so far.. -- WEB SITE ------------------------------------------------------------ Visit http://lcdproc.omnipotent.net/ for the latest updates and news for LCDproc. If you've got comments, suggestions, bug fixes, or problems (related to LCDproc, not women ;), send e-mail to either William W. Ferrell (willfe@yahoo.com) or Scott Scriven (toykeeper@cheerful.com).