INSTALL  Sept 2005
-------------------
RPM translation support (option --with-self-rpm) is on by default.

To Compile:
	./configure && make

	-or for a self contained non-root install do:
	
	./configure --prefix=`pwd`/tmp && make && make install


Requirements for Compilation
-----------------------------
	GCC and a GNU/Linux-like environment.
	Other compilers may work, but one known incompatibility with
	strict ANSI C is excessive length of some variable length format
	strings (i.e. usages of fprintf, vsnprintf, et.al).

Important Environment Variables
-------------------------------

	If you are using a GNU/Linux system with /bin/bash as your
	shell then you can skip the environment configuration.

	The POSIXSHELL and GTAR variables are transferred into the production
	swverify(8) and swign(1) programs.  They should point to the path of the
	posix shell and the GNU tar program.

	If tar is GNU tar then you don't have to set GTAR.

	If /bin/sh is sufficiently posix then you don't have to set POSIXSHELL.

	The following shell variables affect compilation:


	SHELL POSIXSHELL CC CXX CFLAGS PATH GTAR
	----------------------------------------		
	GTAR:  The name of the GNU tar program on your system.
	       If ''tar'' is GNU tar then you don't need to set this.

	MAKE:  Must be GNU make, ** you don't need to set this. **
		GNU make is often installed as ''gmake'' if not
		the default ''make''.  If gmake, then just type
		gmake instead of make in the examples below.

	
	SHELL:  This is the shell that does the compilation work.
                Must be a some-what modern Bourne shell.
		This is already set in your environment and
		ignored by make(1) unless you use the -e option.
		If /bin/sh is too broken then you *must* set this
		to a unbroken shell and use the '-e' option.
			
	POSIXSHELL:  This is the shell that is written into the
                     production shell programs.  The default is /bin/sh. 
	             It should be set to the output of:	

			PATH=`getconf PATH` which sh

			To find your Posix shell try:
				# sh
				# PATH=`getconf PATH` which sh	
				# exit

			Example values that are OK:
				/bin/bash         # Bash has the posix features required.
				/bin/sh           # OK Except on Old Unix, Sun Solaris and *BSD systems.
				/usr/xpg4/bin/sh  # Commonly found on Sun/Solaris platforms.
	
	CC:  Typically 'gcc'  or 'cc' 

	CXX:  Typically 'g++'  or 'cxx' 


	PATH:  If your system is not a GNU/Linux system, such as Sun, and if
			you experience problems then try adding the output of 
			''getconf PATH'' to your PATH.

	 		 PATH=$PATH:`getconf PATH`

	CFLAGS: This can be unset or set to one of the following
		typical values:
				CFLAGS=-O0
				CFLAGS=-O1
				CFLAGS=-O2      # Recommended.
				CFLAGS=-O3
				CFLAGS=-g	# Turn on Debugging


./configure Options
--------------------

	The following configure options are supported by the Makefiles:

	--prefix=DIR               [PREFIX]
	--libexecdir=DIR           [PREFIX/libexec]
	--mandir=DIR               [PREFIX/man]
	--infodir=DIR              [PREFIX/info]
	--datadir=DIR              [PREFIX/share]
	--with-self-rpm	Builds rpm translation utilities using the
				included rpmlib. No RPM installation
				required.
	--with-rpm	Builds rpm translation utilities using the system
				RPM installation and links to the sytem rpm
				shared libs.
				Note: rpm version 4.2 and higher may not compile.
	--with-tests	Builds regression test binaries.
	--with-debugdump	Builds debug code and generates .S files
	--with-no-flex	Builds using the supplied .c file pre-generated by flex.
	--with-no-bison	Builds using the supplied .c file pre-generated by bison.
	--with-flex	
	--with-bison	

	the default PREFIX is /usr/local

	Note:  To install library binaries in /lib/, not /libexec/
	       use option  --libexecdir='/usr/lib'


Build Requirements
------------------
    You need a GNU/Linux-like environment that provides GNU-make,
    POSIX shell and utilities. GCC is the target compiler, other
    ANSI C/C++ compilers probably work. (One known use of GCC
    extensions are long variable-arg format strings).
    GNU flex and bison are optional.  The default operation is to
    use pre-compiled files.  To require flex or bison use 
    --with-flex or --with-bison
   
 
