examples/cpp/README.adoc - kudu - Git at Google

 // Licensed to the Apache Software Foundation (ASF) under one
 // or more contributor license agreements.  See the NOTICE file
 // distributed with this work for additional information
 // regarding copyright ownership.  The ASF licenses this file
 // to you under the Apache License, Version 2.0 (the
 // "License"); you may not use this file except in compliance
 // with the License.  You may obtain a copy of the License at
 //
 //   http://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing,
 // software distributed under the License is distributed on an
 // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 // KIND, either express or implied.  See the License for the
 // specific language governing permissions and limitations
 // under the License.
 = Kudu {cpp} client example README
 :author: Kudu Team
 :homepage: https://kudu.apache.org/

 == Summary
 The Kudu {cpp} client library distribution contains a {cpp} example application
 that demonstrates how to use the Kudu {cpp} client API.  The example
 can be used as a starting point for a custom Kudu {cpp} client application.
 This note contains information on how to build the Kudu {cpp} client example.

 == How to build the example if installing Kudu from packages
 This section describes how to build the example if installing Kudu
 using pre-built packages.

 . Install the required packages as described in the
 https://kudu.apache.org/docs/installation.html#install_packages[documentation on the Kudu Web site].
 The `kudu-client0` package (`libkuduclient0` on Debian/Ubuntu Linux
 distributions) contains the Kudu {cpp} client library, and the `kudu-client-dev`
 package (`libkuduclient-dev` on Debian/Ubuntu Linux distributions) contains
 the Kudu {cpp} client header files and {cpp} code example (`example.cc`)
 along with other auxiliary content.

 . Make sure `cmake` of version at least 2.8 is installed on the system.

 . Copy the example into a custom location where you would like to work
 with the code. Working in the `/usr/share/doc/kuduClient/examples`
 directory is possible but is not recommended since it requires
 super-user access and pollutes the `example` directory with
 intermediate files.
 For example, to copy the `/usr/share/doc/kuduClient/examples` directory
 recursively into `/tmp/kuduClient`:
 +
 [source,bash]
 ----
 cp -r /usr/share/doc/kuduClient/examples /tmp/kuduClient
 ----

 . Navigate into the directory where the `example.cc.gz` file was copied and
 unpack the example source file.  For example:
 +
 [source,bash]
 ----
 cd /tmp/kuduClient/examples
 gunzip example.cc.gz
 ----

 . Run `cmake` to generate appropriate makefiles.  For example, if targeting
 for a debug build
 +
 [source,bash]
 ----
 cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=debug
 ----
 +
 For a release build, use `release` for `CMAKE_BUILD_TYPE` instead.

 . Run `make` to build the example:
 +
 [source,bash]
 ----
 make
 ----

 == How to build the example if building Kudu from source
 This section describes how to build the example if building Kudu from source.
 To install the `example.cc` and other files, an alternate destination root
 is used.

 Specifying an alternate destination root allows you to install the
 Kudu {cpp} client library, the example file, and other content
 under the specified destination prefix.

 . Follow the https://kudu.apache.org/docs/installation.html#_build_from_source[instructions on the Kudu Web site]
 to build the project from source.

 . Once the project is built, change into the `<build_dir>/src/kudu/client`
 sub-directory.

 . Run `make install` with an alternate destination root. For example, if
 installing into `/tmp/client_alt_root`
 +
 [source,bash]
 ----
 make install DESTDIR=/tmp/client_alt_root
 ----

 . Change the current working directory into the
 `usr/local/share/doc/kuduClient/examples` subdirectory of the alternate
 destination root.  For example, if installing into `/tmp/client_alt_root`
 +
 [source,bash]
 ----
 cd /tmp/client_alt_root/usr/local/share/doc/kuduClient/examples
 ----

 . Run `cmake` to generate appropriate makefiles. For example, if installing
 into `/tmp/client_alt_root` and targeting for a debug build
 +
 [source,bash]
 ----
 cmake -G "Unix Makefiles" -DkuduClient_DIR=/tmp/client_alt_root/usr/local/share/kuduClient/cmake -DCMAKE_BUILD_TYPE=debug
 ----
 +
 For a release build, set `release` for `CMAKE_BUILD_TYPE` instead.

 . Run `make` to build the example:
 +
 [source,bash]
 ----
 make
 ----

 == Running the sample application
 After the example is built, it is ready to run against your Kudu cluster.
 The example application assumes the target Kudu cluster has at least 3
 running tablet servers, because it creates a table with replication factor 3.
 If that's not the case, modify `example.cc` accordingly and re-compile. By
 default, the `example` binary runs against a local Kudu master using the
 default port 7051. You may also specify a different master or multiple masters
 as arguments to the binary, as shown. The following output shows a successful
 invocation of the example application, with some uninteresting log messages
 removed:

 [source,bash]
 ----
 $ ./example localhost:9876 localhost:9877 localhost:9878
 Running with Kudu client version: kudu 1.8.0-SNAPSHOT (rev bbbb45fd31f2eb1570563e925639e549047b0707)
 Long version info: kudu 1.8.0-SNAPSHOT
 revision bbbb45fd31f2eb1570563e925639e549047b0707
 build type DEBUG
 built by wdberkeley at 27 Mar 2018 23:52:18 PST on cloudbook.local
 Received log message from Kudu client library
  Severity: 0
  Filename: /Users/wdberkeley/src/kudu/src/kudu/util/thread.cc
  Line number: 570
  Time: Wed Mar 28 01:50:48 2018
  Message: Started thread 17452818 - kernel-watchdog:kernel-watcher
  ...
  Received log message from Kudu client library
  Severity: 0
  Filename: /Users/wdberkeley/src/kudu/src/kudu/client/client-internal.cc
  Line number: 581
  Time: Wed Mar 28 01:50:48 2018
  Message: Considering host 192.168.1.4 local
 Created a client connection
 Created a schema
 Created a table
 Altered a table
 Inserted some rows into a table
 Scanned some rows out of a table
 Deleted a table
 Done
 ----

 == References
 . https://kudu.apache.org/[The Kudu Project Web Site]
 . https://kudu.apache.org/cpp-client-api/[Kudu {cpp} client API documentation]
	// Licensed to the Apache Software Foundation (ASF) under one
	// or more contributor license agreements. See the NOTICE file
	// distributed with this work for additional information
	// regarding copyright ownership. The ASF licenses this file
	// to you under the Apache License, Version 2.0 (the
	// "License"); you may not use this file except in compliance
	// with the License. You may obtain a copy of the License at
	//
	// http://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing,
	// software distributed under the License is distributed on an
	// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	// KIND, either express or implied. See the License for the
	// specific language governing permissions and limitations
	// under the License.
	= Kudu {cpp} client example README
	:author: Kudu Team
	:homepage: https://kudu.apache.org/

	== Summary
	The Kudu {cpp} client library distribution contains a {cpp} example application
	that demonstrates how to use the Kudu {cpp} client API. The example
	can be used as a starting point for a custom Kudu {cpp} client application.
	This note contains information on how to build the Kudu {cpp} client example.

	== How to build the example if installing Kudu from packages
	This section describes how to build the example if installing Kudu
	using pre-built packages.

	. Install the required packages as described in the
	https://kudu.apache.org/docs/installation.html#install_packages[documentation on the Kudu Web site].
	The `kudu-client0` package (`libkuduclient0` on Debian/Ubuntu Linux
	distributions) contains the Kudu {cpp} client library, and the `kudu-client-dev`
	package (`libkuduclient-dev` on Debian/Ubuntu Linux distributions) contains
	the Kudu {cpp} client header files and {cpp} code example (`example.cc`)
	along with other auxiliary content.

	. Make sure `cmake` of version at least 2.8 is installed on the system.

	. Copy the example into a custom location where you would like to work
	with the code. Working in the `/usr/share/doc/kuduClient/examples`
	directory is possible but is not recommended since it requires
	super-user access and pollutes the `example` directory with
	intermediate files.
	For example, to copy the `/usr/share/doc/kuduClient/examples` directory
	recursively into `/tmp/kuduClient`:
	+
	[source,bash]
	----
	cp -r /usr/share/doc/kuduClient/examples /tmp/kuduClient
	----

	. Navigate into the directory where the `example.cc.gz` file was copied and
	unpack the example source file. For example:
	+
	[source,bash]
	----
	cd /tmp/kuduClient/examples
	gunzip example.cc.gz
	----

	. Run `cmake` to generate appropriate makefiles. For example, if targeting
	for a debug build
	+
	[source,bash]
	----
	cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=debug
	----
	+
	For a release build, use `release` for `CMAKE_BUILD_TYPE` instead.

	. Run `make` to build the example:
	+
	[source,bash]
	----
	make
	----

	== How to build the example if building Kudu from source
	This section describes how to build the example if building Kudu from source.
	To install the `example.cc` and other files, an alternate destination root
	is used.

	Specifying an alternate destination root allows you to install the
	Kudu {cpp} client library, the example file, and other content
	under the specified destination prefix.

	. Follow the https://kudu.apache.org/docs/installation.html#_build_from_source[instructions on the Kudu Web site]
	to build the project from source.

	. Once the project is built, change into the `<build_dir>/src/kudu/client`
	sub-directory.

	. Run `make install` with an alternate destination root. For example, if
	installing into `/tmp/client_alt_root`
	+
	[source,bash]
	----
	make install DESTDIR=/tmp/client_alt_root
	----

	. Change the current working directory into the
	`usr/local/share/doc/kuduClient/examples` subdirectory of the alternate
	destination root. For example, if installing into `/tmp/client_alt_root`
	+
	[source,bash]
	----
	cd /tmp/client_alt_root/usr/local/share/doc/kuduClient/examples
	----

	. Run `cmake` to generate appropriate makefiles. For example, if installing
	into `/tmp/client_alt_root` and targeting for a debug build
	+
	[source,bash]
	----
	cmake -G "Unix Makefiles" -DkuduClient_DIR=/tmp/client_alt_root/usr/local/share/kuduClient/cmake -DCMAKE_BUILD_TYPE=debug
	----
	+
	For a release build, set `release` for `CMAKE_BUILD_TYPE` instead.

	. Run `make` to build the example:
	+
	[source,bash]
	----
	make
	----

	== Running the sample application
	After the example is built, it is ready to run against your Kudu cluster.
	The example application assumes the target Kudu cluster has at least 3
	running tablet servers, because it creates a table with replication factor 3.
	If that's not the case, modify `example.cc` accordingly and re-compile. By
	default, the `example` binary runs against a local Kudu master using the
	default port 7051. You may also specify a different master or multiple masters
	as arguments to the binary, as shown. The following output shows a successful
	invocation of the example application, with some uninteresting log messages
	removed:

	[source,bash]
	----
	$ ./example localhost:9876 localhost:9877 localhost:9878
	Running with Kudu client version: kudu 1.8.0-SNAPSHOT (rev bbbb45fd31f2eb1570563e925639e549047b0707)
	Long version info: kudu 1.8.0-SNAPSHOT
	revision bbbb45fd31f2eb1570563e925639e549047b0707
	build type DEBUG
	built by wdberkeley at 27 Mar 2018 23:52:18 PST on cloudbook.local
	Received log message from Kudu client library
	Severity: 0
	Filename: /Users/wdberkeley/src/kudu/src/kudu/util/thread.cc
	Line number: 570
	Time: Wed Mar 28 01:50:48 2018
	Message: Started thread 17452818 - kernel-watchdog:kernel-watcher
	...
	Received log message from Kudu client library
	Severity: 0
	Filename: /Users/wdberkeley/src/kudu/src/kudu/client/client-internal.cc
	Line number: 581
	Time: Wed Mar 28 01:50:48 2018
	Message: Considering host 192.168.1.4 local
	Created a client connection
	Created a schema
	Created a table
	Altered a table
	Inserted some rows into a table
	Scanned some rows out of a table
	Deleted a table
	Done
	----

	== References
	. https://kudu.apache.org/[The Kudu Project Web Site]
	. https://kudu.apache.org/cpp-client-api/[Kudu {cpp} client API documentation]