Installing Qpid/C++ on Windows ============================== Table of Contents ================= 1. Introduction 2. Prerequisites 2.1. What to Install 2.2. Important Environment Variable Settings 3. Building from a Source Distribution 4. Building a Repository Working Copy 5. Tests 6. Doxygen 7. Troubleshooting 1. Introduction =============== Note that the broker and client API can be built and installed separately. They both link against a common library. This document describes how to build the Qpid/C++ broker and client on Windows using Microsoft Visual Studio 2008 (VC9). It describes how to build from both a checkout of the source and from a source distribution. Please see INSTALL for information on building on Linux/UNIX. 2. Prerequisites ================ We prefer to avoid spending time accommodating older versions of these packages, so please make sure that you have the latest stable versions. Known version numbers for a successful build are given in parentheses. Take these as a recommended minimum version. 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 (1.35) To build from a source repository (SVN) checkout you will need boost plus: * CMake (2.4) * python (2.5.2) * ruby (1.8.4) NOTE: Python 3.x is known to NOT work - please use 2.7 or earlier. Ruby should be prior to version 2. Regardless of which type of build you perform, if you wish to run the full test suite, you will need to have python, listed above, 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=C:\python25;%PATH% It is also necessary to set BOOST_ROOT to refer to the base of your Boost installation. The Visual Studio projects refer to it. For example: # set BOOST_ROOT="C:\Program Files\boost\boost_1_35_0" 3. Building from a Source Distribution ====================================== The Qpid client/broker, examples, and tests are built with a single Visual Studio solution file which is generated by CMake. From a command prompt: # cd qpid\cpp # cmake -i -G "Visual Studio 9 2008" . 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 Release, and build. You can build both Release and Debug from the same project. If you build all the projects you can then "Build" the RUN_TESTS project. This will run the test suite against the Qpid version just built. 4. 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. To get the source code from the subversion repository (trunk) do: C:\qpid> svn checkout https://svn.apache.org/repos/asf/qpid/trunk The first step in the build is to configure and generate the Visual Studio projects. This step also generates a significant number of source files that are part of the build. - Run CMakeSetup. The CMake binary install often leaves a shortcut to CMakeSetup on the desktop - it is named CMake. - The CMakeSetup window has 2 directory selection areas at the top; one for where the source is located (C:\qpid\trunk\qpid\cpp) and one for where you wish to place the build. A directory separate from the source directory is generally preferred; it can be, but need not be, a subdirectory to the source. (C:\qpid\build) - The first time you run CMakeSetup it will ask you to select a generator. You should select the method you prefer to build with: Visual Studio 2008 or NMake Makefiles. - The Cache Values area of the window is where the system and build settings are displayed. You can change these by clicking on the values if desired. - Click the Configure button. The first time Qpid is configured this step may take a few minutes and you will see lots of messages about generated source files. If the Cache Values area has any red lines, change or correct the value if needed (it may only be red because it's new - you only need to change/correct items that correspond to errors in configuration). Click Configure again. Repeat until all the Cache Values are gray. - Click the OK button to generate the project/make files. Open the qpid-cpp.sln solution located in the build directory, select Debug or Release, and build. You can build both Release and Debug from the same project. If you build all the projects you can then "Build" the RUN_TESTS project. This will run the test suite against the Qpid version just built. 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.