#
# $XORP: xorp/BUILD_NOTES,v 1.27 2005/04/01 19:42:24 pavlin 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


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

To run the internal tests, you must have "bash" and "python" installed.
Then, after the code is compiled, you need to run the following command
in the top-level directory:

gmake check


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

3.1. 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, and
      3.4.2 20040827 (prerelease)

  * 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:
    - The code compiles with the default compiler, and the internal tests
      appear to succeed.

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

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

3.2. NetBSD
===========

  * NetBSD-2.0-current:
    - The code compiles, and the internal tests appear to succeed.
    - 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.3. 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

  * 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:
    - The default gcc/g++ compiler (version 3.3.5 (propolice)) has a bug
      in the propolice implementation, 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.4. 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.

3.5. Mac OS X
=============

  * 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.
    - Unicast routing appears to work.
    - Multicast routing doesn't work, because the kernel doesn't have
      the appropriate support.

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

See file ${XORP}/ERRATA.
