From 1baab6a2d585cb388308c5f98d24e824538cc1c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ra=C3=BAl=20Cumplido?= Date: Mon, 12 Sep 2022 17:09:54 +0200 Subject: [PATCH 1/3] ARROW-17575: [Docs][C++] Update build document to follow new CMake package --- docs/source/cpp/build_system.rst | 50 ++++++++++++++++++++++++++++++-- docs/source/java/cdata.rst | 2 +- 2 files changed, 48 insertions(+), 4 deletions(-) diff --git a/docs/source/cpp/build_system.rst b/docs/source/cpp/build_system.rst index d4a0c82cc61a0..16474ead5b601 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,55 @@ 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 recomend 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``. + +.. 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 +`_ 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 44e4f230ba65d..c9aa35360622f 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 11) 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** From 3285e3e5e76d9d40046b116982ecae17abb17778 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ra=C3=BAl=20Cumplido?= Date: Tue, 13 Sep 2022 10:10:43 +0200 Subject: [PATCH 2/3] ARROW-17575: [Docs][C++] Fix typo and table formatting --- docs/source/cpp/build_system.rst | 48 ++++++++++++++++---------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/source/cpp/build_system.rst b/docs/source/cpp/build_system.rst index 16474ead5b601..56451ecc3bed5 100644 --- a/docs/source/cpp/build_system.rst +++ b/docs/source/cpp/build_system.rst @@ -71,7 +71,7 @@ In addition, it will have created some targets that you can link against * ``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 recomend using ``Arrow::arrow_shared`` and +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. @@ -90,29 +90,29 @@ There are other available packages, they can also be used with the `find_package `_ 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 | -+-----------------------------------------------+----------------------------------------------------+-------------------------------------------------+ ++-----------------------------------------------+--------------------------------------------------------+-----------------------------------------------------+ +| 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. From 3f2c76d0cef6e7b45b53a7d71709eeb23a274502 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ra=C3=BAl=20Cumplido?= Date: Tue, 13 Sep 2022 10:38:52 +0200 Subject: [PATCH 3/3] ARROW-17575: [Docs][C++] Add example of usage to define CMAKE_PREFIX_PATH --- docs/source/cpp/build_system.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/source/cpp/build_system.rst b/docs/source/cpp/build_system.rst index 56451ecc3bed5..131d7b6f855ec 100644 --- a/docs/source/cpp/build_system.rst +++ b/docs/source/cpp/build_system.rst @@ -79,6 +79,27 @@ 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 +`_ or an +`environment variable `_. + +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.