4. xearth - EG Package Installation

You have just blown the money for a holiday pony-trekking to Reykjavik, on a Linux box. You've just spent 2 weekends assembling it, you want results.

RedHat packages come with pre-configured Linux installations of many packages, but you want the authors original (more recent) version. Many authors ship binaries for impatient customers, many authors take pride in the fact that they don't have to.

If you have never installed a source package before, you have a simple chain of steps to follow. At any stage, the process could fail, requiring you to roll up your sleeves, and do some work.

Some developers have an exclusion clause - if you can't read a Makefile, you shouldn't be equipped with gcc. Others are less enlightened, and do the work for you. Often a makefile will need minor adjustment to suit you, and reading the Makefile often helps to understand the package.

I used to have an open-mind, until I hit a few huge packages with cranky Makefiles, and overnight compilations. I think those people must have come from a cobol background. Now I see the first make error message, as a warning of others to come. Often proved wrong (TM).

4.1 cmd - a useful utility
4.2 mk - a useful utility
4.3 xearth
4.4 Pre-requirements
4.5 xearth-1.0
4.6 Locating xearth on disk InfoMagic Disk set
4.7 cd /cdrom/X11/xapps/graphics/
4.8 mkdir /tmp/pkgs_cd
4.9 tar -C /tmp/pkgs_cd -zxf ./xearth-1.0.tgz
4.10 cd /tmp/pkgs_cd/xearth-1.0
4.11 xmkmf
4.12 make
4.13 make install ; make install.man
4.14 xearth -pos "fixed 62.4 -51.1" -grid &
4.15 man xearth
4.16 vi  /.xinitrc
4.17 delete xearth-1.0
4.18 Worked example - done!
4.19 configure
4.20 configure --prefix=/usr/local
4.21 make linux
4.22 package_elf-01.tgz
4.23 old_lib.so

4.1

cmd - a useful utility

This is a new command to create (locate) commands. Use SELECT+PASTE to copy it to a file (via an editor such as xedit), and chmod 755 it.

	#!/bin/sh
	# cmd
	# set -x
	#	# FILE=$HOME/bin/$1 # if you prefer
	#
	if LINE=`type $1`
	then
		FILE=`echo $LINE | awk '{print $3}'`
	else
		FILE=/usr/local/bin/$1
	fi
	vi $FILE
	if [ -f $FILE ]
	then
		set -x
		[ -x $FILE ] || chmod 755 $FILE
	fi

4.2

mk - a useful utility

You can make your life easier by pasteing the following into a shell script. Don't forget chmod 775 /usr/local/bin/mk

	#!/bin/sh
	# mk - simple wrapper for make
	# keeps output in a log file
	# "$@" means "$1" "$2" "$3" ...
	# tee may over buffer interactive commands within make

	LOGFILE=gps.out

	( echo ; date ; echo ; echo "# make $*" ; echo ) >> $LOGFILE

	make "$@" 2>&1 | tee -a $LOGFILE
Now instead of typing make or make install you type mk or mk install.

The result is much the same, except that the screen output is also written to a logfile. Interactive make scripts may have a problem with tee not displaying the text soon enough, but this is rare.

Now: every time you see make, type mk instead!.

4.3

xearth

Installing xearth is really easy, the description of how-to do it takes only a few lines (read the README and INSTALL on the disks). The only information you've GOT to have, is that it's called 'xearth' and it is excellent.

The Raven Issue-One LOGO, was produced using xearth. When you run it, it bocomes the X11 desktop background, gets updated every 5 minutes, and displays the names of major cities.

Persoanlly, I use it as desktop clock. I know it's the end of my shift when it's light in Bombay.

4.4

Pre-requirements

I hate pre-conditions, but like a lot of X11 software, you have to have X11 running. Issue-One has a section on /etc/XF86Config.

You will need to have gcc, the gnu c compiler installed, and all the correct LIBS installed. This is likely to be done - if you installed the recommended parts of the Slackware d-diskset, and the x-diskset. Fortunately, people like Pat Volkerding, have done the really hard word of making a system that boots and runs and runs.

4.5

xearth-1.0

4.6

Locating xearth on disk InfoMagic Disk set

If you have copied the Infomagic /cdrom/ls_lr from disk one to /tmp/ls_lr, you can search for it by name. If you don't have the CDROMs, but do have Internet access, you can ftp it.

######## grep -i xearth /tmp/ls_ls/ls_lr ######## 

