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