#
# $XORP: xorp/BUILD_NOTES,v 1.104 2008/07/17 17:40:41 pavlin Exp $
#

	Build Notes for XORP (eXtensible Open Router Platform)



1. Compilation
==============

1.1 Compiling the binaries
==========================

To compile XORP, you must have GNU make (gmake) installed. Then just
run the following commands in the top-level directory:

./configure
gmake

To change the default C and C++ compilers, then assign the binary
names to the CC and CXX user environmental variables respectively.
E.g., if you want to use the gcc34/g++34 compilers, then use (in case
of csh/tcsh) the following commands before running "./configure":

setenv CC gcc34
setenv CXX g++34

To compile XORP with additional user-specified compiler flags, assign
those flags to the CFLAGS and CXXFLAGS environmental variables (for the
C and C++ compiler respectively) before running "./configure".
If the flags must be after all other compiler flags (e.g., if they
are suppose to overwrite some internally added flags), then use
environmental variables CFLAGS_END and CXXFLAGS_END (for the C and C++
compiler respectively).

1.2 Generating documentation
============================

The documentation for each XORP release is available from the XORP Web
site. The following procedure (for FreeBSD) can be used to generate the
documentation directly from the source files.

# Install TeX and LaTeX:
cd /usr/ports/print/teTeX
make
make install

# Optionally install the Prosper LaTeX class:
cd /usr/ports/textproc/prosper
make
make install

# Compile the documentation.
# Note that this must be done directly in the XORP directory with the
# original source files.
cd /path/to/xorp
./configure
cd docs
gmake
gmake

2. Internal tests
=================

To run the internal tests, you must have "bash" and "python" installed.
Note that if the python's executable filename is not "python", then
you would have to create a symbolic link with such name. E.g., execute
as a root:

cd /path/to/python/binary
ln -s python2.4 python

After the code is compiled, you need to run the following command
in the top-level XORP directory:

gmake check


3. OS-specific notes
======================

3.1. DragonFlyBSD
============

  * DragonFlyBSD-1.4
    - The code compiles with the default compiler, and the internal tests
      appear to succeed:
      gcc (GCC) 3.4.5 20050809 (prerelease) [DragonFly] (propolice, visibility)

  * DragonFlyBSD-1.6
    - The following system header file has a bug (it uses the C++ keyword
      "new" for the name of a variable):
        /usr/include/machine/atomic.h

      The following patch must be applied to that file before compiling XORP:
      http://www.dragonflybsd.org/cvsweb/src/sys/i386/include/atomic.h.diff?r1=1.20.2.1&r2=1.20.2.2

    - The code compiles with the default compiler, and the internal tests
      appear to succeed:
      gcc (GCC) 3.4.5 20050809 (prerelease) [DragonFly] (propolice, visibility)

  * DragonFlyBSD-1.8
    - The code compiles with the default compiler, and the internal tests
      appear to succeed:
      gcc (GCC) 3.4.6 [DragonFly] (propolice, visibility)

  * DragonFlyBSD-1.10.1
    - The code compiles with the default compiler, and the internal tests
      appear to succeed:
      gcc (GCC) 3.4.6 [DragonFly] (propolice, visibility)

  * DragonFlyBSD-1.12.2
    - The code compiles with the default compiler, and the internal tests
      appear to succeed:
      gcc (GCC) 4.1.2 (DragonFly)

3.2. FreeBSD
============

  * FreeBSD-4.5, FreeBSD-4.6.2, FreeBSD-4.6-RELEASE, FreeBSD-4.8-RELEASE:
    - Earlier XORP releases have been developed and tested on those
      platforms.

  * FreeBSD-4.9-RELEASE and FreeBSD-4.10-RELEASE:
    - No known issues.
    - The code should compile with the following versions of the
      gcc/g++ compiler: 2.95.4 (default), 3.3.4,
      3.4.2 20040827 (prerelease), and 3.4.6.

  * FreeBSD-5.1:
    - The default gcc/g++ compiler (version 3.2.2) has a bug, hence
      you must install a new compiler (e.g., gcc-3.3 from
      /usr/ports/lang/gcc33 in the ports collection). Then, you must
      set environmental variables CC and CXX to point to the new compiler
      before running "./configure"
      (e.g., "setenv CC gcc33; setenv CXX g++33").
    - The code compiles with the new compiler, and the internal tests
      appear to succeed.

  * FreeBSD-5.2, FreeBSD-5.3, FreeBSD-5.4
    - The code compiles with the default compiler, and the internal tests
      appear to succeed.

  * FreeBSD-6.0 on i386
    - No known issues.

  * FreeBSD-6.0 on amd64
    - Multicast routing doesn't work because of a broken "struct igmpmsg"
      definition inside <netinet/ip_mroute.h>.
      The fix (already in FreeBSD-6.1) is to replace
      u_long with uint32_t inside the body of "struct igmpmsg", and
      then recompile both the FreeBSD kernel and XORP.
    - The SNMP support inside the "mibs" directory fails to compile.
    - The rest of code compiles with the default compiler, and the internal
      tests appear to succeed:
      gcc (GCC) 3.4.4 [FreeBSD] 20050518

  * The following compiler is known to be buggy, and should not be used
    to compile XORP:
    - gcc34 (GCC) 3.4.0 20040310 (prerelease) [FreeBSD]
    A newer compiler such as the following should be used instead:
    - gcc34 (GCC) 3.4.2 20040827 (prerelease) [FreeBSD]

  * FreeBSD-6.1 on i386
    - The code compiles with the default compiler, and the internal tests
      appear to succeed:
      gcc (GCC) 3.4.4 [FreeBSD] 20050518

  * FreeBSD-6.1 on amd64
    - The SNMP support inside the "mibs" directory can be compiled only
      if the "--enable-shared" flag is used when running "./configure":
      ./configure --with-snmp --enable-shared
    - The rest of code compiles with the following compilers, and the internal
      tests appear to succeed:
      gcc (GCC) 3.4.4 [FreeBSD] 20050518 (default)
      gcc42 (GCC) 4.2.0 20060218 (experimental)
      gcc43 (GCC) 4.3.0 20070223 (experimental)

  * FreeBSD-6.2 on i386
    - The code compiles with the default compiler, and the internal tests
      appear to succeed:
      gcc (GCC) 3.4.6 [FreeBSD] 20060305

  * FreeBSD-7.0 on i386 and amd64
    - The code compiles with the default compiler, and the internal tests
      appear to succeed:
      gcc (GCC) 4.2.1 20070719  [FreeBSD]

