Skip to content

Commit c725c7e

Browse files
ajdavisajdavis
committed
CDRIVER-882 rearrange install guide
Remove redundant install instructions from README and combine all instructions in installing.page. Improve the instructions (CDRIVER-722) especially for Open SSL on El Capitan (CDRIVER-941).
1 parent 1df06e3 commit c725c7e

File tree

2 files changed

+104
-138
lines changed

2 files changed

+104
-138
lines changed

‎README.rst‎

Lines changed: 15 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -83,19 +83,19 @@ MongoDB project, please report it according to the `instructions here
8383
<http://docs.mongodb.org/manual/tutorial/create-a-vulnerability-report>`_.
8484

8585

86-
Building from Release Tarball
87-
=============================
86+
Building the Driver from Source
87+
===============================
8888

89-
Unless you intend on contributing to the mongo-c-driver, you will want to build
90-
from a release tarball.
89+
Detailed installation instructions are in the manual:
90+
http://api.mongodb.org/mongo-c-driver/current/installing.html
9191

92-
The most current release is 1.2.0 which you can download here.
93-
`mongo-c-driver-1.2.0.tar.gz <https://github.com/mongodb/mongo-c-driver/releases/download/1.2.0/mongo-c-driver-1.2.0.tar.gz>`_.
92+
From a tarball
93+
--------------
9494

95-
To build on UNIX-like systems, do the following::
95+
Download the latest release from `the release page <https://github.com/mongodb/mongo-c-driver/releases>`_, then::
9696

97-
$ tar xzf mongo-c-driver-1.2.0.tar.gz
98-
$ cd mongo-c-driver-1.2.0
97+
$ tar xzf mongo-c-driver-$ver.tar.gz
98+
$ cd mongo-c-driver-$ver
9999
$ ./configure
100100
$ make
101101
$ sudo make install
@@ -106,7 +106,7 @@ To see all of the options available to you during configuration, run::
106106

107107
To build on Windows Vista or newer with Visual Studio 2010, do the following::
108108

109-
cd mongo-c-driver-1.2.0
109+
cd mongo-c-driver-$ver
110110
cd src\libbson
111111
cmake -DCMAKE_INSTALL_PREFIX=C:\usr -G "Visual Studio 10 Win64" .
112112
msbuild.exe ALL_BUILD.vcxproj
@@ -123,78 +123,13 @@ mongo-c-driver contains a copy of libbson in the case that your system does
123123
not already have libbson installed. The configure script will detect if
124124
libbson is not installed and install it too.
125125

126-
Dependencies
127-
------------
128-
129-
Fedora::
130-
131-
$ sudo yum install git gcc automake autoconf libtool
132-
133-
Debian::
134-
135-
$ sudo apt-get install git gcc automake autoconf libtool
136-
137-
FreeBSD::
138-
139-
$ su -c 'pkg install git gcc automake autoconf libtool'
140-
141-
142126
Fetch Sources and Build
143127
-----------------------
144128

145129
You can use the following to checkout and build mongo-c-driver::
146130

