6/1/03
Version 0.9

Please read the README.txt file in the same directory with this file
before continuing. More general information is available there. This
file documents the process of installing and building from source.

Binary distributions of the OpenSAML code are available as part of the
Shibboleth project. (http://shibboleth.internet2.edu/) There are no
binaries available separately from the Shibboleth distributions.

Building and using the C++ version requires a fair bit of effort because
of numerous dependent libraries and the need to use a version of gcc/g++
that does not ship with most older Linux or Unix versions. Also note that
C++ lacks a stable binary interface, which means that in almost all cases,
the same compiler must be used to build all the libraries that will
eventually be linked to OpenSAML. Any version of gcc 3.x+ will work,
but the same version must be used throughout, and the corresponding
version of libstdc++ must be present on any machine where the code will be
used.

The astute observer will note that every release of gcc since 3.0 contains a
new version of libstdc++.so with a new version number on the end. This means
you can generally install package updates to libstdc++ without overwriting
any earlier releases. On the other hand, installing gcc updates can be much
more destructive, since they often overwrite your system compiler and
sometimes even libc. You may wish to build on one machine you can update the
compiler on, and simply install libgcc and libstd++ packages on other hosts.

What follows is a non-exhaustive, but largely correct example of how to
obtain and build versions of all the needed libraries and OpenSAML. This
is merely a guide, and does not capture all the potential problems one
might encounter. One must also be prepared to adapt to pre-existing software
or machine quirks, and as with all open source software, "go with the flow".

Don't immediately start asking questions when something fails, until you've
explored the error and tinkered a bit. Also try and refer to the particular
package's web site and support vehicles before assuming it's a problem
specific to OpenSAML. We have not modified any code of any dependent
package! We have in one case provided a custom tarball that contains a
corrected configure script because the default distribution is broken, but
the package's code itself is unmodified.


Platforms

The code is tested on Red Hat Linux 7.2 and 7.3 and Solaris 8. Other
Solaris and Linux versions probably work. Other Unix systems might
work with some porting effort. Feedback and code or build changes are
welcome but may not be immediately incorporated. To port, start with
./configure as described below, and see what happens!

Windows will eventually be supported. The code currently is buildable with
Visual C++ 6.0, but it's not an official part of the project yet. You'll see
workspace and project files in the CVS that should provide a starting point.
None of the dependencies are dealt with, so you'll have to change the paths
and all that stuff manually in the IDE.

When you see an OS in parentheses below (eg. (Linux)) that's a note that
applies only to that platform.

The commands below assume use of GNU tar (the -z switch)


Compilers

Currently, only gcc/g++ are used in our development and testing on Unix.
Visual C++ 6.0 is used on Windows. We have done some work with other
compilers (notably Sun/Forte Workshop on Solaris), but issues remain. One
common issue is that even with the very new version of libtool we include in
the distribution, it's often necessary to set the LD environment variable to
your C++ compiler's link command, to make linking work properly when
building any of the C++ packages.

OK, ready? Dive in...each piece is headed by a ****** title block so you can
scan for those.

The following assumptions are made in the configure commands, and should be
modified to suit your needs:

The components are to be built and installed to /opt/shibboleth to avoid
interference from preinstalled, older versions of libraries. This is very
crucial on Linux, where some of these libraries might exist in /usr/lib
(and will be too old).

*******
gcc/g++
*******

You must use version 3.0 or newer.

(RH Linux 7.2/7.3)

The easiest way to get a new gcc without destroying your existing gcc, which
is very likely 2.96 or thereabouts, is to update to 3.04 via the Red Hat 7.2
update RPMs for gcc, g++, libgcc, and libstdc++, and all the related
development packages. The reason is that the 3.04 RPMs install gcc and g++
as gcc3 and g++3 alongside your old compilers. Newer versions like 3.1 and
3.2 install over top of your system's gcc, which you may not like.

To get these RPMs, look in
ftp://ftp.rpmfind.net/linux/redhat/updates/7.2/en/os/i386/

Note that when you're building with that 3.04 package, you should set your
CC and CXX environment variables to gcc3 and g++3 respectively or you will
get errors while building the C++ code. Do not mix compilers, ever!

(Solaris)

Since Solaris doesn't come with gcc at all, you could build it from source
or download a binary package from www.sunfreeware.com. Packages for 3.2.x that
use the Sun linker are available, and are highly recommended. If you build
from source, you probably will have to direct it at Sun's linker and not use
GNU ld.


*******
OpenSSL
*******

Aside from the information below, the thing you need to keep in mind here
is that a lot of packages below, and other important packages in the open
source world, use OpenSSL. If you're going to run them in the same process
with one another, then you have to build consistently against one version.

For example, if you're using OpenSAML inside of, say, Apache+mod_ssl,
you will need to reconfigure and rebuild mod_ssl if you're using a
binary version of OpenSAML built with a newer version of OpenSSL.

Many packages linked to OpenSSL will reveal the version they used if you
run the ldd command on them, since OpenSSL's shared libraries are
(incorrectly) stamped with a version suffix that matches the OpenSSL
version. If you see 0.9.6 and you want to use 0.9.7 below, you'll need
to rebuild.

(RH Linux)

OpenSSL is fairly core on Linux, and you should probably update via Red
Hat's update RPMs, which technically aren't the most current, but they work
and are patched. We've built against the standard 0.9.6 revision from Red
Hat.

Also note that Red Hat stamps a different version on their build, so you
tend to get libssl.so.1 or libssl.so.2 instead of libssl.so.0.9.6, which
means you have to be conscious of what you have on your system. Sadly,
sometimes even renaming or symlinking them will work.

(Solaris)

We suggest version 0.9.7a or greater.

http://www.openssl.org/source/openssl-0.9.7a.tar.gz

$ tar xvzf openssl-0.9.7a.tar.gz
$ cd openssl-0.9.7a
$ ./config --prefix=/opt/shibboleth threads shared
$ make
$ make install


*******
libcurl
*******

We now prefer version 7.10.3, though some autoconf support exists to
compile against older versions.

(RH Linux)

There are usually pretty recent RPMs available from the Curl web site, but
you'll find you have to install both curl-devel and curl packages to avoid
dependency problems. You might want to just build from source into your
build tree and ignore the preinstalled version.

To install the latest RPMs at time of writing:

$ rpm -Uvh http://curl.haxx.se/download/curl-ssl-7.10.3-1.i386.rpm \
            http://curl.haxx.se/download/curl-ssl-devel-7.10.3-1.i386.rpm

To build from source, see Solaris below.

(Solaris)
            
The latest code is http://curl.haxx.se/download/curl-7.10.3.tar.gz

To build:

$ tar xvzf curl-7.10.3.tar.gz
$ cd curl-7.10.3
$ ./configure --without-ca-bundle --enable-static=no --with-ssl=<openssl root> \
	--prefix=/opt/shibboleth
$ make
$ make install


*******
log4cpp
*******

Your first C++ foray. Don't worry, it won't be too painful. This is the one
where you'll need our tarball to get a Solaris build to work. Just use it
for Linux as well. This project is not in a stable state. We're using a
snapshot release.

http://wayf.internet2.edu/shibboleth/log4cpp-0.3.4b.tar.gz

$ tar xvzf log4cpp-0.3.4b.tar.gz
$ cd log4cpp-0.3.4b
$ ./configure --prefix=/opt/shibboleth --with-pthreads=yes --enable-static=no \
    --enable-doxygen=no
$ make
$ make install


******
Xerces
******

We're on version 2.2 (and that's the only one you can use). This takes a
while to build, so grab your coffee here once make is underway. Make sure
you set XERCESCROOT as appropriate below (the sample shows a build in a home
directory). Also set the -x and -c switches as needed to specify your
compilers to runConfigure.