3.3. NetBSD
===========

  * NetBSD-2.0, NetBSD-3.0, NetBSD-3.0.1, and NetBSD-3.1
    - The SNMP support inside the "mibs" directory may fail to compile.
    - The rest of code compiles, and the internal tests appear to succeed:
      gcc (GCC) 3.3.3 (NetBSD nb3 20040520)
    - If the compilation fails with the following error:
      "/usr/pkg/bin/bash: Undefined PLT symbol "read" (reloc type = 7, symnum = 92)"
      then just run "gmake" again, and the compilation should continue from
      the point it has failed.
    - The default datasize limit per user may not be sufficient to compile
      some parts of the code, hence you may need to increase the datasize
      limit.  If you see a compilation error like:
	  ld: final link failed: Memory exhausted
      then you should increase the data size limit by
      "limit datasize 200000" in csh/tcsh or "ulimit -d 200000" in sh.
      If necessary, increase further the datasize limit.
    - The default limit of maximum opened file descriptors per process
      is 64 which may not be sufficient. If you run a XORP program and
      there are errors like:

	  [ 2004/06/20 22:26:09  ERROR test_pim:31634 LIBCOMM +582 comm_sock.c comm_sock_accept ] Error accepting socket 4: Too many open files

      then you should increase the file descriptors limit by
      "limit descriptors 400" in csh/tcsh or "ulimit -n 400" in sh.

  * NetBSD-4.0
    - The code compiles with the default compiler, and the internal tests
      appear to succeed:
      gcc (GCC) 4.1.2 20061021 prerelease (NetBSD nb3 20061125)

3.4. OpenBSD
============

  * If the system would be used as a multicast router, then add the
    following lines to /etc/rc.conf.local and reboot:

    # Enable multicast routing (see netstart(8) for details).
    multicast_host=NO
    multicast_router=YES

    Note that OpenBSD-3.7 is the first release that has PIM multicast routing
    support in the kernel.

  * OpenBSD-3.5:
    - The default gcc/g++ compiler (version 2.95.x) has a bug, hence
      you must install a new compiler (e.g., gcc-3.3.2 and g++-3.3.2 from
      packages). Then, you must set environmental variables CC and CXX
      to point to the new compiler before running "./configure"
      (e.g., "setenv CC egcc; setenv CXX eg++").
    - The code compiles with the new compiler, but some of the internal
      tests fail.
    - The default datasize limit per user may not be sufficient to compile
      some parts of the code, hence you may need to increase the datasize
      limit.  If you see a compilation error like:
	  /usr/bin/ld: final link failed: Memory exhausted
	  collect2: ld returned 1 exit status
      then you should increase the data size limit by
      "limit datasize 200000" in csh/tcsh or "ulimit -d 200000" in sh.
      If necessary, increase further the datasize limit.
    - The default limit of maximum opened file descriptors per process
      is 64 which may not be sufficient. If you run a XORP program and
      there are errors like:

	  [ 2004/06/20 22:26:09  ERROR test_pim:31634 LIBCOMM +582 comm_sock.c comm_sock_accept ] Error accepting socket 4: Too many open files

      then you should increase the file descriptors limit by
      "limit descriptors 400" in csh/tcsh or "ulimit -n 400" in sh.

  * OpenBSD-3.6-current (as of February 2005) on i386 and amd64,
    OpenBSD-3.8, OpenBSD-3.9, OpenBSD-4.0, OpenBSD-4.1, OpenBSD-4.2,
    OpenBSD-4.3
    - The default gcc/g++ compiler (version 3.3.5 (propolice)) has a bug
      in the propolice implementation:
          http://www.monkey.org/openbsd/archive2/tech/200503/msg00011.html
      Hence, you must disable the propolice feature. You need to add the
      "-fno-stack-protector" flag to your CFLAGS and CXXFLAGS
      environmental variables. E.g. (in csh/tcsh): 
	  setenv CFLAGS -fno-stack-protector
	  setenv CXXFLAGS -fno-stack-protector
	  ./configure
    - The code compiles, and the internal tests appear to succeed.
      Multicast routing seems to work.
    - The default datasize limit per user may not be sufficient to compile
      some parts of the code, hence you may need to increase the datasize
      limit.  If you see a compilation error like:
	  collect2: ld terminated with signal 11 [Segmentation fault], core dumped
      then you should increase the data size limit by
      "limit datasize 200000" in csh/tcsh or "ulimit -d 200000" in sh.
      If necessary, increase further the datasize limit.
    - The default limit of maximum opened file descriptors per process
    - The default limit of maximum opened file descriptors per process
      is 64 (increased to 128 in OpenBSD-4.2) which may not be
      sufficient. If you run a XORP program and there are errors like:

	  [ 2004/06/20 22:26:09  ERROR test_pim:31634 LIBCOMM +582 comm_sock.c comm_sock_accept ] Error accepting socket 4: Too many open files

      then you should increase the file descriptors limit by
      "limit descriptors 400" in csh/tcsh or "ulimit -n 400" in sh.

