
            gpsim Install Instructions
            --------------------------

TOC
---

 1.0  Install instructions
 2.0  How to Build gpsim without the gui
 3.0  How to Build gpsim without root privileges
 4.0  How to create your own gpsim distribution
 5.0  Installing gtk+-extra and eXdbm
 6.0  How to install gpsim from RPM's



1.0 Installation instructions
    -------------------------


Starting with gpsim-0.18.0, two probably not so common packages:

gtk+-extra
eXdbm

are going to be needed. Please see the end of this file for instructions 
on their installation.

************* NOTE ****************

for gpsim-0.20.0, gtk+-extra.0.99.9 is needed. See the gpsim web page on 
how to get it.

***********************************


INSTALLATION (the most common way)
----------------------------------

If you've ever installed software under Linux/UNIX before, then this 
will be completely familiar to you.

1) create a parent subdirectory for gpsim (e.g. gnupic)

$ mkdir ~/gnupic       # choose whatever directory name you like

2) Copy the tar ball to this directory and expand it:

$ cd ~/gnupic
$ mv the_path_of_where_ever_the_tarball_is/gpsim-0.x.y.tar.gz .
$ tar -xvzf gpsim-0.x.y.tar.gz

(Where 'x.y' is the release number.) This will create a subdirectory called gpsim-0.x.y . All of gpsim's source code will be untarred to here.

3) cd gpsim-0.x.y

4) ./configure
This will check your system for the proper tools necessary to build gpsim and then it will create Makefiles.

***NOTE TO HACKERS***

As of version gpsim-0.17.0, gpsim use the GNU Libtool for making shared libraries. This is good in that it helps make gpsim usable on more platforms. It's bad in that it does not create an executable until the 'make install' step. (It instead creates a script after the make step. This script may be invoked the same way gpsim was invoked prior to 0.17.0 .) Consequently, this makes gpsim difficult to debug. If you want to debug gpsim without having to install it, then you can disable the shared libraries feature:

./configure  --disable-shared

5) make all

This will create the executable.

6) su root . You'll need su privileges to complete the install. If you don't have root privileges or don't wish to install gpsim in the /usr/local/bin directory, then see the steps below on building without root privileges.

7) make install
This copies the executable into the /usr/local/bin subdirectory. 




2.0 HOW TO BUILD gpsim WITHOUT THE GUI
    ----------------------------------


Repeat steps 1,2, and 3 from above.

4) ./configure --disable-gui

Note: if you already had built gpsim with the gui support and then decide you want to take it out, then you'll also needed to do a 'make clean' before you do the 'make' in step 5. The make clean will remove all of the old object files.



3.0 HOW TO BUILD gpsim WITHOUT ROOT PRIVILEGES
    ------------------------------------------

Contributed by Erik Thiele <mailto:erikyyy@erikyyy.de>

(
Preface by Scott:

Erik has created a step-by-step list of instructions for
completely installing gpsim into a local directory. If you
do not have root priviledges or just do not wish to install 
gpsim into the default directories then these instructions 
are for you.
)


 first create your local installation directory,
# if you don't already have one.
mkdir $HOME/localinst

# now make the directory where you compile the programs in.
mkdir $HOME/compiling

# go into that directory
cd $HOME/compiling
# now download exdbm-VERSION-tar.gz and
# gpsim-VERSION-tar.gz into the current directory.
# also download gtk+extra-VERSION-tar.gz
# if your distribution doesn't contain it. just start
gtkextra-config
# if that program was not found, you need to install gtk+extra

# now let's first compile and install gtk+extra
# you can skip this step if you already have gtk+extra installed.
cd $HOME/compiling
tar xzvf gtk+extra-VERSION-tar.gz
cd gtk+extra-VERSION-
./configure --prefix=$HOME/localinst/gtk+extra
make install
cd $HOME
# edit your shell configuration and add something like
export PATH="$PATH":$HOME/localinst/gtk+extra/bin
export LD_LIBRARY_PATH="$LD_LIBRARY_PATH":$HOME/localinst/gtk+extra/lib
# don't forget to relogin to let changes take effect.
# now you can try to execute
gtkextra-config
# if it worked, gtk+extra is now installed.

# now lets install exdbm library.
cd $HOME/compiling
tar xzvf exdbm-VERSION-tar.gz
cd exdbm-VERSION-
./configure --prefix=$HOME/localinst/eXdbm
make install
cd $HOME
# edit your shell configuration and add something like
export LD_LIBRARY_PATH="$LD_LIBRARY_PATH":~/localinst/eXdbm/lib
# don't forget to relogin to let changes take effect.

# now lets install gpsim
cd $HOME/compiling
tar xzvf gpsim-VERSION-tar.gz
cd gpsim-VERSION-
./configure --with-exdbm=$HOME/localinst/eXdbm --prefix=$HOME/localinst/gpsim
make install
cd $HOME
# edit your shell configuration and add something like
export PATH="$PATH":$HOME/localinst/gpsim/bin
# don't forget to relogin to let changes take effect.

# if you want to save diskspace you can now do
rm -rf $HOME/compiling/eXdbm
rm -rf $HOME/compiling/gpsim
rm -rf $HOME/compiling/gtk+extra
# as these files were only needed for compiling and installation.



4.0 HOW TO MAKE YOUR OWN gpsim DISTRIBUTION
    ---------------------------------------
Since gpsim uses automake, you get a whole lot of features for free. I won't go into all of them, but sometimes you might want to tweak gpsim and make your own tar ball. All you have to do is:

$ make dist

If you want to dink the rev numbers, then edit gpsim-0.x.y/configure.in and then from within gpsim-0.x.y/ :

$ automake
$ autoconf
$ ./configure 
$ make dist

5.0 INSTALLING gtk+-extra and eXdbm
    -------------------------------

First, you're going to need to grab these two packages. gtk+-extra can be obtained from either its own web page or gpsim's (At the time of this writing, I do not know gtk+-extra's home page url). eXdbm, on the other hand, should be grabbed from gpsim's web page. I've fixed a bug in their install logic and changed their static Makefile to an automake type. For each of these packages, you can use the `standard' technique for installing gnu software:

$ tar -xvzf package.tar.gz
$ cd package
$ ./configure
$ make
$ su
$ make install
$ exit

Where package is either gtk+-extra or eXdbm.


6.0 INSTALLING RPM's
    ----------------

