$Ringlet:
c/net/mail/actbook/doc/en_US.ISO8859-1/articles/actbook/actbook.sgml,v
1.3 2002/01/09 14:15:12 roam Exp $
This article describes the internals and development history of ActBook, a contact list editor for the Evolution, the popular e-mail client from Ximian GNOME.
ActBook is an Evolution component, designed to offer an ACT!-like interface to the Evolution addressbook. Most of its API mimics the API of the Evolution addressbook component for the simple reason that, well, ActBook is an addressbook app :) ActBook is designed to work with the Ximian GNOME version of Evolution .
You may view the ActBook documentation as a single file.
The ActBook home site is http://devel.ringlet.net/mail/actbook/.
For the ActBook development history, please see the ChangeLog in HTML or text format.
Currently, the only way to install ActBook is to build it from a source tarball.
Note: The build of ActBook requires some libraries from the Evolution package that are not installed during the Evolution install phase, or by the pre-built Evolution packages. Thus, to build ActBook from its source distribution, you will need to obtain the Evolution source in some form - a tar/gzip archive, an SRPM package, etc.
To install ActBook from its source distribution, follow this procedure:
Acquire the source distribution
Currently, the only way to acquire the ActBook source distribution is by e-mail from SBND Technologies.
Acquire the Ximian Evolution source distribution
Currently, ActBook only builds using the sources of Evolution 1.0. You will need to obtain the Evolution sources from the Ximian web-site.
Unpack the Evolution source
The exact way in which this is done depends on the format of the Evolution source distribution that you have obtained.
If you have obtained a tar/gzip archive of Evolution (evolution-1.0.tar.gz), unpack the Evolution source using the following command:
% tar -zxf /path/to/evolution-1.0.tar.gz
If you have obtained an SRPM (source RPM) package (e.g. evolution-1.0-1.srpm), unpack the Evolution source by installing the SRPM archive using the following command:
# rpm -ivh /path/to/evolution-1.0-1.srpm
Note: You may need to obtain root privileges to install an RPM package.
Configure the Evolution build settings
Many Unix applications need a configuration stage before their actual build. They need to be pointed at the location of various libraries, applications or system directories; they need to be configured to use one of several different types of interface for some system, library or application interfaces; they need to be customized to behave in one of several different ways towards the user.
Evolution uses a GNU configure framework. Before building the actual libraries and binaries, you need to change to the Evolution source directory (/usr/src/redhat/SOURCES/evolution-1.0/ if you are using SRPM, or a subdirectory named evolution-1.0/ if you are using a tar/gzip archive) and invoke the configure script. It accepts various arguments; in the simplest case, you will only need to use the following command:
% ./configure
If that should fail, you need to examine the output of the configure script and provide additional parameters. To obtain a list of the parameters that may be passed to the GNU configure script, use the following command:
% ./configure --help
In particular, you may need to specify the path to the DB3 database that will be used for the Evolution build.
Build Evolution
Evolution is now ready to be built. Assuming that you have a GNU version of the make build utility, this is as easy as changing to the Evolution source directory (as in the configuration stage above) and typing:
% make
Note: On some operating systems, the make installed by default is not a GNU version. There is usually a port or package of GNU make, which is usually installed as gmake. In that case, the command needed to build Evolution is gmake instead of make.
Unpack the ActBook source
Now that you have successfully built Evolution, it is time to do something about ActBook :) Since the only way that the ActBook source is currently distributed is as a tar/gzip archive, you will need to unpack it using the command:
% tar -zxf /path/to/actbook-1.0pre1.tar.gz
Configure the ActBook build settings
Just like Evolution, ActBook needs to be pointed at the locations of various GNOME components. Change to the ActBook source directory, named actbook-1.0pre1/, and issue the same command you used to configure Evolution, with one or two additional parameters: the paths to the Evolution source and build directories. Usually, the source and build directories are the same, but this is not necessarily so. In the simplest case, when the source and build directories are the same, you need to specify the --with-evolution=/path/to/evolution-1.0/ argument to the GNU configure script of ActBook. If the source and build directories are different, use the --with-evolution-src=/path/to/the/evolution/source/dir/ and --with-evolution-build=/path/to/the/evolution-build/dir/ parameters.
In the simplest case, all you need to do is issue the following command:
% ./configure --with-evolution=/path/to/evolution-1.0/
Build ActBook
Once the configure script completes its examination of the system, it is time for the actual ActBook build. Just as with Evolution, you only need to issue a make (or gmake) command, and the ActBook build infrastructure will take care of the rest.
Install ActBook
We are almost there! :) ActBook has been successfully built, now all you need is to install it. Just like with many other programs, this is done with the following command (and again, you may need to substitute gmake for make:
# make install
Note: You may need to obtain root privileges to install ActBook in a location outside your home directory or the system /tmp directory.
And that is all there is to it! :)
Once ActBook has been successfully installed, it can be used via the Evolution shell. Before you use it, though, you may have to create a local configuration folder in your home directory. If you have not used Evolution before installing ActBook, there is nothing you need to do - since ActBook installs its configuration files in the Evolution data directory, they will be copied to your home directory when it is initialized at the first start of Evolution. If, however, you have already used Evolution, and you already have a evolution/local/ directory in your home directory, you may need to copy the ActBook configuration data there by hand.
Locate the Evolution default_user/ directory
ActBook installs its configuration files under the default_user/ directory where Evolution was installed. (Note: installed, not built). Usually, the default_user/ directory a subdirectory of either /usr/X11R6/share/gnome/evolution/, or /usr/share/gnome/evolution/, or /usr/local/share/gnome/evolution/.
Once you find the Evolution default_user/ directory, look for a subdirectory named local/ContACT/. This is where ActBook has installed its configuration files.
Create your ContACT/ configuration directory
To let Evolution know that you want to use ActBook, you need to create a local/ContACT/ subdirectory of the evolution/ in your home directory. You can do this using the command:
% mkdir ~/evolution/local/ContACT
Copy the ActBook configuration files
Simply execute the command (one single long line):
% cp /usr/X11R6/share/gnome/evolution/default_user/local/ContACT/* ~/evolution/local/ContACT/
You may need to substitute the directory you located in the first step for /usr/X11R6/share/gnome/.
With this, the ActBook configuration files have been copied to your home directory. Now you can start Evolution and there should be a new folder named ContACT in its folder list. Clicking on it starts ActBook. You may use the Evolution folder context menu to create a shortcut for ActBook, so you can start it with a single click in the Evolution shortcut bar.
This, and other documents, can be downloaded from http://devel.ringlet.net/.
For questions about this documentation, e-mail <roam@ringlet.net>.