Introduce examples directory

This introduces the top-level examples directory, which will be for examples of how to use the Kudu clients and integrations. As a first step, I moved the client examples from src/kudu/client/examples to examples/cpp. I also renamed "sample" -> "example" generally. I also manually verified that the instructions in the README for building the example application still work. Change-Id: Iceca48771541f95e4f0caf8c098bc85d34aa558e Reviewed-on: http://gerrit.cloudera.org:8080/9837 Reviewed-by: Adar Dembo <[email protected]> Tested-by: Kudu Jenkins Reviewed-by: Andrew Wong <[email protected]>
cutiechi · Mar 28, 2018 · 9bf32a4 · 9bf32a4
1 parent f7ab95e
commit 9bf32a4
Show file tree

Hide file tree

Showing 5 changed files with 49 additions and 49 deletions.
diff --git a/src/kudu/client/samples/CMakeLists.txt → examples/cpp/CMakeLists.txt b/src/kudu/client/samples/CMakeLists.txt → examples/cpp/CMakeLists.txt
@@ -15,12 +15,12 @@
 # specific language governing permissions and limitations
 # under the License.
 #
-# Client API sample executables
+# Client API example executables
 
 cmake_minimum_required(VERSION 2.8)
 
 find_package(kuduClient REQUIRED)
 include_directories(${KUDU_CLIENT_INCLUDE_DIR})
 
-add_executable(sample sample.cc)
-target_link_libraries(sample kudu_client)
+add_executable(example example.cc)
+target_link_libraries(example kudu_client)
diff --git a/src/kudu/client/samples/README.adoc → examples/cpp/README.adoc b/src/kudu/client/samples/README.adoc → examples/cpp/README.adoc
@@ -14,15 +14,15 @@
 // KIND, either express or implied.  See the License for the
 // specific language governing permissions and limitations
 // under the License.
-= Kudu {cpp} client sample README
+= Kudu {cpp} client example README
 :author: Kudu Team
 :homepage: https://kudu.apache.org/
 
 == Summary
 The Kudu {cpp} client library distribution contains {cpp} example application
-that demonstrates how to use the Kudu {cpp} client API.  The sample
+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 sample.
+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
@@ -33,49 +33,49 @@ https://kudu.apache.org/docs/installation.html#install_packages[documentation on
 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 sample (`sample.cc`)
+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 sample into a custom location where you would like to work
-with the code. Working in the `/usr/share/doc/kuduClient/samples`
+. 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 `sample` directory with
+super-user access and pollutes the `example` directory with
 intermediate files.
-For example, to copy the `/usr/share/doc/kuduClient/samples` directory
+For example, to copy the `/usr/share/doc/kuduClient/examples` directory
 recursively into `/tmp/kuduClient`:
 [source,shell]
-cp -r /usr/share/doc/kuduClient/samples /tmp/kuduClient
+cp -r /usr/share/doc/kuduClient/examples /tmp/kuduClient
 
-. Navigate into the directory where the `sample.cc.gz` file was copied and
-unpack the sample source file.  For example:
+. Navigate into the directory where the `example.cc.gz` file was copied and
+unpack the example source file.  For example:
 [source,shell]
-cd /tmp/kuduClient/samples
-gunzip sample.cc.gz
+cd /tmp/kuduClient/examples
+gunzip example.cc.gz
 
 . Run `cmake` to generate appropriate makefiles.  For example, if targeting
 for a debug build
 (for a release build, use `release` for `CMAKE_BUILD_TYPE` correspondingly):
 [source,shell]
 cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=debug
 
-. Run `make` to build the sample:
+. Run `make` to build the example:
 [source,shell]
 make
 
-. After the sample is built, it is ready to run against your Kudu master server.
-The sample application assumes the target Kudu cluster has at least 3
+. After the example is built, it is ready to run against your Kudu master server.
+The example application assumes the target Kudu cluster has at least 3
 tablet servers up and running (because it creates a table with replication
-factor 3).  If it's not the case, you can modify the `sample.cc` accordingly
-and re-compile it.  Below is the sample output with log messages in the middle
-removed: the `sample` binary runs against Kudu master server running
+factor 3).  If it's not the case, you can modify the `example.cc` accordingly
+and re-compile it.  Below is the example output with log messages in the middle
+removed: the `example` binary runs against Kudu master server running
 with the default parameters at the same machine.  Port 7051 is the default
 one and could be omitted along with the preceding colomn because the master
 server is running with the default parameters (it's left only to illustrate how
 to specify port number).
 [source,shell]
