PROTON-1323: update the versions for 0.15.0 (RC1)
[qpid-proton.git] / INSTALL.md
1 Qpid Proton Install Information
2 ===============================
3
4 Proton comes with two separate build systems. The CMake build system can builds
5 the entire codebase, including proton-c, all proton-c language bindings, and
6 the pure Java proton-j implementation. The maven build system can only build
7 the Java portions of the code.
8
9 CMake (Linux)
10 -------------
11
12 The following prerequisites are required to do a full build on RPM based systems (RHEL, Fedora etc.).
13 If you do not wish to build a given language binding you can omit the devel
14 package for that language:
15
16     # required dependencies
17     $ yum install gcc cmake libuuid-devel
18
19     # dependencies needed for ssl support
20     $ yum install openssl-devel
21
22     # dependencies needed for Cyrus SASL support
23     $ yum install cyrus-sasl-devel
24
25     # dependencies needed for bindings
26     $ yum install swig          # Required for all bindings
27     $ yum install python-devel                               # Python
28     $ yum install ruby-devel rubygem-rspec rubygem-simplecov # Ruby
29     $ yum install pphp-devel                                 # PHP
30     $ yum install perl-devel                                 # Perl
31
32     # dependencies needed for java (note that any non-ancient jvm will
33     # work, 1.8.0 is just what is current for fedora 23)
34     $ yum install java-1.8.0-openjdk-devel
35
36     # dependencies needed for python docs
37     $ yum install epydoc
38
39 The following prerequisites are required to do a full build on Debian based systems (Ubuntu). 
40 If you do not wish to build a given language binding you can omit the dev
41 package for that language:
42
43     # Required dependencies 
44     $ apt-get install gcc cmake cmake-curses-gui uuid-dev
45
46     # dependencies needed for ssl support
47     $ apt-get install libssl-dev
48
49     # dependencies needed for Cyrus SASL support
50     $ apt-get install libsasl2-2 libsasl2-dev
51
52     # dependencies needed for bindings
53     $ apt-get install swig python-dev ruby-dev libperl-dev
54
55     # dependencies needed for java (note that any non-ancient jvm will
56     # work, 1.8.0 is just what is current for ubuntu 14)
57     $ apt-get install openjdk-8-jdk
58
59     # dependencies needed for python docs
60     $ apt-get install python-epydoc
61
62 From the directory where you found this README file:
63
64     $ mkdir build
65     $ cd build
66
67     # Set the install prefix. You may need to adjust depending on your
68     # system.
69     $ cmake .. -DCMAKE_INSTALL_PREFIX=/usr -DSYSINSTALL_BINDINGS=ON
70
71     # Omit the docs target if you do not wish to build or install
72     # documentation.
73     $ make all docs
74
75     # Note that this step will require root privileges.
76     $ make install
77
78 When make install completes, all installed files are listed in the
79 install_manifest.txt file. The contents of this file may be used to
80 uninstall.
81
82 Note: When SYSINSTALL_BINDINGS is enabled (ON), the
83 CMAKE_INSTALL_PREFIX does not affect the location for where the
84 language bindings (Python, Perl, PHP, Ruby) are installed. For those
85 elements, the location is determined by the language interpreter
86 itself; i.e., each interpreter is queried for the proper location for
87 extensions. If you want to constrain where the Proton code is
88 installed, set SYSINSTALL_BINDINGS to OFF. This will install all
89 bindings to a common location under ${CMAKE_INSTALL_PREFIX}. When
90 installed like this, each user will need to manually configure their
91 interpreters with the respective binding location.
92
93 CMake (Windows)
94 ---------------
95
96 This describes how to build the Proton library on Windows using
97 Microsoft Visual C++.
98
99 The Proton build uses the CMake tool to generate the Visual Studio
100 project files. These project files can then be loaded into Visual
101 Studio and used to build the Proton library.
102
103 The following packages must be installed:
104
105   - Visual Studio 2005 or newer (regular or C++ Express)
106   - Python (www.python.org)
107   - CMake (www.cmake.org)
108
109 Additional packages are required for the language bindings
110
111   - swig (www.swig.org)
112   - development headers and libraries for the language of choice
113
114 Notes:
115
116   - be sure to install relevant Microsoft Service Packs and updates
117   - python.exe, cmake.exe and swig.exe  _must_ all be added to your PATH
118
119 To generate the Visual Studio project files, from the directory where you found
120 this README file:
121
122     > mkdir build
123     > cd build
124     > cmake ..
125
126 If CMake doesn't guess things correctly, useful additional arguments are:
127
128     -G "Visual Studio 10"
129     -DSWIG_EXECUTABLE=C:\swigwin-2.0.7\swig.exe
130
131 Refer to the CMake documentation for more information.
132
133 Build and install from a command prompt (using msbuild)
134     > cmake --build . --target install --config RelWithDebInfo
135
136 Loading the ALL_BUILD project into Visual Studio
137
138   1. Run the Microsoft Visual Studio IDE
139   2. From within the IDE, open the ALL_BUILD project file or proton
140      solution file - it should be in the 'build' directory you created
141      above.
142   3. Select the appropriate configuration. RelWithDebInfo works best
143      with the included CMake/CTest scripts
144
145 Note that if you wish to build debug version of proton for use with
146 swig bindings on Windows, you must have the appropriate debug target
147 libraries to link against.
148
149 Installing Language Bindings
150 ----------------------------
151
152 Most dynamic languages provide a way for asking where to install
153 libraries in order to place them in a default search path.
154
155 When SYSINSTALL_BINDINGS is disabled (OFF), Proton installs all
156 dynamic language bindings into a central, default location:
157
158     BINDINGS=${CMAKE_INSTALL_PREFIX}/${LIB_INSTALL_DIR}/proton/bindings
159
160 In order to use these bindings, you'll need to configure your
161 interpreter to load the bindings from the appropriate directory:
162
163  * Perl   - Add ${BINDINGS}/perl to PERL5LIB
164  * PHP    - Set the PHPRC envvar to point to ${BINDINGS}/php/proton.ini
165  * Python - Add ${BINDINGS}/python to PYTHONPATH
166  * Ruby   - Add ${BINDINGS}/ruby to RUBYLIB
167
168 You can configure the build to install a specific binding to the
169 location specified by the system interpreter with the
170 SYSINSTALL_[LANGUAGE] options, where [LANGUAGE] is one of JAVA, PERL,
171 PHP, PYTHON, or RUBY.:
172
173     $ cmake .. -DSYSINSTALL_PHP=ON
174
175 Disabling Language Bindings
176 ---------------------------
177
178 To disable any given language bindings, you can use the
179 BUILD_[LANGUAGE] option where [LANGUAGE] is one of JAVA, PERL, PHP,
180 PYTHON or RUBY, e.g.:
181
182     $ cmake .. -DBUILD_PHP=OFF
183
184 Maven (All platforms)
185 ---------------------
186
187 The following prerequisites are required to do a full build.
188
189   + Apache Maven 3.0 (or higher) (http://maven.apache.org/)
190
191 From the directory where you found this README file:
192
193     # To compile and package all Java modules (omitting the tests)
194     $ mvn -DskipTests package
195
196     # To install the packages in the local Maven repository (usually ~/.m2/repo)
197     $ mvn -DskipTests install
198