3.5. Linux
==========

  * Linux RedHat-7.2 (kernel 2.4.18):
    - The code compiles, but some of the internal tests fail dumping core.
      The problem is attributable to exception handler failures caused by
      the default compiler/binutils combination.  More information is
      available at:
	http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=54724
    - IGMP and PIM-SM appear to work.

  * Linux RedHat-7.3 (kernel 2.4-20):
    - No known issues.
    - The code should compile with the following versions of the
      gcc/g++ compiler: 2.96 (default).

  * Linux RedHat-9.2 (kernel 2.4.20-8smp):
    - You must install the following RPMs (and all other RPMs they depend on):
      - openssl-devel (e.g., openssl-devel-0.9.7a-5.i386.rpm)
      - ncurses (e.g., ncurses-5.3-4.i386.rpm)
    - The code compiles, and the internal tests appear to succeed.

  * Linux Fedora Core2 (kernel 2.6.5-1.358):
    - The code compiles, but some of the internal tests may fail.

  * Linux Fedora Core4 (kernel 2.6.11-1.1369_FC4smp):
    - The code compiles, and the internal tests appear to succeed
      with the following compilers: gcc-4.0.0 (default), gcc-4.0.1,
      gcc-4.0.2.

  * Linux Fedora Core5 (2.6.16-1.2080_FC5smp):
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.1.0 20060304 (Red Hat 4.1.0-3)

  * Linux Fedora Core6 (2.6.18-1.2798.fc6PAE):
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.1.1 20061011 (Red Hat 4.1.1-30)

  * Linux Fedora 7 (2.6.21-1.3194.fc7):
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.1.2 20070502 (Red Hat 4.1.2-12)

  * Linux Fedora 8 (2.6.21-2950.fc8xen):
    - Optionally install the following packages:
      - libpcap-dev
        This package is needed for sending/receiving link layer data frames.
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.1.2 20070925 (Red Hat 4.1.2-33)

  * Linux Fedora 9 (2.6.25-14.fc9.i686):
    - Optionally install the following packages:
      - libpcap-devel
        This package is needed for sending/receiving link layer data frames.
    - The code compiles, and the internal tests appear to succeed
      except test33 in "bgp/harness/test_peering1.sh"
    - gcc (GCC) 4.3.0 20080428 (Red Hat 4.3.0-8)

  * Linux Debian-3.1 (sarge) (2.4.27-3-386):
    - You must install the following packages:
      - libssl (e.g., libssl0.9.7)
      - libssl-dev
      - gcc (e.g., gcc-3.3)
      - g++ (e.g., g++-3.3)
    - The binaries for the GCC C and C++ compilers might not be called
      gcc/g++, but gcc-3.3 and g++-3.3.
      Either create a link from gcc to gcc-3.3 and from g++ to g++-3.3,
      or set the CC and CXX environments to point to the binary names.
      E.g., in csh/tcsh: setenv CC gcc-3.3; setenv CXX g++-3.3
    - If you see an error like the following when compiling with make/gmake:
        python ../../xrl/scripts/tgt-gen -I../../xrl/interfaces finder.tgt
        sh: line 1: cpp: command not found
      then you would need to create a link from cpp to the C preprocessor.
      E.g., if the C preprocessor is /usr/bin/cpp-3.3, then execute as root:
        cd /usr/bin; ln -s cpp-3.3 cpp
    - The code compiles, and the internal tests appear to succeed.
    - gcc-3.3 (GCC) 3.3.5 (Debian 1:3.3.5-13)

  * Linux Debian-4.0 (etch) (2.6.18-5-486):
    - Optionally install the following packages:
      - libpcap0.8-dev
        This package is needed for sending/receiving link layer data frames.
    - The binaries for the GCC C and C++ compilers might not be called
      gcc/g++, but gcc-4.1 and g++-4.1.
      Either create a link from gcc to gcc-4.1 and from g++ to g++-4.1,
      or set the CC and CXX environments to point to the binary names.
      E.g., in csh/tcsh: setenv CC gcc-4.1; setenv CXX g++-4.1
    - The code compiles, and the internal tests appear to succeed.
    - gcc-4.1 (GCC) 4.1.1-15 (Debian 4:4.1.1-15)
    - gcc-4.1 (GCC) 4.1.3 20070812 (prerelease) (Debian 4.1.2-15)

  * Linux Gentoo 2006.1:
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.1.1 (Gentoo 4.1.1-r3)

  * Linux Gentoo 2007.0 with hardened profile:
    - The following hardened compiler has some issues (correct C++ programs
      might coredump), and should not be used:
        g++ (GCC) 3.4.6 (Gentoo Hardened 3.4.6-r2, ssp-3.4.6-1.0, pie-8.7.10)
      The solution is to use gcc-config and switch to a gcc profile that
      disables ssp, e.g., the "hardenednossp" profile.

  * Linux Gentoo 2008.0 (kernel 2.6.24-gentoo-r7):
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.1.2 (Gentoo 4.1.2 p1.1)

  * Linux Ubuntu-7.04 (Server Edition, kernel 2.6.20-15-server):
    - You must install the following packages:
      - make
        Note that the installed binary name is "make" so you need
        to run "make" instead of "gmake" to compile the source code.
        Alternatively, add "gmake" as a symbolic link to "make":
        cd /usr/bin; ln -s make gmake
      - libssl-dev (e.g., version 0.9.8c-4build1)
      - gcc (e.g., gcc-4.1)
      - g++ (e.g., g++-4.1)
    - Optionally install the following packages:
      - libpcap0.8-dev
        This package is needed for sending/receiving link layer data frames.
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.1.2 (Ubuntu 4.1.2-0ubuntu4)
    - Tested on the following architectures: i386, sparc64

  * Linux Ubuntu-7.10 (Server Edition, kernel 2.6.22-14-server):
    - You must install the following packages:
      - make
        Note that the installed binary name is "make" so you need
        to run "make" instead of "gmake" to compile the source code.
        Alternatively, add "gmake" as a symbolic link to "make":
        cd /usr/bin; ln -s make gmake
      - libssl-dev (e.g., version 0.9.8e-5ubuntu3.1)
      - gcc (e.g., gcc-4.1)
      - g++ (e.g., g++-4.1)
    - Optionally install the following packages:
      - libpcap0.8-dev
        This package is needed for sending/receiving link layer data frames.
      - iptables-dev
        This package is needed for configuring firewall rules using XORP.
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.2.3 (Ubuntu 4.2.3-2ubuntu7)
    - Tested on the following architectures: i386, amd64

  * Linux Ubuntu-8.04.1 (Server Edition, kernel 2.6.24-19-server):
    - You must install the following packages:
      - make
        Note that the installed binary name is "make" so you need
        to run "make" instead of "gmake" to compile the source code.
        Alternatively, add "gmake" as a symbolic link to "make":
        cd /usr/bin; ln -s make gmake
      - libssl-dev (e.g., version 0.9.8g-4ubuntu3.3)
      - gcc (e.g., gcc-4.2)
      - g++ (e.g., g++-4.2)
    - Optionally install the following packages:
      - libpcap0.8-dev
        This package is needed for sending/receiving link layer data frames.
      - iptables-dev
        This package is needed for configuring firewall rules using XORP.
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.2.3 (Ubuntu 4.2.3-2ubuntu7)
    - Tested on the following architectures: i386

  * There is a known problem with building XORP on Linux with gcc-4.0.x
    and optimization enabled. It is a bug in gcc, see XORP Bugzilla #435
    for details:
        http://www.xorp.org/bugzilla/show_bug.cgi?id=435
    A simple work-around is not to enable compiler's optimization, or
    just to upgrade to a newer compiler (4.1.x or later).

  * There is a known problem with building XORP on Linux with gcc-3.3
    or gcc-3.4 and post-2.15 binutils.
    It is a bug in gcc, see XORP Bugzilla #497 for details:
        http://www.xorp.org/bugzilla/show_bug.cgi?id=497
    Newer versions of the gcc compiler (e.g., gcc-4.0.2 or gcc-4.1) should
    be used instead.

  * Intel C/C++ compiler 9.x can be used to compile XORP on Linux
    platform.

