nealrichardson commented on a change in pull request #7021: URL: https://github.com/apache/arrow/pull/7021#discussion_r419518977
########## File path: docs/source/developers/docker.rst ########## @@ -0,0 +1,197 @@ +.. raw:: html + + <!-- + 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. + --> + +Running Docker Builds +===================== + +Most of our Linux based continuous integration tasks are decoupled from public +CI services using docker and docker-compose. Keeping the CI configuration +minimal makes local reproducibility possible. + +Usage +----- + +There are multiple ways to execute the docker based builds. The recommended is +to use the archery tool: + +Installation +~~~~~~~~~~~~ + +Requires ``python>=3.5``. It is recommended to install archery in ``editable`` +mode to automatically update the intallation by pulling the arrow repository. + +.. code:: bash + + pip install -e dev/archery[docker] + +Inspect the available commands and options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: bash + + archery docker --help + archery docker run --help + +``archery docker run`` tries to provide a similar interface to Review comment: Does it though? `run` here seems to entail `build && run`. ########## File path: docs/source/developers/docker.rst ########## @@ -0,0 +1,143 @@ +.. raw:: html + + <!-- + 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. + --> + +Running Docker Builds +===================== + +Most of our Linux based continuous integration tasks are decoupled from public +CI services using docker and docker-compose. Keeping the CI configuration +minimal makes local reproducibility possible. + +Usage +----- + +There are multiple ways to execute the docker based builds. The recommented is +to use the archery tool: Review comment: An immediate followup, right? I'm not sure that I agree with deferring but I'll allow it as long as it's the next thing you do. It looks like you already added some of the relevant information below, not sure how much more you need. ########## File path: docs/source/developers/docker.rst ########## @@ -0,0 +1,143 @@ +.. raw:: html + + <!-- + 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. + --> + +Running Docker Builds +===================== + +Most of our Linux based continuous integration tasks are decoupled from public +CI services using docker and docker-compose. Keeping the CI configuration +minimal makes local reproducibility possible. + +Usage +----- + +There are multiple ways to execute the docker based builds. The recommented is +to use the archery tool: + +Installation: + +.. code:: bash + + pip install -e dev/archery[docker] + +Execute a build: + +.. code::bash + + archery docker run conda-python Review comment: Sounds like YAGNI to me, anyone else have an opinion? ########## File path: docs/source/example1.dat ########## @@ -0,0 +1 @@ +some data Review comment: Was this supposed to be checked in? ########## File path: docs/source/developers/integration.rst ########## @@ -56,15 +56,19 @@ build mount is used for caching and sharing state between staged images. You can build and run a service by using the `build` and `run` docker-compose sub-command, e.g. `docker-compose build python && docker-compose run python`. We do not publish the build images, you need to build them manually. This -method requires the user to build the images in reverse dependency order. To -simplify this, we provide a Makefile. +method requires the user to build the images in reverse dependency order. .. code-block:: shell # Build and run manually - docker-compose build cpp - docker-compose build python - docker-compose run python + docker-compose build conda-cpp + docker-compose build conda-python + docker-compose run conda-python - # Using the makefile with proper image dependency resolution - make -f Makefile.docker python +To simplify this, Archery provides a command for it: + +.. code-block:: shell + + archery docker run conda-python + +See the `Running Docker Builds`_ for more details. Review comment: ```suggestion See `Running Docker Builds`_ for more details. ``` ########## File path: docs/source/developers/docker.rst ########## @@ -0,0 +1,197 @@ +.. raw:: html + + <!-- + 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. + --> + +Running Docker Builds +===================== + +Most of our Linux based continuous integration tasks are decoupled from public +CI services using docker and docker-compose. Keeping the CI configuration +minimal makes local reproducibility possible. + +Usage +----- + +There are multiple ways to execute the docker based builds. The recommended is +to use the archery tool: + +Installation +~~~~~~~~~~~~ + +Requires ``python>=3.5``. It is recommended to install archery in ``editable`` +mode to automatically update the intallation by pulling the arrow repository. + +.. code:: bash + + pip install -e dev/archery[docker] + +Inspect the available commands and options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: bash + + archery docker --help + archery docker run --help + +``archery docker run`` tries to provide a similar interface to +``docker-compose run``, but with builtin support for building hierarchical +images. + +Examples +~~~~~~~~ + +**Execute a build:** + +.. code:: bash + + archery docker run conda-python + +Archery calls the following docker-compose commands: + +.. code:: bash + + docker-compose pull --ignore-pull-failures conda-cpp + docker-compose build conda-cpp + docker-compose pull --ignore-pull-failures conda-python + docker-compose build conda-python + docker-compose run --rm conda-python + +**To disable the image pulling:** + +.. code:: bash + + archery docker run --no-cache conda-python + +Which translates to: + +.. code:: bash + + docker-compose build --no-cache conda-cpp + docker-compose build --no-cache conda-python + docker-compose run --rm conda-python + +**To disable the cache only for the leaf image:** + +Useful to force building the development version of a dependency. +The leaf image is ``conda-python-pandas`` in the example. + +.. code:: bash + + PANDAS=master archery docker run --no-cache-leaf conda-python-pandas + +Which translates to: + +.. code:: bash + + export PANDAS=master + docker-compose pull --ignore-pull-failures conda-cpp + docker-compose build conda-cpp + docker-compose pull --ignore-pull-failures conda-python + docker-compose build conda-python + docker-compose build --no-cache conda-python-pandas + docker-compose run --rm conda-python-pandas + Review comment: Wish: a `--dry-run` flag that just prints the commands that would be run. Would be helpful for those who are more familiar with `docker-compose` and for those who need to edit docker-compose.yml ########## File path: docs/source/developers/docker.rst ########## @@ -0,0 +1,197 @@ +.. raw:: html + + <!-- + 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. + --> + +Running Docker Builds +===================== + +Most of our Linux based continuous integration tasks are decoupled from public +CI services using docker and docker-compose. Keeping the CI configuration +minimal makes local reproducibility possible. + +Usage +----- + +There are multiple ways to execute the docker based builds. The recommended is +to use the archery tool: + +Installation +~~~~~~~~~~~~ + +Requires ``python>=3.5``. It is recommended to install archery in ``editable`` +mode to automatically update the intallation by pulling the arrow repository. + +.. code:: bash + + pip install -e dev/archery[docker] + +Inspect the available commands and options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: bash + + archery docker --help + archery docker run --help + +``archery docker run`` tries to provide a similar interface to +``docker-compose run``, but with builtin support for building hierarchical +images. + +Examples +~~~~~~~~ + +**Execute a build:** + +.. code:: bash + + archery docker run conda-python + +Archery calls the following docker-compose commands: + +.. code:: bash + + docker-compose pull --ignore-pull-failures conda-cpp + docker-compose build conda-cpp + docker-compose pull --ignore-pull-failures conda-python + docker-compose build conda-python + docker-compose run --rm conda-python + +**To disable the image pulling:** + +.. code:: bash + + archery docker run --no-cache conda-python + +Which translates to: + +.. code:: bash + + docker-compose build --no-cache conda-cpp + docker-compose build --no-cache conda-python + docker-compose run --rm conda-python + +**To disable the cache only for the leaf image:** + +Useful to force building the development version of a dependency. +The leaf image is ``conda-python-pandas`` in the example. Review comment: This still doesn't tell me what a leaf image is. ########## File path: docs/source/developers/docker.rst ########## @@ -0,0 +1,197 @@ +.. raw:: html + + <!-- + 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. + --> + +Running Docker Builds +===================== + +Most of our Linux based continuous integration tasks are decoupled from public +CI services using docker and docker-compose. Keeping the CI configuration +minimal makes local reproducibility possible. + +Usage +----- + +There are multiple ways to execute the docker based builds. The recommended is +to use the archery tool: + +Installation +~~~~~~~~~~~~ + +Requires ``python>=3.5``. It is recommended to install archery in ``editable`` Review comment: ```suggestion ``archery`` requires ``python>=3.5``. It is recommended to install archery in ``editable`` ``` ########## File path: docs/source/developers/docker.rst ########## @@ -0,0 +1,197 @@ +.. raw:: html + + <!-- + 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. + --> + +Running Docker Builds +===================== + +Most of our Linux based continuous integration tasks are decoupled from public +CI services using docker and docker-compose. Keeping the CI configuration +minimal makes local reproducibility possible. + +Usage +----- + +There are multiple ways to execute the docker based builds. The recommended is +to use the archery tool: + +Installation +~~~~~~~~~~~~ + +Requires ``python>=3.5``. It is recommended to install archery in ``editable`` +mode to automatically update the intallation by pulling the arrow repository. + +.. code:: bash + + pip install -e dev/archery[docker] + +Inspect the available commands and options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: bash + + archery docker --help + archery docker run --help + +``archery docker run`` tries to provide a similar interface to +``docker-compose run``, but with builtin support for building hierarchical +images. + +Examples +~~~~~~~~ + +**Execute a build:** + +.. code:: bash + + archery docker run conda-python + +Archery calls the following docker-compose commands: + +.. code:: bash + + docker-compose pull --ignore-pull-failures conda-cpp + docker-compose build conda-cpp + docker-compose pull --ignore-pull-failures conda-python + docker-compose build conda-python + docker-compose run --rm conda-python + +**To disable the image pulling:** + +.. code:: bash + + archery docker run --no-cache conda-python + +Which translates to: + +.. code:: bash + + docker-compose build --no-cache conda-cpp + docker-compose build --no-cache conda-python + docker-compose run --rm conda-python + +**To disable the cache only for the leaf image:** + +Useful to force building the development version of a dependency. +The leaf image is ``conda-python-pandas`` in the example. + +.. code:: bash + + PANDAS=master archery docker run --no-cache-leaf conda-python-pandas + +Which translates to: + +.. code:: bash + + export PANDAS=master + docker-compose pull --ignore-pull-failures conda-cpp + docker-compose build conda-cpp + docker-compose pull --ignore-pull-failures conda-python + docker-compose build conda-python + docker-compose build --no-cache conda-python-pandas + docker-compose run --rm conda-python-pandas + +Note that it doens't pull the conda-python-pandas image and disable the cache +when building it. + +``PANDAS`` is a `build parameter <Docker Build Parameters>`_, see the +defaults in the .env file. + +**To entirely skip building the image:** + +.. code:: bash + + archery docker run --no-build conda-python + +In order to alter the runtime parameters pass docker environment variables to +the container during its execution: + +.. code:: bash + + archery docker run --env CMAKE_BUILD_TYPE=release ubuntu-cpp + +See the available C++ in the ``ci/scripts/cpp_build.sh`` script. + +**Run the image with custom command:** + +Custom docker commands may be passed as the second argument. The following Review comment: second argument? Looks like the fourth to me. ########## File path: docs/source/developers/docker.rst ########## @@ -0,0 +1,197 @@ +.. raw:: html + + <!-- + 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. + --> + +Running Docker Builds +===================== + +Most of our Linux based continuous integration tasks are decoupled from public +CI services using docker and docker-compose. Keeping the CI configuration +minimal makes local reproducibility possible. + +Usage +----- + +There are multiple ways to execute the docker based builds. The recommended is +to use the archery tool: + +Installation +~~~~~~~~~~~~ + +Requires ``python>=3.5``. It is recommended to install archery in ``editable`` +mode to automatically update the intallation by pulling the arrow repository. + +.. code:: bash + + pip install -e dev/archery[docker] + +Inspect the available commands and options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: bash + + archery docker --help + archery docker run --help + +``archery docker run`` tries to provide a similar interface to +``docker-compose run``, but with builtin support for building hierarchical +images. + +Examples +~~~~~~~~ + +**Execute a build:** + +.. code:: bash + + archery docker run conda-python + +Archery calls the following docker-compose commands: + +.. code:: bash + + docker-compose pull --ignore-pull-failures conda-cpp + docker-compose build conda-cpp + docker-compose pull --ignore-pull-failures conda-python + docker-compose build conda-python + docker-compose run --rm conda-python + +**To disable the image pulling:** + +.. code:: bash + + archery docker run --no-cache conda-python + +Which translates to: + +.. code:: bash + + docker-compose build --no-cache conda-cpp + docker-compose build --no-cache conda-python + docker-compose run --rm conda-python + +**To disable the cache only for the leaf image:** + +Useful to force building the development version of a dependency. +The leaf image is ``conda-python-pandas`` in the example. + +.. code:: bash + + PANDAS=master archery docker run --no-cache-leaf conda-python-pandas + +Which translates to: + +.. code:: bash + + export PANDAS=master + docker-compose pull --ignore-pull-failures conda-cpp + docker-compose build conda-cpp + docker-compose pull --ignore-pull-failures conda-python + docker-compose build conda-python + docker-compose build --no-cache conda-python-pandas + docker-compose run --rm conda-python-pandas + +Note that it doens't pull the conda-python-pandas image and disable the cache +when building it. + +``PANDAS`` is a `build parameter <Docker Build Parameters>`_, see the +defaults in the .env file. + +**To entirely skip building the image:** Review comment: why would I do this? ########## File path: docs/source/developers/docker.rst ########## @@ -0,0 +1,197 @@ +.. raw:: html + + <!-- + 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. + --> + +Running Docker Builds +===================== + +Most of our Linux based continuous integration tasks are decoupled from public +CI services using docker and docker-compose. Keeping the CI configuration +minimal makes local reproducibility possible. + +Usage +----- + +There are multiple ways to execute the docker based builds. The recommended is +to use the archery tool: + +Installation +~~~~~~~~~~~~ + +Requires ``python>=3.5``. It is recommended to install archery in ``editable`` +mode to automatically update the intallation by pulling the arrow repository. + +.. code:: bash + + pip install -e dev/archery[docker] + +Inspect the available commands and options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: bash + + archery docker --help + archery docker run --help + +``archery docker run`` tries to provide a similar interface to +``docker-compose run``, but with builtin support for building hierarchical +images. + +Examples +~~~~~~~~ + +**Execute a build:** + +.. code:: bash + + archery docker run conda-python + +Archery calls the following docker-compose commands: + +.. code:: bash + + docker-compose pull --ignore-pull-failures conda-cpp + docker-compose build conda-cpp + docker-compose pull --ignore-pull-failures conda-python + docker-compose build conda-python + docker-compose run --rm conda-python + +**To disable the image pulling:** + +.. code:: bash + + archery docker run --no-cache conda-python + +Which translates to: + +.. code:: bash + + docker-compose build --no-cache conda-cpp + docker-compose build --no-cache conda-python + docker-compose run --rm conda-python + +**To disable the cache only for the leaf image:** + +Useful to force building the development version of a dependency. +The leaf image is ``conda-python-pandas`` in the example. + +.. code:: bash + + PANDAS=master archery docker run --no-cache-leaf conda-python-pandas + +Which translates to: + +.. code:: bash + + export PANDAS=master + docker-compose pull --ignore-pull-failures conda-cpp + docker-compose build conda-cpp + docker-compose pull --ignore-pull-failures conda-python + docker-compose build conda-python + docker-compose build --no-cache conda-python-pandas + docker-compose run --rm conda-python-pandas + +Note that it doens't pull the conda-python-pandas image and disable the cache +when building it. + +``PANDAS`` is a `build parameter <Docker Build Parameters>`_, see the +defaults in the .env file. + +**To entirely skip building the image:** + +.. code:: bash + + archery docker run --no-build conda-python + +In order to alter the runtime parameters pass docker environment variables to +the container during its execution: Review comment: How? (be explicit, don't make me guess by inspecting the example) ########## File path: docs/source/developers/docker.rst ########## @@ -0,0 +1,197 @@ +.. raw:: html + + <!-- + 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. + --> + +Running Docker Builds +===================== + +Most of our Linux based continuous integration tasks are decoupled from public +CI services using docker and docker-compose. Keeping the CI configuration +minimal makes local reproducibility possible. + +Usage +----- + +There are multiple ways to execute the docker based builds. The recommended is +to use the archery tool: + +Installation +~~~~~~~~~~~~ + +Requires ``python>=3.5``. It is recommended to install archery in ``editable`` +mode to automatically update the intallation by pulling the arrow repository. + +.. code:: bash + + pip install -e dev/archery[docker] + +Inspect the available commands and options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: bash + + archery docker --help + archery docker run --help + +``archery docker run`` tries to provide a similar interface to +``docker-compose run``, but with builtin support for building hierarchical +images. + +Examples +~~~~~~~~ + +**Execute a build:** + +.. code:: bash + + archery docker run conda-python + +Archery calls the following docker-compose commands: + +.. code:: bash + + docker-compose pull --ignore-pull-failures conda-cpp + docker-compose build conda-cpp + docker-compose pull --ignore-pull-failures conda-python + docker-compose build conda-python + docker-compose run --rm conda-python + +**To disable the image pulling:** + +.. code:: bash + + archery docker run --no-cache conda-python + +Which translates to: + +.. code:: bash + + docker-compose build --no-cache conda-cpp + docker-compose build --no-cache conda-python + docker-compose run --rm conda-python + +**To disable the cache only for the leaf image:** + +Useful to force building the development version of a dependency. +The leaf image is ``conda-python-pandas`` in the example. + +.. code:: bash + + PANDAS=master archery docker run --no-cache-leaf conda-python-pandas + +Which translates to: + +.. code:: bash + + export PANDAS=master + docker-compose pull --ignore-pull-failures conda-cpp + docker-compose build conda-cpp + docker-compose pull --ignore-pull-failures conda-python + docker-compose build conda-python + docker-compose build --no-cache conda-python-pandas + docker-compose run --rm conda-python-pandas + +Note that it doens't pull the conda-python-pandas image and disable the cache +when building it. + +``PANDAS`` is a `build parameter <Docker Build Parameters>`_, see the +defaults in the .env file. + +**To entirely skip building the image:** + +.. code:: bash + + archery docker run --no-build conda-python + +In order to alter the runtime parameters pass docker environment variables to +the container during its execution: + +.. code:: bash + + archery docker run --env CMAKE_BUILD_TYPE=release ubuntu-cpp + +See the available C++ in the ``ci/scripts/cpp_build.sh`` script. Review comment: available C++... what? build flags? ########## File path: docs/source/developers/docker.rst ########## @@ -0,0 +1,197 @@ +.. raw:: html + + <!-- + 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. + --> + +Running Docker Builds +===================== + +Most of our Linux based continuous integration tasks are decoupled from public +CI services using docker and docker-compose. Keeping the CI configuration +minimal makes local reproducibility possible. + +Usage +----- + +There are multiple ways to execute the docker based builds. The recommended is +to use the archery tool: + +Installation +~~~~~~~~~~~~ + +Requires ``python>=3.5``. It is recommended to install archery in ``editable`` +mode to automatically update the intallation by pulling the arrow repository. + +.. code:: bash + + pip install -e dev/archery[docker] + +Inspect the available commands and options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: bash + + archery docker --help + archery docker run --help + +``archery docker run`` tries to provide a similar interface to +``docker-compose run``, but with builtin support for building hierarchical +images. + +Examples +~~~~~~~~ + +**Execute a build:** + +.. code:: bash + + archery docker run conda-python + +Archery calls the following docker-compose commands: + +.. code:: bash + + docker-compose pull --ignore-pull-failures conda-cpp + docker-compose build conda-cpp + docker-compose pull --ignore-pull-failures conda-python + docker-compose build conda-python + docker-compose run --rm conda-python + +**To disable the image pulling:** + +.. code:: bash + + archery docker run --no-cache conda-python + +Which translates to: + +.. code:: bash + + docker-compose build --no-cache conda-cpp + docker-compose build --no-cache conda-python + docker-compose run --rm conda-python + +**To disable the cache only for the leaf image:** + +Useful to force building the development version of a dependency. +The leaf image is ``conda-python-pandas`` in the example. + +.. code:: bash + + PANDAS=master archery docker run --no-cache-leaf conda-python-pandas + +Which translates to: + +.. code:: bash + + export PANDAS=master + docker-compose pull --ignore-pull-failures conda-cpp + docker-compose build conda-cpp + docker-compose pull --ignore-pull-failures conda-python + docker-compose build conda-python + docker-compose build --no-cache conda-python-pandas + docker-compose run --rm conda-python-pandas + +Note that it doens't pull the conda-python-pandas image and disable the cache Review comment: ```suggestion Note that it doesn't pull the conda-python-pandas image and disable the cache ``` ########## File path: docs/source/developers/docker.rst ########## @@ -0,0 +1,197 @@ +.. raw:: html + + <!-- + 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. + --> + +Running Docker Builds +===================== + +Most of our Linux based continuous integration tasks are decoupled from public +CI services using docker and docker-compose. Keeping the CI configuration +minimal makes local reproducibility possible. + +Usage +----- + +There are multiple ways to execute the docker based builds. The recommended is +to use the archery tool: + +Installation +~~~~~~~~~~~~ + +Requires ``python>=3.5``. It is recommended to install archery in ``editable`` +mode to automatically update the intallation by pulling the arrow repository. + +.. code:: bash + + pip install -e dev/archery[docker] + +Inspect the available commands and options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: bash + + archery docker --help + archery docker run --help + +``archery docker run`` tries to provide a similar interface to +``docker-compose run``, but with builtin support for building hierarchical +images. + +Examples +~~~~~~~~ + +**Execute a build:** + +.. code:: bash + + archery docker run conda-python + +Archery calls the following docker-compose commands: + +.. code:: bash + + docker-compose pull --ignore-pull-failures conda-cpp + docker-compose build conda-cpp + docker-compose pull --ignore-pull-failures conda-python + docker-compose build conda-python + docker-compose run --rm conda-python + +**To disable the image pulling:** + +.. code:: bash + + archery docker run --no-cache conda-python + +Which translates to: + +.. code:: bash + + docker-compose build --no-cache conda-cpp + docker-compose build --no-cache conda-python + docker-compose run --rm conda-python + +**To disable the cache only for the leaf image:** + +Useful to force building the development version of a dependency. +The leaf image is ``conda-python-pandas`` in the example. + +.. code:: bash + + PANDAS=master archery docker run --no-cache-leaf conda-python-pandas + +Which translates to: + +.. code:: bash + + export PANDAS=master + docker-compose pull --ignore-pull-failures conda-cpp + docker-compose build conda-cpp + docker-compose pull --ignore-pull-failures conda-python + docker-compose build conda-python + docker-compose build --no-cache conda-python-pandas + docker-compose run --rm conda-python-pandas + +Note that it doens't pull the conda-python-pandas image and disable the cache +when building it. + +``PANDAS`` is a `build parameter <Docker Build Parameters>`_, see the +defaults in the .env file. + +**To entirely skip building the image:** + +.. code:: bash + + archery docker run --no-build conda-python + +In order to alter the runtime parameters pass docker environment variables to +the container during its execution: + +.. code:: bash + + archery docker run --env CMAKE_BUILD_TYPE=release ubuntu-cpp + +See the available C++ in the ``ci/scripts/cpp_build.sh`` script. + +**Run the image with custom command:** + +Custom docker commands may be passed as the second argument. The following +example starts an interactive ``bash`` session in the container - useful for +debugging the build interactively: + +.. code:: bash + + archery docker run ubuntu-cpp bash + + +Development +----------- + +The docker-compose configuration is tuned towards reusable development +containers using hierarchical images. For example multiple language bindings +are dependent on the C++ implementation, so instead of redefining the +C++ environment multiple Dockerfiles, we can reuse the exact same base C++ +image when building Glib, Ruby, R and Python bindings. +This helps reducing duplications and preventing a series of maintenance, but Review comment: ```suggestion This reduces duplication and streamlines maintenance, but ``` ---------------------------------------------------------------- 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. For queries about this service, please contact Infrastructure at: [email protected]
