INSTALL-WINDOWS.txt

#
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.
#

		Installing Qpid/C++ on Windows
		==============================

Table of Contents
=================
1. Introduction

2. Prerequisites
   2.1. What to Install
   2.2. Important Environment Variable Settings
   2.3. Setting up Boost
3. Building Qpid
   3.1. Building from a Source Distribution
   3.2. Building a Repository Working Copy
4. Building with Qpid Proton for AMQP 1.0 support
5. Tests
6. Doxygen
7. Troubleshooting


1. Introduction
===============
This document describes how to build the Qpid/C++ broker and client on
Windows using Microsoft Visual Studio 2012 (VC11).

Please see INSTALL for information on building on Linux/UNIX and for
building Qpid Java.


2. Prerequisites
================
Known version numbers for a successful build are given in parentheses.

2.1. What to Install
====================

The following libraries and header files must be installed to build
from either a source checkout or a source distribution:

 * boost      <http://www.boost.org>                   	(1.58)
 * CMake      <http://www.cmake.org>                    (3.2)
 * python     <http://www.python.org>                   (2.7.10)
 * ruby       <http://www.ruby-lang.org>               	(2.2.2)

Optional libraries and headers may be installed to build language-
specific bindings and tests:

 * swig       <http://www.swig.org>                     (2.0.10)
 * perl       <http://www.perl.HELPME>                  (1.2.3)
 * nunit      <http://www.nunit.HELPME>                 (2.5.8)
 * doxygen
 
NOTES:
 * Support for Python 3.x is in progress. Version 2.7 works.
 * Regardless of which type of build you perform if you wish to run the
   full test suite you will need to have python installed.

2.2. Important Environment Variable Settings
============================================

Ensure that all the build tools are available on your path, when they are
manually installed to non-standard locations. For example:

 # set PATH=%PATH%;C:\Perl\bin
 # set PATH=%PATH%;C:\Program Files\Python26
 # set PATH=%PATH%;C:\Program Files\ruby\bin
 # set PATH=%PATH%;C:\Program Files\CMake 2.8\bin
 # set PATH=%PATH%;C:\Program Files\doxygen\bin
 # set PATH=%PATH%;C:\Program Files\Python26\Scripts
 # set PATH=%PATH%;C:\Program Files\CMake 2.8\bin
 # set PATH=%PATH%;C:\Program Files\NUnit 2.5.8\bin\net-2.0

2.3. Setting Up Boost
=====================

For Boost 1.58 the community provides prebuilt Windows binaries. See
http://sourceforge.net/projects/boost/files/boost-binaries/1.58.0/

Choose the installer that has the binary bits for the version of Visual
Studio and architecture that you plan to use. For example file
boost_1_58_0-bin-msvc-11.0-64.exe has the include files and dll files
for Visual Studio 2012 x64 project development.

2.3.1. Configure boost so CMake finds this one version
======================================================

CMake can find and use the Boost installation easily if the package
boost package is installed as follows:

 * Install the package to C:\boost
 * Create a link for a \lib folder to point to the actual library
   files:
     # cd C:\boost
     # mklink /J lib lib64-msvc-11.0

   or

   Rename the actual library folder to "lib":
     # rename lib64-msvc-11.0 lib

With a setup like this you do not need to specify any Boost
environment variables or set any CMake switches.

An issue is that CMake will find this boost for 32-bit and
for 64-bit builds. One of them will work and the other will not.
If you have an architecture you plan to use all the time then this is
a reasonable setup.

2.3.2. Configure boost so CMake finds one of many versions
==========================================================

CMake can be steered to use any one of multiple concurrent boost
installations. Using this method you can build with any version of
Visual Studio and with any architecture without rearranging your
boost folders.

 * Install the Boost package to C:\boost_1_58_0
   Do NOT install to C:\boost

 * Set environment variables to point to the boost installation
   # set BOOST_INCLUDEDIR=C:\boost_1_58_0
   # set BOOST_LIBRARYDIR=C:\boost_1_58_0\lib64-msvc-11.0
   # cmake -G "Visual Studio 11 2012 Win64"  ....

CMake will use the same include files regardless of the compiler/
architecture. CMake can be directed to use  any of the libs that are
for the specific compiler/architecture build by varying the
BOOST_LIBRARYDIR setting.

3. Building Qpid
================
The Qpid client/broker, examples, and tests are built with a Visual
Studio solution file and many project files which are generated by
CMake.

From a command prompt:

 # cd qpid\cpp
 # mkdir build
 # cd build
 # cmake -G "Visual Studio 10" ..

Output from CMake includes .h files in the include directory, .vcproj
files for executables and dlls, and the qpid-cpp.sln solution file.

Open the qpid-cpp.sln solution, select Debug or RelWithDebInfo, and build.

3.1. Building from a Source Distribution
========================================

Unzip the distribution zip file into C:\qpid and follow the instructions
in Section 3.

3.2. Building a Repository Working Copy
=======================================
This section will assume that you will create a directory for your Qpid
work. This directory will be referred to below as C:\qpid.

Get the source code from the subversion repository:

 # C:\qpid> svn checkout https://svn.apache.org/repos/asf/qpid/trunk

Then follow the build instructions in Section 3.

4. Building with Qpid Proton for AMQP 1.0 support
=================================================

The easiest way to get Qpid Proton linked into a Qpid build is through
a shared install directory.

Suppose you have Qpid and Qpid Proton sources in directories:

  C:\qpid
  C:\proton

When you run CMake for Proton you must specify an install prefix. The install
folder will hold the Proton include files and libs that Qpid needs.

  C:\proton\build> cmake -DCMAKE_INSTALL_PREFIX=C:\qpid\cpp\install
  C:\proton\build> Proton.sln
  <build the INSTALL project>

Back in the Qpid build, specify the same install prefix.

  C:\qpid\cpp\build> cmake -DCMAKE_INSTALL_PREFIX=C:\qpid\cpp\install
  C:\qpid\cpp\build> qpid-cpp.sln
  <build>

Expect to see ths line in the CMake console output:

   -- Qpid proton found, amqp 1.0 support enabled


5. Tests
========
See src/tests/README.txt for details.


6. Doxygen
==========
Doxygen generates documentation in several formats from source code
using special comments. You can use javadoc style comments if you know
javadoc, if you don't or want to know the fully story on doxygen
markup see http://www.stack.nl/~dimitri/doxygen/

Even even if the code is completely uncommented, doxygen generates
UML-esque dependency diagrams that are ''extremely'' useful in navigating
around the code, especially for newcomers.

The user-level API documentation can be generated by building the
user-api-docs project from the generated Visual Studio solution. The
documentation is generated into the docs/api/html directory under your
build directory.

7. Troubleshooting
==================

When the broker is executed it will try to store a file in the "qpidd"
subdirectory of the current user's temporary file directory, or in
C:\WINDOWS\TEMP. If the qpidd directory can't be created or accessed the
broker startup will fail.