3.6. Mac OS X
=============

  * All:
    - Unicast routing appears to work.
    - Multicast routing doesn't work, because the kernel doesn't have
      the appropriate support.

  * OS X 10.3.8 (Darwin 7.8.0):
    - gcc version 3.3 20030304 (Apple Computer, Inc. build 1495)
    - The code compiles, and the internal tests appear to succeed.

  * OS X 10.4.2 - 10.4.9 (Darwin 8.2.0 - 8.9.0) on PowerPC:
    - gcc version 4.0.0 20041026 (Apple Computer, Inc. build 4061)
    - The code compiles, and the internal tests appear to succeed.

  * OS X 10.4.5 (Darwin 8.5.3) on i386:
    - gcc version 4.0.1 (Apple Computer, Inc. build 5250)
    - The code compiles, and the internal tests appear to succeed.

  * OS X 10.5.2 (Darwin 9.2.2), OS X 10.5.3 (Darwin 9.3.0),
    OS X 10.5.4 (Darwin 9.4.0) on i386:
    - gcc version 4.0.1 (Apple Computer, Inc. build 5465)
    - The code compiles, and the internal tests appear to succeed.

3.7 Microsoft Windows
=====================

  * All:
    - We encourage users to try XORP on newer, unsupported versions of
      Windows and report their results to the development team.

    - 64-bit versions of Windows are known not to support MinGW, and are
      therefore not currently supported by XORP.

    - For instructions how to build the XORP Installer for Windows
      see xorp/contrib/win32/installer/README.

    - NOTE WELL: If you are trying to build XORP with MinGW-current as of
      31st July 2006, you will need to manually remove the
      -Wmissing-declarations and -Wmissing-prototypes warning flags from
      the CPARANOIDFLAGS variable in XORP's configure script in order
      to build XORP without interruption.
      This is due to the new way that MSVCRT inline functions are dealt
      with in the mingw-runtime system headers. No other workaround
      is known at this time.

  * Windows Server 2003 (Service Pack 1) (32-bit, x86):
    - XORP is only supported on Windows Server 2003, and is targeted for
      32-bit x86 systems.

    - If a Win32 support patch is shipped for your release, please apply
      it before filing bug reports with the core team.

    - Unicast routing appears to work.
    - All regression tests pass as of XORP 1.2.
    - IPv6 is not supported.
    - RTMv2 is not supported.
    - Multicast is not supported.

    - The code compiles using the MinGW port of gcc 3.4.2, using the
      MSYS shell environment.

    - Instructions for building XORP on Windows Server are identical
      to those for building XORP on a UNIX platform. However, the
      following caveats apply.

      * If you specify the --with-openssl option to configure, it may be
        propagated to the libtecla build, causing the top-level make to break.

      * Any paths passed to the configure script must be in MinGW UNIX-style
        format. Example: 'C:\XORP' becomes '/c/xorp'.

      A patch must be manually applied to the MinGW toolchain before
      attempting to build XORP, as we use API functions which are present in
      the Windows SDK but which are not yet present in the system headers
      which ship with MinGW as of May 2006.

      You MAY need to bracket references to off_t in MinGW's <unistd.h>
      header with '#if 0'.

      The patch may be found in the xorp/contrib/win32 directory.

      * Download the source for w32api-3.7 from mingw.org and untar it
        into a writable location.
      * Change into this directory.
      * Apply the w32api-3.7-xorp.patch to this tree with 'patch -p1'.
      * From within the w32api-3.7 directory, run ./configure --prefix=/usr
        to ensure that the existing w32api binary installation will be
        overwritten.
        (The paths under the MinGW / are aliased under /usr too, but the
        w32api makefiles are confused by a single slash in their PREFIX.)
      * make && make install

      If you encounter any problems, please send the output of the command
      "msysinfo all" and contact the XORP development team with this
      information.

    - We recommend that you install MinGW, MSYS, and the required GNU/Win32
      ports under the path C:\MinGW\, in that order.

    - We recommend that you initially use the Nullsoft Installer which
      is now shipping on MinGW.org to install the 'current' version of
      the base MinGW tools.

    - Once the base MinGW installation is complete, you should then
      manually update the toolchain which this program installs by
      downloading and untarring the following packages in the root of
      your MinGW installation.

       * MSYS-1.0.11-2004
       * binutils-2.15.91
       * gcc-g++
       * gcc-core
       * gdb-6.3-1
       * mingw-runtime
       * mingw-utils
       * mingw32-make
       * msysDTK-1.0.0
       * w32api-3.7

    - Make sure that symbolic links or copies of mingw32-make.exe as
      make.exe and gmake.exe respectively in your MinGW path.

    - You must install the following GNU/Win32 ports:-

       * openssl-bin (Binaries)
       * openssl-lib (Developer files)
       * pcre-bin (Binaries)
       * pcre-lib (Developer files)

      They may be found at: http://gnuwin32.sourceforge.net/packages.html

    - You must install Python for Windows if you intend to run the
      regression tests. This may be found at: http://www.python.org/download/

      The path to the python.exe binary must either be present in PATH after
      installation, or a symlink created in the MinGW environment.

    - In certain cases the compilation might try to use Python to
      auto-generate some files. In that case, one possible work-around
      solution would be install Python. However, if the compilation
      fails with an error like:

