This is an automated email from the ASF dual-hosted git repository.
kou pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/master by this push:
new 6fc33e741d ARROW-17575: [Docs][C++] Update build document to follow
new CMake package (#14097)
6fc33e741d is described below
commit 6fc33e741d099259a206872d9087a6851a640537
Author: Raúl Cumplido <[email protected]>
AuthorDate: Tue Sep 13 15:48:45 2022 +0200
ARROW-17575: [Docs][C++] Update build document to follow new CMake package
(#14097)
This is a follow up to update our build documentation from the changes on
https://github.com/apache/arrow/pull/13892
Authored-by: Raúl Cumplido <[email protected]>
Signed-off-by: Sutou Kouhei <[email protected]>
---
docs/source/cpp/build_system.rst | 71 ++++++++++++++++++++++++++++++++++++++--
docs/source/java/cdata.rst | 2 +-
2 files changed, 69 insertions(+), 4 deletions(-)
diff --git a/docs/source/cpp/build_system.rst b/docs/source/cpp/build_system.rst
index d4a0c82cc6..131d7b6f85 100644
--- a/docs/source/cpp/build_system.rst
+++ b/docs/source/cpp/build_system.rst
@@ -51,7 +51,7 @@ file into an executable linked with the Arrow C++ shared
library:
find_package(Arrow REQUIRED)
add_executable(my_example my_example.cc)
- target_link_libraries(my_example PRIVATE arrow_shared)
+ target_link_libraries(my_example PRIVATE Arrow::arrow_shared)
Available variables and targets
-------------------------------
@@ -67,11 +67,76 @@ CMake variables:
In addition, it will have created some targets that you can link against
(note these are plain strings, not variables):
-* ``arrow_shared`` links to the Arrow shared libraries
-* ``arrow_static`` links to the Arrow static libraries
+* ``Arrow::arrow_shared`` links to the Arrow shared libraries
+* ``Arrow::arrow_static`` links to the Arrow static libraries
+
+For backwards compatibility purposes the ``arrow_shared`` and ``arrow_static``
+targets are also available but we recommend using ``Arrow::arrow_shared`` and
+``Arrow::arrow_static`` respectively.
In most cases, it is recommended to use the Arrow shared libraries.
+If Arrow is installed on a custom path instead of a common system one you
+will have to add the path where Arrow is installed to ``CMAKE_PREFIX_PATH``.
+
+``CMAKE_PREFIX_PATH`` can be defined as a `CMake variable
+<https://cmake.org/cmake/help/latest/variable/CMAKE_PREFIX_PATH.html>`_ or an
+`environment variable
<https://cmake.org/cmake/help/latest/envvar/CMAKE_PREFIX_PATH.html>`_.
+
+Your system might already have a ``CMAKE_PREFIX_PATH`` environment variable
+defined, use the following to expand it with the path to your Arrow
+installation. In this case ``ARROW_ROOT`` is expected to contain the
+path to your Arrow installation:
+
+.. code-block:: shell
+
+ export
CMAKE_PREFIX_PATH=${ARROW_ROOT}${CMAKE_PREFIX_PATH:+:${CMAKE_PREFIX_PATH}}
+
+In the case of using a CMake variable you can add it when configuring the
+project like the following to contain the possible existing
+``CMAKE_PREFIX_PATH`` environment variable:
+
+.. code-block:: shell
+
+ cmake ...
-DCMAKE_PREFIX_PATH=${ARROW_ROOT}${CMAKE_PREFIX_PATH:+:${CMAKE_PREFIX_PATH}}
+
+.. note::
+ The usage of ``COMPONENTS`` on our ``find_package`` implementation is
+ currently not supported.
+
+Other available packages
+------------------------
+
+There are other available packages, they can also be used with the
`find_package
+<https://cmake.org/cmake/help/latest/command/find_package.html>`_ directive.
+This is the list of available ones and the respective targets created:
+
++-----------------------------------------------+--------------------------------------------------------+-----------------------------------------------------+
+| find_package usage | shared target
| static target
|
++===============================================+========================================================+=====================================================+
+| ``find_package(ArrowCUDA REQUIRED)`` |
``ArrowCUDA::arrow_cuda_shared`` |
``ArrowCUDA::arrow_cuda_static`` |
++-----------------------------------------------+--------------------------------------------------------+-----------------------------------------------------+
+| ``find_package(ArrowDataset REQUIRED)`` |
``ArrowDataset::arrow_dataset_shared`` |
``ArrowDataset::arrow_dataset_static`` |
++-----------------------------------------------+--------------------------------------------------------+-----------------------------------------------------+
+| ``find_package(ArrowFlight REQUIRED)`` |
``ArrowFlight::arrow_flight_shared`` |
``ArrowFlight::arrow_flight_static`` |
++-----------------------------------------------+--------------------------------------------------------+-----------------------------------------------------+
+| ``find_package(ArrowFlightSql REQUIRED)`` |
``ArrowFlightSql::arrow_flight_sql_shared`` |
``ArrowFlightSql::arrow_flight_sql_static`` |
++-----------------------------------------------+--------------------------------------------------------+-----------------------------------------------------+
+| ``find_package(ArrowFlightTesting REQUIRED)`` |
``ArrowFlightTesting::arrow_flight_testing_shared`` |
``ArrowFlightTesting::arrow_flight_testing_static`` |
++-----------------------------------------------+--------------------------------------------------------+-----------------------------------------------------+
+| ``find_package(ArrowSubstrait REQUIRED)`` |
``ArrowSubstrait::arrow_substrait_shared`` |
``ArrowSubstrait::arrow_substrait_static`` |
++-----------------------------------------------+--------------------------------------------------------+-----------------------------------------------------+
+| ``find_package(ArrowTesting REQUIRED)`` |
``ArrowTesting::arrow_testing_shared`` |
``ArrowTesting::arrow_testing_static`` |
++-----------------------------------------------+--------------------------------------------------------+-----------------------------------------------------+
+| ``find_package(Gandiva REQUIRED)`` | ``Gandiva::gandiva_shared``
| ``Gandiva::gandiva_static``
|
++-----------------------------------------------+--------------------------------------------------------+-----------------------------------------------------+
+| ``find_package(Parquet REQUIRED)`` | ``Parquet::parquet_shared``
| ``Parquet::parquet_static``
|
++-----------------------------------------------+--------------------------------------------------------+-----------------------------------------------------+
+| ``find_package(Plasma REQUIRED)`` | ``Plasma::plasma_shared``
| ``Plasma::plasma_static``
|
++-----------------------------------------------+--------------------------------------------------------+-----------------------------------------------------+
+
+``Plasma`` will also expose ``Plasma::plasma-store-server`` for the Plasma
store server executable.
+
.. note::
CMake is case-sensitive. The names and variables listed above have to be
spelt exactly that way!
diff --git a/docs/source/java/cdata.rst b/docs/source/java/cdata.rst
index 94c86d6a4f..0f30fe1031 100644
--- a/docs/source/java/cdata.rst
+++ b/docs/source/java/cdata.rst
@@ -438,7 +438,7 @@ CMakeLists.txt definition file:
include_directories(${JNI_INCLUDE_DIRS})
set(CMAKE_CXX_STANDARD 17)
add_executable(${PROJECT_NAME} main.cpp)
- target_link_libraries(cdatacpptojava PRIVATE arrow_shared)
+ target_link_libraries(cdatacpptojava PRIVATE Arrow::arrow_shared)
target_link_libraries(cdatacpptojava PRIVATE ${JNI_LIBRARIES})
**Result**
