cpp-netlib.github.com/0.11.1/getting_started.html at master · cpp-netlib/cpp-netlib.github.com

History

357 lines (345 loc) · 23.5 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

<title>Getting Started — cpp-netlib v0.11.1</title>

var DOCUMENTATION_OPTIONS = {

URL_ROOT: './',

VERSION: '0.11.1',

COLLAPSE_INDEX: false,

FILE_SUFFIX: '.html',

HAS_SOURCE: true

};

</script>

<!--[if lte IE 6]>

<![endif]-->

</head>

<body>

<h3>Navigation</h3>

<ul>

<a href="examples.html" title="Examples"

accesskey="N">next</a></li>

<a href="whats_new.html" title="What’s New"

accesskey="P">previous</a> |</li>

<li><a href="contents.html">cpp-netlib v0.11.1</a> »</li>

</ul>

</div>

<span id="id1"></span><h1>Getting Started<a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h1>

<h2>Downloading an official release<a class="headerlink" href="#downloading-an-official-release" title="Permalink to this headline">¶</a></h2>

<p>You can find links to the latest official release from the project’s official

website:</p>

<div><a class="reference external" href="http://cpp-netlib.org/">http://cpp-netlib.org/</a></div></blockquote>

<p>All previous stable versions of <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt> can be downloaded from

<a class="reference external" href="http://github.com/cpp-netlib/cpp-netlib/downloads">Github</a> from this url:</p>

<div><a class="reference external" href="http://github.com/cpp-netlib/cpp-netlib/downloads">http://github.com/cpp-netlib/cpp-netlib/downloads</a></div></blockquote>

<p>Each release is available as gzipped (Using the command

<tt class="docutils literal"><span class="pre">tar</span> <span class="pre">xzf</span> <span class="pre">cpp-netlib.tar.gz</span></tt>) or bzipped (Using <tt class="docutils literal"><span class="pre">tar</span> <span class="pre">xjf</span>

<span class="pre">cpp-netlib.tar.bz2</span></tt>) tarball, or as a zipfile (<tt class="docutils literal"><span class="pre">unzip</span>

<span class="pre">cpp-netlib.zip</span></tt>, or on Windows using a tool such as <a class="reference external" href="http://www.7-zip.org/">7zip</a>).</p>

</div>

<h2>Downloading a development version<a class="headerlink" href="#downloading-a-development-version" title="Permalink to this headline">¶</a></h2>

<p>The <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt> uses <a class="reference external" href="http://git-scm.com/">Git</a> for source control, so to use any

development versions Git must be installed on your system.</p>

<p>Using the command line, the command to get the latest code is:</p>

<div class="highlight-python"><div class="highlight"><pre>shell$ git clone git://github.com/cpp-netlib/cpp-netlib.git

</pre></div>

</div>

<p>This should be enough information get to started. To do more complex

things with Git, such as pulling changes or checking out a new branch,

refer to the <a class="reference external" href="http://git-scm.com/documentation">Git documentation</a>.</p>

<p class="last">Previous versions of <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt> referred to the

<em>mikhailberis</em> repository as the main development repository. This

account is still valid, but not always up-to-date. In the interest of

consistency, the main repository has been changed to <em>cpp-netlib</em>.</p>

</div>

<p>Windows users need to use <a class="reference external" href="http://code.google.com/p/msysgit/downloads/list">msysGit</a>, and to invoke the command above

from a shell.</p>

<p>For fans of <a class="reference external" href="http://subversion.tigris.org/">Subversion</a>, the same code can be checked out from

<a class="reference external" href="http://svn.github.com/cpp-netlib/cpp-netlib.git">http://svn.github.com/cpp-netlib/cpp-netlib.git</a>.</p>

<p class="last">The <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt> project is hosted on <a class="reference external" href="http://github.com/cpp-netlib/cpp-netlib/downloads">GitHub</a> and follows the

prescribed development model for <a class="reference external" href="http://github.com/cpp-netlib/cpp-netlib/downloads">GitHub</a> based projects. This means in case

you want to submit patches, you will have to create a fork of the project

(read up on <a class="reference external" href="http://help.github.com/forking/">forking</a>) and then submit a pull request (read up on submitting

<a class="reference external" href="http://help.github.com/pull-requests/">pull requests</a>).</p>

</div>

<h2>Getting Boost<a class="headerlink" href="#getting-boost" title="Permalink to this headline">¶</a></h2>