/c/python24/python ../../xrl/scripts/tgt-gen -I../../xrl/interfaces bgp.tgt
process_begin: CreateProcess((null), /c/python24/python ../../xrl/scripts/tgt-gen -I../../xrl/interfaces bgp.tgt, ...) failed.
make (e=3): The system cannot find the path specified.

      then try using the following command in the top-level XORP directory:

      env PYTHON=C:/dos/style/path/to/python.exe ./configure

    - The RunShellCommand class has a hard-coded path to the MSYS shell.
      This is currently a no-op because the router manager no longer uses
      this class for running XORP modules.

    - To take a full BGP route feed, a registry key must be updated:
      HKLM\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters
      must be set to 0xFFFFFFFF. Be warned that this removes the upper
      limit on use of nonpageable system memory for kernel FIB entries;
      if the kernel FIB memory requirements ever exceed physical memory,
      the NT kernel will panic.

      The XORP installer has a property page which allows this to be set
      by the administrator, but it does not roll back these settings when
      XORP is uninstalled.

    - If the Windows Routing and Remote Access (RRAS) service is running,
      the XORP FEA process may not be able to update the Windows IPv4
      routing tables. The FEA will detect when this service is running
      and print a warning message to the XORP process log.

    - The XORP Shell (xorpsh.exe) should be run from within a native
      Win32 command prompt. If run from within any other kind of shell,
      it may not work.

  * Windows 'Longhorn' Server (Build 5384) (32-bit, x86):
    - XORP is known to compile on this operating system, but is currently
      unsupported, with the following caveats as they apply to the
      instructions given for building under Windows Server 2003:

      * MinGW and MSYS must be installed in separate directories in order
        to work.
      * As such, MSYSROOT must be set to point to the MSYS root directory,
        and links/copies of sh.exe and bash.exe made in the MinGW tree.
      * The GnuWin32 utilities should be installed in the MinGW tree.
      * The latest bleeding-edge MinGW toolchain is in use (g++ 3.4.5).
      * ActiveState Python is known to install correctly; the open source
        Python will not.

      The following points only apply to the use of the XORP tinderbox:
      * A copy or link of sh.exe as bash.exe must be made for the BGP
        regression tests to run.
      * CopSSH does not install under Vista or Longhorn.
      * SSH for Windows does not install under Vista or Longhorn.
      * Subsystem for UNIX Applications (SUA), as an alternative means of
        running sshd, is not ready as of this writing for Vista or Longhorn.

  * Windows Vista Ultimate Beta (Build 5384) (32-bit, x86):
    - The binary snapshots for Windows Server 2003 are known to run on
      this operating system, but are not officially supported.

