<commit_before>.. Licensed to the Apache Software Foundation (ASF) under one
.. or more contributor license agreements.  See the NOTICE file
.. distributed with this work for additional information
.. regarding copyright ownership.  The ASF licenses this file
.. to you under the Apache License, Version 2.0 (the
.. "License"); you may not use this file except in compliance
.. with the License.  You may obtain a copy of the License at

..   http://www.apache.org/licenses/LICENSE-2.0

.. Unless required by applicable law or agreed to in writing,
.. software distributed under the License is distributed on an
.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
.. KIND, either express or implied.  See the License for the
.. specific language governing permissions and limitations
.. under the License.

.. _building-arrow-cpp:

==================
Building Arrow C++
==================

System setup
============

Arrow uses CMake as a build configuration system. We recommend building
out-of-source. If you are not familiar with this terminology:

* **In-source build**: ``cmake`` is invoked directly from the ``cpp``
  directory. This can be inflexible when you wish to maintain multiple build
  environments (e.g. one for debug builds and another for release builds)
* **Out-of-source build**: ``cmake`` is invoked from another directory,
  creating an isolated build environment that does not interact with any other
  build environment. For example, you could create ``cpp/build-debug`` and
  invoke ``cmake $CMAKE_ARGS ..`` from this directory

Building requires:

* A C++11-enabled compiler. On Linux, gcc 4.8 and higher should be
  sufficient. For Windows, at least Visual Studio 2017 is required.
* CMake 3.5 or higher
* On Linux and macOS, either ``make`` or ``ninja`` build utilities

On Ubuntu/Debian you can install the requirements with:

.. code-block:: shell

   sudo apt-get install \
        build-essential \
        cmake

On Alpine Linux:

.. code-block:: shell

   apk add autoconf \
           bash \
           cmake \
           g++ \
           gcc \
           make
           
On Fedora Linux:

.. code-block:: shell

   sudo dnf install \
        cmake \
        gcc \
        gcc-c++ \
        make

On macOS, you can use `Homebrew <https://brew.sh/>`_:

.. code-block:: shell

   git clone https://github.com/apache/arrow.git
   cd arrow
   brew update && brew bundle --file=cpp/Brewfile

With `vcpkg <https://github.com/Microsoft/vcpkg>`_:

.. code-block:: shell
   
   git clone https://github.com/apache/arrow.git
   cd arrow
   vcpkg install \
     --x-manifest-root cpp \
     --feature-flags=versions \
     --clean-after-build

On MSYS2:

.. code-block:: shell

   pacman --sync --refresh --noconfirm \
     ccache \
     git \
     mingw-w64-${MSYSTEM_CARCH}-boost \
     mingw-w64-${MSYSTEM_CARCH}-brotli \
     mingw-w64-${MSYSTEM_CARCH}-cmake \
     mingw-w64-${MSYSTEM_CARCH}-gcc \
     mingw-w64-${MSYSTEM_CARCH}-gflags \
     mingw-w64-${MSYSTEM_CARCH}-glog \
     mingw-w64-${MSYSTEM_CARCH}-gtest \
     mingw-w64-${MSYSTEM_CARCH}-lz4 \
     mingw-w64-${MSYSTEM_CARCH}-protobuf \
     mingw-w64-${MSYSTEM_CARCH}-python3-numpy \
     mingw-w64-${MSYSTEM_CARCH}-rapidjson \
     mingw-w64-${MSYSTEM_CARCH}-snappy \
     mingw-w64-${MSYSTEM_CARCH}-thrift \
     mingw-w64-${MSYSTEM_CARCH}-zlib \
     mingw-w64-${MSYSTEM_CARCH}-zstd

.. _cpp-building-building:

Building
========

The build system uses ``CMAKE_BUILD_TYPE=release`` by default, so if this
argument is omitted then a release build will be produced.

.. note::

   You need to set more options to build on Windows. See
   :ref:`developers-cpp-windows` for details.

Several build types are possible:

* ``Debug``: doesn't apply any compiler optimizations and adds debugging
  information in the binary.
* ``RelWithDebInfo``: applies compiler optimizations while adding debug
  information in the binary.
* ``Release``: applies compiler optimizations and removes debug information
  from the binary.

You can also run default build with flag ``-DARROW_EXTRA_ERROR_CONTEXT=ON``, see
:ref:`cpp-extra-debugging`.

Minimal release build:

.. code-block:: shell

   git clone https://github.com/apache/arrow.git
   cd arrow/cpp
   mkdir release
   cd release
   cmake ..
   make

Minimal debug build with unit tests:

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

The unit tests are not built by default. After building, one can also invoke
the unit tests using the ``ctest`` tool provided by CMake (note that ``test``
depends on ``python`` being available).<commit_msg>ARROW-14039: [C++][Docs] Indicate memory requirements for building<commit_after>.. Licensed to the Apache Software Foundation (ASF) under one
.. or more contributor license agreements.  See the NOTICE file
.. distributed with this work for additional information
.. regarding copyright ownership.  The ASF licenses this file
.. to you under the Apache License, Version 2.0 (the
.. "License"); you may not use this file except in compliance
.. with the License.  You may obtain a copy of the License at