147-
git clone https://github.com/mongodb/mongo-c-driver.git
148-
cd mongo-c-driver
149-
./autogen.sh
150-
make
151-
sudo make install
152-
153-
In standard automake fasion, ./autogen.sh only needs to be run once.
154-
You can use ./configure directly going forward.
155-
Also, see ./configure --help for all configure options.
156-
157-
158-
Building on Windows
159-
===================
160-
161-
Currently, the cmake build system for mongo-c-driver does not build the libbson
162-
package as well. This needs to be done manually with cmake.
163-
164-
SSL is supported through the use of OpenSSL. SASL is not currently supported
165-
but is planned. To enable OpenSSL support, install the appropriate OpenSSL for
166-
Windows from `here <http://slproweb.com/products/Win32OpenSSL.html>`_. The
167-
instructions below assume 64-bit builds, so you would want to get the version
168-
for "Win64 OpenSSL 1.0.1f" which includes libraries and headers.
169-
170-
If you are building from git, and not a release tarball, you also need to
171-
initialize the git submodule for libbson::
172-
173-
git submodule init
174-
git submodule update
175-
176-
Then proceed to build and install libbson using cmake and Visual Studio's
177-
command line tool, msbuild.exe. You can of course open these project files
178-
from Visual Studio as well::
179-
180-
cd src\libbson
181-
cmake -DCMAKE_INSTALL_PREFIX=C:\usr -G "Visual Studio 10 Win64" .
182-
msbuild.exe ALL_BUILD.vcxproj
183-
msbuild.exe INSTALL.vcxproj
184-
cd ..\..
185-
cmake -DCMAKE_INSTALL_PREFIX=C:\usr -DBSON_ROOT_DIR=C:\usr -G "Visual Studio 10 Win64" .
186-
msbuild.exe ALL_BUILD.vcxproj
187-
msbuild.exe INSTALL.vcxproj
188-
189-
190-
Generating the Docs
191-
===================
192-
193-
To generate the documentation you must install the :code:`yelp-tools` package.
194-
On Linux this package can be found in the package manager for your distribution,
195-
on OSX we recommend using `TingPing's homebrew-gnome tap <https://github.com/TingPing/homebrew-gnome>`_.
196-
197-
Then use the following :code:`./configure` options:
198-
199-
* :code:`--enable-html-docs` - builds the HTML documentation
200-
* :code:`--enable-man-pages` - builds and installs the man-pages.
131+
$ git clone https://github.com/mongodb/mongo-c-driver.git
132+
$ cd mongo-c-driver
133+
$ ./autogen.sh
134+
$ make
135+
$ sudo make install

‎doc/installing.page‎

Lines changed: 89 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -51,45 +51,31 @@
5151

5252
</section>
5353