-$ ./sample 127.0.0.1:7051
+$ ./example 127.0.0.1:7051
 Running with Kudu client version: kudu 1.1.0-SNAPSHOT (rev 91a1ed09c4c572a22bab15360ddaf481d5632927)
 Long version info: kudu 1.1.0-SNAPSHOT
 revision 91a1ed09c4c572a22bab15360ddaf481d5632927
@@ -105,11 +105,11 @@ Done
 
 == 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 `sample.cc` and other files, an alternate destination root
+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 sample file and other content
+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]
@@ -124,33 +124,33 @@ installing into `/tmp/client_alt_root`
 make install DESTDIR=/tmp/client_alt_root
 
 . Change the current working directory into the
-`usr/local/share/doc/kuduClient/samples` subdirectory of the alternate
+`usr/local/share/doc/kuduClient/examples` subdirectory of the alternate
 destination root.  For example, if installing into `/tmp/client_alt_root`
 [source,shell]
-cd /tmp/client_alt_root/usr/local/share/doc/kuduClient/samples
+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
 (for a release build, use `release` for `CMAKE_BUILD_TYPE` correspondingly):
 [source,shell]
 cmake -G "Unix Makefiles" -DkuduClient_DIR=/tmp/client_alt_root/usr/local/share/kuduClient/cmake -DCMAKE_BUILD_TYPE=debug
 
-. Run `make` to build the sample:
+. Run `make` to build the example:
 [source,shell]
 make
 
-. After the sample is built, it is ready to run against your Kudu master server.
-The sample application assumes the target Kudu cluster has at least 3
+. After the example is built, it is ready to run against your Kudu master server.
+The example application assumes the target Kudu cluster has at least 3
 tablet servers up and running (because it creates a table with replication
-factor 3).  If it's not the case, you can modify the `sample.cc` accordingly
-and re-compile it.  Below is the sample output with log messages in the middle
-removed: the `sample` binary runs against Kudu master server running
+factor 3).  If it's not the case, you can modify the `example.cc` accordingly
+and re-compile it.  Below is the example output with log messages in the middle
+removed: the `example` binary runs against Kudu master server running
 with the default parameters at the same machine.  Port 7051 is the default
 one and could be omitted along with the preceding colomn because the master
 server is running with the default parameters (it's left only to illustrate how
 to specify port number).
 [source,shell]
-$ ./sample 127.0.0.1:7051
+$ ./example 127.0.0.1:7051
 Running with Kudu client version: kudu 1.1.0-SNAPSHOT (rev 91a1ed09c4c572a22bab15360ddaf481d5632927)
 Long version info: kudu 1.1.0-SNAPSHOT
 revision 91a1ed09c4c572a22bab15360ddaf481d5632927

diff --git a/src/kudu/client/samples/sample.cc → examples/cpp/example.cc b/src/kudu/client/samples/sample.cc → examples/cpp/example.cc
diff --git a/src/kudu/client/CMakeLists.txt b/src/kudu/client/CMakeLists.txt
@@ -199,13 +199,13 @@ install(FILES
   ../util/status.h
   DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/kudu/util)
 
-# Client sample code.
+# Client example code.
 #
 # Can't use CMAKE_INSTALL_DOCDIR because we don't ever call project().
 install(FILES
-  samples/CMakeLists.txt
-  samples/sample.cc
-  DESTINATION ${CMAKE_INSTALL_DATADIR}/doc/kuduClient/samples)
+  ../../../examples/cpp/CMakeLists.txt
+  ../../../examples/cpp/example.cc
+  DESTINATION ${CMAKE_INSTALL_DATADIR}/doc/kuduClient/examples)
 
 # Exported cmake file for just the library's targets.
 #