3.8. Cross-compilation
======================

  * All:
    - Running the "gmake check" internal tests within the
      cross-compilation environment will not work, unless the build
      machine is capable of running the cross-compiled binaries for the
      target architecture.
 
  * IA-64
    - The code is known to cross-compile on Linux, but it is unknown
      whether the internal tests succeed.
      XORP itself hasn't been tested on IA-64 machine, so it is unknown
      whether it will run properly.

  * MIPS (Broadcom for Linksys WRT54G)
    - The code is known to cross-compile on Linux, but it is unknown
      whether the internal tests succeed.
      XORP itself hasn't been tested on Linksys WRT54, so it is unknown
      whether it will run properly.

  * PowerPC-603
    - The code is known to cross-compile on Linux, but it is unknown
      whether the internal tests succeed.
      XORP itself hasn't been tested on PowerPC-603 machine, so it is
      unknown whether it will run properly.

  * Sparc64
    - The code is known to cross-compile on Linux, but it is unknown
      whether the internal tests succeed.
      XORP itself hasn't been tested on Sparc64 machine, so it is unknown
      whether it will run properly.

  * XScale
    - The code is known to cross-compile on Linux, but it is unknown
      whether the internal tests succeed.
      XORP appears to run on Linux MontaVista-3.1, but it hasn't been
      tested thoughtfully.

  * Instructions for installing crosstool-based cross-compilation tools.

    Use the following instructions to install cross-compilation tools
    and use those tools to compile XORP:

    a) Download crosstool from http://kegel.com/crosstool/ and untar it:

       wget http://kegel.com/crosstool/crosstool-0.42.tar.gz
       tar zxvf crosstool-0.42.tar.gz
       cd crosstool-0.42

    b) Apply one of the following patches:

       - IA-64
         patch < demo-ia64.sh.patch

----------------------------------------------------------------------
--- demo-ia64.sh.org	2005-03-09 13:49:19.000000000 -0800
+++ demo-ia64.sh	2006-10-18 17:37:25.000000000 -0700
@@ -18,6 +18,7 @@
 #eval `cat ia64.dat gcc-3.4.0-glibc-2.3.2.dat`        sh all.sh --notest
 #eval `cat ia64.dat gcc-3.4.1-glibc-2.3.2.dat`        sh all.sh --notest
 #eval `cat ia64.dat gcc-3.4.1-glibc-2.3.3.dat`        sh all.sh --notest
- eval `cat ia64.dat gcc-3.4.2-glibc-2.3.3.dat`        sh all.sh --notest
+# eval `cat ia64.dat gcc-3.4.2-glibc-2.3.3.dat`        sh all.sh --notest
+ eval `cat ia64.dat gcc-3.4.5-glibc-2.3.6.dat`        sh all.sh --notest
 
 echo Done.
----------------------------------------------------------------------

       - MIPS (Broadcom for Linksys WRT54G)
         patch < demo-mipsel.sh.patch

----------------------------------------------------------------------
--- demo-mipsel.sh.org	2005-03-07 16:34:34.000000000 -0800
+++ demo-mipsel.sh	2006-10-25 16:25:59.000000000 -0700
@@ -33,8 +33,9 @@
 #eval `cat mipsel.dat gcc-3.4.0-glibc-2.3.2.dat`        sh all.sh --notest
 #eval `cat mipsel.dat gcc-3.4.1-glibc-2.2.5.dat`        sh all.sh --notest
 #eval `cat mipsel.dat gcc-3.4.1-glibc-2.3.2.dat`        sh all.sh --notest
- eval `cat mipsel.dat gcc-3.4.2-glibc-2.2.5.dat`        sh all.sh --notest
+# eval `cat mipsel.dat gcc-3.4.2-glibc-2.2.5.dat`        sh all.sh --notest
 #eval `cat mipsel.dat gcc-3.4.2-glibc-2.3.3.dat`        sh all.sh --notest
 #eval `cat mipsel.dat gcc-3.4.2-glibc-20040827.dat`        sh all.sh --notest
+eval `cat mipsel.dat gcc-3.4.5-glibc-2.3.6.dat`        sh all.sh --notest
 
 echo Done.
----------------------------------------------------------------------

       - PowerPC-603
         cp -p demo-ppc604.sh demo-ppc603.sh
         patch < demo-ppc603.sh.patch

----------------------------------------------------------------------
--- demo-ppc603.sh.org	2005-03-07 16:34:34.000000000 -0800
+++ demo-ppc603.sh	2006-12-14 17:13:18.000000000 -0800
@@ -11,8 +11,9 @@
 mkdir -p $RESULT_TOP
 
 # Build the toolchain.  Takes a couple hours and a couple gigabytes.
-#eval `cat powerpc-604.dat gcc-3.4.0-glibc-2.3.2.dat` sh all.sh --builduserland --notest
- eval `cat powerpc-604.dat gcc-3.4.1-glibc-2.3.3.dat`  sh all.sh --notest
-#eval `cat powerpc-604.dat gcc-3.4.1-glibc-20040827.dat` sh all.sh --notest
+#eval `cat powerpc-603.dat gcc-3.4.0-glibc-2.3.2.dat` sh all.sh --builduserland --notest
+# eval `cat powerpc-603.dat gcc-3.4.1-glibc-2.3.3.dat`  sh all.sh --notest
+#eval `cat powerpc-603.dat gcc-3.4.1-glibc-20040827.dat` sh all.sh --notest
+eval `cat powerpc-603.dat gcc-4.1.0-glibc-2.3.6.dat`  sh all.sh --notest
 
 echo Done.
----------------------------------------------------------------------

       - Sparc64
         patch < demo-sparc64.sh.patch

----------------------------------------------------------------------
--- demo-sparc64.sh.org	2005-03-07 16:34:34.000000000 -0800
+++ demo-sparc64.sh	2006-11-06 19:31:57.000000000 -0800
@@ -15,7 +15,8 @@
 #eval `cat sparc64.dat gcc-3.3.2-glibc-2.3.2.dat` sh all.sh --notest
 #eval `cat sparc64.dat gcc-3.3.3-glibc-2.3.2.dat` sh all.sh --notest
 #eval `cat sparc64.dat gcc-3.4.0-glibc-2.3.2.dat` sh all.sh --notest
