[Docs][C++] Add example of using ExternalProject_Add to use Arrow

[asfimport]

We've given advice to use ExternalProject_Add to build Arrow from source within a users CMake project. (Correct me if I am wrong that that is the preferred method now.) But I found it non-trivial to implement this.

We should add a simple example of doing this to the User Guide. We should also mention that we don't support add_subdirectory as that seems to be a common gotcha as well.

This might overlap with ARROW-9740, but I don't quite understand what that issue is proposing.

Reporter: Will Jones / @wjones127

_{Note: This issue was originally created as ARROW-16914. Please see the migration documentation for further details.}

[asfimport]

Kouhei Sutou / @kou:
Right. We don't support add_subdirectory().

BTW, we may be able to provide an example that uses https://cmake.org/cmake/help/latest/module/FetchContent.html instead of ExternalProject_Add(). ExternalProject_Add() builds Apache Arrow at build time but FetchContent_MakeAvailable() build Apache Arrow at configure time. It means that users can use find_package(Arrow) with FetchContent_MakeAavailable() instead of add_library(arrow_shared SHARED IMPORT) with ExternalProject_Add().

I don't know details of ARROW-9740 too but I think that we can work on this as a separated task of ARROW-9740.

[asfimport]

Will Jones / @wjones127:
Have you used FetchContent in a project before? I tried this:

function(fetch_arrow)
    cmake_parse_arguments(FETCH "" "TAG" "" "")

    include(FetchContent)
    FetchContent_Declare(
        arrow
        GIT_REPOSITORY https://github.com/apache/arrow.git
        GIT_TAG ${FETCH_TAG}
        SOURCE_SUBDIR cpp
    )

    FetchContent_MakeAvailable(arrow)

    find_package(Arrow CONFIG REQUIRED
        PATHS "${arrow_BINARY_DIR}/src/arrow"
    )
endfunction()

Which downloads and configures Arrow nicely, but find_package(Arrow) errors while trying to find ArrowTargets.cmake:

CMake Error at out/build/debug/_deps/arrow-build/src/arrow/ArrowConfig.cmake:74 (include):
  include could not find requested file:

    /home/willjones127/example_arrow/out/build/debug/_deps/arrow-build/src/arrow/ArrowTargets.cmake
Call Stack (most recent call first):
  cmake_modules/FetchArrow.cmake:21 (find_package)
  CMakeLists.txt:16 (fetch_arrow)

Maybe I have to force it to build Arrow as part of configure in order to generate that file? It would be nice if it could generate the target during configuration.

[asfimport]

Kouhei Sutou / @kou:
Sorry. I hadn't tried FetchContent. I tried it and understand that it's not for this use case. Sorry...

FetchContent just downloads at configure time. It doesn't build at configure time. So we can't use find_package(Arrow) with FetchContent.

It seems that we need to use "superbuild" https://www.kitware.com/cmake-superbuilds-git-submodules/ to use find_package(Arrow) but it may be difficult to use in most projects.

[github-actions]

This issue has been marked as stale because it has had no activity in the past 365 days. Please remove the stale label or comment below, or this issue will be closed in 14 days. If this improvement is still desired but has no current owner, please add the 'Status: needs champion' label.