thisisnic commented on a change in pull request #11820:
URL: https://github.com/apache/arrow/pull/11820#discussion_r762924663
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,21 +31,120 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
+**********************************
+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
Review comment:
```suggestion
we will try to make a friendly introduction to the build,
```
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,21 +31,120 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
+**********************************
+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.
-Building C++
-============
+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.
-.. _build-pyarrow:
+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 PyArrow
-================
+Building Arrow C++
+==================
-.. _build-rarrow:
+Why build Arrow 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.
+
+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 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 environment variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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`
+
+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
+paths with environment variables. In R the environment variables are used
+for all things connected to the build, also for setting CMake flags.
+
+Building from source vs. using binaries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Using binaries is a fast and simple way of working with the last release
+of Arrow. However, if you use these it means that you will be unable to
+make changes to the Arrow C++ library.
+
+**Note:** every language has it's own way of dealing with binaries.
Review comment:
```suggestion
**Note:** every language has its own way of dealing with binaries.
```
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,21 +31,120 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
+**********************************
+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.
-Building C++
-============
+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.
-.. _build-pyarrow:
+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>`_.
Review comment:
```suggestion
This content is intended to help explain the concepts related to
and tools required for building Arrow's C++ library from source.
If you are looking for the specific required steps, or already feel
comfortable
with compiling Arrow's C++ library, 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>`_.
```
How about we add a little bit here to emphasise that this section is about
*understanding* and isn't intended to provide concrete steps for the reader?
##########
File path: docs/source/developers/guide/step_by_step/building.rst
##########
@@ -31,21 +31,120 @@
.. _build-arrow:
-*********************************
-Building Arrow's libraries 🏋🏿♀️
-*********************************
+**********************************
+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.
-Building C++
-============
+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.
-.. _build-pyarrow:
+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 PyArrow
-================
+Building Arrow C++
+==================
-.. _build-rarrow:
+Why build Arrow 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,
Review comment:
```suggestion
underlying C++ functions. If you want to work on PyArrow or 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]
