ARROW-17575: [Docs][C++] Update build document to follow new CMake pa…

…ckage (apache#14097) This is a follow up to update our build documentation from the changes on apache#13892 Authored-by: Raúl Cumplido <raulcumplido@gmail.com> Signed-off-by: Sutou Kouhei <kou@clear-code.com>
zagto · Oct 7, 2022 · b1ab2b7 · b1ab2b7
1 parent 3c28787
commit b1ab2b7
Show file tree

Hide file tree

Showing 2 changed files with 69 additions and 4 deletions.
diff --git 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
@@ -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**