Mar  6 19:42       115688 disc1/debian/debian-0.93/binary/x11/xearth-1.0-1.deb
Mar  6 22:27         5549 disc1/debian/debian-0.93/source/x11/xearth-1.0-1.diff.gz
Mar  6 22:27       157845 disc1/debian/debian-0.93/source/x11/xearth-1.0-1.tar.gz
Feb 26 18:05       119485 disc2/RedHat/RPMS/xearth-1.0-3.i386.rpm
Nov 17 16:18         6152 disc3/X11/xapps/graphics/xearth-1.0.README
Nov 17 17:10         1209 disc3/X11/xapps/graphics/xearth-1.0.lsm
Nov 17 16:32       153162 disc3/X11/xapps/graphics/xearth-1.0.tgz
Feb 26 18:05       155091 disc6/SRPMS/xearth-1.0-3.src.rpm
Nov  4 19:43       519141 disc6/axp/RedHat/RPMS/xearth-1.0-2.axp.rpm
This shows that 'xearth' is an ingredient of several distributions.

I used the version from sunsite - disk 3.

4.7

cd /cdrom/X11/xapps/graphics/

This is where the xearth package source is. You must have the correct CDROM mounted using mount /cdrom (see Issue-1 for editing your /etc/fstab file).

4.8

mkdir /tmp/pkgs_cd

Make a directory where you build various packages from the cd's. During 'make install', many packages copy the necessary files to /usr/local/bin, and others. xearth does this for you.

This means the source directory can be deleted, or left available for browsing. /tmp/pkgs_cd is a good place to unpack and play with files from the cd-rom. If you like them, you should move them to wherever you chose to put it. /usr/local/src/package or /usr/src/package is a good place.

	mkdir /tmp/pkgs_cd
	chown gps /tmp/pkgs_cd # ie your user
	mkdir /tmp/pkgs_ftp 

If you are desperate for disk space, and want to kill something, look in /tmp. (and /var/log, and /usr/tmp, and /usr/docs, and /usr/lib/package...).

Packages as Self Contained Units

Many packages have default layouts configured, so that all files are kept in the package's home directory. Some even put their own tmp and log files in there too!. Others use /tmp/package and /var/log/package.

All xearth files get created in /tmp/pkgs_cd/xearth-1.0 until you "complete" the installation.

No root password required

xearth compiled and ran as a plain user. root login was later needed to install the files into /usr/X11/bin. If you are trusting, you can do all the installation as root.

The idea is that the root password is used occasionally. The package is built as (you), and can be tested as a plain user. Then you decide if you want to run make install as root.

Most reputable packages can be trusted, and most of the ones you will handle are, but if a package needs root permission to build or run, the question is why? (( The answer is usually that the Makefile was tested that way, and thanks for providing a Makefile that does work. ))

4.9

tar -C /tmp/pkgs_cd -zxf ./xearth-1.0.tgz

Unpack the archive you have just found, into the directory you specified.

This runs the 'tar' command (tape archive), telling it to use /tmp/pkgs_cd as the -C current directory. Ie it does a cd /tmp/pkgs_cd to write the files, but finds and loads xearth from ./.

The -f FILENAME, options tells tar the name of the tar-file to work on. Note that tar won't allow anything else between the -f and FILENAME. The orignal tar didn't even allow a gap!

The -z option tells tar that the tar-file is gnu-zip compressed, and needs the builtin gzip utiltiy.

The -x option means EXTRACT all files from the archive. To get a table of contents, use -ztf instead of -zxf.

If you have 'mc' you can let it help you, do some of the typing. It can also browse inside .tgz files. The command line keys are :

If the tar file package, contains a top level directory, such as "./xearth-1.0", when you use mc to browse the tar file, (which you should do anyway), you can COPY (using F5) the top directory to the other panel (eg /usr/src). If F5 is snatched by X11, use ESC-5 instead.

4.10

cd /tmp/pkgs_cd/xearth-1.0

Notice that the package created a sub-directory, with all its files in. This is known as polite behavior. Some packages create lots of files in the top directory (/tmp/pkgs_cd or wherever you were), they require you to delete and do again.

xearth is also practical. It numbers the directory by the version number of the package. This means that xearth 1.0 source will go into a different directory. Thank-you Kirk Lauritz Johnson tuna@cag.lcs.mit.edu

Browse the files, you should find INSTALL, README and HISTORY at the top of the list. Reading the INSTALL tells you how to build and install it.

You should read it, as it may have changed, or I may be intentionally skipping important discussion texts (no point duplicating the README here). However, here is what I did.

4.11

xmkmf

x-make-makefile, is a utility to create Makefiles. The package designer has done a lot of work, and told xmkmf what to look for. Remember that the package has to compile on Linux, and SUN, and SVR4, and ...

xmkmf scans your machine, and makes a few relevent adjustments to the Makefile (it generates a new one from Makefile.in). Some other packages may require make depend, or ./configure, but check their README files.

4.12

make

The make command, reads the Makefile, and picks a default target (the first in the Makefile is usually called all :-) It then looks to see if any work is needed to bring TARGET upto date.

