| |
| <!DOCTYPE html> |
| |
| |
| <html lang="en" data-content_root="../../" > |
| |
| <head> |
| <meta charset="utf-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" /> |
| |
| <title>Development Guidelines — Apache Arrow v23.0.0.dev37</title> |
| |
| |
| |
| <script data-cfasync="false"> |
| document.documentElement.dataset.mode = localStorage.getItem("mode") || ""; |
| document.documentElement.dataset.theme = localStorage.getItem("theme") || ""; |
| </script> |
| <!-- |
| this give us a css class that will be invisible only if js is disabled |
| --> |
| <noscript> |
| <style> |
| .pst-js-only { display: none !important; } |
| |
| </style> |
| </noscript> |
| |
| <!-- Loaded before other Sphinx assets --> |
| <link href="../../_static/styles/theme.css?digest=8878045cc6db502f8baf" rel="stylesheet" /> |
| <link href="../../_static/styles/pydata-sphinx-theme.css?digest=8878045cc6db502f8baf" rel="stylesheet" /> |
| |
| <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=03e43079" /> |
| <link rel="stylesheet" type="text/css" href="../../_static/copybutton.css?v=76b2166b" /> |
| <link rel="stylesheet" type="text/css" href="../../_static/sphinx-design.min.css?v=95c83b7e" /> |
| <link rel="stylesheet" type="text/css" href="../../_static/theme_overrides.css?v=8dcd28dc" /> |
| |
| <!-- So that users can add custom icons --> |
| <script src="../../_static/scripts/fontawesome.js?digest=8878045cc6db502f8baf"></script> |
| <!-- Pre-loaded scripts that we'll load fully later --> |
| <link rel="preload" as="script" href="../../_static/scripts/bootstrap.js?digest=8878045cc6db502f8baf" /> |
| <link rel="preload" as="script" href="../../_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf" /> |
| |
| <script src="../../_static/documentation_options.js?v=9fc6757a"></script> |
| <script src="../../_static/doctools.js?v=9bcbadda"></script> |
| <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script> |
| <script src="../../_static/clipboard.min.js?v=a7894cd8"></script> |
| <script src="../../_static/copybutton.js?v=3bb21c8c"></script> |
| <script src="../../_static/design-tabs.js?v=f930bc37"></script> |
| <script>DOCUMENTATION_OPTIONS.pagename = 'developers/cpp/development';</script> |
| <script> |
| DOCUMENTATION_OPTIONS.theme_version = '0.16.1'; |
| DOCUMENTATION_OPTIONS.theme_switcher_json_url = '/docs/_static/versions.json'; |
| DOCUMENTATION_OPTIONS.theme_switcher_version_match = 'dev/'; |
| DOCUMENTATION_OPTIONS.show_version_warning_banner = |
| true; |
| </script> |
| <link rel="canonical" href="https://arrow.apache.org/docs/developers/cpp/development.html" /> |
| <link rel="icon" href="../../_static/favicon.ico"/> |
| <link rel="index" title="Index" href="../../genindex.html" /> |
| <link rel="search" title="Search" href="../../search.html" /> |
| <link rel="next" title="Developing on Windows" href="windows.html" /> |
| <link rel="prev" title="Building Arrow C++" href="building.html" /> |
| |
| <meta name="viewport" content="width=device-width, initial-scale=1"/> |
| <meta name="docsearch:language" content="en"/> |
| <meta name="docsearch:version" content="23.0.0.dev37" /> |
| |
| <!-- Matomo --> |
| <script> |
| var _paq = window._paq = window._paq || []; |
| /* tracker methods like "setCustomDimension" should be called before "trackPageView" */ |
| /* We explicitly disable cookie tracking to avoid privacy issues */ |
| _paq.push(['disableCookies']); |
| _paq.push(['trackPageView']); |
| _paq.push(['enableLinkTracking']); |
| (function() { |
| var u="https://analytics.apache.org/"; |
| _paq.push(['setTrackerUrl', u+'matomo.php']); |
| _paq.push(['setSiteId', '20']); |
| var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; |
| g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s); |
| })(); |
| </script> |
| <!-- End Matomo Code --> |
| |
| </head> |
| |
| |
| <body data-bs-spy="scroll" data-bs-target=".bd-toc-nav" data-offset="180" data-bs-root-margin="0px 0px -60%" data-default-mode=""> |
| |
| |
| |
| <div id="pst-skip-link" class="skip-link d-print-none"><a href="#main-content">Skip to main content</a></div> |
| |
| <div id="pst-scroll-pixel-helper"></div> |
| |
| <button type="button" class="btn rounded-pill" id="pst-back-to-top"> |
| <i class="fa-solid fa-arrow-up"></i>Back to top</button> |
| |
| |
| <dialog id="pst-search-dialog"> |
| |
| <form class="bd-search d-flex align-items-center" |
| action="../../search.html" |
| method="get"> |
| <i class="fa-solid fa-magnifying-glass"></i> |
| <input type="search" |
| class="form-control" |
| name="q" |
| placeholder="Search the docs ..." |
| aria-label="Search the docs ..." |
| autocomplete="off" |
| autocorrect="off" |
| autocapitalize="off" |
| spellcheck="false"/> |
| <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd>K</kbd></span> |
| </form> |
| </dialog> |
| |
| <div class="pst-async-banner-revealer d-none"> |
| <aside id="bd-header-version-warning" class="d-none d-print-none" aria-label="Version warning"></aside> |
| </div> |
| |
| |
| <header class="bd-header navbar navbar-expand-lg bd-navbar d-print-none"> |
| <div class="bd-header__inner bd-page-width"> |
| <button class="pst-navbar-icon sidebar-toggle primary-toggle" aria-label="Site navigation"> |
| <span class="fa-solid fa-bars"></span> |
| </button> |
| |
| |
| <div class=" navbar-header-items__start"> |
| |
| <div class="navbar-item"> |
| |
| |
| |
| |
| |
| <a class="navbar-brand logo" href="../../index.html"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <img src="../../_static/arrow.png" class="logo__image only-light" alt="Apache Arrow v23.0.0.dev37 - Home"/> |
| <img src="../../_static/arrow-dark.png" class="logo__image only-dark pst-js-only" alt="Apache Arrow v23.0.0.dev37 - Home"/> |
| |
| |
| </a></div> |
| |
| </div> |
| |
| <div class=" navbar-header-items"> |
| |
| <div class="me-auto navbar-header-items__center"> |
| |
| <div class="navbar-item"> |
| <nav> |
| <ul class="bd-navbar-elements navbar-nav"> |
| |
| <li class="nav-item "> |
| <a class="nav-link nav-internal" href="../../format/index.html"> |
| Specifications |
| </a> |
| </li> |
| |
| |
| <li class="nav-item current active"> |
| <a class="nav-link nav-internal" href="../index.html"> |
| Development |
| </a> |
| </li> |
| |
| |
| <li class="nav-item "> |
| <a class="nav-link nav-internal" href="../../implementations.html"> |
| Implementations |
| </a> |
| </li> |
| |
| </ul> |
| </nav></div> |
| |
| </div> |
| |
| |
| <div class="navbar-header-items__end"> |
| |
| <div class="navbar-item navbar-persistent--container"> |
| |
| |
| <button class="btn search-button-field search-button__button pst-js-only" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip"> |
| <i class="fa-solid fa-magnifying-glass"></i> |
| <span class="search-button__default-text">Search</span> |
| <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span> |
| </button> |
| </div> |
| |
| |
| <div class="navbar-item"><div class="kapa-ai-bot"> |
| <script |
| async |
| src="https://widget.kapa.ai/kapa-widget.bundle.js" |
| data-website-id="9db461d5-ac77-4b3f-a5c5-75efa78339d2" |
| data-project-name="Apache Arrow" |
| data-project-color="#000000" |
| data-project-logo="https://arrow.apache.org/img/arrow-logo_chevrons_white-txt_black-bg.png" |
| data-modal-disclaimer="This is a custom LLM with access to all [Arrow documentation](https://arrow.apache.org/docs/). Please include the language you are using in your question, e.g., Python, C++, Java, R, etc." |
| data-consent-required="true" |
| data-user-analytics-cookie-enabled="false" |
| data-consent-screen-disclaimer="By clicking "I agree, let's chat", you consent to the use of the AI assistant in accordance with kapa.ai's [Privacy Policy](https://www.kapa.ai/content/privacy-policy). This service uses reCAPTCHA, which requires your consent to Google's [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms). By proceeding, you explicitly agree to both kapa.ai's and Google's privacy policies." |
| ></script> |
| |
| </div> |
| |
| </div> |
| |
| <div class="navbar-item"> |
| <div class="version-switcher__container dropdown pst-js-only"> |
| <button id="pst-version-switcher-button-2" |
| type="button" |
| class="version-switcher__button btn btn-sm dropdown-toggle" |
| data-bs-toggle="dropdown" |
| aria-haspopup="listbox" |
| aria-controls="pst-version-switcher-list-2" |
| aria-label="Version switcher list" |
| > |
| Choose version <!-- this text may get changed later by javascript --> |
| <span class="caret"></span> |
| </button> |
| <div id="pst-version-switcher-list-2" |
| class="version-switcher__menu dropdown-menu list-group-flush py-0" |
| role="listbox" aria-labelledby="pst-version-switcher-button-2"> |
| <!-- dropdown will be populated by javascript on page load --> |
| </div> |
| </div></div> |
| |
| <div class="navbar-item"> |
| |
| <button class="btn btn-sm nav-link pst-navbar-icon theme-switch-button pst-js-only" aria-label="Color mode" data-bs-title="Color mode" data-bs-placement="bottom" data-bs-toggle="tooltip"> |
| <i class="theme-switch fa-solid fa-sun fa-lg" data-mode="light" title="Light"></i> |
| <i class="theme-switch fa-solid fa-moon fa-lg" data-mode="dark" title="Dark"></i> |
| <i class="theme-switch fa-solid fa-circle-half-stroke fa-lg" data-mode="auto" title="System Settings"></i> |
| </button></div> |
| |
| <div class="navbar-item"><ul class="navbar-icon-links" |
| aria-label="Icon Links"> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://github.com/apache/arrow" title="GitHub" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-square-github fa-lg" aria-hidden="true"></i> |
| <span class="sr-only">GitHub</span></a> |
| </li> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://www.linkedin.com/company/apache-arrow/" title="LinkedIn" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-linkedin fa-lg" aria-hidden="true"></i> |
| <span class="sr-only">LinkedIn</span></a> |
| </li> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://bsky.app/profile/arrow.apache.org" title="BlueSky" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-bluesky fa-lg" aria-hidden="true"></i> |
| <span class="sr-only">BlueSky</span></a> |
| </li> |
| </ul></div> |
| |
| </div> |
| |
| </div> |
| |
| |
| <div class="navbar-persistent--mobile"> |
| |
| <button class="btn search-button-field search-button__button pst-js-only" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip"> |
| <i class="fa-solid fa-magnifying-glass"></i> |
| <span class="search-button__default-text">Search</span> |
| <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span> |
| </button> |
| </div> |
| |
| |
| |
| <button class="pst-navbar-icon sidebar-toggle secondary-toggle" aria-label="On this page"> |
| <span class="fa-solid fa-outdent"></span> |
| </button> |
| |
| </div> |
| |
| </header> |
| |
| |
| <div class="bd-container"> |
| <div class="bd-container__inner bd-page-width"> |
| |
| |
| |
| <dialog id="pst-primary-sidebar-modal"></dialog> |
| <div id="pst-primary-sidebar" class="bd-sidebar-primary bd-sidebar"> |
| |
| |
| |
| <div class="sidebar-header-items sidebar-primary__section"> |
| |
| |
| <div class="sidebar-header-items__center"> |
| |
| |
| |
| <div class="navbar-item"> |
| <nav> |
| <ul class="bd-navbar-elements navbar-nav"> |
| |
| <li class="nav-item "> |
| <a class="nav-link nav-internal" href="../../format/index.html"> |
| Specifications |
| </a> |
| </li> |
| |
| |
| <li class="nav-item current active"> |
| <a class="nav-link nav-internal" href="../index.html"> |
| Development |
| </a> |
| </li> |
| |
| |
| <li class="nav-item "> |
| <a class="nav-link nav-internal" href="../../implementations.html"> |
| Implementations |
| </a> |
| </li> |
| |
| </ul> |
| </nav></div> |
| |
| |
| </div> |
| |
| |
| |
| <div class="sidebar-header-items__end"> |
| |
| <div class="navbar-item"><div class="kapa-ai-bot"> |
| <script |
| async |
| src="https://widget.kapa.ai/kapa-widget.bundle.js" |
| data-website-id="9db461d5-ac77-4b3f-a5c5-75efa78339d2" |
| data-project-name="Apache Arrow" |
| data-project-color="#000000" |
| data-project-logo="https://arrow.apache.org/img/arrow-logo_chevrons_white-txt_black-bg.png" |
| data-modal-disclaimer="This is a custom LLM with access to all [Arrow documentation](https://arrow.apache.org/docs/). Please include the language you are using in your question, e.g., Python, C++, Java, R, etc." |
| data-consent-required="true" |
| data-user-analytics-cookie-enabled="false" |
| data-consent-screen-disclaimer="By clicking "I agree, let's chat", you consent to the use of the AI assistant in accordance with kapa.ai's [Privacy Policy](https://www.kapa.ai/content/privacy-policy). This service uses reCAPTCHA, which requires your consent to Google's [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms). By proceeding, you explicitly agree to both kapa.ai's and Google's privacy policies." |
| ></script> |
| |
| </div> |
| |
| </div> |
| |
| <div class="navbar-item"> |
| <div class="version-switcher__container dropdown pst-js-only"> |
| <button id="pst-version-switcher-button-3" |
| type="button" |
| class="version-switcher__button btn btn-sm dropdown-toggle" |
| data-bs-toggle="dropdown" |
| aria-haspopup="listbox" |
| aria-controls="pst-version-switcher-list-3" |
| aria-label="Version switcher list" |
| > |
| Choose version <!-- this text may get changed later by javascript --> |
| <span class="caret"></span> |
| </button> |
| <div id="pst-version-switcher-list-3" |
| class="version-switcher__menu dropdown-menu list-group-flush py-0" |
| role="listbox" aria-labelledby="pst-version-switcher-button-3"> |
| <!-- dropdown will be populated by javascript on page load --> |
| </div> |
| </div></div> |
| |
| <div class="navbar-item"> |
| |
| <button class="btn btn-sm nav-link pst-navbar-icon theme-switch-button pst-js-only" aria-label="Color mode" data-bs-title="Color mode" data-bs-placement="bottom" data-bs-toggle="tooltip"> |
| <i class="theme-switch fa-solid fa-sun fa-lg" data-mode="light" title="Light"></i> |
| <i class="theme-switch fa-solid fa-moon fa-lg" data-mode="dark" title="Dark"></i> |
| <i class="theme-switch fa-solid fa-circle-half-stroke fa-lg" data-mode="auto" title="System Settings"></i> |
| </button></div> |
| |
| <div class="navbar-item"><ul class="navbar-icon-links" |
| aria-label="Icon Links"> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://github.com/apache/arrow" title="GitHub" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-square-github fa-lg" aria-hidden="true"></i> |
| <span class="sr-only">GitHub</span></a> |
| </li> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://www.linkedin.com/company/apache-arrow/" title="LinkedIn" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-linkedin fa-lg" aria-hidden="true"></i> |
| <span class="sr-only">LinkedIn</span></a> |
| </li> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://bsky.app/profile/arrow.apache.org" title="BlueSky" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-bluesky fa-lg" aria-hidden="true"></i> |
| <span class="sr-only">BlueSky</span></a> |
| </li> |
| </ul></div> |
| |
| </div> |
| |
| </div> |
| |
| <div class="sidebar-primary-items__start sidebar-primary__section"> |
| <div class="sidebar-primary-item"> |
| <nav class="bd-docs-nav bd-links" |
| aria-label="Section Navigation"> |
| <p class="bd-links__title" role="heading" aria-level="1">Section Navigation</p> |
| <div class="bd-toc-item navbar-nav"><ul class="current nav bd-sidenav"> |
| <li class="toctree-l1"><a class="reference internal" href="../bug_reports.html">Bug reports and feature requests</a></li> |
| <li class="toctree-l1 has-children"><a class="reference internal" href="../guide/index.html">New Contributor’s Guide</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul> |
| <li class="toctree-l2"><a class="reference internal" href="../guide/architectural_overview.html">Architectural Overview</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../guide/communication.html">Communication</a></li> |
| <li class="toctree-l2 has-children"><a class="reference internal" href="../guide/step_by_step/index.html">Steps in making your first PR</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul> |
| <li class="toctree-l3"><a class="reference internal" href="../guide/step_by_step/set_up.html">Set up</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../guide/step_by_step/building.html">Building the Arrow libraries 🏋🏿♀️</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../guide/step_by_step/finding_issues.html">Finding good first issues 🔎</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../guide/step_by_step/arrow_codebase.html">Working on the Arrow codebase 🧐</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../guide/step_by_step/testing.html">Testing 🧪</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../guide/step_by_step/styling.html">Styling 😎</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../guide/step_by_step/pr_lifecycle.html">Lifecycle of a pull request</a></li> |
| </ul> |
| </details></li> |
| <li class="toctree-l2"><a class="reference internal" href="../guide/documentation.html">Helping with documentation</a></li> |
| <li class="toctree-l2 has-children"><a class="reference internal" href="../guide/tutorials/index.html">Tutorials</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul> |
| <li class="toctree-l3"><a class="reference internal" href="../guide/tutorials/python_tutorial.html">Python tutorial</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../guide/tutorials/r_tutorial.html">R tutorials</a></li> |
| </ul> |
| </details></li> |
| <li class="toctree-l2"><a class="reference internal" href="../guide/resources.html">Additional information and resources</a></li> |
| </ul> |
| </details></li> |
| <li class="toctree-l1"><a class="reference internal" href="../overview.html">Contributing Overview</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../reviewing.html">Reviewing contributions</a></li> |
| <li class="toctree-l1 current active has-children"><a class="reference internal" href="index.html">C++ Development</a><details open="open"><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul class="current"> |
| <li class="toctree-l2"><a class="reference internal" href="building.html">Building Arrow C++</a></li> |
| <li class="toctree-l2 current active"><a class="current reference internal" href="#">Development Guidelines</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="windows.html">Developing on Windows</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="emscripten.html">Cross compiling for WebAssembly with Emscripten</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="conventions.html">Conventions</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="fuzzing.html">Fuzzing Arrow C++</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="compute.html">Developing Arrow C++ Compute</a></li> |
| <li class="toctree-l2 has-children"><a class="reference internal" href="acero.html">Developing Acero</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul> |
| <li class="toctree-l3"><a class="reference internal" href="acero/swiss_table.html">Swiss Table</a></li> |
| </ul> |
| </details></li> |
| </ul> |
| </details></li> |
| <li class="toctree-l1 has-children"><a class="reference internal" href="../java/index.html">Java Development</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul> |
| <li class="toctree-l2"><a class="reference internal" href="../java/building.html">Building Arrow Java</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../java/development.html">Development Guidelines</a></li> |
| </ul> |
| </details></li> |
| <li class="toctree-l1 has-children"><a class="reference internal" href="../python/index.html">Python Development</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul> |
| <li class="toctree-l2"><a class="reference internal" href="../python/building.html">Building PyArrow</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../python/development.html">Developing PyArrow</a></li> |
| </ul> |
| </details></li> |
| <li class="toctree-l1 has-children"><a class="reference internal" href="../continuous_integration/index.html">Continuous Integration</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul> |
| <li class="toctree-l2"><a class="reference internal" href="../continuous_integration/overview.html">Continuous Integration</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../continuous_integration/docker.html">Running Docker Builds</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../continuous_integration/archery.html">Daily Development using Archery</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../continuous_integration/crossbow.html">Packaging and Testing with Crossbow</a></li> |
| </ul> |
| </details></li> |
| <li class="toctree-l1"><a class="reference internal" href="../benchmarks.html">Benchmarks</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../documentation.html">Building the Documentation</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../release.html">Release Management Guide</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../release_verification.html">Release Verification Process</a></li> |
| </ul> |
| </div> |
| </nav></div> |
| </div> |
| |
| |
| <div class="sidebar-primary-items__end sidebar-primary__section"> |
| <div class="sidebar-primary-item"> |
| <div id="ethical-ad-placement" |
| class="flat" |
| data-ea-publisher="readthedocs" |
| data-ea-type="readthedocs-sidebar" |
| data-ea-manual="true"> |
| </div></div> |
| </div> |
| |
| |
| </div> |
| |
| <main id="main-content" class="bd-main" role="main"> |
| |
| |
| <div class="bd-content"> |
| <div class="bd-article-container"> |
| |
| <div class="bd-header-article d-print-none"> |
| <div class="header-article-items header-article__inner"> |
| |
| <div class="header-article-items__start"> |
| |
| <div class="header-article-item"> |
| |
| <nav aria-label="Breadcrumb" class="d-print-none"> |
| <ul class="bd-breadcrumbs"> |
| |
| <li class="breadcrumb-item breadcrumb-home"> |
| <a href="../../index.html" class="nav-link" aria-label="Home"> |
| <i class="fa-solid fa-home"></i> |
| </a> |
| </li> |
| |
| <li class="breadcrumb-item"><a href="../index.html" class="nav-link">Development</a></li> |
| |
| |
| <li class="breadcrumb-item"><a href="index.html" class="nav-link">C++ Development</a></li> |
| |
| <li class="breadcrumb-item active" aria-current="page"><span class="ellipsis">Development Guidelines</span></li> |
| </ul> |
| </nav> |
| </div> |
| |
| </div> |
| |
| |
| </div> |
| </div> |
| |
| |
| |
| |
| <div id="searchbox"></div> |
| <article class="bd-article"> |
| |
| <section id="development-guidelines"> |
| <span id="development-cpp"></span><h1>Development Guidelines<a class="headerlink" href="#development-guidelines" title="Link to this heading">#</a></h1> |
| <p>This section provides information for developers who wish to contribute to the |
| C++ codebase.</p> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p>Since most of the project’s developers work on Linux or macOS, not all |
| features or developer tools are uniformly supported on Windows. If you are |
| on Windows, have a look at <a class="reference internal" href="windows.html#developers-cpp-windows"><span class="std std-ref">Developing on Windows</span></a>.</p> |
| </div> |
| <section id="compiler-warning-levels"> |
| <h2>Compiler warning levels<a class="headerlink" href="#compiler-warning-levels" title="Link to this heading">#</a></h2> |
| <p>The <code class="docutils literal notranslate"><span class="pre">BUILD_WARNING_LEVEL</span></code> CMake option switches between sets of predetermined |
| compiler warning levels that we use for code tidiness. For release builds, the |
| default warning level is <code class="docutils literal notranslate"><span class="pre">PRODUCTION</span></code>, while for debug builds the default is |
| <code class="docutils literal notranslate"><span class="pre">CHECKIN</span></code>.</p> |
| <p>When using <code class="docutils literal notranslate"><span class="pre">CHECKIN</span></code> for debug builds, <code class="docutils literal notranslate"><span class="pre">-Werror</span></code> is added when using gcc |
| and clang, causing build failures for any warning, and <code class="docutils literal notranslate"><span class="pre">/WX</span></code> is set with MSVC |
| having the same effect.</p> |
| </section> |
| <section id="running-unit-tests"> |
| <h2>Running unit tests<a class="headerlink" href="#running-unit-tests" title="Link to this heading">#</a></h2> |
| <p>The <code class="docutils literal notranslate"><span class="pre">-DARROW_BUILD_TESTS=ON</span></code> CMake option enables building of unit test |
| executables. You can then either run them individually, by launching the |
| desired executable, or run them all at once by launching the <code class="docutils literal notranslate"><span class="pre">ctest</span></code> |
| executable (which is part of the CMake suite).</p> |
| <p>A possible invocation is something like:</p> |
| <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctest<span class="w"> </span>-j16<span class="w"> </span>--output-on-failure |
| </pre></div> |
| </div> |
| <p>where the <code class="docutils literal notranslate"><span class="pre">-j16</span></code> option runs up to 16 tests in parallel, taking advantage |
| of multiple CPU cores and hardware threads.</p> |
| </section> |
| <section id="running-benchmarks"> |
| <h2>Running benchmarks<a class="headerlink" href="#running-benchmarks" title="Link to this heading">#</a></h2> |
| <p>The <code class="docutils literal notranslate"><span class="pre">-DARROW_BUILD_BENCHMARKS=ON</span></code> CMake option enables building of benchmark |
| executables. You can then run benchmarks individually by launching the |
| corresponding executable from the command line, e.g.:</p> |
| <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>./build/release/arrow-builder-benchmark |
| </pre></div> |
| </div> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p>For meaningful benchmark numbers, it is very strongly recommended to build |
| in <code class="docutils literal notranslate"><span class="pre">Release</span></code> mode, so as to enable compiler optimizations.</p> |
| </div> |
| </section> |
| <section id="code-style-linting-and-ci"> |
| <h2>Code Style, Linting, and CI<a class="headerlink" href="#code-style-linting-and-ci" title="Link to this heading">#</a></h2> |
| <p>This project follows <a class="reference external" href="https://google.github.io/styleguide/cppguide.html">Google’s C++ Style Guide</a> with these exceptions:</p> |
| <ul class="simple"> |
| <li><p>We relax the line length restriction to 90 characters.</p></li> |
| <li><p>We use the <code class="docutils literal notranslate"><span class="pre">NULLPTR</span></code> macro in header files (instead of <code class="docutils literal notranslate"><span class="pre">nullptr</span></code>) defined |
| in <code class="docutils literal notranslate"><span class="pre">src/arrow/util/macros.h</span></code> to support building C++/CLI (ARROW-1134).</p></li> |
| <li><p>We relax the guide’s rules regarding structs. For public headers we should |
| use struct only for objects that are principally simple data containers where |
| it is OK to expose all the internal members and any methods are primarily |
| conveniences. For private headers the rules are relaxed further and structs |
| can be used where convenient for types that do not need access control even |
| though they may not be simple data containers.</p></li> |
| <li><p>We prefer pointers for output and input/output parameters (the |
| style guide recommends mutable references in some cases).</p></li> |
| </ul> |
| <p>Our continuous integration builds on GitHub Actions run the unit test |
| suites on a variety of platforms and configuration, including using |
| Address Sanitizer and Undefined Behavior Sanitizer to check for various |
| patterns of misbehaviour such as memory leaks. In addition, the |
| codebase is subjected to a number of code style and code cleanliness checks.</p> |
| <p>In order to have a passing CI build, your modified Git branch must pass the |
| following checks:</p> |
| <ul class="simple"> |
| <li><p>C++ builds with the project’s active version of <code class="docutils literal notranslate"><span class="pre">clang</span></code> without |
| compiler warnings with <code class="docutils literal notranslate"><span class="pre">-DBUILD_WARNING_LEVEL=CHECKIN</span></code>. Note that |
| there are classes of warnings (such as <code class="docutils literal notranslate"><span class="pre">-Wdocumentation</span></code>, see more |
| on this below) that are not caught by <code class="docutils literal notranslate"><span class="pre">gcc</span></code>.</p></li> |
| <li><p>Passes various C++ (and others) style checks by running |
| <code class="docutils literal notranslate"><span class="pre">pre-commit</span> <span class="pre">run</span> <span class="pre">--show-diff-on-failure</span> <span class="pre">--color=always</span> <span class="pre">--all-files</span> |
| <span class="pre">cpp</span></code>.</p></li> |
| </ul> |
| <p>On pull requests, the “Dev / Lint” pipeline will run these checks, and report |
| what files/lines need to be fixed, if any.</p> |
| <section id="checking-for-abi-and-api-stability"> |
| <h3>Checking for ABI and API stability<a class="headerlink" href="#checking-for-abi-and-api-stability" title="Link to this heading">#</a></h3> |
| <p>To build ABI compliance reports, you need to install the two tools |
| <code class="docutils literal notranslate"><span class="pre">abi-dumper</span></code> and <code class="docutils literal notranslate"><span class="pre">abi-compliance-checker</span></code>.</p> |
| <p>Build Arrow C++ in Debug mode, alternatively you could use <code class="docutils literal notranslate"><span class="pre">-Og</span></code> which also |
| builds with the necessary symbols but includes a bit of code optimization. |
| Once the build has finished, you can generate ABI reports using:</p> |
| <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>abi-dumper<span class="w"> </span>-lver<span class="w"> </span><span class="m">9</span><span class="w"> </span>debug/libarrow.so<span class="w"> </span>-o<span class="w"> </span>ABI-9.dump |
| </pre></div> |
| </div> |
| <p>The above version number is freely selectable. As we want to compare versions, |
| you should now <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">checkout</span></code> the version you want to compare it to and re-run |
| the above command using a different version number. Once both reports are |
| generated, you can build a comparison report using</p> |
| <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>abi-compliance-checker<span class="w"> </span>-l<span class="w"> </span>libarrow<span class="w"> </span>-d1<span class="w"> </span>ABI-PY-9.dump<span class="w"> </span>-d2<span class="w"> </span>ABI-PY-10.dump |
| </pre></div> |
| </div> |
| <p>The report is then generated in <code class="docutils literal notranslate"><span class="pre">compat_reports/libarrow</span></code> as a HTML.</p> |
| </section> |
| </section> |
| <section id="api-documentation"> |
| <h2>API Documentation<a class="headerlink" href="#api-documentation" title="Link to this heading">#</a></h2> |
| <p>We use Doxygen style comments (<code class="docutils literal notranslate"><span class="pre">///</span></code>) in header files for comments |
| that we wish to show up in API documentation for classes and |
| functions.</p> |
| <p>When using <code class="docutils literal notranslate"><span class="pre">clang</span></code> and building with |
| <code class="docutils literal notranslate"><span class="pre">-DBUILD_WARNING_LEVEL=CHECKIN</span></code>, the <code class="docutils literal notranslate"><span class="pre">-Wdocumentation</span></code> flag is |
| used which checks for some common documentation inconsistencies, like |
| documenting some, but not all function parameters with <code class="docutils literal notranslate"><span class="pre">\param</span></code>. See |
| the <a class="reference external" href="https://releases.llvm.org/7.0.1/tools/clang/docs/DiagnosticsReference.html#wdocumentation">LLVM documentation warnings section</a> |
| for more about this.</p> |
| <p>While we publish the API documentation as part of the main Sphinx-based |
| documentation site, you can also build the C++ API documentation anytime using |
| Doxygen. Run the following command from the <code class="docutils literal notranslate"><span class="pre">cpp/apidoc</span></code> directory:</p> |
| <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>doxygen<span class="w"> </span>Doxyfile |
| </pre></div> |
| </div> |
| <p>This requires <a class="reference external" href="https://www.doxygen.org">Doxygen</a> to be installed.</p> |
| </section> |
| <section id="apache-parquet-development"> |
| <h2>Apache Parquet Development<a class="headerlink" href="#apache-parquet-development" title="Link to this heading">#</a></h2> |
| <p>To build the C++ libraries for Apache Parquet, add the flag |
| <code class="docutils literal notranslate"><span class="pre">-DARROW_PARQUET=ON</span></code> when invoking CMake. |
| To build Apache Parquet with encryption support, add the flag |
| <code class="docutils literal notranslate"><span class="pre">-DPARQUET_REQUIRE_ENCRYPTION=ON</span></code> when invoking CMake. The Parquet libraries and unit tests |
| can be built with the <code class="docutils literal notranslate"><span class="pre">parquet</span></code> make target:</p> |
| <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span>parquet |
| </pre></div> |
| </div> |
| <p>On Linux and macOS if you do not have Apache Thrift installed on your system, |
| or you are building with <code class="docutils literal notranslate"><span class="pre">-DThrift_SOURCE=BUNDLED</span></code>, you must install |
| <code class="docutils literal notranslate"><span class="pre">bison</span></code> and <code class="docutils literal notranslate"><span class="pre">flex</span></code> packages. On Windows we handle these build dependencies |
| automatically when building Thrift from source.</p> |
| <p>Running <code class="docutils literal notranslate"><span class="pre">ctest</span> <span class="pre">-L</span> <span class="pre">unittest</span></code> will run all built C++ unit tests, while <code class="docutils literal notranslate"><span class="pre">ctest</span> <span class="pre">-L</span> |
| <span class="pre">parquet</span></code> will run only the Parquet unit tests. The unit tests depend on an |
| environment variable <code class="docutils literal notranslate"><span class="pre">PARQUET_TEST_DATA</span></code> that depends on a git submodule to the |
| repository <a class="github reference external" href="https://github.com/apache/parquet-testing">apache/parquet-testing</a>:</p> |
| <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>submodule<span class="w"> </span>update<span class="w"> </span>--init |
| <span class="nb">export</span><span class="w"> </span><span class="nv">PARQUET_TEST_DATA</span><span class="o">=</span><span class="nv">$ARROW_ROOT</span>/cpp/submodules/parquet-testing/data |
| </pre></div> |
| </div> |
| <p>Here <code class="docutils literal notranslate"><span class="pre">$ARROW_ROOT</span></code> is the absolute path to the Arrow codebase.</p> |
| </section> |
| <section id="arrow-flight-rpc"> |
| <h2>Arrow Flight RPC<a class="headerlink" href="#arrow-flight-rpc" title="Link to this heading">#</a></h2> |
| <p>In addition to the Arrow dependencies, Flight requires:</p> |
| <ul class="simple"> |
| <li><p>gRPC (>= 1.14, roughly)</p></li> |
| <li><p>Protobuf (>= 3.6, earlier versions may work)</p></li> |
| <li><p>c-ares (used by gRPC)</p></li> |
| </ul> |
| <p>By default, Arrow will try to download and build these dependencies |
| when building Flight.</p> |
| <p>The optional <code class="docutils literal notranslate"><span class="pre">flight</span></code> libraries and tests can be built by passing |
| <code class="docutils literal notranslate"><span class="pre">-DARROW_FLIGHT=ON</span></code>.</p> |
| <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>cmake<span class="w"> </span>..<span class="w"> </span>-DARROW_FLIGHT<span class="o">=</span>ON<span class="w"> </span>-DARROW_BUILD_TESTS<span class="o">=</span>ON |
| make |
| </pre></div> |
| </div> |
| <p>You can also use existing installations of the extra dependencies. |
| When building, set the environment variables <code class="docutils literal notranslate"><span class="pre">gRPC_ROOT</span></code> and/or |
| <code class="docutils literal notranslate"><span class="pre">Protobuf_ROOT</span></code> and/or <code class="docutils literal notranslate"><span class="pre">c-ares_ROOT</span></code>.</p> |
| <p>We are developing against recent versions of gRPC, and the versions. The |
| <code class="docutils literal notranslate"><span class="pre">libgrpc</span></code> package available from <a class="reference external" href="https://conda-forge.org/">https://conda-forge.org/</a> is one reliable |
| way to obtain gRPC in a cross-platform way. You may try using system libraries |
| for gRPC and Protobuf, but these are likely to be too old. On macOS, you can |
| try <a class="reference external" href="https://brew.sh/">Homebrew</a>:</p> |
| <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>brew<span class="w"> </span>install<span class="w"> </span>grpc |
| </pre></div> |
| </div> |
| </section> |
| </section> |
| |
| |
| </article> |
| |
| |
| |
| |
| |
| <footer class="prev-next-footer d-print-none"> |
| |
| <div class="prev-next-area"> |
| <a class="left-prev" |
| href="building.html" |
| title="previous page"> |
| <i class="fa-solid fa-angle-left"></i> |
| <div class="prev-next-info"> |
| <p class="prev-next-subtitle">previous</p> |
| <p class="prev-next-title">Building Arrow C++</p> |
| </div> |
| </a> |
| <a class="right-next" |
| href="windows.html" |
| title="next page"> |
| <div class="prev-next-info"> |
| <p class="prev-next-subtitle">next</p> |
| <p class="prev-next-title">Developing on Windows</p> |
| </div> |
| <i class="fa-solid fa-angle-right"></i> |
| </a> |
| </div> |
| </footer> |
| |
| </div> |
| |
| |
| |
| <dialog id="pst-secondary-sidebar-modal"></dialog> |
| <div id="pst-secondary-sidebar" class="bd-sidebar-secondary bd-toc"><div class="sidebar-secondary-items sidebar-secondary__inner"> |
| |
| |
| <div class="sidebar-secondary-item"> |
| <div |
| id="pst-page-navigation-heading-2" |
| class="page-toc tocsection onthispage"> |
| <i class="fa-solid fa-list"></i> On this page |
| </div> |
| <nav class="bd-toc-nav page-toc" aria-labelledby="pst-page-navigation-heading-2"> |
| <ul class="visible nav section-nav flex-column"> |
| <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#compiler-warning-levels">Compiler warning levels</a></li> |
| <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#running-unit-tests">Running unit tests</a></li> |
| <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#running-benchmarks">Running benchmarks</a></li> |
| <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#code-style-linting-and-ci">Code Style, Linting, and CI</a><ul class="visible nav section-nav flex-column"> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#checking-for-abi-and-api-stability">Checking for ABI and API stability</a></li> |
| </ul> |
| </li> |
| <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#api-documentation">API Documentation</a></li> |
| <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#apache-parquet-development">Apache Parquet Development</a></li> |
| <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#arrow-flight-rpc">Arrow Flight RPC</a></li> |
| </ul> |
| </nav></div> |
| |
| <div class="sidebar-secondary-item"> |
| |
| |
| <div class="tocsection editthispage"> |
| <a href="https://github.com/apache/arrow/edit/main/docs/source/developers/cpp/development.rst"> |
| <i class="fa-solid fa-pencil"></i> |
| |
| |
| |
| Edit on GitHub |
| |
| |
| </a> |
| </div> |
| </div> |
| |
| </div></div> |
| |
| |
| </div> |
| <footer class="bd-footer-content"> |
| |
| </footer> |
| |
| </main> |
| </div> |
| </div> |
| |
| <!-- Scripts loaded after <body> so the DOM is not blocked --> |
| <script defer src="../../_static/scripts/bootstrap.js?digest=8878045cc6db502f8baf"></script> |
| <script defer src="../../_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf"></script> |
| |
| <footer class="bd-footer"> |
| <div class="bd-footer__inner bd-page-width"> |
| |
| <div class="footer-items__start"> |
| |
| <div class="footer-item"> |
| |
| <p class="copyright"> |
| |
| © Copyright 2016-2025 Apache Software Foundation. |
| Apache Arrow, Arrow, Apache, the Apache logo, and the Apache Arrow project logo are either registered trademarks or trademarks of The Apache Software Foundation in the United States and other countries. |
| <br/> |
| |
| </p> |
| </div> |
| |
| <div class="footer-item"> |
| |
| <p class="sphinx-version"> |
| Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3. |
| <br/> |
| </p> |
| </div> |
| |
| </div> |
| |
| |
| |
| <div class="footer-items__end"> |
| |
| <div class="footer-item"> |
| <p class="theme-version"> |
| <!-- # L10n: Setting the PST URL as an argument as this does not need to be localized --> |
| Built with the <a href="https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html">PyData Sphinx Theme</a> 0.16.1. |
| </p></div> |
| |
| </div> |
| |
| </div> |
| |
| </footer> |
| </body> |
| </html> |
