thisisnic commented on a change in pull request #11820:
URL: https://github.com/apache/arrow/pull/11820#discussion_r762022752
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,21 +31,102 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
+************************************
+Building the Arrow's libraries 🏋🏿♀️
+************************************
+The Arrow project contains good number of libraries that enable
Review comment:
```suggestion
The Arrow project contains a number of libraries that enable
```
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,21 +31,102 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
+************************************
+Building the Arrow's libraries 🏋🏿♀️
Review comment:
```suggestion
Building the Arrow libraries 🏋🏿♀️
```
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,21 +31,102 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
+************************************
+Building the Arrow's libraries 🏋🏿♀️
+************************************
+The Arrow project contains good 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 we will be
+dealing with this second part of the libraries plus some of C++.
Review comment:
```suggestion
dealing with some of these libraries as well has how they work with the C++
library.
```
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,21 +31,102 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
+************************************
+Building the Arrow's libraries 🏋🏿♀️
+************************************
+The Arrow project contains good 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 we will be
+dealing with this second part of the libraries plus some of C++.
-Building C++
-============
+In this case, if you decide to contribute to Arrow you will meet
+the topic of compiling the 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.
+
+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 Arrow C++
+==================
+
+Why build Arrow C++ from source?
+--------------------------------
+
+For Arrow C++ implementation and its bindings (Python and R for example)
+these bindings are wrapping the 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.
+
+About CMake
+-----------
+
+CMake is a cross platform build system generator and it defers
+to another program such as ``make`` or ``ninja`` for the actual build.
+If running into errors with the build process, the first thing to try is
Review comment:
```suggestion
If you are running into errors with the build process, the first thing to
try is
```
##########
File path: docs/source/developers/guide/index.rst
##########
@@ -81,7 +81,7 @@ of adding a basic feature.
appropriate :ref:`communication` channel.
See a short description about the building process of
- :ref:`PyArrow or R-Arrow<build-arrow>` or go straight to detailed
+ :ref:`PyArrow or R package<build-arrow>` or go straight to detailed
Review comment:
```suggestion
:ref:`PyArrow or the R package<build-arrow>` or go straight to detailed
```
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,21 +31,102 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
+************************************
+Building the Arrow's libraries 🏋🏿♀️
+************************************
+The Arrow project contains good 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 we will be
+dealing with this second part of the libraries plus some of C++.
-Building C++
-============
+In this case, if you decide to contribute to Arrow you will meet
+the topic of compiling the 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.
+
+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 Arrow C++
+==================
+
+Why build Arrow C++ from source?
+--------------------------------
+
+For Arrow C++ implementation and its bindings (Python and R for example)
+these bindings are wrapping the 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.
+
+About CMake
+-----------
+
+CMake is a cross platform build system generator and it defers
+to another program such as ``make`` or ``ninja`` for the actual build.
+If running into errors with the build process, the first thing to try is
+to tweak some CMake flags for compiling Arrow.
+
+.. TODO
+.. CMake presets
+.. Ex: "We now have CMake Presets which are useful starting points."
+..
https://github.com/apache/arrow/blob/master/docs/source/developers/cpp/building.rst#cmake-presets
+
+
+Optional flags and why might we use them
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. TODO short description of the use of flags
+.. R and Python have specific lists of flags in their respective building docs
that can be referenced.
+
+.. 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
+
+Building from source vs. using binaries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Using binaries is a fast and simple way of working with the latest
+Arrow version. But you do not have the possibility to add or change
+the code and as a contributor you will need to.
+
+Detailed instructions on building C++ library from source can
+be found :ref:`here <building-arrow-cpp>`.
.. _build-pyarrow:
Building PyArrow
================
-.. _build-rarrow:
+After building Arrow C++ part of Arrow you have to build PyArrow on top
+of it also. The reason is the same, so you can edit the code and run
+tests on the edited code you have locally.
-Building R-Arrow
-================
+**Why do we have to do builds separately?**
+
+As mentioned in the beginning of this page, Python part of the Arrow
+project is built on top of C++. In order to make changes in Python part
+of Arrow as well as C++ part of Arrow, we need to build them separately.
Review comment:
```suggestion
of Arrow as well as the C++ part of Arrow, you need to build them separately.
```
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,21 +31,102 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
+************************************
+Building the Arrow's libraries 🏋🏿♀️
+************************************
+The Arrow project contains good 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 we will be
+dealing with this second part of the libraries plus some of C++.
-Building C++
-============
+In this case, if you decide to contribute to Arrow you will meet
+the topic of compiling the 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.
Review comment:
```suggestion
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.
```
Not all contributors will need to compile the C++; in the R developer docs
we have instructions for using the nightly builds as the C++ source when people
are only making changes to the R code without needing to build C++ from source.
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,21 +31,102 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
+************************************
+Building the Arrow's libraries 🏋🏿♀️
+************************************
+The Arrow project contains good 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 we will be
+dealing with this second part of the libraries plus some of C++.
-Building C++
-============
+In this case, if you decide to contribute to Arrow you will meet
+the topic of compiling the 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.
+
+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 Arrow C++
+==================
+
+Why build Arrow C++ from source?
+--------------------------------
+
+For Arrow C++ implementation and its bindings (Python and R for example)
+these bindings are wrapping the 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.
Review comment:
```suggestion
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.
```
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,21 +31,102 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
+************************************
+Building the Arrow's libraries 🏋🏿♀️
+************************************
+The Arrow project contains good 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 we will be
+dealing with this second part of the libraries plus some of C++.
-Building C++
-============
+In this case, if you decide to contribute to Arrow you will meet
+the topic of compiling the 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.
+
+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 Arrow C++
+==================
+
+Why build Arrow C++ from source?
+--------------------------------
+
+For Arrow C++ implementation and its bindings (Python and R for example)
+these bindings are wrapping the 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.
+
+About CMake
+-----------
+
+CMake is a cross platform build system generator and it defers
+to another program such as ``make`` or ``ninja`` for the actual build.
+If running into errors with the build process, the first thing to try is
+to tweak some CMake flags for compiling Arrow.
+
+.. TODO
+.. CMake presets
+.. Ex: "We now have CMake Presets which are useful starting points."
+..
https://github.com/apache/arrow/blob/master/docs/source/developers/cpp/building.rst#cmake-presets
+
+
+Optional flags and why might we use them
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. TODO short description of the use of flags
+.. R and Python have specific lists of flags in their respective building docs
that can be referenced.
+
+.. 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
+
+Building from source vs. using binaries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Using binaries is a fast and simple way of working with the latest
+Arrow version. But you do not have the possibility to add or change
+the code and as a contributor you will need to.
+
+Detailed instructions on building C++ library from source can
+be found :ref:`here <building-arrow-cpp>`.
.. _build-pyarrow:
Building PyArrow
================
-.. _build-rarrow:
+After building Arrow C++ part of Arrow you have to build PyArrow on top
+of it also. The reason is the same, so you can edit the code and run
+tests on the edited code you have locally.
-Building R-Arrow
-================
+**Why do we have to do builds separately?**
+
+As mentioned in the beginning of this page, Python part of the Arrow
Review comment:
```suggestion
As mentioned at the beginning of this page, the Python part of the Arrow
```
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,21 +31,102 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
+************************************
+Building the Arrow's libraries 🏋🏿♀️
+************************************
+The Arrow project contains good 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 we will be
+dealing with this second part of the libraries plus some of C++.
-Building C++
-============
+In this case, if you decide to contribute to Arrow you will meet
+the topic of compiling the 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.
+
+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 Arrow C++
+==================
+
+Why build Arrow C++ from source?
+--------------------------------
+
+For Arrow C++ implementation and its bindings (Python and R for example)
+these bindings are wrapping the 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.
+
+About CMake
+-----------
+
+CMake is a cross platform build system generator and it defers
Review comment:
```suggestion
CMake is a cross-platform build system generator and it defers
```
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,21 +31,102 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
+************************************
+Building the Arrow's libraries 🏋🏿♀️
+************************************
+The Arrow project contains good 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 we will be
+dealing with this second part of the libraries plus some of C++.
-Building C++
-============
+In this case, if you decide to contribute to Arrow you will meet
+the topic of compiling the 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.
+
+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 Arrow C++
+==================
+
+Why build Arrow C++ from source?
+--------------------------------
+
+For Arrow C++ implementation and its bindings (Python and R for example)
+these bindings are wrapping the 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.
+
+About CMake
+-----------
+
+CMake is a cross platform build system generator and it defers
+to another program such as ``make`` or ``ninja`` for the actual build.
+If running into errors with the build process, the first thing to try is
+to tweak some CMake flags for compiling Arrow.
Review comment:
I wonder if we could be a bit less definitive here; in terms of
suggesting tweaking the CMake flags being *definitely* the first thing to try -
it's not something I've needed to do often for fixing C++ & R build errors. I
think we should be suggesting a thorough look at the error message and that
changing the CMake flags *could* be useful.
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,21 +31,102 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
+************************************
+Building the Arrow's libraries 🏋🏿♀️
+************************************
+The Arrow project contains good 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 we will be
+dealing with this second part of the libraries plus some of C++.
-Building C++
-============
+In this case, if you decide to contribute to Arrow you will meet
+the topic of compiling the 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.
+
+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 Arrow C++
+==================
+
+Why build Arrow C++ from source?
+--------------------------------
+
+For Arrow C++ implementation and its bindings (Python and R for example)
+these bindings are wrapping the 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.
+
+About CMake
+-----------
+
+CMake is a cross platform build system generator and it defers
+to another program such as ``make`` or ``ninja`` for the actual build.
+If running into errors with the build process, the first thing to try is
+to tweak some CMake flags for compiling Arrow.
+
+.. TODO
+.. CMake presets
+.. Ex: "We now have CMake Presets which are useful starting points."
+..
https://github.com/apache/arrow/blob/master/docs/source/developers/cpp/building.rst#cmake-presets
+
+
+Optional flags and why might we use them
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. TODO short description of the use of flags
+.. R and Python have specific lists of flags in their respective building docs
that can be referenced.
+
+.. 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
+
+Building from source vs. using binaries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Using binaries is a fast and simple way of working with the latest
+Arrow version. But you do not have the possibility to add or change
+the code and as a contributor you will need to.
Review comment:
```suggestion
Arrow version. However, if you use these it means that you will be unable
to make
changes to the Arrow C++ library.
```
Removed "you will need to" as this isn't necessarily the case.
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,21 +31,102 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
+************************************
+Building the Arrow's libraries 🏋🏿♀️
+************************************
+The Arrow project contains good 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 we will be
+dealing with this second part of the libraries plus some of C++.
-Building C++
-============
+In this case, if you decide to contribute to Arrow you will meet
+the topic of compiling the 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.
+
+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 Arrow C++
+==================
+
+Why build Arrow C++ from source?
+--------------------------------
+
+For Arrow C++ implementation and its bindings (Python and R for example)
+these bindings are wrapping the 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.
+
+About CMake
+-----------
+
+CMake is a cross platform build system generator and it defers
+to another program such as ``make`` or ``ninja`` for the actual build.
+If running into errors with the build process, the first thing to try is
+to tweak some CMake flags for compiling Arrow.
+
+.. TODO
+.. CMake presets
+.. Ex: "We now have CMake Presets which are useful starting points."
+..
https://github.com/apache/arrow/blob/master/docs/source/developers/cpp/building.rst#cmake-presets
+
+
+Optional flags and why might we use them
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. TODO short description of the use of flags
+.. R and Python have specific lists of flags in their respective building docs
that can be referenced.
+
+.. 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
+
+Building from source vs. using binaries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Using binaries is a fast and simple way of working with the latest
Review comment:
I may be being pedantic about the use of the word "latest" here, but
binaries are the released or nightly versions rather than the truly most
up-to-date version (i.e. latest code merged into the master branch).
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,21 +31,102 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
+************************************
+Building the Arrow's libraries 🏋🏿♀️
+************************************
+The Arrow project contains good 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 we will be
+dealing with this second part of the libraries plus some of C++.
-Building C++
-============
+In this case, if you decide to contribute to Arrow you will meet
+the topic of compiling the 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.
+
+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 Arrow C++
+==================
+
+Why build Arrow C++ from source?
+--------------------------------
+
+For Arrow C++ implementation and its bindings (Python and R for example)
+these bindings are wrapping the 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.
+
+About CMake
+-----------
+
+CMake is a cross platform build system generator and it defers
+to another program such as ``make`` or ``ninja`` for the actual build.
+If running into errors with the build process, the first thing to try is
+to tweak some CMake flags for compiling Arrow.
+
+.. TODO
+.. CMake presets
+.. Ex: "We now have CMake Presets which are useful starting points."
+..
https://github.com/apache/arrow/blob/master/docs/source/developers/cpp/building.rst#cmake-presets
+
+
+Optional flags and why might we use them
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. TODO short description of the use of flags
+.. R and Python have specific lists of flags in their respective building docs
that can be referenced.
+
+.. 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
+
+Building from source vs. using binaries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Using binaries is a fast and simple way of working with the latest
+Arrow version. But you do not have the possibility to add or change
+the code and as a contributor you will need to.
+
+Detailed instructions on building C++ library from source can
+be found :ref:`here <building-arrow-cpp>`.
.. _build-pyarrow:
Building PyArrow
================
-.. _build-rarrow:
+After building Arrow C++ part of Arrow you have to build PyArrow on top
+of it also. The reason is the same, so you can edit the code and run
+tests on the edited code you have locally.
-Building R-Arrow
-================
+**Why do we have to do builds separately?**
+
+As mentioned in the beginning of this page, Python part of the Arrow
+project is built on top of C++. In order to make changes in Python part
Review comment:
```suggestion
project is built on top of the C++ library. In order to make changes in the
Python part
```
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,21 +31,102 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
+************************************
+Building the Arrow's libraries 🏋🏿♀️
+************************************
+The Arrow project contains good 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 we will be
+dealing with this second part of the libraries plus some of C++.
-Building C++
-============
+In this case, if you decide to contribute to Arrow you will meet
+the topic of compiling the 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.
+
+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 Arrow C++
+==================
+
+Why build Arrow C++ from source?
+--------------------------------
+
+For Arrow C++ implementation and its bindings (Python and R for example)
+these bindings are wrapping the 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.
+
+About CMake
+-----------
+
+CMake is a cross platform build system generator and it defers
+to another program such as ``make`` or ``ninja`` for the actual build.
+If running into errors with the build process, the first thing to try is
+to tweak some CMake flags for compiling Arrow.
+
+.. TODO
+.. CMake presets
+.. Ex: "We now have CMake Presets which are useful starting points."
+..
https://github.com/apache/arrow/blob/master/docs/source/developers/cpp/building.rst#cmake-presets
+
+
+Optional flags and why might we use them
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. TODO short description of the use of flags
+.. R and Python have specific lists of flags in their respective building docs
that can be referenced.
+
+.. 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
+
+Building from source vs. using binaries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Using binaries is a fast and simple way of working with the latest
+Arrow version. But you do not have the possibility to add or change
+the code and as a contributor you will need to.
+
+Detailed instructions on building C++ library from source can
+be found :ref:`here <building-arrow-cpp>`.
.. _build-pyarrow:
Building PyArrow
================
-.. _build-rarrow:
+After building Arrow C++ part of Arrow you have to build PyArrow on top
Review comment:
```suggestion
After building the Arrow C++ library, you need to build PyArrow on top
```
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,21 +31,102 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
+************************************
+Building the Arrow's libraries 🏋🏿♀️
+************************************
+The Arrow project contains good 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 we will be
+dealing with this second part of the libraries plus some of C++.
-Building C++
-============
+In this case, if you decide to contribute to Arrow you will meet
+the topic of compiling the 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.
+
+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 Arrow C++
+==================
+
+Why build Arrow C++ from source?
+--------------------------------
+
+For Arrow C++ implementation and its bindings (Python and R for example)
+these bindings are wrapping the 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.
+
+About CMake
+-----------
+
+CMake is a cross platform build system generator and it defers
+to another program such as ``make`` or ``ninja`` for the actual build.
+If running into errors with the build process, the first thing to try is
+to tweak some CMake flags for compiling Arrow.
+
+.. TODO
+.. CMake presets
+.. Ex: "We now have CMake Presets which are useful starting points."
+..
https://github.com/apache/arrow/blob/master/docs/source/developers/cpp/building.rst#cmake-presets
+
+
+Optional flags and why might we use them
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. TODO short description of the use of flags
+.. R and Python have specific lists of flags in their respective building docs
that can be referenced.
+
+.. 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
+
+Building from source vs. using binaries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Using binaries is a fast and simple way of working with the latest
+Arrow version. But you do not have the possibility to add or change
+the code and as a contributor you will need to.
+
+Detailed instructions on building C++ library from source can
+be found :ref:`here <building-arrow-cpp>`.
.. _build-pyarrow:
Building PyArrow
================
-.. _build-rarrow:
+After building Arrow C++ part of Arrow you have to build PyArrow on top
+of it also. The reason is the same, so you can edit the code and run
Review comment:
```suggestion
of it also. The reason is the same; so you can edit the code and run
```
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,21 +31,102 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
+************************************
+Building the Arrow's libraries 🏋🏿♀️
+************************************
+The Arrow project contains good 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 we will be
+dealing with this second part of the libraries plus some of C++.
-Building C++
-============
+In this case, if you decide to contribute to Arrow you will meet
+the topic of compiling the 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.
+
+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 Arrow C++
+==================
+
+Why build Arrow C++ from source?
+--------------------------------
+
+For Arrow C++ implementation and its bindings (Python and R for example)
+these bindings are wrapping the 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.
+
+About CMake
+-----------
+
+CMake is a cross platform build system generator and it defers
+to another program such as ``make`` or ``ninja`` for the actual build.
+If running into errors with the build process, the first thing to try is
+to tweak some CMake flags for compiling Arrow.
+
+.. TODO
+.. CMake presets
+.. Ex: "We now have CMake Presets which are useful starting points."
+..
https://github.com/apache/arrow/blob/master/docs/source/developers/cpp/building.rst#cmake-presets
+
+
+Optional flags and why might we use them
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. TODO short description of the use of flags
+.. R and Python have specific lists of flags in their respective building docs
that can be referenced.
+
+.. 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
+
+Building from source vs. using binaries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Using binaries is a fast and simple way of working with the latest
+Arrow version. But you do not have the possibility to add or change
+the code and as a contributor you will need to.
+
+Detailed instructions on building C++ library from source can
+be found :ref:`here <building-arrow-cpp>`.
.. _build-pyarrow:
Building PyArrow
================
-.. _build-rarrow:
+After building Arrow C++ part of Arrow you have to build PyArrow on top
+of it also. The reason is the same, so you can edit the code and run
+tests on the edited code you have locally.
-Building R-Arrow
-================
+**Why do we have to do builds separately?**
+
+As mentioned in the beginning of this page, Python part of the Arrow
+project is built on top of C++. In order to make changes in Python part
+of Arrow as well as C++ part of Arrow, we need to build them separately.
+
+We hope this introduction was enough to help you start with the building
+process.
+
+.. seealso::
+ Follow the instructions to build PyArrow together with the C++ library
+
+ - :ref:`build_pyarrow`
+ Or
+
+ - :ref:`build_pyarrow_win`
+
+.. _build-rapackage:
+
+Building R package
Review comment:
```suggestion
Building the R package
```
--
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]