@@ -252,9 +252,9 @@ if (NOT APPLE AND NOT "${KUDU_GENERATE_COVERAGE}")
   ADD_KUDU_TEST(client_symbol-test.sh LABELS no_dist_test)
 endif()
 
-# The samples are never built with ASAN/TSAN.
+# The examples are never built with ASAN/TSAN.
 if(NOT "${KUDU_USE_ASAN}" AND NOT "${KUDU_USE_TSAN}")
-  ADD_KUDU_TEST(client_samples-test.sh RUN_SERIAL true LABELS no_dist_test)
+  ADD_KUDU_TEST(client_examples-test.sh RUN_SERIAL true LABELS no_dist_test)
 endif()
 set(KUDU_TEST_LINK_LIBS
   itest_util

diff --git a/src/kudu/client/client_samples-test.sh → src/kudu/client/client_examples-test.sh b/src/kudu/client/client_samples-test.sh → src/kudu/client/client_examples-test.sh
@@ -19,7 +19,7 @@
 #
 
 # This script verifies that the Kudu client library can be installed outside
-# the build tree, that the installed headers are sane, and that the sample code
+# the build tree, that the installed headers are sane, and that the example code
 # can be built and runs correctly.
 
 # Clean up after the test. Must be idempotent.
@@ -91,9 +91,9 @@ OUTPUT_DIR=$(cd $(dirname "$BASH_SOURCE"); pwd)
 
 # Install the client library to a temporary directory.
 # Try to detect whether we're building using Ninja or Make.
-LIBRARY_DIR=$(mktemp -d -t kudu-samples-test.XXXXXXXXXXXXX)
+LIBRARY_DIR=$(mktemp -d -t kudu-examples-test.XXXXXXXXXXXXX)
 PREFIX_DIR=$LIBRARY_DIR/usr/local
-SAMPLES_DIR=$PREFIX_DIR/share/doc/kuduClient/samples
+EXAMPLES_DIR=$PREFIX_DIR/share/doc/kuduClient/examples
 pushd $OUTPUT_DIR/..
 NINJA=$(which ninja 2>/dev/null) || NINJA=""
 if [ -r build.ninja -a -n "$NINJA" ]; then
@@ -131,9 +131,9 @@ if [ -z "$CMAKE" ]; then
   CMAKE=$OUTPUT_DIR/../../../thirdparty/installed/common/bin/cmake
 fi
 
-# Build the client samples using the client library.
+# Build the client examples using the client library.
 # We can just always use Make here, since we're calling cmake ourselves.
-pushd $SAMPLES_DIR
+pushd $EXAMPLES_DIR
 CMAKE_PREFIX_PATH=$PREFIX_DIR $CMAKE .
 make -j$(getconf _NPROCESSORS_ONLN)
 popd
@@ -151,7 +151,7 @@ echo Using localhost IP $LOCALHOST_IP
 export TMPDIR=${TMPDIR:-/tmp}
 export TEST_TMPDIR=${TEST_TMPDIR:-$TMPDIR/kudutest-$UID}
 mkdir -p $TEST_TMPDIR
-BASE_DIR=$(mktemp -d $TEST_TMPDIR/client_samples-test.XXXXXXXX)
+BASE_DIR=$(mktemp -d $TEST_TMPDIR/client_examples-test.XXXXXXXX)
 MASTER_RPC_PORT=7051
 mkdir -p "$BASE_DIR/master/logs"
 $OUTPUT_DIR/kudu-master \
@@ -182,7 +182,7 @@ $OUTPUT_DIR/kudu-tserver \
 TS_PID=$!
 
 # Make sure that at least it's possible to establish a TCP connection to the
-# master's and the tablet server's RPC ports before running the client sample
+# master's and the tablet server's RPC ports before running the client example
 # application.
 if ! wait_for_listen_port $MASTER_PID $MASTER_RPC_PORT 30; then
   exit_error "master is not accepting connections"
@@ -214,5 +214,5 @@ if [ $num_tservers -lt 1 ]; then
   exit_error "tserver has not registered with the master"
 fi
 
-# Run the samples.
-$SAMPLES_DIR/sample $LOCALHOST_IP
+# Run the examples.
+$EXAMPLES_DIR/example $LOCALHOST_IP