You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@geode.apache.org by db...@apache.org on 2018/05/07 21:32:41 UTC
[geode-native] branch develop updated: GEODE-4728: Docs - building
out the open source repo
This is an automated email from the ASF dual-hosted git repository.
dbarnes pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/geode-native.git
The following commit(s) were added to refs/heads/develop by this push:
new ca17a2c GEODE-4728: Docs - building out the open source repo
ca17a2c is described below
commit ca17a2cf85794982c3c04afaf610b1973c0adaa7
Author: Dave Barnes <db...@pivotal.io>
AuthorDate: Mon May 7 14:32:35 2018 -0700
GEODE-4728: Docs - building out the open source repo
---
.../source/subnavs/geode-nc-nav.erb | 41 +++++--
docs/geode-native-book/redirects.rb | 3 +
.../app-dev-walkthrough-cpp.html.md.erb | 130 +++++++++++++++++++++
.../app-dev-walkthrough-dotnet.html.md.erb | 130 +++++++++++++++++++++
.../getting-started-nc-client.html.md.erb | 70 +++++++++++
5 files changed, 365 insertions(+), 9 deletions(-)
diff --git a/docs/geode-native-book/master_middleman/source/subnavs/geode-nc-nav.erb b/docs/geode-native-book/master_middleman/source/subnavs/geode-nc-nav.erb
index 97a9373..306ac6f 100644
--- a/docs/geode-native-book/master_middleman/source/subnavs/geode-nc-nav.erb
+++ b/docs/geode-native-book/master_middleman/source/subnavs/geode-nc-nav.erb
@@ -15,13 +15,36 @@ See the License for the specific language governing permissions and
limitations under the License.
-->
<div id="sub-nav" class="js-sidenav nav-container" role="navigation">
- <a class="sidenav-title" data-behavior="SubMenuMobile">
- Doc Index</a>
- <div class="nav-content">
- <ul>
- <li>
- <a href="/docs/guide-native/15/about-client-users-guide.html">Apache Geode Native Documentation</a>
- </li>
- </ul>
- </div>
+<a class="sidenav-title" data-behavior="SubMenuMobile">Doc Index</a>
+ <div class="nav-content">
+ <ul>
+ <li>
+ <a href="/docs/guide-native/<%=vars.product_version_nodot%>/about-client-users-guide.html">Apache Geode Native Documentation</a>
+ </li>
+ <li class="has_submenu">
+ <a href="/docs/guide-native/<%=vars.product_version_nodot%>/getting-started/getting-started-nc-client.html">Getting Started with the Native Library</a>
+ <ul>
+ <li>
+ <a href="/docs/guide-native/<%=vars.product_version_nodot%>/getting-started/getting-started-nc-client.html#app_dev_walkthroughs">Application Development Walkthroughs</a>
+ </li>
+ <li>
+ <a href="/docs/guide-native/<%=vars.product_version_nodot%>/getting-started/getting-started-nc-client.html#programming_examples">Programming Examples</a>
+ </li>
+ </ul>
+ </li>
+ <li class="has_submenu">
+ <a href="/docs/guide-native/<%=vars.product_version_nodot%>/configuring/configuration.html">Configuring <%=vars.client_name%></a>
+ <ul>
+ <li class="has_submenu">
+ <a href="/docs/guide-native/<%=vars.product_version_nodot%>/configuring/system-level-configuration.html">System Level Configuration</a>
+ <ul>
+ <li>
+ <a href="/docs/guide-native/<%=vars.product_version_nodot%>/configuring/sysprops.html">System Properties</a>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </div>
</div>
diff --git a/docs/geode-native-book/redirects.rb b/docs/geode-native-book/redirects.rb
index 9a7425c..2158498 100644
--- a/docs/geode-native-book/redirects.rb
+++ b/docs/geode-native-book/redirects.rb
@@ -19,3 +19,6 @@ r301 %r{/releases/latest/javadoc/(.*)}, 'http://geode.apache.org/releases/latest
# Links to User Guides #
rewrite '/', '/docs/guide-native/15/about-client-users-guide.html'
rewrite '/index.html', '/docs/guide-native/15/about-client-users-guide.html'
+r301 %r{/gfmanual/(.*)}, 'http://gemfire.docs.pivotal.io/docs-gemfire/$1'
+r301 %r{/serverman/(.*)}, 'http://geode.apache.org/docs/guide/16/$1'
+r301 %r{/geodeman/(.*)}, 'http://geode.apache.org/docs/guide/16/$1'
\ No newline at end of file
diff --git a/docs/geode-native-docs/getting-started/app-dev-walkthrough-cpp.html.md.erb b/docs/geode-native-docs/getting-started/app-dev-walkthrough-cpp.html.md.erb
new file mode 100644
index 0000000..85015f7
--- /dev/null
+++ b/docs/geode-native-docs/getting-started/app-dev-walkthrough-cpp.html.md.erb
@@ -0,0 +1,130 @@
+---
+title: C++ Application Development Walkthrough
+---
+
+This section describes how to set up a native client development environment using C++ and CMake.
+
+## <a id="prerequisites_cpp"></a>Prerequisites
+This walkthrough assumes that certain components are in place:
+
+- The **<%=vars.product_name%> Native Client libraries**. Install the Native Client as described in
+ [Getting Started with the Native Client](getting-started-nc-client.html). Follow the ease-of-use
+ recommendations by installing the Native Client in a well-known location and renaming it.
+
+| System | Native Client Library Well-Known Location |
+|-----|-----|
+| Linux | /usr/local/nativeclient |
+| Windows | C:\Program Files\nativeclient |
+
+
+- The **CMake** tool suite. Download and install CMake, following the instructions on [cmake.org] (https://cmake.org).
+
+- **GemFire**: Install and configure GemFire. See the [_GemFire User's Guide_](http://gemfire.docs.pivotal.io/gemfire/about_gemfire.html) for instructions and system requirements.
+
+To develop a Native Client application using C++ and CMake:
+
+ - Create a project directory structure
+ - Populate the project directories with C++ source code
+ - Configure the CMake build environment
+ - Run CMake to build your application
+ - Run your application
+
+## <a id="setting_up_dirs_cpp"></a>Setting up Directories and Sources
+
+1. Create a project directory structure. In this example, the project is called MyProject. The
+directory structure provides a place for your application source files and a `cmake` modules
+directory for project-specific CMake files:
+
+ ```
+ MyProject/
+ cmake/
+ FindGemFireNative.cmake
+ CMakeLists.txt
+ main.cpp
+ ```
+
+1. Change directory to MyProject and create your application sources. In this example, we have one
+source file, `main.cpp`.
+
+## <a id="configuring_cmake_cpp"></a>Configuring CMake
+
+1. Copy the `FindGemFireNative.cmake` script from one of the Native Client examples to the `cmake` subdirectory.
+
+1. Create CMakeLists.txt. Copy the file from an example, if you like, as a starting point. The CMakeLists.txt file
+should contain the following CMake instructions:
+
+ - CMake minimum version
+
+ ```
+ cmake_minimum_required(VERSION 3.10)
+ ```
+
+ - Your project name and language
+
+ ```
+ project(MyProject LANGUAGES CXX)
+ ```
+
+ - Minimum language version. For the Native Client, the minimum C++ version is 11.
+
+ ```
+ set(CMAKE_CXX_STANDARD 11)
+ ```
+
+ - Path to the CMake modules directory where the `FindGemFireNative.cmake` script is located and an instruction
+ telling CMake to use it:
+
+ ```
+ set(CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake)
+ find_package(GemFireNative REQUIRED COMPONENTS cpp)
+ ```
+
+ - The compilation target and the source(s) to be compiled
+
+ ```
+ add_executable(MyProject main.cpp)
+
+ target_link_libraries(MyProject
+ PUBLIC
+ GemFireNative::cpp)
+ ```
+
+Combined, the above elements comprise the following CMakeLists.txt:
+
+```
+# CMakeLists.txt for C++ Native Client App
+cmake_minimum_required(VERSION 3.10)
+
+project(MyProject LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 11)
+
+set(CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake)
+
+find_package(GemFireNative REQUIRED COMPONENTS cpp)
+
+add_executable(MyProject main.cpp)
+
+target_link_libraries(MyProject
+ PUBLIC
+ GemFireNative::cpp)
+```
+
+## <a id="building_the_app_cpp"></a>Building the App
+
+1. Create a build directory and set it as your current directory:
+
+ ```
+ $ mkdir build
+ $ cd build
+ ```
+
+1. Run CMake twice, once to configure the build, then again to perform the build, generating the executable application.
+
+ ```
+ $ cmake ..
+ $ cmake --build .
+ ```
+
+This creates the executable application in your build directory.
+
diff --git a/docs/geode-native-docs/getting-started/app-dev-walkthrough-dotnet.html.md.erb b/docs/geode-native-docs/getting-started/app-dev-walkthrough-dotnet.html.md.erb
new file mode 100644
index 0000000..675122a
--- /dev/null
+++ b/docs/geode-native-docs/getting-started/app-dev-walkthrough-dotnet.html.md.erb
@@ -0,0 +1,130 @@
+---
+title: .NET Application Development Walkthrough
+---
+
+This section describes how to set up a .NET native client development environment using C# and CMake.
+
+## <a id="prerequisites_dotnet"></a>Prerequisites
+This walkthrough assumes that certain components are in place:
+
+- The **<%=vars.product_name%> Native Client libraries**. Install the Native Client as described in
+ [Getting Started with the Native Client](getting-started-nc-client.html). Follow the ease-of-use
+ recommendations by installing the Native Client in `C:\Program Files\nativeclient`.
+
+- The **CMake** tool suite. Download and install CMake, following the instructions on [cmake.org] (https://cmake.org).
+
+- **GemFire**: Install and configure GemFire. See the [_GemFire User's Guide_](http://gemfire.docs.pivotal.io/gemfire/about_gemfire.html) for instructions and system requirements.
+
+- **Visual Studio 2015** or higher and **.NET 4.5.2**.
+
+To develop a Native Client application using .NET and CMake:
+
+ - Create a project directory structure
+ - Populate the project directories with C# source code
+ - Configure the CMake build environment
+ - Run CMake to configure your application
+ - Build and run your application using Visual Studio
+
+## <a id="setting_up_dirs_dotnet"></a>Setting up Directories and Sources
+
+1. Create a project directory structure. In this example, the project is called MyProject. The
+directory structure provides a place for your application source files and a `cmake` modules
+directory for project-specific CMake files:
+
+ ```
+ MyProject\
+ cmake\
+ FindGemFireNative.cmake
+ CMakeLists.txt
+ Program.cs
+ ```
+
+1. Change directory to MyProject and create your application sources. In this example, we have one
+source file, `Program.cs`.
+
+## <a id="configuring_cmake_dotnet"></a>Configuring CMake
+
+1. Copy the `FindGemFireNative.cmake` script from one of the Native Client examples to the `cmake` subdirectory.
+
+1. Create CMakeLists.txt. Copy the file from an example, if you like, as a starting point. The CMakeLists.txt file
+should contain the following CMake instructions:
+
+ - CMake minimum version
+
+ ```
+ cmake_minimum_required(VERSION 3.10)
+ ```
+
+ - Your project name and language
+
+ ```
+ project(MyProject LANGUAGES CSharp)
+ ```
+
+ - Path to the CMake modules directory where the `FindGemFireNative.cmake` script is located and an instruction
+ telling CMake to use it:
+
+ ```
+ set(CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake)
+ find_package(GemFireNative REQUIRED COMPONENTS dotnet)
+ ```
+
+ - The compilation target and the source(s) to be compiled
+
+ ```
+ add_executable(MyProject Program.cs)
+
+ target_link_libraries(MyProject
+ PUBLIC
+ GemFireNative::dotnet)
+
+ set_target_properties(MyProject PROPERTIES
+ VS_DOTNET_TARGET_FRAMEWORK_VERSION "v4.5.2"
+ VS_DOTNET_REFERENCES "System;${GemFireNative_DOTNET_LIBRARY}")
+ ```
+
+Combined, the above elements comprise the following CMakeLists.txt:
+
+```
+# CMakeLists.txt for .NET Native Client App
+cmake_minimum_required(VERSION 3.10)
+
+project(MyProject LANGUAGES CSharp)
+
+set(CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake)
+
+find_package(GemFireNative REQUIRED COMPONENTS dotnet)
+
+add_executable(MyProject Program.cs)
+
+target_link_libraries(MyProject
+ PUBLIC
+ GemFireNative::dotnet)
+
+set_target_properties(MyProject PROPERTIES
+ VS_DOTNET_TARGET_FRAMEWORK_VERSION "v4.5.2"
+ VS_DOTNET_REFERENCES "System;${GemFireNative_DOTNET_LIBRARY}")
+```
+
+## <a id="building_the_app_dotnet"></a>Configuring the App
+
+1. Create a build directory and set it as your current directory:
+
+ ```
+ $ mkdir build
+ $ cd build
+ ```
+
+1. Run CMake to configure the build:
+
+ ```
+ $ cmake ..
+ ```
+
+This creates a Visual Studio solution for your .NET application. For example, `MyProject.sln`.
+
+## <a id="building_and_running_dotnet"></a>Building and Running the App
+
+Open the solution file in Visual Studio and build the project.
+
+
diff --git a/docs/geode-native-docs/getting-started/getting-started-nc-client.html.md.erb b/docs/geode-native-docs/getting-started/getting-started-nc-client.html.md.erb
new file mode 100644
index 0000000..e6c106f
--- /dev/null
+++ b/docs/geode-native-docs/getting-started/getting-started-nc-client.html.md.erb
@@ -0,0 +1,70 @@
+---
+title: Getting Started with the Native Library
+---
+
+To use the <%=vars.product_name%> Native Library for developing <%=vars.product_name%> client applications:
+
+- Obtain a distribution of the Native library and install it on your development platform.
+- Establish access to a new or existing <%=vars.product_name%> cluster.
+- Set up your development environment with the tools you need, such as a compiler, a dynamic loader, and an OpenSSL security library.
+- Write your client application using the <%=vars.product_name%> native library to interact with the <%=vars.product_name%> server.
+
+## <a id="establish_cluster_access"></a>Establish Access to a <%=vars.product_name%> Cluster
+
+As you develop your application, you will need access to a <%=vars.product_name%> cluster.
+Your client application connects to a <%=vars.product_name%> cluster by specifying the address (host name
+or IP address) and port number of one or more locators, and the name of a region that also exists
+on the cluster.
+
+You can choose whether to use a large, remote, production-quality cluster, a small, local,
+development cluster, or something in-between, such as a testing or experimental lab installation.
+
+See [Client-to-Server Connection Process](../client-cache/client-to-server-connection.html) for details on how your
+client application can connect to the server.
+
+Refer to the [_GemFire User's Guide_](http://gemfire.docs.pivotal.io/gemfire/about_gemfire.html) for instructions on configuring and starting the cluster.
+
+
+## <a id="set_up_dev_environment"></a>Set Up Your Development Environment
+
+Whether you are developing a C++ or .NET application, you will need some essential tools, such as a compiler and a dynamic linker.
+Your compiler must have access to the Native Client header files, and the dynamic loader must have access to the Native Client libraries.
+The header files and libraries are located in *native-client-dir*.
+
+### <a id="app_dev_walkthroughs"></a>Application Development Walkthroughs
+
+- [C++ App Development Walkthrough](app-dev-walkthrough-cpp.html)
+- [.NET App Development Walkthrough](app-dev-walkthrough-dotnet.html)
+
+## <a id="programming_examples"></a>Programming Examples
+
+The <%=vars.product_name%> Client build provides a set of programming examples to help you understand the client API.
+The `examples` directory contains CMake files and a `cpp` subdirectory containing C++ examples.
+The Windows build also includes a `dotnet` subdirectory containing C# examples.
+
+CMake files are located at each level of the directory structure to allow examples to be built individually or in groups.
+
+The directory structure resembles this hierarchy (some entries are omitted for clarity):
+
+ MyProject/
+ cmake/
+ CMakeLists.txt
+ examples/
+ BUILDING.md
+ CMakeLists.txt
+ CMakeLists.txt.in
+ cmake/
+ cpp/
+ BUILDING.md
+ customserializable/
+ customserializer/
+ put-get-remove/
+ dotnet/
+ AuthInitialize/
+ PdxAutoSerializer/
+ PutGetRemove/
+ README.md
+
+See the `BUILDING.md` or `README.md` file in each directory for detailed instructions on building
+and executing the examples, and read the source code to understand how the examples are constructed.
+
--
To stop receiving notification emails like this one, please contact
dbarnes@apache.org.