Version 1.1b

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.

For Windows, read the INSTALL-WIN32.txt file in addition to this file.

Topics have been established in the Shibboleth Wiki for tracking build
considerations and you are encouraged to check there for the latest
information.

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/g++ 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.

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.

NOTE: If you have a problem configuring a package, remember to examine its
config.log file to see what the problem is.


Platforms

The code is tested on Red Hat/Fedora, Solaris 8, and Mac OS X 10.4
Other Solaris and Linux versions probably work. Other Unix systems might
work with some porting effort, but many open source packages are
hit and miss on platforms like HP-UX and AIX. Feedback and code or
build changes are welcome. To port, start with ./configure as described
below, and see what happens!

When configuring packages, the key requirements are for thread-safety
via POSIX pthreads and shared library support.

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

Note that on OS X, the environment variable needed to locate shared
libraries is called DYLD_LIBRARY_PATH.

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

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 shown built and installed to /opt/shibboleth-sp to avoid
interference from preinstalled, older versions of libraries. This is
sometimes crucial on Linux, where some of these libraries might exist
in /usr/lib (and may be too old). This is less of a concern in this day
and age, and you may want to skip building anything included in your
distribution and just use what you have.

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

You must use version 3.0 or newer. We current use a mix of 3.2-3.4
on various platforms. gcc 4.0 and later is a bit bleeding edge, but
does now work (mostly).

(General Linux and OS X)

Most distributions of recent vintage come with a new enough compiler.
If you plan to use a pre-built version of Apache and use other modules
like PHP, it's best to use the version that you have.

(Solaris)

We now support and favor Sun's C/C++ compiler on Solaris, but gcc also
works. The examples below all assume gcc, just to keep things simple.
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.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 build OpenSAML against the same version used with
mod_ssl. If mod_ssl was statically linked against OpenSSL, you will
need to rebuild it to use a shared library version.

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.

(General Linux and OS X)

OpenSSL is a core component on Linux and OS X, and you should probably
update via standard mechanisms supplied with your OS.

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 the latest version of version 0.9.7. The version below is
just an example.

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

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


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

Any version from about 7.11.1 on will work. No known problems exist
with newer releases, apart from any issues that libcurl itself may
have on particular platforms. But it's an active project and bugs
are usually responded to quickly.

(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, as it's a simple build.

To build from source, see Solaris below.

(OS X)

The version supplied by Apple with anything prior to OS X 10.4 is too old.
Source and binary RPMs are available from http://curl.haxx.se/download/
Building from source is suggested (see Solaris below).

(Solaris)
            
The latest code is http://curl.haxx.se/download/curl-7.16.0.tar.gz
When configuring, you'll need to insure the OpenSSL libraries are
in the runtime load path (generally set with LD_LIBRARY_PATH).

To build (the version shown is an example):

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


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

Your first C++ foray. Don't worry, it won't be too painful. This project
is in a limbo state and pending future decisions, we're using a snapshot
release. This library has turned out to be a source of serious problems
with thread safety because the autoconf script was broken. With this latest
snapshot, the script has been fixed on the supported platforms and some
bug fixes have been added.

http://shibboleth.internet2.edu/downloads/log4cpp-0.3.5rc1.tar.gz

$ tar xvzf log4cpp-0.3.5rc1.tar.gz
$ cd log4cpp-0.3.5rc1
$ ./configure --prefix=/opt/shibboleth-sp --disable-static --disable-doxygen
$ make
$ make install


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

The latest Apache-supplied version of Xerces is 2.7, but there are
issues with excessive memory use when caching DOM nodes. Xerces 2.6 also
had signigicant fatal bugs that make it unusuable. A special 2.6.1 release
with fixes and improvements applied has been created by the Shibboleth Project
for use with OpenSAML and Shibboleth. The OpenSAML configure script will detect
and block the use of 2.6.0

For the most part, any prior version since 2.3.0 should also work, but we
*strongly* recommend using our version or version 2.7 and Shibboleth requires it.

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://shibboleth.internet2.edu/downloads/xerces-c-src_2_6_1.tar.gz

$ tar xvzf xerces-c-src_2_6_1.tar.gz
$ cd xerces-c-src_2_6_1/src/xercesc
$ set XERCESCROOT ~/xerces-c-src_2_6_1
$ export XERCESCROOT

(Linux)

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

(OS X)

You must enable the "native" NetAccessor module on this platform.

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

(Solaris)

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


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

This is the Apache XML Signature library. The newest version corrects
build deficiencies on various platforms and should be usable unmodified.

http://xml.apache.org/security/dist/c-library/xml-security-c-1.3.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. You'll also need to make sure that the OpenSSL shared
libraries can be found by the loader, for example setting LD_LIBRARY_PATH.

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

(Solaris)

Also, on at least Solaris and possibly other non-Linux platforms, the install
scripts will not work due to Makefile bugs. The manual steps to install from
the src directory are:

$ cp -r ../include/xsec /opt/shibboleth-sp/include
$ cp ../lib/libxml-security-c.so.13.0 /opt/shibboleth-sp/lib
$ cd /opt/shibboleth-sp/lib
$ ln -s libxml-security-c.so.13.0 libxml-security-c.so.13
$ ln -s libxml-security-c.so.13.0 libxml-security-c.so

You may have more luck with the make install step if you install the GNU
coreutil package.

********
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://www.opensaml.org/

This is fairly simple:

$ ./configure --prefix=/opt/shibboleth-sp --with-curl=/opt/shibboleth-sp \
    --with-log4cpp=/opt/shibboleth-sp --with-openssl=<openssl root> -C
$ make
$ make install

If you want to build it raw out of SVN, you're going to find that old
versions of autoconf and automake (and libtool) you have lying around are
not gonna work. Sorry. We include the libtool you need inside svn, 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:

$ svn co https://svn.middleware.georgetown.edu/cpp-opensaml1 
$ cd cpp-opensaml1
$ ./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.