- eval `cat sparc64.dat gcc-3.4.2-glibc-2.3.3.dat` sh all.sh --notest --testlinux
+# eval `cat sparc64.dat gcc-3.4.2-glibc-2.3.3.dat` sh all.sh --notest --testlinux
 #eval `cat sparc64.dat gcc-3.4.2-glibc-20040827.dat` sh all.sh --notest
+eval `cat sparc64.dat gcc-3.4.5-glibc-2.3.6.dat` sh all.sh --notest
 
 echo Done.
----------------------------------------------------------------------

       - XScale
         patch < demo-armv5b-softfloat.sh.patch

----------------------------------------------------------------------
--- demo-armv5b-softfloat.sh.org	2005-03-07 16:34:34.000000000 -0800
+++ demo-armv5b-softfloat.sh	2006-10-18 15:24:05.000000000 -0700
@@ -13,7 +13,8 @@
 # Build the toolchain.  Takes a couple hours and a couple gigabytes.
 
 #eval `cat armv5b-softfloat.dat gcc-3.4.0-glibc-2.3.2.dat` sh all.sh --notest
- eval `cat armv5b-softfloat.dat gcc-3.4.1-glibc-2.3.3.dat` sh all.sh --notest
+# eval `cat armv5b-softfloat.dat gcc-3.4.1-glibc-2.3.3.dat` sh all.sh --notest
 #eval `cat armv5b-softfloat.dat gcc-3.4.1-glibc-20040827.dat` sh all.sh --notest
+ eval `cat armv5b-softfloat.dat gcc-3.4.5-glibc-2.3.6.dat` sh all.sh --notest
 
 echo Done.
----------------------------------------------------------------------

    c) Compile the toolchain and install it:

       sudo mkdir /opt/crosstool
       sudo chown $USER /opt/crosstool

       # Unset the LD_LIBRARY_PATH environmetal variable
       setenv _SAVE_LD_LIBRARY_PATH $LD_LIBRARY_PATH
       unsetenv LD_LIBRARY_PATH

       # Perform the compilation (it tay take a while)

       - IA-64
         sh demo-ia64.sh

       - MIPS (Broadcom for Linksys WRT54G)
         sh demo-mipsel.sh

       - PowerPC-603
         sh demo-ppc603.sh

       - Sparc64
         sh demo-sparc64.sh

       - XScale
         sh demo-armv5b-softfloat.sh

       # Restore the original LD_LIBRARY_PATH environmetal variable
       cd ..
       setenv LD_LIBRARY_PATH $_SAVE_LD_LIBRARY_PATH
       unsetenv _SAVE_LD_LIBRARY_PATH

    d) Set some environmetal variables that will be used later.
       The values need to be modified appropriately if the tools
       are installed in different directory.

       - IA-64
         setenv CROSS_ARCH ia64-unknown-linux-gnu
         setenv CROSS_ROOT /opt/crosstool/gcc-3.4.5-glibc-2.3.6/${CROSS_ARCH}
         setenv CROSS_ROOT_ARCH ${CROSS_ROOT}/${CROSS_ARCH}

       - MIPS (Broadcom for Linksys WRT54G)
         setenv CROSS_ARCH mipsel-unknown-linux-gnu
         setenv CROSS_ROOT /opt/crosstool/gcc-3.4.5-glibc-2.3.6/${CROSS_ARCH}
         setenv CROSS_ROOT_ARCH ${CROSS_ROOT}/${CROSS_ARCH}

       - PowerPC-603
         setenv CROSS_ARCH powerpc-603-linux-gnu
         setenv CROSS_ROOT /opt/crosstool/gcc-4.1.0-glibc-2.3.6/${CROSS_ARCH}
         setenv CROSS_ROOT_ARCH ${CROSS_ROOT}/${CROSS_ARCH}

       - Sparc64
         setenv CROSS_ARCH sparc64-unknown-linux-gnu
         setenv CROSS_ROOT /opt/crosstool/gcc-3.4.5-glibc-2.3.6/${CROSS_ARCH}
         setenv CROSS_ROOT_ARCH ${CROSS_ROOT}/${CROSS_ARCH}

       - XScale
         setenv CROSS_ARCH armv5b-softfloat-linux
         setenv CROSS_ROOT /opt/crosstool/gcc-3.4.5-glibc-2.3.6/${CROSS_ARCH}
         setenv CROSS_ROOT_ARCH ${CROSS_ROOT}/${CROSS_ARCH}

    e) Download openssl from http://www.openssl.org/ and untar it:

       wget http://www.openssl.org/source/openssl-0.9.8d.tar.gz
       tar zxvf openssl-0.9.8d.tar.gz
       cd openssl-0.9.8d

    f) Add a line like the following to file "Configure" in the section
       with other Linux targets. Note that the second field might need
       to be modified to match the exact path name of the installed
       cross-compiler.

       - IA-64
"ia64-unknown-linux-gnu",	"/opt/crosstool/gcc-3.4.5-glibc-2.3.6/ia64-unknown-linux-gnu/bin/ia64-unknown-linux-gnu-gcc:-DL_ENDIAN -DTERMIO -O3 -Wall::-D_REENTRANT::-ldl:SIXTY_FOUR_BIT_LONG RC4_CHUNK:${ia64_asm}:dlfcn:linux-shared:-fPIC::.so.\$(SHLIB_MAJOR).\$(SHLIB_MINOR)",

       - MIPS (Broadcom for Linksys WRT54G)
