P4P Software Distribution
=========================

Table of Contents
=================
 
 - Introduction
 - Authors and Contact Information
 - License
 - System Requirements
   - Supported Platforms
   - Hardware
   - Software
 - Components
 - Compiling and Installing from Source
   - External Dependencies
     - Linux
     - Windows (MSVC command-line)
   - All Components
   - Individual Components
 - How to Run
   - A Quick Example
 - Documentation
   - Integrating P4P with Your Software
   - Portal Server

Introduction
============

  P4P defines an interface between ISPs and P2P software that is particularly
  simple and intuitive.  The Yale LANS team has developed much of the software
  to begin integration with ISPs (the Portal Server) and P2P applications
  (libraries for querying Portal services, Application Optimization
  Engines, and P4P-guided peer selection). This release supports ALTO protocol
  upon P4P.

Authors and Contact Information
===============================

  The full list of authors is available in the accompanying 'AUTHORS' file.

  The Yale LANS P4P homepage is another source for up-to-date information:
    http://p4p.cs.yale.edu/

License
=======

  The P4P software is covered by a BSD license.  The full license is available
  in the accompanying 'LICENSE' file.

  Note that some of the under the 'apps' directory may be covered by other
  licenses.  These applications have been extended to work with P4P, and we
  include source for those applications in our source tree as a matter of
  simplicity.  Please refer to each application's source for licensing details.

System Requirements
===================

Supported Platforms
-------------------

  Many parts of the P4P software are compatible with both Linux and Windows,
  in particular the common libraries that can be used for integrating P4P with
  existing applications.

  The server-side components, such as the Portal Server, are currently
  compatible only with Linux.

Hardware
--------

  This software does not make any particular assumptions on the machine
  architecture, and should support any architecture that is also supported by
  the software dependencies (see below).  However, the P4P software has only
  been tested on the following platforms:
    - x86
    - x86_64

  Please report success or failures on other architectures to the authors.

Software
--------

  The P4P software makes use of the following external libraries:

    - libcurl
        Version: Any recent version should do
        Website: http://curl.haxx.se/
        Purpose: HTTP client implementation used for accessing Portal
                 servers and Application Optimization Engines

    - Boost
        Version: 1.46 or higher
        Website: http://www.boost.org/
        Purpose: Platform abstractions and data structures used in server-side
                 components

    - libmicrohttpd
        Version: 0.4.0 or higher
        Website: http://www.gnu.org/software/libmicrohttpd/
        Purpose: HTTP server implementation used in server-side components

    - log4cpp
        Version: 1.0 or higher
        Website: http://log4cpp.sourceforge.net/
        Purpose: Logging implementation used in server-side components

    - zlib
        Version: 1.2.3 or higher
        Website: http://www.zlib.net/
        Purpose: gzip compression for HTTP server used in server-side
                 components

  If you are building from source, you will also need the following tools:

    - CMake
        Version: 2.6 or higher
        Website: http://www.cmake.org/
        Purpose: Primary build system for all components

    - Ant
        Version: 1.6 or higher
        Website: http://ant.apache.org/
        Purpose: Invoked for building Java components

    - Doxygen
        Version: 1.5.9 or higher
        Website: http://www.doxygen.org/
        Purpose: Invoked for building API documentation and tutorials

    - LaTeX
        Purpose: Invoked for building guides and manuals

    - One of the following supported compilers:
      - GCC version 4.0 or higher
      - MSVC 6 or higher

    Note that other compilers should work, perhaps with small modifications, but
    they have not been tested. Please feel free to report patches, successes, or
    failures using other compilers to the authors.

Software Components
===================

  The P4P software distribution is subdivided into multiple components. On many
  platforms (e.g., Linux distributions), each component is distributed as a
  separate package.  The components are:

  - p4p-common-cpp
      Description:  Common library for accessing Portal Location and
                    pDistance services, as well as Application Optimization
                    Engines. Contains APIs for P4P-guided peer selection that
                    may be used for integration into existing P2P applications.
                    Also includes full API documentation, including tutorials
                    and code examples.
      Platforms:    cross-platform
      Dependencies: libcurl
      Source Tree:  /common/cpp

  - p4p-common-server
      Description:  Common library for server-side applications
      Platforms:    Linux
      Dependencies: p4p-common, boost, libmicrohttpd, log4cpp, zlib
      Source Tree:  /common-server

  - p4p-portal-server
      Description:  Portal server
      Platforms:    Linux
      Dependencies: p4p-common, p4p-common-server
      Source Tree:  /portal/server

  - p4p-portal-shell
      Description:  Portal shell application for configuring a running Portal
                    server
      Platforms:    cross-platform
      Dependencies: p4p-common
      Source Path:  /portal/shell

  - p4p-portal-utils
      Description:  Utilities for inspecting and visualizing Portal server
                    configurations. Also contains scripts for converting older
                    configuration files into the new format.
      Platforms:    cross-platform
      Dependencies: p4p-common, boost
      Source Path:  /portal/util

  - p4p-portal-docs
      Description:  Configuration guide and example configurations for Portal
                    server
      Platforms:    cross-platform
      Dependencies: none
      Source Path:  /portal/doc