54-
<section id="build-yourself">
54+
<section id="installing-unix">
5555
<info><link type="guide" xref="index#installation" /></info>
56-
<title>Installing from Source</title>
57-
58-
<p>The following instructions are for UNIX-like systems such as GNU/Linux, FreeBSD, and Solaris. To build on Windows, see the instructions for <link xref="installing#building-windows">Building on Windows</link>.</p>
59-
60-
<p>The most recent release of libmongoc is 1.2.0 and can be <link href="https://github.com/mongodb/mongo-c-driver/releases/download/1.2.0/mongo-c-driver-1.2.0.tar.gz">downloaded here</link>. The following snippet will download and extract the current release of the driver.</p>
61-
62-
<screen><output style="prompt">$ </output><input>wget https://github.com/mongodb/mongo-c-driver/releases/download/1.2.0/mongo-c-driver-1.2.0.tar.gz</input>
63-
<output style="prompt">$ </output><input>tar -xzf mongo-c-driver-1.2.0.tar.gz</input>
64-
<output style="prompt">$ </output><input>cd mongo-c-driver-1.2.0/</input></screen>
65-
66-
<p>Minimal dependencies are needed to build the MongoDB C driver. Optionally, if you want Kerberos (GSSAPI) or SSL support, you need to install <code>libsasl2</code> and <code>OpenSSL</code> libraries and development headers respectively.</p>
67-
68-
<note>
69-
<p>
70-
In MongoDB 3.0 and later the default authentication mechanism is SCRAM-SHA-1.
71-
The MongoDB C Driver must be built with OpenSSL to use SCRAM-SHA-1 authentication,
72-
since the driver uses hash algorithms from the OpenSSL library to implement SCRAM-SHA-1,
73-
even if it connects to MongoDB over a non-SSL connection.
74-
</p>
75-
</note>
76-
77-
<p>Make sure you have access to a <link xref="installing#supported-platforms">supported toolchain</link> such as GCC, Clang, Solaris Studio, or MinGW. Optionally, <code>pkg-config</code> can be used if your system supports it to simplify locating proper compiler and linker arguments when compiling your program.</p>
78-
79-
<p>The following will configure for a typical 64-bit Linux system such as RedHat Enterprise Linux 6 or CentOS 6. Note that not all systems place 64-bit libraries in <code>/usr/lib64</code>. Check your system to see what the convention is if you are building 64-bit versions of the library.</p>
80-
81-
<screen>./configure --prefix=/usr --libdir=/usr/lib64</screen>
82-
83-
<note style="advanced">
84-
<p>If you require <code>SSL</code> add <code>--enable-ssl</code> to the above configuration. This will require the <code>openssl-devel</code> on RedHat Entrprise Linux. Other Linux-based operating systems may have another name for this package such as <code>libssl-dev</code> on Debian.</p>
85-
</note>
86-
87-
<note style="advanced">
88-
<p>If you require <code>Kerberos</code> add <code>--enable-sasl</code> to the above configuration. This will require the <code>cyrus-sasl-devel</code> on RedHat Entrprise Linux. Other Linux-based operating systems may have another name for this package.</p>
89-
</note>
90-
91-
<p>If <code>configure</code> completed successfully, you'll see something like the following describing your build configuration.</p>
92-
56+
<title>Building on Unix</title>
57+
<section id="unix-prerequisites">
58+
<title>Prerequisites</title>
59+
<p>OpenSSL is required for authentication or for SSL connections to MongoDB. Kerberos or LDAP support requires Cyrus SASL.</p>
60+
<p>To install all optional dependencies on RedHat / Fedora:</p>
61+
<screen>$ sudo yum install pkg-config openssl-devel cyrus-sasl-devel</screen>
62+
<p>On Debian / Ubuntu:</p>
63+
<screen>$ sudo apt-get install pkg-config libssl-dev libsasl2-dev</screen>
64+
<p>On FreeBSD:</p>
65+
<screen>$ su -c 'pkg install pkgconf openssl cyrus-sasl2'</screen>
66+
</section>
67+
<section id="unix-build">
68+
<title>Building from a release tarball</title>
69+
<p>Unless you intend on contributing to the mongo-c-driver, you will want to build from a release tarball.</p>
70+
<p>The most recent release of libmongoc is 1.2.0 and can be <link href="https://github.com/mongodb/mongo-c-driver/releases/download/1.2.0/mongo-c-driver-1.2.0.tar.gz">downloaded here</link>. The following snippet will download and extract the driver, and configure it:</p>
71+
72+
<screen>
73+
$ wget https://github.com/mongodb/mongo-c-driver/releases/download/1.2.0/mongo-c-driver-1.2.0.tar.gz
74+
$ tar xzf mongo-c-driver-1.2.0.tar.gz
75+
$ cd mongo-c-driver-1.2.0
76+
$ ./configure
77+
</screen>
78+
<p>If <code>configure</code> completed successfully, you'll see something like the following describing your build configuration.</p>
9379
<screen>libmongoc was configured with the following options:
9480

9581
Build configuration:
@@ -105,30 +91,75 @@ SSL : yes
10591
Libbson : bundled
10692