"mipsel-unknown-linux-gnu",	"/opt/crosstool/gcc-3.4.5-glibc-2.3.6/mipsel-unknown-linux-gnu/bin/mipsel-unknown-linux-gnu-gcc:-DL_ENDIAN -DTERMIO -O3 -Wall::-D_REENTRANT::-ldl:BN_LLONG BF_PTR:${no_asm}:dlfcn:linux-shared:-fPIC::.so.\$(SHLIB_MAJOR).\$(SHLIB_MINOR)",

       - PowerPC-603
"powerpc-603-linux-gnu",	"/opt/crosstool/gcc-4.1.0-glibc-2.3.6/powerpc-603-linux-gnu/bin/powerpc-603-linux-gnu-gcc:-DB_ENDIAN -DTERMIO -O3 -Wall::-D_REENTRANT::-ldl:BN_LLONG RC4_CHAR RC4_CHUNK DES_RISC1 DES_UNROLL::${no_asm}::::::::::dlfcn:linux-shared:-fPIC::.so.\$(SHLIB_MAJOR).\$(SHLIB_MINOR)",

       - Sparc64
"sparc64-unknown-linux-gnu",    "/opt/crosstool/gcc-3.4.5-glibc-2.3.6/sparc64-unknown-linux-gnu/bin/sparc64-unknown-linux-gnu-gcc:-DB_ENDIAN -DTERMIOS -O3 -Wall::-D_REENTRANT::-ldl:SIXTY_FOUR_BIT_LONG BF_PTR:${no_asm}:dlfcn:linux-shared:-fPIC::.so.\$(SHLIB_MAJOR).\$(SHLIB_MINOR)",

       - XScale
"armv5b-softfloat-linux",	"/opt/crosstool/gcc-3.4.5-glibc-2.3.6/armv5b-softfloat-linux/bin/armv5b-softfloat-linux-gcc:-DB_ENDIAN -DTERMIO -O3 -fomit-frame-pointer -Wall::-D_REENTRANT::-ldl:BN_LLONG BF_PTR:${no_asm}:dlfcn:linux-shared:-fPIC::.so.\$(SHLIB_MAJOR).\$(SHLIB_MINOR)",

    g) Cross-compile openssl and install it:

       ./Configure $CROSS_ARCH
       make INSTALL_PREFIX=$CROSS_ROOT_ARCH install

    h) Prepare the XORP cross-compilation environment.
       The first three commands can be skipped if they were done in
       step (d):

       - IA-64
         setenv CROSS_ARCH ia64-unknown-linux-gnu
         setenv CROSS_ROOT /opt/crosstool/gcc-3.4.5-glibc-2.3.6/${CROSS_ARCH}

       - MIPS (Broadcom for Linksys WRT54G)
         setenv CROSS_ARCH mipsel-unknown-linux-gnu
         setenv CROSS_ROOT /opt/crosstool/gcc-3.4.5-glibc-2.3.6/${CROSS_ARCH}

       - PowerPC-603
         setenv CROSS_ARCH powerpc-603-linux-gnu
         setenv CROSS_ROOT /opt/crosstool/gcc-4.1.0-glibc-2.3.6/${CROSS_ARCH}

       - Sparc64
         setenv CROSS_ARCH sparc64-unknown-linux-gnu
         setenv CROSS_ROOT /opt/crosstool/gcc-3.4.5-glibc-2.3.6/${CROSS_ARCH}

       - XScale
         setenv CROSS_ARCH armv5b-softfloat-linux
         setenv CROSS_ROOT /opt/crosstool/gcc-3.4.5-glibc-2.3.6/${CROSS_ARCH}

       setenv CROSS_ROOT_ARCH ${CROSS_ROOT}/${CROSS_ARCH}
       setenv CC ${CROSS_ROOT}/bin/${CROSS_ARCH}-gcc
       setenv CXX ${CROSS_ROOT}/bin/${CROSS_ARCH}-g++
       setenv LD ${CROSS_ROOT}/bin/${CROSS_ARCH}-ld
       setenv RANLIB ${CROSS_ROOT}/bin/${CROSS_ARCH}-ranlib
       setenv NM ${CROSS_ROOT}/bin/${CROSS_ARCH}-nm

       [Optional]
       setenv PATH ${PATH}:${CROSS_ROOT}/bin
       rehash

    i) Cross-compile XORP:

       cd /path/to/xorp/source/code
       ./configure --host=${CROSS_ARCH} --with-openssl=${CROSS_ROOT_ARCH}/usr/local/ssl
       gmake


4. Performance optimization
===========================

[Note: this section is incomplete]

By default, XORP is compiled with compiler debug information enabled
and no optimization.

Use the following command to disable the compiler debug information and
to enable optimization:

./configure --enable-optimize --disable-debug

Remember that if XORP was compiled previously with different options,
it must be recompiled from scratch:

gmake clean
gmake

Additional compiler-related optimizations flags can be specified on
the command line by setting CFLAGS (the C compiler flags) and CXXFLAGS
(the C++ compiler flags). E.g., the following options can be used for
Intel PentiumPro CPU optimizations:

./configure --enable-optimize --disable-debug \
    "CFLAGS=-march=pentiumpro -O3 -fomit-frame-pointer" \
    "CXXFLAGS=-march=pentiumpro -O3 -fomit-frame-pointer"

Other flags that can be set on the command line are CPPFLAGS (the C/C++
pre-processor flags), and LDFLAGS (the linker flags).

5. Known problems
=================

See file ${XORP}/ERRATA.