Compiling and Installing from Source
====================================

This section provides instructions for building and installing the P4P
components from source.  Note that it is possible to build all P4P components
at once, or it is possible to build and install them individually (e.g., to
simplify packaging on some platforms).  Instructions are provided for both
methods.

External Dependencies
---------------------

  Linux
  -----

    It is assumed that all software dependencies are already installed. Note
    that in some Linux distributions, you may need to install additional '-dev'
    or '-devel' packages as appropriate.


  Windows (MSVC command-line)
  ---------------------------

    NOTE: These instructions refer to the "C:\Program Files\" directory.  If you
    are using a 64-bit platform, this will instead be "C:\Program Files (x86)\".

    1) Install Boost from http://www.boostpro.com/products/free.  Version 1.35
       or higher is required, and versions up through 1.37.0 should be
       automatically detected.  Please install to the default directory, which
       should be "C:\Program Files\boost\boost_x_xx\".

       You may instead build Boost from source if desired.

    2) Download and build libcurl from http://curl.haxx.se/download.html. Select
       the curl-x.x.x.zip file.

       a) Unzip to "C:\Program Files\curl" so that the directory
          "C:\Program Files\curl\lib" contains the "curllib.vcproj" file.
 
       b) Make the following modifications:

          - Open lib/Makefile.vc6 and lib/Makefile.vc8 and change the following
            variables from their original values:
              LIB_NAME = curl
              LIB_NAME_DEBUG = curld
              IMPLIB_NAME = curl
              IMPLIB_NAME_DEBUG = curld

          - Replace wsock32.lib with ws2_32.lib in the WINLIBS variable.

          - Remove bufferoverflowu.lib from the WINLIBS variable (in
            Makefile.vc8 only).

       c) In the curl\lib directory, run:
            nmake /f Makefile.vc8 cfg=release-dll
          (substitute 'vc6' for 'vc8' if appropriate).

       d) Add the following system environment variables:
          CMAKE_INCLUDE_PATH = C:\Program Files\curl\include
          CMAKE_LIBRARY_PATH = C:\Program Files\curl\lib

Building All Components
-----------------------

  The easiest way to get started is to build all components. The build system
  will automatically search for the required dependencies for each component,
  and build only those that have all dependencies satisfied.

  A typical process to compile the project is as following:

    mkdir build-temp
    cd build-temp
    cmake ../
    make
    sudo make install

  NOTE: with Windows MSVC, you will need to you will need to make the following
    adjustments:
      - Use
          cmake -G "NMake Makefiles" .
        instead of:
          cmake .
      - Use 'nmake' instead of 'make'

Building Individual Components
------------------------------

  Before building a particular component, ensure that all internal dependencies
  (see 'Software Components' section for details) have already been built and
  installed.

  Change to the directory containing the individual component, then use the same
  commands as given above in the 'Building All Components' section.

How to Run
==========
  In portal/server/resource/conf there are two important files: 
  p4p-portal-intf.conf and interop.conf.

  The first file is the interface configuration file for p4p_portal.
  Please refer to ./p4p_portal --help to see how to run the portal server. 
  A simple example is "./p4p_portal --interfaces-file p4p-portal-intf.conf".
  You MUST specify IP address of your ALTO server in p4p-portal-intf.conf
  before running ./p4p_portal. For example, "address = p4p-1.cs.yale.edu".

  The second is a ISP/PID configuration file used in the ALTO interop 2012. 
  (for draft-gurbani-alto-interop-cases-02) 
  First type "./p4p_portal_shell" to start the shell. Then in the shell type "server [hostname]"
  to connect the portal server. Finally, type "load interop.conf" to load the file into the portal server.

A Quick Example
---------------
  cd p4p/alto-prototype
  In terminal (0)
    build-temp/portal/server/p4p_portal --interfaces-file portal/server/resource/conf/p4p-portal-intf.conf
  In terminal (1)
    cp portal/server/resource/conf/interop.conf ./
    build-temp/portal/shell/p4p_portal_shell
      server <IP address>
      load interop.conf
  In terminal (2)
    python test/interop-cases-02.py <ALTO server IP address>

Documentation
=============

Integrating P4P with Your Software
----------------------------------

  The P4P Common Library provides common functionality that can be used when
  integrating P4P into your applications. For complete documentation, you may
  build the documentation with the following commands (requires doxygen to be
  installed):

    cmake .
    make p4p_common_cpp_doxygen

  Next, open the compiled documentation in your favorite web browser. For
  example:

    firefox p4p-common/cpp/doxygen/html/index.html

Portal Server
-------------

  A Portal Server provides network information to P4P-enabled applications, and
  is typically operated by an ISP.  For information on configuring and running
  a Portal Server, please refer to the Portal User Manual.  You may compile the
  manual with the following commands (requires LaTeX to be installed):
  
    cmake .
    make p4p_portal_manual_pdf

  Next, open the manual in your favorite PDF reader. For example:

    acroread portal/doc/config-manual/out/p4p_portal_manual.pdf