You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@arrow.apache.org by GitBox <gi...@apache.org> on 2021/12/01 08:48:53 UTC
[GitHub] [arrow] AlenkaF opened a new pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
AlenkaF opened a new pull request #11820:
URL: https://github.com/apache/arrow/pull/11820
Add Building C++ and PyArrow sections of the New Contributor's guide.
--
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-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] AlenkaF commented on a change in pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
Posted by GitBox <gi...@apache.org>.
AlenkaF commented on a change in pull request #11820:
URL: https://github.com/apache/arrow/pull/11820#discussion_r761719996
##########
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:
Yeah, showing I am still a little confused :P Will try to rephrase - as I would love to have this info when I started ;)
--
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-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] AlenkaF commented on a change in pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
Posted by GitBox <gi...@apache.org>.
AlenkaF commented on a change in pull request #11820:
URL: https://github.com/apache/arrow/pull/11820#discussion_r761708121
##########
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:
Oh, didn't even know that. Will have to learn about other libraries to be able to explain the difference. Thanks for pointing it out!
--
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-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] ursabot edited a comment on pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
Posted by GitBox <gi...@apache.org>.
ursabot edited a comment on pull request #11820:
URL: https://github.com/apache/arrow/pull/11820#issuecomment-988794944
Benchmark runs are scheduled for baseline = 6896c6eeca22c2ea3d713aa64cfea518499de0c6 and contender = 065b1fcba985b067e960947e79ae62c8925dc42a. 065b1fcba985b067e960947e79ae62c8925dc42a is a master commit associated with this PR. Results will be available as each benchmark for each run completes.
Conbench compare runs links:
[Finished :arrow_down:0.0% :arrow_up:0.0%] [ec2-t3-xlarge-us-east-2](https://conbench.ursa.dev/compare/runs/84ac46d7a7c64b24a9f516b34d59f3da...eae4e29a561843298f064f2a35c3f5a8/)
[Scheduled] [ursa-i9-9960x](https://conbench.ursa.dev/compare/runs/30c6b37602aa4b9d8ed4a3169c6fb346...e65db6d792254adfa7caed792bc8f0b9/)
[Scheduled] [ursa-thinkcentre-m75q](https://conbench.ursa.dev/compare/runs/71c8f1c6e7d046cb8731852ae259e854...3650988425bf4321abe68911540cca5e/)
Supported benchmarks:
ec2-t3-xlarge-us-east-2: Supported benchmark langs: Python. Runs only benchmarks with cloud = True
ursa-i9-9960x: Supported benchmark langs: Python, R, JavaScript
ursa-thinkcentre-m75q: Supported benchmark langs: C++, Java
--
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-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] jorisvandenbossche commented on a change in pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
Posted by GitBox <gi...@apache.org>.
jorisvandenbossche commented on a change in pull request #11820:
URL: https://github.com/apache/arrow/pull/11820#discussion_r761260095
##########
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:
```suggestion
compiling the source code and use of CMake. You may have some
```
--
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-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] AlenkaF commented on pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
Posted by GitBox <gi...@apache.org>.
AlenkaF commented on pull request #11820:
URL: https://github.com/apache/arrow/pull/11820#issuecomment-986688195
Added the suggestions and the TODO parts (flags, env vars and CMake presets). I think this is ready for another round of review @thisisnic @jorisvandenbossche @pitrou Thank you!
--
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-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] AlenkaF commented on a change in pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
Posted by GitBox <gi...@apache.org>.
AlenkaF commented on a change in pull request #11820:
URL: https://github.com/apache/arrow/pull/11820#discussion_r762820605
##########
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:
Thanks for pointing it out! I will rephrase.
--
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-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] pitrou commented on a change in pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
Posted by GitBox <gi...@apache.org>.
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-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] jorisvandenbossche commented on a change in pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
Posted by GitBox <gi...@apache.org>.
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] thisisnic commented on a change in pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
Posted by GitBox <gi...@apache.org>.
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] thisisnic commented on a change in pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
Posted by GitBox <gi...@apache.org>.
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] wjones127 commented on a change in pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
Posted by GitBox <gi...@apache.org>.
wjones127 commented on a change in pull request #11820:
URL: https://github.com/apache/arrow/pull/11820#discussion_r761657687
##########
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
Review comment:
Two things worth mentioning here:
1. R and Python have specific lists of flags in their respective building docs that can be referenced.
2. We now have [CMake Presets](https://github.com/apache/arrow/blob/master/docs/source/developers/cpp/building.rst#cmake-presets) which are useful starting points.
--
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-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] thisisnic closed pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
Posted by GitBox <gi...@apache.org>.
thisisnic closed pull request #11820:
URL: https://github.com/apache/arrow/pull/11820
--
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-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] ursabot commented on pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
Posted by GitBox <gi...@apache.org>.
ursabot commented on pull request #11820:
URL: https://github.com/apache/arrow/pull/11820#issuecomment-988794944
Benchmark runs are scheduled for baseline = 6896c6eeca22c2ea3d713aa64cfea518499de0c6 and contender = 065b1fcba985b067e960947e79ae62c8925dc42a. 065b1fcba985b067e960947e79ae62c8925dc42a is a master commit associated with this PR. Results will be available as each benchmark for each run completes.
Conbench compare runs links:
[Scheduled] [ec2-t3-xlarge-us-east-2](https://conbench.ursa.dev/compare/runs/84ac46d7a7c64b24a9f516b34d59f3da...eae4e29a561843298f064f2a35c3f5a8/)
[Scheduled] [ursa-i9-9960x](https://conbench.ursa.dev/compare/runs/30c6b37602aa4b9d8ed4a3169c6fb346...e65db6d792254adfa7caed792bc8f0b9/)
[Scheduled] [ursa-thinkcentre-m75q](https://conbench.ursa.dev/compare/runs/71c8f1c6e7d046cb8731852ae259e854...3650988425bf4321abe68911540cca5e/)
Supported benchmarks:
ec2-t3-xlarge-us-east-2: Supported benchmark langs: Python. Runs only benchmarks with cloud = True
ursa-i9-9960x: Supported benchmark langs: Python, R, JavaScript
ursa-thinkcentre-m75q: Supported benchmark langs: C++, Java
--
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-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] rok commented on a change in pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
Posted by GitBox <gi...@apache.org>.
rok commented on a change in pull request #11820:
URL: https://github.com/apache/arrow/pull/11820#discussion_r760072636
##########
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 work done in other
+languages (Python, R, ..) is wrapping-binding-connecting underlying
Review comment:
```suggestion
languages (Python, R, ..) are wrapping underlying
```
##########
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 work done in other
Review comment:
```suggestion
The core of Arrow is written in C++ and all bindings in other
```
--
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-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] AlenkaF commented on pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
Posted by GitBox <gi...@apache.org>.
AlenkaF commented on pull request #11820:
URL: https://github.com/apache/arrow/pull/11820#issuecomment-984586292
Failing build doesn't seem to be related (RStudio Package Manager error).
--
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-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] jorisvandenbossche commented on a change in pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
Posted by GitBox <gi...@apache.org>.
jorisvandenbossche commented on a change in pull request #11820:
URL: https://github.com/apache/arrow/pull/11820#discussion_r761262716
##########
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
Review comment:
The "uses make for the actual build" actually depends on the cmake settings. For example we recommend to use ninja instead of make.
##########
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:
This sentence is a bit hard to read. Maybe something like "You will probably need to tweak some CMake flags for compiling Arrow."
##########
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:
```suggestion
After building the C++ part of Arrow you have to build PyArrow on top of it
```
##########
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
Review comment:
This is only true for the C++ implementation and its bindings. We should maybe try to reword this a bit to more correctly represent the fact that there are non-C++ Arrow implementations
##########
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:
```suggestion
for the actual build. In the compilation process of Arrow what will
```
--
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-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] github-actions[bot] commented on pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
Posted by GitBox <gi...@apache.org>.
github-actions[bot] commented on pull request #11820:
URL: https://github.com/apache/arrow/pull/11820#issuecomment-983419108
https://issues.apache.org/jira/browse/ARROW-14753
--
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-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] ursabot edited a comment on pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
Posted by GitBox <gi...@apache.org>.
ursabot edited a comment on pull request #11820:
URL: https://github.com/apache/arrow/pull/11820#issuecomment-988794944
Benchmark runs are scheduled for baseline = 6896c6eeca22c2ea3d713aa64cfea518499de0c6 and contender = 065b1fcba985b067e960947e79ae62c8925dc42a. 065b1fcba985b067e960947e79ae62c8925dc42a is a master commit associated with this PR. Results will be available as each benchmark for each run completes.
Conbench compare runs links:
[Finished :arrow_down:0.0% :arrow_up:0.0%] [ec2-t3-xlarge-us-east-2](https://conbench.ursa.dev/compare/runs/84ac46d7a7c64b24a9f516b34d59f3da...eae4e29a561843298f064f2a35c3f5a8/)
[Finished :arrow_down:0.0% :arrow_up:0.0%] [ursa-i9-9960x](https://conbench.ursa.dev/compare/runs/30c6b37602aa4b9d8ed4a3169c6fb346...e65db6d792254adfa7caed792bc8f0b9/)
[Finished :arrow_down:0.22% :arrow_up:0.04%] [ursa-thinkcentre-m75q](https://conbench.ursa.dev/compare/runs/71c8f1c6e7d046cb8731852ae259e854...3650988425bf4321abe68911540cca5e/)
Supported benchmarks:
ec2-t3-xlarge-us-east-2: Supported benchmark langs: Python. Runs only benchmarks with cloud = True
ursa-i9-9960x: Supported benchmark langs: Python, R, JavaScript
ursa-thinkcentre-m75q: Supported benchmark langs: C++, Java
--
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-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] ursabot edited a comment on pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
Posted by GitBox <gi...@apache.org>.
ursabot edited a comment on pull request #11820:
URL: https://github.com/apache/arrow/pull/11820#issuecomment-988794944
Benchmark runs are scheduled for baseline = 6896c6eeca22c2ea3d713aa64cfea518499de0c6 and contender = 065b1fcba985b067e960947e79ae62c8925dc42a. 065b1fcba985b067e960947e79ae62c8925dc42a is a master commit associated with this PR. Results will be available as each benchmark for each run completes.
Conbench compare runs links:
[Finished :arrow_down:0.0% :arrow_up:0.0%] [ec2-t3-xlarge-us-east-2](https://conbench.ursa.dev/compare/runs/84ac46d7a7c64b24a9f516b34d59f3da...eae4e29a561843298f064f2a35c3f5a8/)
[Finished :arrow_down:0.0% :arrow_up:0.0%] [ursa-i9-9960x](https://conbench.ursa.dev/compare/runs/30c6b37602aa4b9d8ed4a3169c6fb346...e65db6d792254adfa7caed792bc8f0b9/)
[Scheduled] [ursa-thinkcentre-m75q](https://conbench.ursa.dev/compare/runs/71c8f1c6e7d046cb8731852ae259e854...3650988425bf4321abe68911540cca5e/)
Supported benchmarks:
ec2-t3-xlarge-us-east-2: Supported benchmark langs: Python. Runs only benchmarks with cloud = True
ursa-i9-9960x: Supported benchmark langs: Python, R, JavaScript
ursa-thinkcentre-m75q: Supported benchmark langs: C++, Java
--
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-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] AlenkaF commented on a change in pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
Posted by GitBox <gi...@apache.org>.
AlenkaF commented on a change in pull request #11820:
URL: https://github.com/apache/arrow/pull/11820#discussion_r761712578
##########
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:
Well, it's nicely explained in https://arrow.apache.org/overview/ 🤦♀️
--
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-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] AlenkaF commented on pull request #11820: ARROW-14753: [Doc] Steps in making your first PR - building C++
Posted by GitBox <gi...@apache.org>.
AlenkaF commented on pull request #11820:
URL: https://github.com/apache/arrow/pull/11820#issuecomment-985313525
Thanks everybody for the comments!
> Do you intend to fill the TODOs here or in another PR?
I wanted to do it later, but I think I gained some understanding to manage it now. In case the review will take longer as expected I would still think about putting it into a separate PR to make the process faster.
As this is harder topic to write about for me (flags and env variables) it would be great to have some suggestions!
--
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-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org