10793
Documentation:
108-
Generate man pages : yes
109-
Install man pages : yes
110-
</screen>
111-
112-
<p>We can now build the driver with the venerable <code>make</code> program.</p>
113-
114-
<screen><output style="prompt">$ </output><input>make</input></screen>
115-
116-
<note>
117-
<p>You can optionally build code objects in parallel using the <code>-j</code> option to GNU make. Some implementations of <code>make</code> do not support this option, such as Sun's make on Solaris. To build in parallel on an 8 core machine, you might use:</p>
118-
<screen><output style="prompt">$ </output><input>gmake -j8</input></screen>
119-
</note>
120-
121-
<p>To install the driver, we use <code>make</code> with the <code>install</code> target.</p>
122-
123-
<screen><output style="prompt">$ </output><input>sudo make install</input></screen>
124-
125-
<note>
126-
<p>On systems that do not support the <code>sudo</code> command, we can use <code>su -c 'make install'</code>.</p>
127-
</note>
94+
Generate man pages : no
95+
Install man pages : no</screen>
96+
<p>mongo-c-driver contains a copy of libbson as a git submodule, in case your system does not already have libbson installed. The configure script will detect if libbson is not installed and use the bundled libbson.</p>
97+
98+
<screen>
99+
$ make
100+
$ sudo make install
101+
</screen>
102+
</section>
103+
<section id="unix-build-git">
104+
<title>Building from git</title>
105+
<p>To build an unreleased version of the driver from git requires additional dependencies.</p>
106+
<p>RedHat / Fedora:</p>
107+
<screen>$ sudo yum install git gcc automake autoconf libtool</screen>
108+
<p>Debian / Ubuntu:</p>
109+
<screen>$ sudo apt-get install git gcc automake autoconf libtool</screen>
110+
<p>FreeBSD:</p>
111+
<screen>$ su -c 'pkg install git gcc automake autoconf libtool'</screen>
112+
</section>
113+
<section id="unix-build-docs">
114+
<title>Generating the documentation</title>
115+
<p>Install the <code>yelp-tools</code> and <code>yelp-xsl</code> packages, then:</p>
116+
<screen>$ ./configure --enable-html-docs --enable-man-pages
117+
$ make man html</screen>
118+
</section>
119+
</section>
128120

121+
<section id="installing-osx">
122+
<info><link type="guide" xref="index#installation" /></info>
123+
<title>Building on Mac OS X</title>
124+
<section id="prerequisites-osx">
125+
<title>Prerequisites</title>
126+
<section id="gcc-osx">
127+
<title>XCode Command Line Tools</title>
128+
<p>To install the XCode Command Line Tools, just type <code>xcode-select --install</code> in the Terminal and follow the instructions.</p>
129+
</section>
130+
<section id="openssl-el-capitan">
131+
<title>OpenSSL support on El Capitan</title>
132+
<p>Beginning in OS X 10.11 El Capitan, OS X no longer includes the OpenSSL headers. To build the driver with SSL on El Capitan and later, first <link href="http://brew.sh/">install Homebrew according to its instructions</link>, then:</p>
133+
<screen>
134+
$ brew install openssl
135+
$ export LDFLAGS="-L/usr/local/opt/openssl/lib"
136+
$ export CPPFLAGS="-I/usr/local/opt/openssl/include"</screen>
137+
</section>
138+
</section>
139+
<section id="building-osx">
140+
<title>Building on OS X</title>
141+
<p>Download the latest release tarball:</p>
142+
<screen>
143+
$ curl -LO https://github.com/mongodb/mongo-c-driver/releases/download/1.2.0/mongo-c-driver-1.2.0.tar.gz
144+
$ tar xzf mongo-c-driver-1.2.0.tar.gz
145+
$ cd mongo-c-driver-1.2.0</screen>
146+
<p>Build and install the driver:</p>
147+
<screen>
148+
$ ./configure
149+
$ make
150+
$ sudo make install</screen>
151+
</section>
152+
<section id="build-docs-osx">
153+
<title>Generating the documentation on OS X</title>
154+
<p>Homebrew is required to generate the driver's HTML documentation and man pages:</p>
155+
<screen>$ brew install yelp-xsl yelp-tools
156+
$ ./configure --enable-html-docs --enable-man-pages
157+
$ make man html</screen>
158+
</section>
129159
</section>
130160

131161
<section id="building-windows">
162+
<info><link type="guide" xref="index#installation" /></info>
132163
<title>Building on Windows</title>
133164

134165
<p>Building on Windows requires Windows Vista or newer and Visual Studio 2010 or newer. Additionally, <code>cmake</code> is required to generate Visual Studio project files.</p>

0 commit comments

Comments
 (0)