RPM configuration:
------------------
    * By default, the RPM capabilities are not compiled.
    * To compile the RPM capabilities use one of the ./configure
      options: --with-rpm  or --with-self-rpm
    
                --with-rpm      Requires rpm shared libraries
                                in /lib or /usr/lib.
                --with-self-rpm Does not require rpm.
   
 
Disabling FLEX and BISON Requirement:
-------------------------------------
                --with-no-flex
                --with-no-bison 
   	(This is the default)
 
To build with all object debuging functions included:
-----------------------------------------------------
     Use configure option '--with-debugdump'
     For example:

          CFLAGS=-g ./configure --prefix=`pwd`/tmp --with-tests --with-debugdump --with-self-rpm
          make && make install
    
     Then try:

          swprogs/swinstall -p -x verbose=9 --allow-rpm <any_rpm  
    

Examples:
---------
    CFLAGS=-O0 ./configure --prefix=`pwd`/tmp --with-self-rpm  && make && make install
        -OR-
    CFLAGS=-O2 ./configure --prefix=/usr --with-self-rpm --libexecdir=/usr/lib --infodir=/usr/share/info --mandir=/usr/share/man  && make
	
	For non-root install to the source package ./tmp directory.

		./configure CFLAGS=-O0 --prefix=`pwd`/tmp  && make && make install && make testall

	For non-root install to a directory in your home directory:

		./configure --prefix=$HOME/swbis && make
     
	On a RedHat System 8.0:

		CFLAGS=-O2 ./configure --prefix=/usr --libexecdir=/usr/lib --mandir=/usr/share/man && make
				- or -
		./configure --prefix=/usr --mandir=/usr/share/man && make

	On a Unix or GNU/Linux System without a libexec directory.

		./configure --prefix=/usr --libexecdir=/usr/lib --mandir=/usr/share/man && make

	To Turn on the debugging compiler option.

		CFLAGS=-g ./configure && make

	To make all all the tests and include rpm support support:
		CFLAGS=-O2 ./configure --prefix=/usr --mandir=/usr/share/man --with-rpm --with-tests && make

	Example of what you might have to do on a AMD64 linux machine:
	As of gcc (GCC) 3.4.2 20041017 (Red Hat 3.4.2-6.fc3), you need -m32 -O0 to avoid 
	core dumps and flakyness.
		LDFLAGS=-m32  CFLAGS="-m32 -O0" ./configure --prefix=$HOME/amd64 --with-self-rpm  && make

	Example of what you might have to do on a Solaris machine:

		export GTAR=gtar; export POSIXSHELL=/usr/xpg4/bin/sh; export CC=gcc; \
			export  CXX=g++; export SHELL=/usr/xpg4/bin/sh \
			./configure CFLAGS=-O0 --prefix=${HOME}/swbis && gmake


Helpful hints if something goes wrong:
--------------------------------------

	* Just type 'gmake' instead of 'make'.
	
	* If /bin/sh is broken then set SHELL=/better/bourne/shell
	  and invoke make or gmake with the -e option.
			# gmake -e
	
	* Find out what the C and C++ compiler commands are
           then try various combinations of (for example):
		export CXX=c++ 
		export CXX=g++ 
		export CC=cc 
		export CC=gcc
		export POSIXSHELL=<your posix shell>
		export SHELL=<your posix shell>,  then invoke this shell.

	* Just type 'make' again and it might work.

	* unset the CFLAGS environment variable,
		and don't give it on the command line.

	For Example:
		export CC=cc; export CC=cxx; export GTAR=gtar; export SHELL=/usr/xpg4/bin/sh; gmake -e

		-or- if not using bash, then you may have to do this:

		export CC=cc; export CC=cxx; \
		export GTAR=gtar; export SHELL=/usr/xpg4/bin/sh gmake -e

How to install:
---------------
	*===============================================================	
	* The <libexec> dir is compiled as a static string.  Therefore 
	* if you relocate the <libexec> directory, expect breakage.
	*===============================================================	

	After building, run: 

           make install

	All the files will install within the prefix directory unless 
	specifically configured otherwise.

