jorisvandenbossche commented on a change in pull request #11820:
URL: https://github.com/apache/arrow/pull/11820#discussion_r762953347
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,87 +31,120 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
-
-If you decide to contribute to Arrow you will meet the topic of
-compiling source code and use of CMake. You may have some
-experience with it or not. If not, it is good to read through
-this part so you understand what is happening in the process of
-building Arrow better.
+**********************************
+Building the Arrow libraries 🏋🏿♀️
+**********************************
+
+The Arrow project contains a number of libraries that enable
+work in many languages. Most libraries (C++, C#, Go, Java,
+JavaScript, Julia, and Rust) already contain distinct implementations
+of Arrow.
+
+It is different for C (Glib), MATLAB, Python, R, and Ruby as they
Review comment:
```suggestion
This is different for C (Glib), MATLAB, Python, R, and Ruby as they
```
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,87 +31,120 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
-
-If you decide to contribute to Arrow you will meet the topic of
-compiling source code and use of CMake. You may have some
-experience with it or not. If not, it is good to read through
-this part so you understand what is happening in the process of
-building Arrow better.
+**********************************
+Building the Arrow libraries 🏋🏿♀️
+**********************************
+
+The Arrow project contains a number of libraries that enable
+work in many languages. Most libraries (C++, C#, Go, Java,
+JavaScript, Julia, and Rust) already contain distinct implementations
+of Arrow.
+
+It is different for C (Glib), MATLAB, Python, R, and Ruby as they
+are built on top of the C++ library. In this section of the guide
+we will try to make a friendly introduction to the build
+dealing with some of these libraries as well has how they work with
+the C++ library.
+
+If you decide to contribute to Arrow you might need to compile the
+C++ source code. This is done using a tool called CMake, which you
+may or may not have experience with. If not, this section of the
+guide will help you better understand CMake and the process
+of building Arrow's C++ code.
If you feel comfortable with compiling then feel free to proceed
to the :ref:`C++ <building-arrow-cpp>`, :ref:`PyArrow <build_pyarrow>` or
`R package build section
<https://arrow.apache.org/docs/r/articles/developing.html>`_.
-Building C++
-============
+Building Arrow C++
+==================
+
+Why build Arrow C++ from source?
+--------------------------------
-Why build C++ from source?
---------------------------
+For Arrow implementations which are built on top of the C++ implementation
+(e.g. Python and R), wrappers and interfaces have been written to the
+underlying C++ functions. If you want to work on PyArrow or R package,
+you may need to edit the source code of the C++ library too.
-The core of Arrow is written in C++ and all bindings in other
-languages (Python, R, ..) are wrapping underlying
-C++ functions. Even if you want to work on PyArrow or R package
-the source code of C++ may have to be edited also.
+Detailed instructions on building C++ library from source can
+be found :ref:`here <building-arrow-cpp>`.
About CMake
-----------
-CMake is a cross platform build system generator and it uses make
-for the actual build. In the compiling process of Arrow what will
-most probably be needed is some tweaking of the flags that are added
-to cmake in the compiling process of Arrow.
+CMake is a cross-platform build system generator and it defers
+to another program such as ``make`` or ``ninja`` for the actual build.
+If you are running into errors with the build process, the first thing to
+do is to look at the error message thoroughly and check the building
+documentation for any similar error advice. Also changing the CMake flags
+for compiling Arrow could be useful.
+
+CMake presets
+-------------
+
+You could also try to build with CMake presets which are a collection of
+build and test recipes for Arrow's CMake. They are a very useful
+starting points.
+More detailed information about CMake presets can be found in
+the :ref:`cmake_presets` section.
-Optional flags and why might we use them
+Optional flags and environment variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. TODO short description of the use of flags
+
+Flags used in the CMake build are used to include additional components
+and to handle third-party dependencies.
+The build for C++ library can be minimal with no use of flags or can
+be changed with adding optional components from the
+:ref:`list <cpp_build_optional_components>`.
.. seealso::
Full list of optional flags: :ref:`cpp_build_optional_components`
-.. Environment variables useful for developers
-.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. TODO short description of the use of env vars
+R and Python have specific lists of flags in their respective builds
+that need to be included. You can find the links at the end
+of this section.
+
+In general on Python side the options are set with CMake flags and
Review comment:
```suggestion
In general on Python side, the options are set with CMake flags and
```
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,87 +31,120 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
-
-If you decide to contribute to Arrow you will meet the topic of
-compiling source code and use of CMake. You may have some
-experience with it or not. If not, it is good to read through
-this part so you understand what is happening in the process of
-building Arrow better.
+**********************************
+Building the Arrow libraries 🏋🏿♀️
+**********************************
+
+The Arrow project contains a number of libraries that enable
+work in many languages. Most libraries (C++, C#, Go, Java,
+JavaScript, Julia, and Rust) already contain distinct implementations
+of Arrow.
+
+It is different for C (Glib), MATLAB, Python, R, and Ruby as they
+are built on top of the C++ library. In this section of the guide
+we will try to make a friendly introduction to the build
+dealing with some of these libraries as well has how they work with
+the C++ library.
+
+If you decide to contribute to Arrow you might need to compile the
+C++ source code. This is done using a tool called CMake, which you
+may or may not have experience with. If not, this section of the
+guide will help you better understand CMake and the process
+of building Arrow's C++ code.
If you feel comfortable with compiling then feel free to proceed
to the :ref:`C++ <building-arrow-cpp>`, :ref:`PyArrow <build_pyarrow>` or
`R package build section
<https://arrow.apache.org/docs/r/articles/developing.html>`_.
-Building C++
-============
+Building Arrow C++
+==================
+
+Why build Arrow C++ from source?
+--------------------------------
-Why build C++ from source?
---------------------------
+For Arrow implementations which are built on top of the C++ implementation
+(e.g. Python and R), wrappers and interfaces have been written to the
+underlying C++ functions. If you want to work on PyArrow or R package,
+you may need to edit the source code of the C++ library too.
-The core of Arrow is written in C++ and all bindings in other
-languages (Python, R, ..) are wrapping underlying
-C++ functions. Even if you want to work on PyArrow or R package
-the source code of C++ may have to be edited also.
+Detailed instructions on building C++ library from source can
+be found :ref:`here <building-arrow-cpp>`.
About CMake
-----------
-CMake is a cross platform build system generator and it uses make
-for the actual build. In the compiling process of Arrow what will
-most probably be needed is some tweaking of the flags that are added
-to cmake in the compiling process of Arrow.
+CMake is a cross-platform build system generator and it defers
+to another program such as ``make`` or ``ninja`` for the actual build.
+If you are running into errors with the build process, the first thing to
+do is to look at the error message thoroughly and check the building
+documentation for any similar error advice. Also changing the CMake flags
+for compiling Arrow could be useful.
+
+CMake presets
+-------------
Review comment:
```suggestion
^^^^^^^^^^^^^^^^^^^
```
(then it's a subsection below "CMake"?)
--
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]
