7/15/03 Version 0.9.1 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. For Windows, read the INSTALL-WIN32.txt file in addition to this file. 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! 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. 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= \ --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 $ set XERCESCROOT ~/xerces-c-src2_2_0 $ export XERCESCROOT (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.