<p><tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt> depends on <a class="reference external" href="http://www.boost.org/doc/libs/release/more/getting_started/index.html">Boost</a>. It should work for any version

of Boost above 1.50.0. If Boost is not installed on your system, the

latest package can be found on the <a class="reference external" href="http://www.boost.org/users/download/">Boost web-site</a>. The environment

variable <tt class="docutils literal"><span class="pre">BOOST_ROOT</span></tt> must be defined, which must be the full path

name of the top directory of the Boost distribution. Although Boost

is mostly header only, applications built using <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt>

still requires linking with <a class="reference external" href="http://www.boost.org/libs/system/index.html">Boost.System</a>, <a class="reference external" href="http://www.boost.org/libs/date_time/index.html">Boost.Date_time</a>, and

<a class="reference external" href="http://www.boost.org/libs/regex/index.html">Boost.Regex</a>.</p>

<p class="last">You can follow the steps in the <a class="reference external" href="http://www.boost.org/doc/libs/release/more/getting_started/index.html">Boost Getting Started</a> guide to

install Boost into your development system.</p>

</div>

<p class="first admonition-title">Warning</p>

<p class="last">There is a known incompatibility between <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt> and

Boost 1.46.1 on some compilers. It is not recommended to use <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt>

with Boost 1.46.1. Some have reported though that Boost 1.47.0

and <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt> work together better.</p>

</div>

<h2>Getting CMake<a class="headerlink" href="#getting-cmake" title="Permalink to this headline">¶</a></h2>

<p>The <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt> uses <a class="reference external" href="http://www.cmake.org/">CMake</a> to generate platform-specific build files. If

you intend to run the test suite, you can follow the instructions below.

Otherwise, you don’t need CMake to use <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt> in your project. The

<tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt> requires CMake version 2.8 or higher.</p>

<p>Let’s assume that you have unpacked the <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt> at the top of your

HOME directory. On Unix-like systems you will typically be able to change into

your HOME directory using the command <tt class="docutils literal"><span class="pre">cd</span> <span class="pre">~</span></tt>. This sample below assumes that

the <tt class="docutils literal"><span class="pre">~/cpp-netlib</span></tt> directory exists, and is the top-level directory of the

<tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt> release.</p>

</div>

<h2>Building with CMake<a class="headerlink" href="#building-with-cmake" title="Permalink to this headline">¶</a></h2>

<p>To build the tests that come with <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt>, we first need to configure the

build system to use our compiler of choice. This is done by running the

<tt class="docutils literal"><span class="pre">cmake</span></tt> command at the top-level directory of <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt> with

additional parameters:</p>

<div class="highlight-python"><div class="highlight"><pre>$ mkdir ~/cpp-netlib-build

$ cd ~/cpp-netlib-build

$ cmake -DCMAKE_BUILD_TYPE=Debug \

> -DCMAKE_C_COMPILER=gcc \

> -DCMAKE_CXX_COMPILER=g++ \

> ../cpp-netlib

</pre></div>

</div>

<p class="last">While it’s not compulsory, it’s recommended that

<tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt> is built outside the source directory.

For the purposes of documentation, we’ll assume that all

builds are done in <tt class="docutils literal"><span class="pre">~/cpp-netlib-build</span></tt>.</p>

</div>

<p>If you intend to use the SSL support when using the HTTP client libraries in

<tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt>, you may need to build it with <a class="reference external" href="http://www.openssl.org/">OpenSSL</a> installed or at least

available to CMake. If you have the development headers for <a class="reference external" href="http://www.openssl.org/">OpenSSL</a> installed

on your system when you build <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt>, CMake will be able to detect it

and set the <tt class="docutils literal"><span class="pre">BOOST_NETWORK_ENABLE_HTTPS</span></tt> macro when building the library to

support HTTPS URIs.</p>

<p>One example for building the library with <a class="reference external" href="http://www.openssl.org/">OpenSSL</a> support with a custom

(non-installed) version of <a class="reference external" href="http://www.openssl.org/">OpenSSL</a> is by doing the following:</p>

<div class="highlight-python"><div class="highlight"><pre>$ cmake -DCMAKE_BUILD_TYPE=Debug \

> -DCMAKE_C_COMPILER=clang \

> -DCMAKE_CXX_COMPILER=clang++ \

> -DOPENSSL_ROOT_DIR=/Users/dberris/homebrew/Cellar/openssl/1.0.1f

> ../cpp-netlib

</pre></div>

</div>