In this case, it calls gcc to compile xearth.c and link it with the other files, to make a binary executable.

4.13

make install ; make install.man

You should run as a plain user as much as possible, but when installing you will need a second window, logged-in as root, to complete the installation.

make installcopies the necessary files onto the system directories. The source is not copied, and can be deleted (sooner or later).

Most applications can be tested as a plain user, and don't need root permissions at all, until they need to create files in a system bin directory.

4.14

xearth -pos "fixed 62.4 -51.1" -grid &

You don't need any parameters, xearth is enough.

The & tells the shell to run this command in the background. Most X11 applications run this way.

If you don't, it makes it easier to use CTRL-C to generate an Intr, and stop the program. If you forget, and wish to use that tty, but don't want to quit the program, use CTRL-Z followed by bg %1.

The suspended job gets resumed as a background style process. A background process is one that the foreground isn't waiting for.

4.15

man xearth

This shows the range of options that xearth has.

4.16

vi  /.xinitrc

This is one of the X11 startup files. It doesn't have to exist, but if it does, it must contain olvwm or fvwm. By adding xearth to it, it will get started automatically, when you start X11. If it doesn't, it could be a sign that you are running as someone else.

	# /HOME/.xinitrc
	# run by shell during openwin or startx
	# must call window-manager-wm

	xhost pigeon
	xhost kestrel
	raven.tcl &
	sleep 2
	clock &
	xearth -pos "fixed 62.4 -51.1" -grid &
	olvwm
	# fvwm

4.17

delete xearth-1.0

It's easiest to use 'mc' to delete directories, rm is prone to typing errors.

You no-longer need the source online. You can re-generate it from the CDROM, and the installed package has its files installed elsewhere. You can delete the directory, or leave it there for browsing.

	cd /tmp/pkgs_ftp
	rm -rf xearth-1.0

4.18

Worked example - done!

This is how many packages install. They work out of the box, they don't blow-up during make, and they do something real-neat asap.

Other packages mentioned in Raven will have LESS help, telling you what worked for me. If it doesn't work, investigate. Always check for README files, and such.

Regrettably, not every package works perfectly. Personally I discard those that don't, as any trick to make it work takes ages to find, and gets forgotten. However it often happens for no fault of the package. Particularly if the package used to work perfectly with a.out, but needs a different set of libraries, or linking options to work with ELF.

RPM packages, are pre-compiled, and make it easier to quickly install something. Someone else has tweaked the Makefile, and run it in the correct sequence. However, for essential components, you may wish to confirm that you can build from the source, so that if you move to another system you have a reference point that did work.

4.19

configure

Instead of xmkmf (or as well as!), some packages have a configure script that configures the compilation, and installation. It probably sets the names of spool directories, but doesn't really configure the RUNNING application, but pre-configures the compiled application.

When an application needs defaults other than the compiled-in ones, there is usually a run-time (start time) configuration file, such as /etc/conf.package

4.20

configure --prefix=/usr/local

This is the most common default parameter for installing things like xpaint, or user desktop tools, though there are many dialects and interpretations of what "local" implies.

Is it local to the workstation? ie the users choice. Is is something that is specific to the site? such as a local network service.

Personally, I let the package decide itself, as it makes upgrading much easier. I've just installed mc-3.2.1 over mc-2.1.8. I didn't delete the old, I just sprayed the new over it. However, at least I don't have two versions! One is /usr/bin, and one in /usr/local/bin.

If you don't want /usr/local/bin (etc), and you don't mind having to repeat the same incantation for an update; can over-ride it with

	configure --prefix=/usr # to use /usr/bin, /usr/lib, or even
	configure --prefix=/    # to use     /bin, /sbin, /lib, /etc.

4.21

make linux

Some packages avoid the added complexity of configure, but do provide Makfile customisations for specific systems. Many EXPECT you to edit (or at least view) the Makefile, and may provide a make linux target.

4.22

package_elf-01.tgz

Some applications come in both source and ready-compiled packages. This particularly applies to Motif apps, where you need to spend £100 to get the Motif compilation libraries. If you don't have them, download the STATICALLY linked binaries. The DYNAMICALLY linked binaries are smaller, as the shared Motif Libraries are already on your disk (If it says libXm.so not found, you haven't purchased Motif, and the files aren't installed on your disk).

Often the binary package, won't contain the documentation, or background information, then you have to ftp both. Occasionally, an application will be shipped as a single gzip'd executable, that doesn't NEED any other files.

4.23

old_lib.so

If the linker or loader can't find a necessary library, you may have to install the package that brings it, or hunt on the CDROM's for support for old environments.

eg A program compiled for X11R5 will (often) still work on X11R6, but it will require the old libraries to be installed. Slackware ususally has packages of outdated-libraries for exactly this reason.