[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.