<p>You can also use a different root directory for the <a class="reference external" href="http://www.boost.org/doc/libs/release/more/getting_started/index.html">Boost</a> project by using the

<tt class="docutils literal"><span class="pre">-DBOOST_ROOT</span></tt> configuration option to CMake. This is useful if you intend to

build the library with a specific version of Boost that you’ve built in a

separate directory:</p>

<div class="highlight-python"><div class="highlight"><pre>$ cmake -DCMAKE_BUILD_TYPE=Debug \

> -DCMAKE_C_COMPILER=clang \

> -DCMAKE_CXX_COMPILER=clang++ \

> -DOPENSSL_ROOT_DIR=/Users/dberris/homebrew/Cellar/openssl/1.0.1f \

> -DBOOST_ROOT=/Users/dberris/Source/boost_1_55_0

> ../cpp-netlib

</pre></div>

</div>

<h3>Building on Linux<a class="headerlink" href="#building-on-linux" title="Permalink to this headline">¶</a></h3>

<p>On Linux, this will generate the appropriate Makefiles that will enable you to

build and run the tests and examples that come with <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt>. To build

the tests, you can run <tt class="docutils literal"><span class="pre">make</span></tt> in the same top-level directory of

<tt class="docutils literal"><span class="pre">~/cpp-netlib-build</span></tt>:</p>

<div class="highlight-python"><div class="highlight"><pre>$ make

</pre></div>

</div>

<p>Just like with traditional GNU Make, you can add the <tt class="docutils literal"><span class="pre">-j</span></tt> parameter

to specify how many parallel builds to run. In case you’re in a sufficiently

powerful system and would like to parallelize the build into 4 jobs, you can

do this with:</p>

</pre></div>

</div>

<p class="last">As a caveat, <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt> is heavy on template metaprogramming and will

require a lot of computing and memory resources to build the individual

tests. Do this at the risk of <a class="reference external" href="http://en.wikipedia.org/wiki/Thrashing_(computer_science)">thrashing</a> your system. However, this

compile-time burden is much reduced in recent versions.</p>

</div>

<p>Once the build has completed, you can now run the test suite by issuing:</p>

<div class="highlight-python"><div class="highlight"><pre>$ make test

</pre></div>

</div>

<p>You can install <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt> by issuing:</p>

<div class="highlight-python"><div class="highlight"><pre>$ sudo make install

</pre></div>

</div>

<p>By default this installs <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt> into <tt class="docutils literal"><span class="pre">/usr/local</span></tt>.</p>

<p>As of version 0.9.3, <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt> produces three static

libraries. Using GCC on Linux these are:</p>

<div class="highlight-python"><div class="highlight"><pre><span class="n">libcppnetlib</span><span class="o">-</span><span class="n">client</span><span class="o">-</span><span class="n">connections</span><span class="o">.</span><span class="n">a</span>

<span class="n">libcppnetlib</span><span class="o">-</span><span class="n">server</span><span class="o">-</span><span class="n">parsers</span><span class="o">.</span><span class="n">a</span>

<span class="n">libcppnetlib</span><span class="o">-</span><span class="n">uri</span><span class="o">.</span><span class="n">a</span>

</pre></div>

</div>

<p class="last">Users can find them in <tt class="docutils literal"><span class="pre">~/cpp-netlib-build/libs/network/src</span></tt>.</p>

</div>

<h3>Building On Windows<a class="headerlink" href="#building-on-windows" title="Permalink to this headline">¶</a></h3>

<p>If you’re using the Microsoft Visual C++ compiler or the Microsoft Visual Studio

IDE and you would like to build <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt> from within Visual Studio, you

can look for the solution and project files as the artifacts of the call to

<tt class="docutils literal"><span class="pre">cmake</span></tt> – the file should be named <tt class="docutils literal"><span class="pre">CPP-NETLIB.sln</span></tt> (the solution) along

with a number of project files for Visual Studio.</p>

<p>As of version 0.9.3, <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt> produces three static

libraries. Using Visual C++ on Windows they are:</p>

<div class="highlight-python"><div class="highlight"><pre><span class="n">cppnetlib</span><span class="o">-</span><span class="n">client</span><span class="o">-</span><span class="n">connections</span><span class="o">.</span><span class="n">lib</span>

<span class="n">cppnetlib</span><span class="o">-</span><span class="n">server</span><span class="o">-</span><span class="n">parsers</span><span class="o">.</span><span class="n">lib</span>

<span class="n">cppnetlib</span><span class="o">-</span><span class="n">uri</span><span class="o">.</span><span class="n">lib</span>

