Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

ARROW-17575: [Docs][C++] Update build document to follow new CMake package #14097

Merged
merged 3 commits into from
Sep 13, 2022
Merged

ARROW-17575: [Docs][C++] Update build document to follow new CMake package #14097

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1baab6a
ARROW-17575: [Docs][C++] Update build document to follow new CMake pa…
raulcd Sep 12, 2022
3285e3e
ARROW-17575: [Docs][C++] Fix typo and table formatting
raulcd Sep 13, 2022
3f2c76d
ARROW-17575: [Docs][C++] Add example of usage to define CMAKE_PREFIX_…
raulcd Sep 13, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
71 changes: 68 additions & 3 deletions docs/source/cpp/build_system.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
-------------------------------
Expand All @@ -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``.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you add examples how to add the path to CMAKE_PREFIX_PATH?

There are 2 ways to add:

  1. cmake ... -DCMAKE_PREFIX_PATH=...: CMake variable: https://cmake.org/cmake/help/latest/variable/CMAKE_PREFIX_PATH.html
  2. export CMAKE_PREFIX_PATH=...: Environment variable: https://cmake.org/cmake/help/latest/envvar/CMAKE_PREFIX_PATH.html

I think the latter is better for most cases because the CMAKE_PREFIX_PATH environment variable may be defined in other place.

If we specify cmake -DCMAKE_PREFIX_PATH=${ARROW_ROOT}, the pre-defined CMAKE_PREFIX_PATH environment variable value is ignored. (I didn't confirm it yet but I think so. Sorry.) We can use the pre-defined CMAKE_PREFIX_PATH environment variable value by cmake -DCMAKE_PREFIX_PATH=${ARROW_ROOT}${CMAKE_PREFIX_PATH:+:${CMAKE_PREFIX_PATH}. (${X:+...} is a variable substitution syntax. See also ${parameter:+word} in https://www.gnu.org/software/bash/manual/html_node/Shell-Parameter-Expansion.html . This is used here to not include an empty path such as cmake -DCMAKE_PREFIX_PATH=${ARROW_ROOT}:.)

We can use the variable substitution syntax with export CMAKE_PREFIX_PATH=... case:

export CMAKE_PREFIX_PATH=${ARROW_ROOT}${CMAKE_PREFIX_PATH:+:${CMAKE_PREFIX_PATH}}

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks a lot! I've added a couple of examples, let me know if it makes sense or you think there's something more missing.


``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!
Expand Down
2 changes: 1 addition & 1 deletion docs/source/java/cdata.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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**
Expand Down