#
# $XORP: xorp/BUILD_NOTES,v 1.67 2006/08/02 22:19:31 bms Exp $
#

	Build Notes for XORP (eXtensible Open Router Platform)



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

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).

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)

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
    - The utils/flower_malloc/test_flower_malloc.sh test fails.
    - 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 utils/flower_malloc/test_flower_malloc.sh test fails.
    - The SNMP support inside the "mibs" directory fails to compile.
    - 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)

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

  * NetBSD-2.0 and NetBSD-3.0:
    - 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.

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:
    - 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
      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.

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)

  * 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.

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.7 (Darwin 8.2.0 - 8.7.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.

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.

    - 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.

4. Known problems
=================

See file ${XORP}/ERRATA.
