/*
 * GNU.FREE 2001
 *
 * Copyright (c) 1999, 2000, 2001 The Free Software Foundation (www.fsf.org)
 *
 * GNU.FREE Co-ordinator: Jason Kitcat <jeep@thecouch.org>
 *
 * GNU site: http://www.gnu.org/software/gnu.free/gnufree.html
 * 
 * FREE e-democracy site: http://www.thecouch.org/free/
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program (gpl.txt); if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 *
 */

INSTALL

=========================
- Installing GNU.FREE 1.5
=========================

Before you can run GNU.FREE you will need to make some alterations to the code.

As of version 1.4 you must run the FreeInstall program for a full, secure
installation of GNU.FREE. To run the installation:

-MacOS Users:
Double-click the FreeInstall.app icon

-Other OS Users:
Run FreeInstall.Install from FreeInstall.jar in the FREE-1.5 directory

On a typical Solaris setup with Java SDK 1.2 you would do it with a command like
this (change the paths according to your system):

"/usr/java1.2/bin/java -cp FreeInstall.jar:log4j.jar:freeawt.jar FreeInstall.Install"

Other command-line systems will use the same or nearly the same syntax.

Follow the prompts in the FreeInstall interface to enter the correct information. Note that 
server names can be either DNS style (sterling.swingdigital.com) or numeric IP addresses
 (142.42.36.21).
 
When entering passwords avoid using plain English. Passwords ideally should be long and a
combination of letters and numbers. The following punction is also allowed ;()*=-_+@,.<>?

If any problems occur all file changes are recorded in the FreeInstall.log file.

(Note that you'll need a Java 1.1.x compiler and Virtual Machine to do
all this, there's a GNU page of help at http://www.gnu.org/software/java/java.html
or see http://java.sun.com for more info)


======================
- Finishing Off
======================

By using the installation program, FreeInstall, a key security file in
the util directory will have changed. This encodes some important security info
which is unique to your implementation. It is stored, along with other common
GNU.FREE files in freeutil.jar - a copy is included if you want to quickly run GNU.FREE for
demo purposes. For secure implementation you MUST create your own copy of freeutil.jar
and here's how (NB those using CodeWarrior can do it from the IDE):

1) Rename the existing freeutil.jar to freeutil.old.jar

2) Move from the FREE-1.5 directory to FREE-1.5/Free/util/

3) Compile the files, in our typical Solaris implementation this would be with:

	"/usr/java1.2/bin/javac *.java"
	
	(which would be run when you are in FREE-1.5/Free/util/ directory)
	
4) Create a jar file, in our typical Solaris setup we would type:

	"/usr/java1.2/bin/jar -cf freeutil.jar *.class"

	(which would be run when you are in FREE-1.5/Util/Free/util/ directory)
	
5) Finish off by copying the new freeutil.jar found in FREE-1.5/Util/Free/util/
   to the FREE-1.5 directory.


>>>>>>>>>>>>>>>> JNLP NOTE <<<<<<<<<<<<<<<<<<<<

If you plan on using JNLP to distribute the GNU.FREE client then you need to do
one minor code change until we alter the install system.

Open FreeClient/FClient.java and remove line 77:

	"FreePanel.showSplash(4000);"
	
(or comment it out!)

Now carry on... when done read JNLP-INSTALL for more.

>>>>>>>>>>>>>>>> EOF JNLP NOTE <<<<<<<<<<<<<<<<<<<<


Now you need to compile the main GNU.FREE programs which all depend on the freeutil.jar
file we've just made.

To compile & run GNU.FREE programs you need to make sure that you set a compile time
classpath which includes the FREE-1.5 directory as well as the following files
included with GNU.FREE:

-freeutil.jar
	A new copy of common GNU.FREE files
-freeawt.jar
	Support files for the GNU.FREE interface
-freedbpool.jar
	Database caching/optimisation files
-hsql.jar
	The Hypersonic SQL database system
-log4j.jar
	The log4j logging system
-cryptix32.jar
	Encryption & security algorithms
	
Make sure you are in the "FREE-1.5" directory before you compile the 3 GNU.FREE programs.
(Again CodeWarriors users should just use the IDE).

In our example Solaris system you would compile using the following commands:

	"/usr/java1.2/bin/javac -classpath freeutil.jar:freeawt.jar:freedbpool.jar:hsql.jar:log4j.jar:cryptix32.jar Free/*.java"
	
	(Note that on Systems like Windows the classpath is seperated with a ";")
	
Run the command again but:

	"/usr/java1.2/bin/javac -classpath freeutil.jar:freeawt.jar:freedbpool.jar:hsql.jar:log4j.jar:cryptix32.jar ERServer/*.java"
	
And one more time for FreeClient:
	
	"/usr/java1.2/bin/javac -classpath freeutil.jar:freeawt.jar FreeClient/*.java"
	
And that's it! You should be all done.... Read on if you want to learn how to run the
programs.

[ PERFORMANCE NOTE: While GNU.FREE has many performance optimizations there are often
  compiler facilities to further tune Java systems. For example Sun's (Solaris) compiler
  takes a -O command-line option to optimize code. However this may dramatically slow
  down compiltion time, crete larger class files and cause new bugs. We do not test
  GNU.FREE code with this option so proceed at your own risk.
  
  There also tools both commercial and Free which reduce class size, optimize code and
  obfuscate Java output (this can make reverse engineering harder but by no means impossible).
  For more information see sites such as http://www.meurrens.org/ip-Links/java/codeEngineering/
  which provide details and links to software. ]


======================
- Running GNU.FREE
======================

Running Java programs can be bit tricky to the uninitiated because you need to specify
the Package name and also the main class name. Now I'm the first to admit that the GNU.FREE
package names aren't all brilliant but I'm going to stick with them for the time being.
Anyway here are the names you need to invoke for the Java Virtual Machine:

Regional/Totaller Server		Free.RTServer
Electoral Roll Server			ERServer.ERServer
Voting Client program			FreeClient.FClient

So in our Solaris system that would be done (respectively):

	"/usr/java1.2/bin/java -cp freeutil.jar:freeawt.jar:freedbpool.jar:hsql.jar:log4j.jar:cryptix32.jar:$CLASSPATH Free.RTServer"
	
	"/usr/java1.2/bin/java -cp freeutil.jar:freeawt.jar:freedbpool.jar:hsql.jar:log4j.jar:cryptix32.jar:$CLASSPATH ERServer.ERServer"

	"/usr/java1.2/bin/java -cp freeutil.jar:freeawt.jar:$CLASSPATH FreeClient.FClient"
	
Why all that "$CLASSPATH" stuff? Because specifying a runtime classpath overrides the 
system classpath settings, but we don't want that to happen. So what doess $CLASSPATH
say? In this example it contains:

	"./:/package/java/lib/:/local/share/arch/solaris2/package/warwick-a1/lib/classes"
	
Your programs should be up and running now!

You still need to populate databases and build keys. Check the "Getting Started" document in
the Docs directory of your installation or on the website (filename: gs1.html) for information
on how to do this.

Once that's been done make sure you read the hints 'n tips and advice in the "Running Elections"
file (filename: re1.html) - have a good election!

Visit http://www.thecouch.org/free/ for more help and advice.
	
++++

Problems, bugs and updates for this file and GNU.FREE as a whole should go to jeep@thecouch.org

EOF INSTALL