PROTON-1777: update versions for 0.22.0-rc1
[qpid-proton.git] / INSTALL.md
1 Installing Qpid Proton
2 ======================
3
4 The CMake build system can build the entire codebase, including proton-c,
5 and all its language bindings.
6
7 Dependencies
8 ------------
9
10 Cross-platform dependencies
11
12   - CMake 2.8.7+
13   - Swig 1.3+ (for the bindings)
14   - Python 2.6+ (for the Python binding)
15   - Ruby 1.9+ (for the Ruby binding)
16
17 Linux dependencies
18
19   - GNU Make 3.81+
20   - GCC 4.4+
21   - Cyrus SASL 2.1+ (for SASL support)
22   - OpenSSL 1.0+ (for SSL support)
23
24 Windows dependencies
25
26   - Visual Studio 2005 or newer (regular or C++ Express)
27
28 CMake (Linux)
29 -------------
30
31 The following prerequisites are required to do a full build on
32 RPM-based systems (RHEL, Fedora, etc.).  If you do not wish to build a
33 given language binding you can omit the devel package for that
34 language.
35
36     # Required dependencies
37     $ yum install gcc gcc-c++ make cmake libuuid-devel
38
39     # Dependencies needed for SSL support
40     $ yum install openssl-devel
41
42     # Dependencies needed for Cyrus SASL support
43     $ yum install cyrus-sasl-devel cyrus-sasl-plain cyrus-sasl-md5
44
45     # Dependencies needed for bindings
46     $ yum install swig                                       # Required for all bindings
47     $ yum install python-devel                               # Python
48     $ yum install ruby-devel rubygem-minitest                # Ruby
49
50     # Dependencies needed to generate documentation
51     $ yum install epydoc                                     # Python
52     $ yum install rubygem-yard                               # Ruby
53     $ yum install doxygen                                    # C, C++
54
55 The following prerequisites are required to do a full build on
56 Debian-based systems (Ubuntu).  If you do not wish to build a given
57 language binding you can omit the dev package for that language.
58
59     # Required dependencies 
60     $ apt-get install gcc g++ cmake cmake-curses-gui uuid-dev
61
62     # Dependencies needed for SSL support
63     $ apt-get install libssl-dev
64
65     # dependencies needed for Cyrus SASL support
66     $ apt-get install libsasl2-2 libsasl2-dev libsasl2-modules
67
68     # dependencies needed for bindings
69     $ apt-get install swig python-dev ruby-dev
70
71     # dependencies needed for python docs
72     $ apt-get install python-epydoc
73
74 From the directory where you found this `INSTALL.md` file:
75
76     $ mkdir build
77     $ cd build
78
79     # Set the install prefix. You may need to adjust it depending on your
80     # system.
81     $ cmake .. -DCMAKE_INSTALL_PREFIX=/usr -DSYSINSTALL_BINDINGS=ON
82
83     # Omit the docs target if you do not wish to build or install
84     # documentation.
85     $ make all docs
86
87     # Note that this step will require root privileges.
88     $ make install
89
90 When make install completes, all installed files are listed in the
91 `install_manifest.txt` file. The contents of this file may be used to
92 uninstall.
93
94 CMake (Windows)
95 ---------------
96
97 This describes how to build the Proton library on Windows using
98 Microsoft Visual C++.
99
100 The Proton build uses the CMake tool to generate the Visual Studio
101 project files. These project files can then be loaded into Visual
102 Studio and used to build the Proton library.
103
104 The following packages must be installed:
105
106   - Visual Studio 2005 or newer (regular or C++ Express)
107   - Python (www.python.org)
108   - CMake (www.cmake.org)
109
110 Additional packages are required for the language bindings:
111
112   - Swig (www.swig.org)
113   - Development headers and libraries for the language of choice
114
115 Notes:
116
117   - Be sure to install relevant Microsoft Service Packs and updates
118   - python.exe, cmake.exe and swig.exe _must_ all be added to your PATH
119
120 To generate the Visual Studio project files, from the directory where you found
121 this `INSTALL.md` file:
122
123     > mkdir build
124     > cd build
125     > cmake ..
126
127 If CMake doesn't guess things correctly, useful additional arguments are:
128
129     -G "Visual Studio 10"
130     -DSWIG_EXECUTABLE=C:\swigwin-2.0.7\swig.exe
131
132 Refer to the CMake documentation for more information.
133
134 Build and install from a command prompt (using msbuild):
135
136     > cmake --build . --target install --config RelWithDebInfo
137
138 Loading the `ALL_BUILD` project into Visual Studio:
139
140   1. Run the Microsoft Visual Studio IDE
141   2. From within the IDE, open the `ALL_BUILD` project file or Proton
142      solution file - it should be in the `build` directory you created
143      above.
144   3. Select the appropriate configuration. RelWithDebInfo works best
145      with the included CMake/CTest scripts
146
147 Note that if you wish to build debug version of Proton for use with
148 Swig bindings on Windows, you must have the appropriate debug target
149 libraries to link against.
150
151 Other Platforms
152 ---------------
153
154 Proton can use the http://libuv.org IO library on any platform where
155 it is available. Install the libuv library and header files and adapt
156 the instructions for building on Linux.
157
158 The libuv library is not required on Linux or Windows, but if you wish
159 you can use it instead of the default native IO by running cmake with
160 `-Dproactor=libuv`.
161
162 Installing Language Bindings
163 ----------------------------
164
165 Most dynamic languages provide a way for asking where to install
166 libraries in order to place them in a default search path.
167
168 When `SYSINSTALL_BINDINGS` is enabled (`ON`), the
169 `CMAKE_INSTALL_PREFIX` does not affect the location for where the
170 language bindings (Python and Ruby) are installed. For those
171 elements, the location is determined by the language interpreter
172 itself; that is, each interpreter is queried for the proper location
173 for extensions.
174
175 When `SYSINSTALL_BINDINGS` is disabled (`OFF`), Proton installs all
176 dynamic language bindings into a central, default location:
177
178     BINDINGS=${CMAKE_INSTALL_PREFIX}/${LIB_INSTALL_DIR}/proton/bindings
179
180 In order to use these bindings, you'll need to configure your
181 interpreter to load the bindings from the appropriate directory.
182
183   - Python - Add ${BINDINGS}/python to PYTHONPATH
184   - Ruby   - Add ${BINDINGS}/ruby to RUBYLIB
185
186 You can configure the build to install a specific binding to the
187 location specified by the system interpreter with the
188 SYSINSTALL_[LANGUAGE] options, where [LANGUAGE] is one of PYTHON
189 or RUBY.
190
191     $ cmake .. -DSYSINSTALL_PYTHON=ON
192
193 Disabling Language Bindings
194 ---------------------------
195
196 To disable any given language bindings, you can use the
197 BUILD_[LANGUAGE] option where [LANGUAGE] is one of PYTHON
198 or RUBY, for example:
199
200     $ cmake .. -DBUILD_PYTHON=OFF