Add offline build how-to in thirdparty/README.md

cpp/README.md

@@ -21,10 +21,10 @@
 
 ## System setup
 
-Arrow uses CMake as a build configuration system. Currently, it supports in-source and
-out-of-source builds with the latter one being preferred.
+Arrow uses CMake as a build configuration system. Currently, it supports
+in-source and out-of-source builds with the latter one being preferred.
 
-Build Arrow requires:
+Building Arrow requires:
 
 * A C++11-enabled compiler. On Linux, gcc 4.8 and higher should be sufficient.
 * CMake
@@ -108,11 +108,11 @@ ASAN, and `ARROW_USE_ASAN` is mutually-exclusive with the valgrind option
 
 ### Building/Running fuzzers
 
-Fuzzers can help finding unhandled exceptions and problems with untrusted input that
-may lead to crashes, security issues and undefined behavior. They do this by
-generating random input data and observing the behavior of the executed code. To build
-the fuzzer code, LLVM is required (GCC-based compilers won't work). You can build them
-using the following code:
+Fuzzers can help finding unhandled exceptions and problems with untrusted input
+that may lead to crashes, security issues and undefined behavior. They do this
+by generating random input data and observing the behavior of the executed
+code. To build the fuzzer code, LLVM is required (GCC-based compilers won't
+work). You can build them using the following code:
 
     cmake -DARROW_FUZZING=ON -DARROW_USE_ASAN=ON ..
 
@@ -158,7 +158,7 @@ There are some problems that may occur during the compilation process:
 
 ### Third-party dependencies and configuration
 
-Arrow depends on a number of thirdparty libraries. We support these in a few
+Arrow depends on a number of third-party libraries. We support these in a few
 ways:
 
 * Building dependencies from source by downloading archives from the internet
@@ -166,7 +166,8 @@ ways:
   builds)
 * Building with locally-installed libraries
 
-See [thirdparty/README.md][5] for details about these options.
+See [thirdparty/README.md][5] for details about these options and how to
+configure your build toolchain.
 
 ### Building Python integration library (optional)
 

cpp/thirdparty/README.md

@@ -0,0 +1,89 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# Arrow C++ Thirdparty Dependencies
+
+The version numbers for our third-party dependencies are listed in
+`thirdparty/versions.txt`. This is used by the CMake build system as well as
+the dependency downloader script (see below), which can be used to set up
+offline builds.
+
+## Configuring your own build toolchain
+
+To set up your own specific build toolchain, here are the relevant environment
+variables
+
+* Boost: `BOOST_ROOT`
+* Googletest: `GTEST_HOME` (only required to build the unit tests)
+* gflags: `GFLAGS_HOME` (only required to build the unit tests)
+* Google Benchmark: `GBENCHMARK_HOME` (only required if building benchmarks)
+* Flatbuffers: `FLATBUFFERS_HOME` (only required for -DARROW_IPC=on, which is
+  the default)
+* Hadoop: `HADOOP_HOME` (only required for the HDFS I/O extensions)
+* jemalloc: `JEMALLOC_HOME`
+* brotli: `BROTLI_HOME`, can be disabled with `-DARROW_WITH_BROTLI=off`
+* lz4: `LZ4_HOME`, can be disabled with `-DARROW_WITH_LZ4=off`
+* snappy: `SNAPPY_HOME`, can be disabled with `-DARROW_WITH_SNAPPY=off`
+* zlib: `ZLIB_HOME`, can be disabled with `-DARROW_WITH_ZLIB=off`
+* zstd: `ZSTD_HOME`, can be disabled with `-DARROW_WITH_ZSTD=off`
+
+If you have all of your toolchain libraries installed at the same prefix, you
+can use the environment variable `$ARROW_BUILD_TOOLCHAIN` to automatically set
+all of these variables. Note that `ARROW_BUILD_TOOLCHAIN` will not set
+`BOOST_ROOT`, so if you have custom Boost installation, you must set this
+environment variable separately.
+
+## Configuring for offline builds
+
+If you do not use the above variables to direct the Arrow build system to
+preinstalled dependencies, they will be built automatically by the build
+system. The source archive for each dependency will be downloaded via the
+internet, which can cause issues in environments with limited access to the
+internet.
+
+To enable offline builds, you can download the source artifacts yourself and
+use environment variables of the form `ARROW_$LIBRARY_URL` to direct the build
+system to read from a local file rather than accessing the internet.
+
+To make this easier for you, we have prepared a script
+`thirdparty/download_dependencies.sh` which will download the correct version
+of each dependency to a directory of your choosing. It will print a list of
+bash-style environment variable statements at the end to use for your build
+script:
+
+```shell
+$ ./thirdparty/download_dependencies $HOME/arrow-thirdparty-deps
+# some output omitted
+
+# Environment variables for offline Arrow build
+export ARROW_BOOST_URL=$HOME/arrow-thirdparty-deps/boost.tar.gz
+export ARROW_GTEST_URL=$HOME/arrow-thirdparty-deps/gtest.tar.gz
+export ARROW_GFLAGS_URL=$HOME/arrow-thirdparty-deps/gflags.tar.gz
+export ARROW_GBENCHMARK_URL=$HOME/arrow-thirdparty-deps/gbenchmark.tar.gz
+export ARROW_FLATBUFFERS_URL=$HOME/arrow-thirdparty-deps/flatbuffers.tar.gz
+export ARROW_RAPIDJSON_URL=$HOME/arrow-thirdparty-deps/rapidjson.tar.gz
+export ARROW_SNAPPY_URL=$HOME/arrow-thirdparty-deps/snappy.tar.gz
+export ARROW_BROTLI_URL=$HOME/arrow-thirdparty-deps/brotli.tar.gz
+export ARROW_LZ4_URL=$HOME/arrow-thirdparty-deps/lz4.tar.gz
+export ARROW_ZLIB_URL=$HOME/arrow-thirdparty-deps/zlib.tar.gz
+export ARROW_ZSTD_URL=$HOME/arrow-thirdparty-deps/zstd.tar.gz
+export ARROW_PROTOBUF_URL=$HOME/arrow-thirdparty-deps/protobuf.tar.gz
+export ARROW_GRPC_URL=$HOME/arrow-thirdparty-deps/grpc.tar.gz
+export ARROW_ORC_URL=$HOME/arrow-thirdparty-deps/orc.tar.gz
+```