jorisvandenbossche commented on a change in pull request #11778: URL: https://github.com/apache/arrow/pull/11778#discussion_r759946404
########## File path: docs/source/developers/cpp/building.rst ########## @@ -121,6 +121,99 @@ On MSYS2: Building ======== +All the instructions below assume that you have cloned the Arrow git +repository and navigated to the ``cpp`` subdirectory: + +.. code-block:: shell + + $ git clone https://github.com/apache/arrow.git + $ cd arrow/cpp + +CMake presets +------------- + +Using CMake version 3.21.0 or higher, some presets for various build +configurations are provided. You can get a list of the available presets +using ``cmake --list-presets``: + +.. code-block:: shell + + $ cmake --list-presets + Available configure presets: + + "ninja-debug-minimal" - Debug build without anything enabled + "ninja-debug-basic" - Debug build with tests and reduced dependencies + "ninja-debug" - Debug build with tests and more optional components + [ etc. ] + +You can inspect the specific options enabled by a given preset using +``cmake -N --preset <preset name>``: + +.. code-block:: shell + + $ cmake --preset -N ninja-debug-minimal + Preset CMake variables: + + ARROW_BUILD_INTEGRATION="OFF" + ARROW_BUILD_STATIC="OFF" + ARROW_BUILD_TESTS="OFF" + ARROW_EXTRA_ERROR_CONTEXT="ON" + ARROW_WITH_RE2="OFF" + ARROW_WITH_UTF8PROC="OFF" + CMAKE_BUILD_TYPE="Debug" + +You can also create a build from a given preset: + +.. code-block:: shell + + $ mkdir build + $ cd build + $ cmake .. --preset ninja-debug-minimal + Preset CMake variables: + + ARROW_BUILD_INTEGRATION="OFF" + ARROW_BUILD_STATIC="OFF" + ARROW_BUILD_TESTS="OFF" + ARROW_EXTRA_ERROR_CONTEXT="ON" + ARROW_WITH_RE2="OFF" + ARROW_WITH_UTF8PROC="OFF" + CMAKE_BUILD_TYPE="Debug" + + -- Building using CMake version: 3.21.3 + [ etc. ] + +and then ask to compile the build targets: + +.. code-block:: shell + + $ cmake --build . Review comment: Is this `cmake --build` something presets specific? (in other parts of the docs I think we mention to do the `make` and `make install` combo) ########## File path: docs/source/developers/cpp/building.rst ########## @@ -145,45 +238,34 @@ Minimal release build (1GB of RAM for building or more recommended): .. code-block:: shell - git clone https://github.com/apache/arrow.git - cd arrow/cpp - mkdir release - cd release - cmake .. - make + $ mkdir build-release Review comment: I know you added on top that all instructions assume you navigated to `arrow/cpp`, but I think it might be worth repeating this a few times at least when creating a new directory (eg could add a comment on the same line like `# inside arrow/cpp directory`) ########## File path: docs/source/developers/cpp/building.rst ########## @@ -121,6 +121,99 @@ On MSYS2: Building ======== +All the instructions below assume that you have cloned the Arrow git +repository and navigated to the ``cpp`` subdirectory: + +.. code-block:: shell + + $ git clone https://github.com/apache/arrow.git + $ cd arrow/cpp + +CMake presets +------------- + +Using CMake version 3.21.0 or higher, some presets for various build +configurations are provided. You can get a list of the available presets +using ``cmake --list-presets``: + +.. code-block:: shell + + $ cmake --list-presets + Available configure presets: + + "ninja-debug-minimal" - Debug build without anything enabled + "ninja-debug-basic" - Debug build with tests and reduced dependencies + "ninja-debug" - Debug build with tests and more optional components + [ etc. ] + +You can inspect the specific options enabled by a given preset using +``cmake -N --preset <preset name>``: + +.. code-block:: shell + + $ cmake --preset -N ninja-debug-minimal + Preset CMake variables: + + ARROW_BUILD_INTEGRATION="OFF" + ARROW_BUILD_STATIC="OFF" + ARROW_BUILD_TESTS="OFF" + ARROW_EXTRA_ERROR_CONTEXT="ON" + ARROW_WITH_RE2="OFF" + ARROW_WITH_UTF8PROC="OFF" + CMAKE_BUILD_TYPE="Debug" + +You can also create a build from a given preset: + +.. code-block:: shell + + $ mkdir build + $ cd build + $ cmake .. --preset ninja-debug-minimal Review comment: Is there a way you can combine a preset with some additional manual config options? (eg in practice you will most of the time also have to specify for example DCMAKE_INSTALL_PREFIX, or for example specifying the dependency source?) ########## File path: docs/source/developers/cpp/building.rst ########## @@ -145,45 +238,34 @@ Minimal release build (1GB of RAM for building or more recommended): .. code-block:: shell - git clone https://github.com/apache/arrow.git - cd arrow/cpp - mkdir release - cd release - cmake .. - make + $ mkdir build-release + $ cd build-release + $ cmake .. + $ make -j8 # if you have 8 CPU cores, otherwise adjust Minimal debug build with unit tests (4GB of RAM for building or more recommended): .. code-block:: shell - git clone https://github.com/apache/arrow.git - cd arrow - git submodule update --init --recursive - export ARROW_TEST_DATA=$PWD/testing/data - cd cpp - mkdir debug - cd debug - cmake -DCMAKE_BUILD_TYPE=Debug -DARROW_BUILD_TESTS=ON .. - make unittest + $ git submodule update --init --recursive Review comment: When giving tutorials, I have noticed that many beginners don't necessarily know the meaning of `$` as signaling "this is on the prompt" (I also think that not all platforms / consoles actually use this symbol?) So I have been actively removing it from instructions (because otherwise people naively copy this line from the docs, and get an error about $). If we could make the `$` non-copy-pastable, that would be a nice combination I think. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
