| |
| |
| <!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="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" /> |
| |
| <title>Development Guidelines — Apache Arrow v17.0.0.dev77</title> |
| |
| |
| |
| <script data-cfasync="false"> |
| document.documentElement.dataset.mode = localStorage.getItem("mode") || ""; |
| document.documentElement.dataset.theme = localStorage.getItem("theme") || "light"; |
| </script> |
| |
| <!-- Loaded before other Sphinx assets --> |
| <link href="../../_static/styles/theme.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" /> |
| <link href="../../_static/styles/bootstrap.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" /> |
| <link href="../../_static/styles/pydata-sphinx-theme.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" /> |
| |
| |
| <link href="../../_static/vendor/fontawesome/6.5.1/css/all.min.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" /> |
| <link rel="preload" as="font" type="font/woff2" crossorigin href="../../_static/vendor/fontawesome/6.5.1/webfonts/fa-solid-900.woff2" /> |
| <link rel="preload" as="font" type="font/woff2" crossorigin href="../../_static/vendor/fontawesome/6.5.1/webfonts/fa-brands-400.woff2" /> |
| <link rel="preload" as="font" type="font/woff2" crossorigin href="../../_static/vendor/fontawesome/6.5.1/webfonts/fa-regular-400.woff2" /> |
| |
| <link rel="stylesheet" type="text/css" href="../../_static/pygments.css" /> |
| <link rel="stylesheet" type="text/css" href="../../_static/copybutton.css" /> |
| <link rel="stylesheet" type="text/css" href="../../_static/design-style.1e8bd061cd6da7fc9cf755528e8ffc24.min.css" /> |
| <link rel="stylesheet" type="text/css" href="../../_static/theme_overrides.css" /> |
| |
| <!-- Pre-loaded scripts that we'll load fully later --> |
| <link rel="preload" as="script" href="../../_static/scripts/bootstrap.js?digest=8d27b9dea8ad943066ae" /> |
| <link rel="preload" as="script" href="../../_static/scripts/pydata-sphinx-theme.js?digest=8d27b9dea8ad943066ae" /> |
| <script src="../../_static/vendor/fontawesome/6.5.1/js/all.min.js?digest=8d27b9dea8ad943066ae"></script> |
| |
| <script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script> |
| <script src="../../_static/doctools.js"></script> |
| <script src="../../_static/sphinx_highlight.js"></script> |
| <script src="../../_static/clipboard.min.js"></script> |
| <script src="../../_static/copybutton.js"></script> |
| <script src="../../_static/design-tabs.js"></script> |
| <script>DOCUMENTATION_OPTIONS.pagename = 'developers/cpp/development';</script> |
| <script> |
| DOCUMENTATION_OPTIONS.theme_version = '0.15.2'; |
| 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"/> |
| |
| <!-- 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=""> |
| |
| |
| |
| <a id="pst-skip-link" class="skip-link" href="#main-content">Skip to main content</a> |
| |
| <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> |
| |
| |
| <input type="checkbox" |
| class="sidebar-toggle" |
| name="__primary" |
| id="__primary"/> |
| <label class="overlay overlay-primary" for="__primary"></label> |
| |
| <input type="checkbox" |
| class="sidebar-toggle" |
| name="__secondary" |
| id="__secondary"/> |
| <label class="overlay overlay-secondary" for="__secondary"></label> |
| |
| <div class="search-button__wrapper"> |
| <div class="search-button__overlay"></div> |
| <div class="search-button__search-container"> |
| <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" |
| id="search-input" |
| 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></div> |
| </div> |
| |
| <header class="bd-header navbar navbar-expand-lg bd-navbar"> |
| <div class="bd-header__inner bd-page-width"> |
| <label class="sidebar-toggle primary-toggle" for="__primary"> |
| <span class="fa-solid fa-bars"></span> |
| </label> |
| |
| |
| <div class="col-lg-3 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 v17.0.0.dev77 - Home"/> |
| <script>document.write(`<img src="../../_static/arrow-dark.png" class="logo__image only-dark" alt="Apache Arrow v17.0.0.dev77 - Home"/>`);</script> |
| |
| |
| </a></div> |
| |
| </div> |
| |
| <div class="col-lg-9 navbar-header-items"> |
| |
| <div class="me-auto navbar-header-items__center"> |
| |
| <div class="navbar-item"> |
| <nav class="navbar-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 dropdown"> |
| <button class="btn dropdown-toggle nav-item" type="button" data-bs-toggle="dropdown" aria-expanded="false" aria-controls="pst-nav-more-links"> |
| Implementations |
| </button> |
| <ul id="pst-nav-more-links" class="dropdown-menu"> |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../../c_glib/index.html"> |
| C/GLib |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../../cpp/index.html"> |
| C++ |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/csharp/README.md"> |
| C# |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://pkg.go.dev/github.com/apache/arrow/go/v17"> |
| Go |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../../java/index.html"> |
| Java |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../../js/index.html"> |
| JavaScript |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/julia/"> |
| Julia |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/matlab/README.md"> |
| MATLAB |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/nanoarrow/"> |
| nanoarrow |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../../python/index.html"> |
| Python |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../../r/index.html"> |
| R |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/ruby/README.md"> |
| Ruby |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://docs.rs/crate/arrow/"> |
| Rust |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../../status.html"> |
| Implementation Status |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/cpp/"> |
| C++ cookbook |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/java/"> |
| Java cookbook |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/py/"> |
| Python cookbook |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/r/"> |
| R cookbook |
| </a> |
| </li> |
| |
| </ul> |
| </li> |
| |
| </ul> |
| </nav></div> |
| |
| </div> |
| |
| |
| <div class="navbar-header-items__end"> |
| |
| <div class="navbar-item navbar-persistent--container"> |
| |
| |
| <script> |
| document.write(` |
| <button class="btn navbar-btn search-button-field search-button__button" 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> |
| `); |
| </script> |
| </div> |
| |
| |
| <div class="navbar-item"> |
| <script> |
| document.write(` |
| <div class="version-switcher__container dropdown"> |
| <button id="pst-version-switcher-button-2" |
| type="button" |
| class="version-switcher__button btn btn-sm navbar-btn 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> |
| `); |
| </script></div> |
| |
| <div class="navbar-item"> |
| |
| <script> |
| document.write(` |
| <button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip"> |
| <span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span> |
| <span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span> |
| <span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span> |
| </button> |
| `); |
| </script></div> |
| |
| <div class="navbar-item"><ul class="navbar-icon-links navbar-nav" |
| aria-label="Icon Links"> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://github.com/apache/arrow" title="GitHub" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fa-brands fa-square-github fa-lg" aria-hidden="true"></i></span> |
| <span class="sr-only">GitHub</span></a> |
| </li> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://twitter.com/ApacheArrow" title="X" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fa-brands fa-square-x-twitter fa-lg" aria-hidden="true"></i></span> |
| <span class="sr-only">X</span></a> |
| </li> |
| </ul></div> |
| |
| </div> |
| |
| </div> |
| |
| |
| <div class="navbar-persistent--mobile"> |
| |
| <script> |
| document.write(` |
| <button class="btn navbar-btn search-button-field search-button__button" 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> |
| `); |
| </script> |
| </div> |
| |
| |
| |
| <label class="sidebar-toggle secondary-toggle" for="__secondary" tabindex="0"> |
| <span class="fa-solid fa-outdent"></span> |
| </label> |
| |
| </div> |
| |
| </header> |
| |
| |
| <div class="bd-container"> |
| <div class="bd-container__inner bd-page-width"> |
| |
| |
| |
| <div 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 class="navbar-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 dropdown"> |
| <button class="btn dropdown-toggle nav-item" type="button" data-bs-toggle="dropdown" aria-expanded="false" aria-controls="pst-nav-more-links-2"> |
| Implementations |
| </button> |
| <ul id="pst-nav-more-links-2" class="dropdown-menu"> |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../../c_glib/index.html"> |
| C/GLib |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../../cpp/index.html"> |
| C++ |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/csharp/README.md"> |
| C# |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://pkg.go.dev/github.com/apache/arrow/go/v17"> |
| Go |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../../java/index.html"> |
| Java |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../../js/index.html"> |
| JavaScript |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/julia/"> |
| Julia |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/matlab/README.md"> |
| MATLAB |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/nanoarrow/"> |
| nanoarrow |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../../python/index.html"> |
| Python |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../../r/index.html"> |
| R |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/ruby/README.md"> |
| Ruby |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://docs.rs/crate/arrow/"> |
| Rust |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../../status.html"> |
| Implementation Status |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/cpp/"> |
| C++ cookbook |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/java/"> |
| Java cookbook |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/py/"> |
| Python cookbook |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/r/"> |
| R cookbook |
| </a> |
| </li> |
| |
| </ul> |
| </li> |
| |
| </ul> |
| </nav></div> |
| |
| </div> |
| |
| |
| |
| <div class="sidebar-header-items__end"> |
| |
| <div class="navbar-item"> |
| <script> |
| document.write(` |
| <div class="version-switcher__container dropdown"> |
| <button id="pst-version-switcher-button-3" |
| type="button" |
| class="version-switcher__button btn btn-sm navbar-btn 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> |
| `); |
| </script></div> |
| |
| <div class="navbar-item"> |
| |
| <script> |
| document.write(` |
| <button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip"> |
| <span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span> |
| <span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span> |
| <span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span> |
| </button> |
| `); |
| </script></div> |
| |
| <div class="navbar-item"><ul class="navbar-icon-links navbar-nav" |
| aria-label="Icon Links"> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://github.com/apache/arrow" title="GitHub" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fa-brands fa-square-github fa-lg" aria-hidden="true"></i></span> |
| <span class="sr-only">GitHub</span></a> |
| </li> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://twitter.com/ApacheArrow" title="X" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fa-brands fa-square-x-twitter fa-lg" aria-hidden="true"></i></span> |
| <span class="sr-only">X</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><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-1"><i class="fa-solid fa-chevron-down"></i></label><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><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-2"><i class="fa-solid fa-chevron-down"></i></label><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> |
| </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><input class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-3"><i class="fa-solid fa-chevron-down"></i></label><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> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="../guide/resources.html">Additional information and resources</a></li> |
| </ul> |
| </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><input checked="" class="toctree-checkbox" id="toctree-checkbox-4" name="toctree-checkbox-4" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-4"><i class="fa-solid fa-chevron-down"></i></label><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> |
| </ul> |
| </li> |
| <li class="toctree-l1 has-children"><a class="reference internal" href="../java/index.html">Java Development</a><input class="toctree-checkbox" id="toctree-checkbox-5" name="toctree-checkbox-5" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-5"><i class="fa-solid fa-chevron-down"></i></label><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> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="../python.html">Python Development</a></li> |
| <li class="toctree-l1 has-children"><a class="reference internal" href="../continuous_integration/index.html">Continuous Integration</a><input class="toctree-checkbox" id="toctree-checkbox-6" name="toctree-checkbox-6" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-6"><i class="fa-solid fa-chevron-down"></i></label><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> |
| </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> |
| |
| <div id="rtd-footer-container"></div> |
| |
| |
| </div> |
| |
| <main id="main-content" class="bd-main"> |
| |
| |
| <div class="bd-content"> |
| <div class="bd-article-container"> |
| |
| <div class="bd-header-article"> |
| <div class="header-article-items header-article__inner"> |
| |
| <div class="header-article-items__start"> |
| |
| <div class="header-article-item"> |
| |
| |
| |
| <nav aria-label="Breadcrumb"> |
| <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">Development...</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="Permalink 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="Permalink 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="Permalink 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="Permalink 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="Permalink 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, checked with the <code class="docutils literal notranslate"><span class="pre">lint</span></code> |
| subcommand to <a class="reference internal" href="../continuous_integration/archery.html#archery"><span class="std std-ref">Archery</span></a>. This can also be fixed locally |
| by running <code class="docutils literal notranslate"><span class="pre">archery</span> <span class="pre">lint</span> <span class="pre">--cpplint</span> <span class="pre">--clang-format</span> <span class="pre">--clang-tidy</span> <span class="pre">--fix</span></code>.</p></li> |
| <li><p>CMake files pass style checks, can be fixed by running |
| <code class="docutils literal notranslate"><span class="pre">archery</span> <span class="pre">lint</span> <span class="pre">--cmake-format</span> <span class="pre">--fix</span></code>. This requires Python |
| 3 and <a class="reference external" href="https://github.com/cheshirekow/cmake_format">cmake_format</a> (note: |
| this currently does not work on Windows).</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> |
| <p>In order to account for variations in the behavior of <code class="docutils literal notranslate"><span class="pre">clang-format</span></code> between |
| major versions of LLVM, we pin the version of <code class="docutils literal notranslate"><span class="pre">clang-format</span></code> used. You can |
| confirm the current pinned version by finding the <code class="docutils literal notranslate"><span class="pre">CLANG_TOOLS</span></code> variable |
| value in <a class="reference external" href="https://github.com/apache/arrow/blob/main/.env">.env</a>. Note that |
| the version must match exactly; a newer version (even a patch release) will |
| not work. LLVM can be installed through a system package manager or a package |
| manager like Conda or Homebrew, though note they may not offer the exact |
| version needed. Alternatively, binaries can be directly downloaded from the |
| <a class="reference external" href="https://releases.llvm.org/">LLVM website</a>.</p> |
| <p>For convenience, C++ style checks can run via a build, in addition to |
| Archery. To do so, build one or more of the targets <code class="docutils literal notranslate"><span class="pre">format</span></code> (for |
| clang-format), <code class="docutils literal notranslate"><span class="pre">lint_cpp_cli</span></code>, <code class="docutils literal notranslate"><span class="pre">lint</span></code> (for cpplint), or |
| <code class="docutils literal notranslate"><span class="pre">clang-tidy</span></code>. For example:</p> |
| <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>cmake<span class="w"> </span>-GNinja<span class="w"> </span>../cpp<span class="w"> </span>... |
| <span class="gp">$ </span>ninja<span class="w"> </span>format<span class="w"> </span>lint<span class="w"> </span>clang-tidy<span class="w"> </span>lint_cpp_cli |
| </pre></div> |
| </div> |
| <p>Depending on how you installed clang-format, the build system may not be able |
| to find it. In that case, invoking CMake will show errors like the following:</p> |
| <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">-- clang-format 12 not found</span> |
| </pre></div> |
| </div> |
| <p>Or if the wrong version is installed:</p> |
| <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">-- clang-format found, but version did not match "^clang-format version 12"</span> |
| </pre></div> |
| </div> |
| <p>You can provide an explicit path to the directory containing the clang-format |
| executable and others with the environment variable <code class="docutils literal notranslate"><span class="pre">$CLANG_TOOLS_PATH</span></code>, or |
| by passing <code class="docutils literal notranslate"><span class="pre">-DClangTools_PATH=$PATH_TO_CLANG_TOOLS</span></code> when invoking CMake. For |
| example:</p> |
| <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp"># </span>We<span class="w"> </span>unpacked<span class="w"> </span>LLVM<span class="w"> </span>here: |
| <span class="gp">$ </span>~/tools/bin/clang-format<span class="w"> </span>--version |
| <span class="go">clang-format version 12.0.0</span> |
| <span class="gp"># </span>Pass<span class="w"> </span>the<span class="w"> </span>directory<span class="w"> </span>containing<span class="w"> </span>the<span class="w"> </span>tools<span class="w"> </span>to<span class="w"> </span>CMake |
| <span class="gp">$ </span>cmake<span class="w"> </span>../cpp<span class="w"> </span>-DClangTools_PATH<span class="o">=</span>~/tools/bin/ |
| <span class="go">...snip...</span> |
| <span class="go">-- clang-tidy found at /home/user/tools/bin/clang-tidy</span> |
| <span class="go">-- clang-format found at /home/user/tools/bin/clang-format</span> |
| <span class="go">...snip...</span> |
| </pre></div> |
| </div> |
| <p>To make linting more reproducible for everyone, we provide a <code class="docutils literal notranslate"><span class="pre">docker-compose</span></code> |
| target that is executable from the root of the repository:</p> |
| <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>docker-compose<span class="w"> </span>run<span class="w"> </span>ubuntu-lint |
| </pre></div> |
| </div> |
| <p>Alternatively, on an open pull request, the comment bot can format C++ code |
| for you (it will push a commit to the branch that can then be pulled). Just |
| comment the following:</p> |
| <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">@github-actions autotune</span> |
| </pre></div> |
| </div> |
| <section id="cleaning-includes-with-include-what-you-use-iwyu"> |
| <h3>Cleaning includes with include-what-you-use (IWYU)<a class="headerlink" href="#cleaning-includes-with-include-what-you-use-iwyu" title="Permalink to this heading">#</a></h3> |
| <p>We occasionally use Google’s <a class="reference external" href="https://github.com/include-what-you-use/include-what-you-use">include-what-you-use</a> tool, also |
| known as IWYU, to remove unnecessary imports.</p> |
| <p>To begin using IWYU, you must first build it by following the instructions in |
| the project’s documentation. Once the <code class="docutils literal notranslate"><span class="pre">include-what-you-use</span></code> executable is in |
| your <code class="docutils literal notranslate"><span class="pre">$PATH</span></code>, you must run CMake with <code class="docutils literal notranslate"><span class="pre">-DCMAKE_EXPORT_COMPILE_COMMANDS=ON</span></code> |
| in a new out-of-source CMake build directory like so:</p> |
| <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>mkdir<span class="w"> </span>-p<span class="w"> </span><span class="nv">$ARROW_ROOT</span>/cpp/iwyu |
| <span class="nb">cd</span><span class="w"> </span><span class="nv">$ARROW_ROOT</span>/cpp/iwyu |
| cmake<span class="w"> </span>-DCMAKE_EXPORT_COMPILE_COMMANDS<span class="o">=</span>ON<span class="w"> </span><span class="se">\</span> |
| <span class="w"> </span>-DARROW_BUILD_BENCHMARKS<span class="o">=</span>ON<span class="w"> </span><span class="se">\</span> |
| <span class="w"> </span>-DARROW_BUILD_BENCHMARKS_REFERENCE<span class="o">=</span>ON<span class="w"> </span><span class="se">\</span> |
| <span class="w"> </span>-DARROW_BUILD_TESTS<span class="o">=</span>ON<span class="w"> </span><span class="se">\</span> |
| <span class="w"> </span>-DARROW_BUILD_UTILITIES<span class="o">=</span>ON<span class="w"> </span><span class="se">\</span> |
| <span class="w"> </span>-DARROW_COMPUTE<span class="o">=</span>ON<span class="w"> </span><span class="se">\</span> |
| <span class="w"> </span>-DARROW_CSV<span class="o">=</span>ON<span class="w"> </span><span class="se">\</span> |
| <span class="w"> </span>-DARROW_DATASET<span class="o">=</span>ON<span class="w"> </span><span class="se">\</span> |
| <span class="w"> </span>-DARROW_FILESYSTEM<span class="o">=</span>ON<span class="w"> </span><span class="se">\</span> |
| <span class="w"> </span>-DARROW_FLIGHT<span class="o">=</span>ON<span class="w"> </span><span class="se">\</span> |
| <span class="w"> </span>-DARROW_GANDIVA<span class="o">=</span>ON<span class="w"> </span><span class="se">\</span> |
| <span class="w"> </span>-DARROW_HDFS<span class="o">=</span>ON<span class="w"> </span><span class="se">\</span> |
| <span class="w"> </span>-DARROW_JSON<span class="o">=</span>ON<span class="w"> </span><span class="se">\</span> |
| <span class="w"> </span>-DARROW_PARQUET<span class="o">=</span>ON<span class="w"> </span><span class="se">\</span> |
| <span class="w"> </span>-DARROW_S3<span class="o">=</span>ON<span class="w"> </span><span class="se">\</span> |
| <span class="w"> </span>-DARROW_WITH_BROTLI<span class="o">=</span>ON<span class="w"> </span><span class="se">\</span> |
| <span class="w"> </span>-DARROW_WITH_BZ2<span class="o">=</span>ON<span class="w"> </span><span class="se">\</span> |
| <span class="w"> </span>-DARROW_WITH_LZ4<span class="o">=</span>ON<span class="w"> </span><span class="se">\</span> |
| <span class="w"> </span>-DARROW_WITH_SNAPPY<span class="o">=</span>ON<span class="w"> </span><span class="se">\</span> |
| <span class="w"> </span>-DARROW_WITH_ZLIB<span class="o">=</span>ON<span class="w"> </span><span class="se">\</span> |
| <span class="w"> </span>-DARROW_WITH_ZSTD<span class="o">=</span>ON<span class="w"> </span><span class="se">\</span> |
| <span class="w"> </span>.. |
| </pre></div> |
| </div> |
| <p>In order for IWYU to run on the desired component in the codebase, it must be |
| enabled by the CMake configuration flags. Once this is done, you can run IWYU |
| on the whole codebase by running a helper <code class="docutils literal notranslate"><span class="pre">iwyu.sh</span></code> script:</p> |
| <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="nv">IWYU_SH</span><span class="o">=</span><span class="nv">$ARROW_ROOT</span>/cpp/build-support/iwyu/iwyu.sh |
| ./<span class="nv">$IWYU_SH</span> |
| </pre></div> |
| </div> |
| <p>Since this is very time consuming, you can check a subset of files matching |
| some string pattern with the special “match” option</p> |
| <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>./<span class="nv">$IWYU_SH</span><span class="w"> </span>match<span class="w"> </span><span class="nv">$PATTERN</span> |
| </pre></div> |
| </div> |
| <p>For example, if you wanted to do IWYU checks on all files in |
| <code class="docutils literal notranslate"><span class="pre">src/arrow/array</span></code>, you could run</p> |
| <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>./<span class="nv">$IWYU_SH</span><span class="w"> </span>match<span class="w"> </span>arrow/array |
| </pre></div> |
| </div> |
| </section> |
| <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="Permalink 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="Permalink 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="Permalink 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="Permalink 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">grpc-cpp</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"> |
| |
| <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> |
| |
| |
| |
| <div 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="#cleaning-includes-with-include-what-you-use-iwyu">Cleaning includes with include-what-you-use (IWYU)</a></li> |
| <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 src="../../_static/scripts/bootstrap.js?digest=8d27b9dea8ad943066ae"></script> |
| <script src="../../_static/scripts/pydata-sphinx-theme.js?digest=8d27b9dea8ad943066ae"></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-2024 Apache Software Foundation. |
| Apache Arrow, Arrow, Apache, the Apache feather 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> 6.2.0. |
| <br/> |
| </p> |
| </div> |
| |
| </div> |
| |
| |
| |
| <div class="footer-items__end"> |
| |
| <div class="footer-item"> |
| <p class="theme-version"> |
| Built with the <a href="https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html">PyData Sphinx Theme</a> 0.15.2. |
| </p></div> |
| |
| </div> |
| |
| </div> |
| |
| </footer> |
| </body> |
| </html> |