..   http://www.apache.org/licenses/LICENSE-2.0

.. Unless required by applicable law or agreed to in writing,
.. software distributed under the License is distributed on an
.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
.. KIND, either express or implied.  See the License for the
.. specific language governing permissions and limitations
.. under the License.

.. _building-arrow-cpp:

==================
Building Arrow C++
==================

System setup
============

Arrow uses CMake as a build configuration system. We recommend building
out-of-source. If you are not familiar with this terminology:

* **In-source build**: ``cmake`` is invoked directly from the ``cpp``
  directory. This can be inflexible when you wish to maintain multiple build
  environments (e.g. one for debug builds and another for release builds)
* **Out-of-source build**: ``cmake`` is invoked from another directory,
  creating an isolated build environment that does not interact with any other
  build environment. For example, you could create ``cpp/build-debug`` and
  invoke ``cmake $CMAKE_ARGS ..`` from this directory

Building requires:

* A C++11-enabled compiler. On Linux, gcc 4.8 and higher should be
  sufficient. For Windows, at least Visual Studio 2017 is required.
* CMake 3.5 or higher
* On Linux and macOS, either ``make`` or ``ninja`` build utilities
* At least 1GB of RAM for a minimal build, 4GB for a minimal  
  debug build with tests and 8GB for a full build using
  :ref:`docker <docker>`.

On Ubuntu/Debian you can install the requirements with:

.. code-block:: shell

   sudo apt-get install \
        build-essential \
        cmake

On Alpine Linux:

.. code-block:: shell

   apk add autoconf \
           bash \
           cmake \
           g++ \
           gcc \
           make
           
On Fedora Linux:

.. code-block:: shell

   sudo dnf install \
        cmake \
        gcc \
        gcc-c++ \
        make

On macOS, you can use `Homebrew <https://brew.sh/>`_:

.. code-block:: shell

   git clone https://github.com/apache/arrow.git
   cd arrow
   brew update && brew bundle --file=cpp/Brewfile

With `vcpkg <https://github.com/Microsoft/vcpkg>`_:

.. code-block:: shell
   
   git clone https://github.com/apache/arrow.git
   cd arrow
   vcpkg install \
     --x-manifest-root cpp \
     --feature-flags=versions \
     --clean-after-build

On MSYS2:

.. code-block:: shell

   pacman --sync --refresh --noconfirm \
     ccache \
     git \
     mingw-w64-${MSYSTEM_CARCH}-boost \
     mingw-w64-${MSYSTEM_CARCH}-brotli \
     mingw-w64-${MSYSTEM_CARCH}-cmake \
     mingw-w64-${MSYSTEM_CARCH}-gcc \
     mingw-w64-${MSYSTEM_CARCH}-gflags \
     mingw-w64-${MSYSTEM_CARCH}-glog \
     mingw-w64-${MSYSTEM_CARCH}-gtest \
     mingw-w64-${MSYSTEM_CARCH}-lz4 \
     mingw-w64-${MSYSTEM_CARCH}-protobuf \
     mingw-w64-${MSYSTEM_CARCH}-python3-numpy \
     mingw-w64-${MSYSTEM_CARCH}-rapidjson \
     mingw-w64-${MSYSTEM_CARCH}-snappy \
     mingw-w64-${MSYSTEM_CARCH}-thrift \
     mingw-w64-${MSYSTEM_CARCH}-zlib \
     mingw-w64-${MSYSTEM_CARCH}-zstd

.. _cpp-building-building:

Building
========

The build system uses ``CMAKE_BUILD_TYPE=release`` by default, so if this
argument is omitted then a release build will be produced.

.. note::

   You need to set more options to build on Windows. See
   :ref:`developers-cpp-windows` for details.

Several build types are possible:

* ``Debug``: doesn't apply any compiler optimizations and adds debugging
  information in the binary.
* ``RelWithDebInfo``: applies compiler optimizations while adding debug
  information in the binary.
* ``Release``: applies compiler optimizations and removes debug information
  from the binary.

You can also run default build with flag ``-DARROW_EXTRA_ERROR_CONTEXT=ON``, see
:ref:`cpp-extra-debugging`.

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

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

The unit tests are not built by default. After building, one can also invoke
the unit tests using the ``ctest`` tool provided by CMake (note that ``test``
depends on ``python`` being available).

CMake 
`UNITY_BUILD <https://cmake.org/cmake/help/latest/prop_tgt/UNITY_BUILD.html/>`_
can increase memory requirements to complete a build, so in memory constrained
environments it should be turned off.

* ``-DCMAKE_UNITY_BUILD=OFF``: Combine source files during building
{'fraction_non_alphanumeric': 0.11093688749509996, 'fraction_numerical': 0.010192081536652292, 'mean_word_length': 3.0738522954091816, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 13, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '116939', 'n_tokens_mistral': 3235, 'n_tokens_neox': 3057, 'n_words': 1094}