pitrou commented on a change in pull request #11820:
URL: https://github.com/apache/arrow/pull/11820#discussion_r761252165
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -35,17 +35,83 @@
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
Review comment:
The mention of CMake applies mostly to Arrow C++ and C++-derived
bindings such as Python or R (not Java or Go, for example). Perhaps you could
start this document by mentioning this context?
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -35,17 +35,83 @@
Building Arrow's libraries 🏋🏿♀️
Review comment:
It's not in this PR, but this should probably be "Building the Arrow
libraries".
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -35,17 +35,83 @@
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.
+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++
============
+Why build C++ from source?
+--------------------------
+
+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.
+
+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.
+
+
+Optional flags and why might we use them
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. TODO short description of the use of flags
+
+.. 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 C++ part of Arrow you have to build PyArrow on top of it
Review comment:
"the Arrow C++ libraries"
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -35,17 +35,83 @@
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.
+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++
============
+Why build C++ from source?
Review comment:
"Arrow C++", not just "C++" (and in the title above as well) :-)
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -35,17 +35,83 @@
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.
+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++
============
+Why build C++ from source?
+--------------------------
+
+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.
+
+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.
Review comment:
"CMake"
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -35,17 +35,83 @@
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.
+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++
============
+Why build C++ from source?
+--------------------------
+
+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.
+
+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.
+
+
+Optional flags and why might we use them
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. TODO short description of the use of flags
+
+.. 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 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?**
Review comment:
I'm not sure it's worth bothering beginners with this question :-) If we
want to, though, we'll need to find a better wording for the answer, as
currently it feels a bit confusing.
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -35,17 +35,83 @@
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.
+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++
============
+Why build C++ from source?
+--------------------------
+
+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.
+
+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
Review comment:
Hmm, it doesn't necessarily use make (we actually recommend
[Ninja](https://ninja-build.org/) in the C++ build docs).
Therefore you could rephrase this as : "... and it defers to another program
such as `make` or `ninja` for the actual build".
--
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: github-unsubscr...@arrow.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