http://xml.apache.org/dist/xerces-c/stable/xerces-c-src2_2_0.tar.gz

If that fails, try this:
http://xml.apache.org/dist/xerces-c/stable/archives/Xerces-C_2_2_0/xerces-c-src2_2_0.tar.gz

$ tar xvzf xerces-c-src2_2_0.tar.gz
$ cd xerces-c-src2_2_0/src/xercesc
$ setenv XERCESCROOT ~/xerces-c-src2_2_0

(Linux)

$ ./runConfigure -p linux -c gcc -x g++ -r pthread -b 32 -P /opt/shibboleth
$ make
$ make install

(Solaris)

$ ./runConfigure -p solaris -c gcc -x g++ -r pthread -b 32 -P /opt/shibboleth
$ make
$ make install


**************
xml-security-c
**************

This is the XML Signature library.

http://www.apache.org/dist/xml/security/c-library/xml-security-0.2.0.tar.gz

You'll need to set XERCESCROOT as before, and also set OPENSSL if your OpenSSL
installation isn't in a standard place like /usr/lib. This is normally only
true for Solaris.

$ tar xvzf xml-security-0.2.0.tar.gz
$ cd xml-security-0.2.0/src
$ ./configure --prefix=/opt/shibboleth --without-xalan 
$ make
$ make install


********
OpenSAML
********

Umm, what were we doing? Oh, right. You're finally ready to build the bloody
thing.

You can do this a couple of different ways. The easiest is probably via the
source distribution, at http://shibboleth.internet2.edu/

This is fairly simple:

$ ./configure --prefix=/opt/shibboleth --with-xmlsec=/opt/shibboleth -C
$ make
$ make install

On Linux, you may have a problem later linking against libsaml because of
an error in the libtool archive, libsaml.la. To fix this, edit that file
and remove the reference to /usr/lib/libstdc++.so

$ vi /opt/shibboleth/lib/libsaml.la
(edit the dependency list to remove the non-existing libstdc++ in /usr/lib)

If you want to build it raw out of CVS, you're going to find that any old
versions of autoconf and automake (and libtool) you have lying around are
not gonna work. Sorry. We include the libtool you need inside cvs, so you'll
only need to update or at least install a new automake and autoconf. You can
use packages or build them yourself, either is fine.

To get the code and bootstrap the build:

$ cvs -d:pserver:anoncvs@cvs.internet2.edu:/home/cvs/shibboleth login
$ cvs -d:pserver:anoncvs@cvs.internet2.edu:/home/cvs/shibboleth co -r Rel_0_9 opensaml
$ cd opensaml/c
$ ./bootstrap

Then go back up and build as above.

To see if your build worked, make sure the signtest program was successfully
built and linked. You can run it out of the test folder.

Now follow the flowchart:

                        Did the build succeed?
            Yes?                                        No?

CONGRATULATIONS! Get beer.                     Condolences. Get beer.