How to Configure the runtime config files:
------------------------------------------ 
	The Run time defaults Files are usually:

		<prefix>/lib/swbis/swdefaults
		<prefix>/lib/swbis/swbisdefaults 
		~/.swbis/swdefaults
		~/.swbis/swbisdefaults

	To verify your customizations display the options
	 and defaults files:
		swcopy --show-options
		swcopy --show-options-files

How to test the compilation:
-----------------------------

	Note:
	If /bin/sh and tar are not a posix shell and not GNU tar
        then set SHELL and GTAR and export them.

	*- Self-contained qualificaton test.
	-------------------------------------
	  - You don't have to be (should not be) root.
	  - You will need the following utilities:
		gpg     :  GnuPG (1.0.7 or 1.2.x)
	        tar     :  GNU tar 1.13.17, or 1.13.25 installed.
                           If not installed as 'tar' then you must set GTAR.
	        md5sum  :
                sha1sum :
		openssl :  Only req'd if you don't have sha1sum or md5sum
 
            After unpacking as a non-root user run at the shell prompt:

		sh bin/testbuild0

			- or -

                Examples:
	        ---------	
		GTAR=gtar POSIXSHELL=/usr/xpg4/bin/sh sh bin/testbuild0
		GTAR=gtar XX=`getconf PATH` POSIXSHELL=`PATH=$XX which sh` sh bin/testbuild0


		For Example, on a particular FreeBSD 5.1 host:
		----------------------------------------------
		(export GTAR=gtar; export POSIXSHELL=/usr/local/xpg4/bin/sh; export MAKE=gmake; sh bin/testbuild0)
			-or-

		(export GTAR=gtar; export POSIXSHELL=/bin/bash; export MAKE=gmake; sh bin/testbuild0)

	
		For Example, on a particular Solaris host:
		-------------------------------------------
		(export CC=gcc; export CXX=g++; export POSIXSHELL=/usr/xpg4/bin/sh; export GTAR=gtar; export MAKE=gmake; sh bin/testbuild0)

	*- Parser and digest tests.
	---------------------------
		make test

	*- Parser, digests and package signing test.
	----------------------------------------------------
		make testall

	*- Test package signing and verification.
	------------------------------------------
	See the Makefile target 'testsuite2'

		make testsuite2


	*- Test sha1 and md5  and the parser.
	--------------------------------------
	See the Makefile target 'testsuite1'

		make testsuite1

	Swbis uses md5 and sha1 code taken from the GNU/Linux code base
	and modified slightly, and, in addition is using the same code
	to verify and generate the digests.
	Users who are deploying on platforms other than Intel/32-bit 
	RedHat 6.0/7.0/8.0 should test the sha1 and md5 code by running:
		
		make digesttest
		make digesttest2

	    Tested systems that passed:
		RedHat GNU/Linux (6.0 thru 8.0) Intel 32-Bit
		Debian GNU/Linux (2.4.18) Sparc Ultra 60
		SunOS sparc-solaris2 5.9 Generic_112233-03 sun4u sparc

	*- Development Regression Tests
	-------------------------------
	First, compile and install with --with-tests and --with-rpm

		 (cd tests/regression; make test008) &&
		 (cd tests/regression; make test009) &&
		 (cd tests/regression; make test015) &&
		 (cd tests/regression; make test016) &&
		 (cd tests/regression; make test017) &&
		 (cd tests/regression; make test018) &&
		 (cd tests/regression; make test019) &&
		 (cd tests/regression; make test020) &&
		 (cd tests/regression; make test021) &&
		 (cd tests/regression; make test022) &&
		 (cd tests/regression; make test023)


		# These tests require you to be 'root' and
		* require GNU tar (1.13.25)

		 (cd tests/regression; make test031) &&
		 (cd tests/regression; make test032) &&
		 (cd tests/regression; make test033) &&
		 (cd tests/regression; make test034)


	*- Make this source package.
	-----------------------------
	Requirements:	
		1) Gnu Privacy Guard version 1.2.x or 1.0.7
		2) Gnu Tar version 1.13.25 (or 1.13.17).
		3) The "Test User" key must be in your GPG setup.	
		(The "Test User" keys are found in var/gnupg)
	Run:  
		$ AUTHOR="Test User" bin/make_archive --release
			# This command will make a signed archive of "."
			# Using the "Test User" keys (which the scripts supply
			# the passphrase for (pass="Iforgot").
--
end of INSTALL.