</pre></div>

</div>

<p class="last">Users can find them in <tt class="docutils literal"><span class="pre">~/cpp-netlib-build/libs/network/src</span></tt>.</p>

</div>

<h2>Using <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt><a class="headerlink" href="#using-cpp-netlib" title="Permalink to this headline">¶</a></h2>

<h3>CMake projects<a class="headerlink" href="#cmake-projects" title="Permalink to this headline">¶</a></h3>

<p>Projects using CMake can add the following lines in their <tt class="docutils literal"><span class="pre">CMakeLists.txt</span></tt> to

be able to use <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt>:</p>

<div class="highlight-python"><div class="highlight"><pre>set ( CMAKE_PREFIX_PATH ${CMAKE_PREFIX_PATH} ~/cpp-netlib-build )

find_package ( cppnetlib 0.11.0 REQUIRED )

include_directories ( ${CPPNETLIB_INCLUDE_DIRS} )

target_link_libraries ( MyApplication ${CPPNETLIB_LIBRARIES} )

</pre></div>

</div>

<p class="last">Setting <tt class="docutils literal"><span class="pre">CMAKE_PREFIX_PATH</span></tt> is only required when <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt>

is not installed to a location that CMake searches. When <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt>

is installed to the default location (<tt class="docutils literal"><span class="pre">/usr/local</span></tt>), <tt class="docutils literal"><span class="pre">CMake</span></tt> can find it.</p>

</div>

<p class="last">We assume that <tt class="docutils literal"><span class="pre">MyApplication</span></tt> is the application that you are

building and which depends on <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt>.</p>

</div>

<h2>Reporting Issues, Getting Support<a class="headerlink" href="#reporting-issues-getting-support" title="Permalink to this headline">¶</a></h2>

<p>In case you find yourself stuck or if you’ve found a bug (or you want to just

join the discussion) you have a few options to choose from.</p>

<p>For reporting bugs, feature requests, and asking questions about the

implementation and/or the documentation, you can go to the GitHub issues page

for the project at <a class="reference external" href="http://github.com/cpp-netlib/cpp-netlib/issues">http://github.com/cpp-netlib/cpp-netlib/issues</a>.</p>

<p>You can also opt to join the developers mailing list for a more personal

interaction with the developers of the project. You can join the mailing list

through <a class="reference external" href="http://groups.google.com/forum/#!forum/cpp-netlib">http://groups.google.com/forum/#!forum/cpp-netlib</a>.</p>

</div>

<h3><a href="contents.html">Table Of Contents</a></h3>

<ul>

<li><a class="reference internal" href="#">Getting Started</a><ul>

<li><a class="reference internal" href="#downloading-an-official-release">Downloading an official release</a></li>

<li><a class="reference internal" href="#downloading-a-development-version">Downloading a development version</a></li>

<li><a class="reference internal" href="#getting-boost">Getting Boost</a></li>

<li><a class="reference internal" href="#getting-cmake">Getting CMake</a></li>

<li><a class="reference internal" href="#building-with-cmake">Building with CMake</a><ul>

<li><a class="reference internal" href="#building-on-linux">Building on Linux</a></li>

<li><a class="reference internal" href="#building-on-windows">Building On Windows</a></li>

</ul>

</li>

<li><a class="reference internal" href="#using-cpp-netlib">Using <tt class="docutils literal"><span class="pre">cpp-netlib</span></tt></a><ul>

<li><a class="reference internal" href="#cmake-projects">CMake projects</a></li>

</ul>

</li>

<li><a class="reference internal" href="#reporting-issues-getting-support">Reporting Issues, Getting Support</a></li>

</ul>

</li>

</ul>

<h4>Previous topic</h4>

<p class="topless"><a href="whats_new.html"

title="previous chapter">What’s New</a></p>

<h4>Next topic</h4>

<p class="topless"><a href="examples.html"

title="next chapter">Examples</a></p>

<h3>Quick search</h3>

</form>

Enter search terms or a module, class or function name.

</p>

</div>

</div>

</div>

<h3>Navigation</h3>

<ul>

<a href="examples.html" title="Examples"

>next</a></li>

<a href="whats_new.html" title="What’s New"

>previous</a> |</li>

<li><a href="contents.html">cpp-netlib v0.11.1</a> »</li>

</ul>

</div>

Last updated on Dec 18, 2014.

Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.

</div>

</body>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

getting_started.html

Latest commit

History

getting_started.html

File metadata and controls