Commands and Options

<!doctype html> <html lang="en" dir="ltr"> <head> <meta name="google-signin-client-id" content="157101835696-ooapojlodmuabs2do2vuhhnf90bccmoi.apps.googleusercontent.com"> <meta name="google-signin-scope" content="profile email https://www.googleapis.com/auth/developerprofiles https://www.googleapis.com/auth/developerprofiles.award"> <meta property="og:site_name" content="Bazel"> <meta property="og:type" content="website"><meta name="theme-color" content="#0c713a"><meta charset="utf-8"> <meta content="IE=Edge" http-equiv="X-UA-Compatible"> <meta name="viewport" content="width=device-width, initial-scale=1"> <link rel="manifest" href="/_pwa/bazel/manifest.json" crossorigin="use-credentials"> <link rel="preconnect" href="//www.gstatic.com" crossorigin> <link rel="preconnect" href="//fonts.gstatic.com" crossorigin> <link rel="preconnect" href="//fonts.googleapis.com" crossorigin> <link rel="preconnect" href="//apis.google.com" crossorigin> <link rel="preconnect" href="//www.google-analytics.com" crossorigin><link rel="stylesheet" href="//fonts.googleapis.com/css?family=Roboto:300,400,400italic,500,500italic,700,700italic|Roboto+Mono:400,500,700&display=swap"> <link rel="stylesheet" href="//fonts.googleapis.com/css2?family=Material+Icons&family=Material+Symbols+Outlined&display=block"><link rel="stylesheet" href="https://www.gstatic.com/devrel-devsite/prod/v870e399c64f7c43c99a3043db4b3a74327bb93d0914e84a0c3dba90bbfd67625/bazel/css/app.css"> <link rel="shortcut icon" href="https://www.gstatic.com/devrel-devsite/prod/v870e399c64f7c43c99a3043db4b3a74327bb93d0914e84a0c3dba90bbfd67625/bazel/images/favicon-prod.png"> <link rel="apple-touch-icon" href="https://www.gstatic.com/devrel-devsite/prod/v870e399c64f7c43c99a3043db4b3a74327bb93d0914e84a0c3dba90bbfd67625/bazel/images/touchicon-180.png"><link rel="canonical" href="https://bazel.build/docs/user-manual"><link rel="search" type="application/opensearchdescription+xml" title="Bazel" href="https://bazel.build/s/opensearch.xml"> <link rel="alternate" hreflang="en" href="https://bazel.build/docs/user-manual" /><link rel="alternate" hreflang="x-default" href="https://bazel.build/docs/user-manual" /><link rel="alternate" hreflang="ar" href="https://bazel.build/docs/user-manual?hl=ar" /><link rel="alternate" hreflang="bn" href="https://bazel.build/docs/user-manual?hl=bn" /><link rel="alternate" hreflang="zh-Hans" href="https://bazel.build/docs/user-manual?hl=zh-cn" /><link rel="alternate" hreflang="zh-Hant" href="https://bazel.build/docs/user-manual?hl=zh-tw" /><link rel="alternate" hreflang="fa" href="https://bazel.build/docs/user-manual?hl=fa" /><link rel="alternate" hreflang="he" href="https://bazel.build/docs/user-manual?hl=he" /><link rel="alternate" hreflang="hi" href="https://bazel.build/docs/user-manual?hl=hi" /><link rel="alternate" hreflang="id" href="https://bazel.build/docs/user-manual?hl=id" /><link rel="alternate" hreflang="ja" href="https://bazel.build/docs/user-manual?hl=ja" /><link rel="alternate" hreflang="ko" href="https://bazel.build/docs/user-manual?hl=ko" /><link rel="alternate" hreflang="pt-BR" href="https://bazel.build/docs/user-manual?hl=pt-br" /><link rel="alternate" hreflang="es-419" href="https://bazel.build/docs/user-manual?hl=es-419" /><link rel="alternate" hreflang="th" href="https://bazel.build/docs/user-manual?hl=th" /><link rel="alternate" hreflang="tr" href="https://bazel.build/docs/user-manual?hl=tr" /><link rel="alternate" hreflang="vi" href="https://bazel.build/docs/user-manual?hl=vi" /><link rel="alternate" hreflang="en-cn" href="https://bazel.google.cn/docs/user-manual" /><link rel="alternate" hreflang="x-default" href="https://bazel.google.cn/docs/user-manual" /><link rel="alternate" hreflang="ar-cn" href="https://bazel.google.cn/docs/user-manual?hl=ar" /><link rel="alternate" hreflang="bn-cn" href="https://bazel.google.cn/docs/user-manual?hl=bn" /><link rel="alternate" hreflang="zh-Hans-cn" href="https://bazel.google.cn/docs/user-manual?hl=zh-cn" /><link rel="alternate" hreflang="zh-Hant-cn" href="https://bazel.google.cn/docs/user-manual?hl=zh-tw" /><link rel="alternate" hreflang="fa-cn" href="https://bazel.google.cn/docs/user-manual?hl=fa" /><link rel="alternate" hreflang="he-cn" href="https://bazel.google.cn/docs/user-manual?hl=he" /><link rel="alternate" hreflang="hi-cn" href="https://bazel.google.cn/docs/user-manual?hl=hi" /><link rel="alternate" hreflang="id-cn" href="https://bazel.google.cn/docs/user-manual?hl=id" /><link rel="alternate" hreflang="ja-cn" href="https://bazel.google.cn/docs/user-manual?hl=ja" /><link rel="alternate" hreflang="ko-cn" href="https://bazel.google.cn/docs/user-manual?hl=ko" /><link rel="alternate" hreflang="pt-BR-cn" href="https://bazel.google.cn/docs/user-manual?hl=pt-br" /><link rel="alternate" hreflang="es-419-cn" href="https://bazel.google.cn/docs/user-manual?hl=es-419" /><link rel="alternate" hreflang="th-cn" href="https://bazel.google.cn/docs/user-manual?hl=th" /><link rel="alternate" hreflang="tr-cn" href="https://bazel.google.cn/docs/user-manual?hl=tr" /><link rel="alternate" hreflang="vi-cn" href="https://bazel.google.cn/docs/user-manual?hl=vi" /><title>Commands and Options  |  Bazel</title> <meta property="og:title" content="Commands and Options  |  Bazel"><meta property="og:url" content="https://bazel.build/docs/user-manual"><meta property="og:locale" content="en"><script type="application/ld+json"> { "@context": "https://schema.org", "@type": "Article", "headline": "Commands and Options" } </script> <link rel="stylesheet" href="/extras.css"></head> <body class="" template="page" theme="bazel-theme" type="article" layout="docs" display-toc pending> <devsite-progress type="indeterminate" id="app-progress"></devsite-progress> <section class="devsite-wrapper"> <devsite-cookie-notification-bar></devsite-cookie-notification-bar><devsite-header role="banner"> <div class="devsite-header--inner nocontent"> <div class="devsite-top-logo-row-wrapper-wrapper"> <div class="devsite-top-logo-row-wrapper"> <div class="devsite-top-logo-row"> <button type="button" id="devsite-hamburger-menu" class="devsite-header-icon-button button-flat material-icons gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Navigation menu button" visually-hidden aria-label="Open menu"> </button> <div class="devsite-product-name-wrapper"> <a href="/" class="devsite-site-logo-link gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Site logo" track-type="globalNav" track-name="bazel" track-metadata-position="nav" track-metadata-eventDetail="nav"> <picture> <img src="https://www.gstatic.com/devrel-devsite/prod/v870e399c64f7c43c99a3043db4b3a74327bb93d0914e84a0c3dba90bbfd67625/bazel/images/lockup.svg" class="devsite-site-logo" alt="Bazel"> </picture> </a> <span class="devsite-product-name"> <ul class="devsite-breadcrumb-list" > <li class="devsite-breadcrumb-item "> </li> </ul> </span> </div> <div class="devsite-top-logo-row-middle"> <div class="devsite-header-upper-tabs"> <devsite-tabs class="upper-tabs"> <nav class="devsite-tabs-wrapper" aria-label="Upper tabs"> <tab > <a href="https://bazel.build/about" track-metadata-eventdetail="https://bazel.build/about" class="devsite-tabs-content gc-analytics-event " track-type="nav" track-metadata-position="nav - about bazel" track-metadata-module="primary nav" data-category="Site-Wide Custom Events" data-label="Tab: About Bazel" track-name="about bazel" > About Bazel </a> </tab> <tab > <a href="https://bazel.build/start" track-metadata-eventdetail="https://bazel.build/start" class="devsite-tabs-content gc-analytics-event " track-type="nav" track-metadata-position="nav - getting started" track-metadata-module="primary nav" data-category="Site-Wide Custom Events" data-label="Tab: Getting started" track-name="getting started" > Getting started </a> </tab> <tab class="devsite-active"> <a href="https://bazel.build/docs" track-metadata-eventdetail="https://bazel.build/docs" class="devsite-tabs-content gc-analytics-event " track-type="nav" track-metadata-position="nav - user guide" track-metadata-module="primary nav" aria-label="User guide, selected" data-category="Site-Wide Custom Events" data-label="Tab: User guide" track-name="user guide" > User guide </a> </tab> <tab > <a href="https://bazel.build/reference" track-metadata-eventdetail="https://bazel.build/reference" class="devsite-tabs-content gc-analytics-event " track-type="nav" track-metadata-position="nav - reference" track-metadata-module="primary nav" data-category="Site-Wide Custom Events" data-label="Tab: Reference" track-name="reference" > Reference </a> </tab> <tab > <a href="https://bazel.build/extending" track-metadata-eventdetail="https://bazel.build/extending" class="devsite-tabs-content gc-analytics-event " track-type="nav" track-metadata-position="nav - extending" track-metadata-module="primary nav" data-category="Site-Wide Custom Events" data-label="Tab: Extending" track-name="extending" > Extending </a> </tab> <tab > <a href="https://bazel.build/community" track-metadata-eventdetail="https://bazel.build/community" class="devsite-tabs-content gc-analytics-event " track-type="nav" track-metadata-position="nav - community" track-metadata-module="primary nav" data-category="Site-Wide Custom Events" data-label="Tab: Community" track-name="community" > Community </a> </tab> <tab class="devsite-dropdown "> <a href="https://bazel.build/versions" track-metadata-eventdetail="https://bazel.build/versions" class="devsite-tabs-content gc-analytics-event " track-type="nav" track-metadata-position="nav - versioned docs" track-metadata-module="primary nav" data-category="Site-Wide Custom Events" data-label="Tab: Versioned docs" track-name="versioned docs" > Versioned docs </a> <a href="#" role="button" aria-haspopup="true" aria-expanded="false" aria-label="Dropdown menu for Versioned docs" track-type="nav" track-metadata-eventdetail="https://bazel.build/versions" track-metadata-position="nav - versioned docs" track-metadata-module="primary nav" data-category="Site-Wide Custom Events" data-label="Tab: Versioned docs" track-name="versioned docs" class="devsite-tabs-dropdown-toggle devsite-icon devsite-icon-arrow-drop-down"></a> <div class="devsite-tabs-dropdown" aria-label="submenu" hidden> <div class="devsite-tabs-dropdown-content"> <div class="devsite-tabs-dropdown-column "> <ul class="devsite-tabs-dropdown-section "> <li class="devsite-nav-item"> <a href="https://bazel.build/versions/7.4.0" track-type="nav" track-metadata-eventdetail="https://bazel.build/versions/7.4.0" track-metadata-position="nav - versioned docs" track-metadata-module="tertiary nav" tooltip > <div class="devsite-nav-item-title"> 7.4 </div> </a> </li> <li class="devsite-nav-item"> <a href="https://bazel.build/versions/7.3.0" track-type="nav" track-metadata-eventdetail="https://bazel.build/versions/7.3.0" track-metadata-position="nav - versioned docs" track-metadata-module="tertiary nav" tooltip > <div class="devsite-nav-item-title"> 7.3 </div> </a> </li> <li class="devsite-nav-item"> <a href="https://bazel.build/versions/7.2.0" track-type="nav" track-metadata-eventdetail="https://bazel.build/versions/7.2.0" track-metadata-position="nav - versioned docs" track-metadata-module="tertiary nav" tooltip > <div class="devsite-nav-item-title"> 7.2 </div> </a> </li> <li class="devsite-nav-item"> <a href="https://bazel.build/versions/7.1.0" track-type="nav" track-metadata-eventdetail="https://bazel.build/versions/7.1.0" track-metadata-position="nav - versioned docs" track-metadata-module="tertiary nav" tooltip > <div class="devsite-nav-item-title"> 7.1 </div> </a> </li> <li class="devsite-nav-item"> <a href="https://bazel.build/versions/7.0.0" track-type="nav" track-metadata-eventdetail="https://bazel.build/versions/7.0.0" track-metadata-position="nav - versioned docs" track-metadata-module="tertiary nav" tooltip > <div class="devsite-nav-item-title"> 7.0 </div> </a> </li> <li class="devsite-nav-item"> <a href="https://bazel.build/versions/6.5.0" track-type="nav" track-metadata-eventdetail="https://bazel.build/versions/6.5.0" track-metadata-position="nav - versioned docs" track-metadata-module="tertiary nav" tooltip > <div class="devsite-nav-item-title"> 6.5 </div> </a> </li> <li class="devsite-nav-item"> <a href="https://docs.bazel.build/versions/5.4.1/bazel-overview.html" track-type="nav" track-metadata-eventdetail="https://docs.bazel.build/versions/5.4.1/bazel-overview.html" track-metadata-position="nav - versioned docs" track-metadata-module="tertiary nav" tooltip > <div class="devsite-nav-item-title"> 5.4.1 </div> </a> </li> </ul> </div> <div class="devsite-tabs-dropdown-column "> <ul class="devsite-tabs-dropdown-section "> <li class="devsite-nav-item"> <a href="https://bazel.build/" track-type="nav" track-metadata-eventdetail="https://bazel.build/" track-metadata-position="nav - versioned docs" track-metadata-module="tertiary nav" tooltip > <div class="devsite-nav-item-title"> Nightly </div> </a> </li> <li class="devsite-nav-item"> <a href="https://bazel.build/versions" track-type="nav" track-metadata-eventdetail="https://bazel.build/versions" track-metadata-position="nav - versioned docs" track-metadata-module="tertiary nav" tooltip > <div class="devsite-nav-item-title"> More… </div> </a> </li> </ul> </div> </div> </div> </tab> </nav> </devsite-tabs> </div> <devsite-search enable-signin enable-search enable-suggestions enable-query-completion project-name="Bazel" tenant-name="Bazel" > <form class="devsite-search-form" action="https://bazel.build/s/results" method="GET"> <div class="devsite-search-container"> <button type="button" search-open class="devsite-search-button devsite-header-icon-button button-flat material-icons" aria-label="Open search"></button> <div class="devsite-searchbox"> <input aria-activedescendant="" aria-autocomplete="list" aria-label="Search" aria-expanded="false" aria-haspopup="listbox" autocomplete="off" class="devsite-search-field devsite-search-query" name="q" placeholder="Search" role="combobox" type="text" value="" > <div class="devsite-search-image material-icons" aria-hidden="true"> </div> <div class="devsite-search-shortcut-icon-container" aria-hidden="true"> <kbd class="devsite-search-shortcut-icon">/</kbd> </div> </div> </div> </form> <button type="button" search-close class="devsite-search-button devsite-header-icon-button button-flat material-icons" aria-label="Close search"></button> </devsite-search> </div> <devsite-language-selector> <ul role="presentation"> <li role="presentation"> <a role="menuitem" lang="en" >English</a> </li> <li role="presentation"> <a role="menuitem" lang="es_419" >Español – América Latina</a> </li> <li role="presentation"> <a role="menuitem" lang="id" >Indonesia</a> </li> <li role="presentation"> <a role="menuitem" lang="pt_br" >Português – Brasil</a> </li> <li role="presentation"> <a role="menuitem" lang="vi" >Tiếng Việt</a> </li> <li role="presentation"> <a role="menuitem" lang="tr" >Türkçe</a> </li> <li role="presentation"> <a role="menuitem" lang="he" >עברית</a> </li> <li role="presentation"> <a role="menuitem" lang="ar" >العربيّة</a> </li> <li role="presentation"> <a role="menuitem" lang="fa" >فارسی</a> </li> <li role="presentation"> <a role="menuitem" lang="hi" >हिंदी</a> </li> <li role="presentation"> <a role="menuitem" lang="bn" >বাংলা</a> </li> <li role="presentation"> <a role="menuitem" lang="th" >ภาษาไทย</a> </li> <li role="presentation"> <a role="menuitem" lang="zh_cn" >中文 – 简体</a> </li> <li role="presentation"> <a role="menuitem" lang="zh_tw" >中文 – 繁體</a> </li> <li role="presentation"> <a role="menuitem" lang="ja" >日本語</a> </li> <li role="presentation"> <a role="menuitem" lang="ko" >한국어</a> </li> </ul> </devsite-language-selector> <a class="devsite-header-link devsite-top-button button gc-analytics-event" href="//github.com/bazelbuild/bazel/" data-category="Site-Wide Custom Events" data-label="Site header link" > GitHub </a> <devsite-user enable-profiles id="devsite-user"> <span class="button devsite-top-button" aria-hidden="true" visually-hidden>Sign in</span> </devsite-user> </div> </div> </div> <div class="devsite-collapsible-section "> <div class="devsite-header-background"> <div class="devsite-product-id-row" > <div class="devsite-product-description-row"> <ul class="devsite-breadcrumb-list" > <li class="devsite-breadcrumb-item "> <a href="https://bazel.build/docs" class="devsite-breadcrumb-link gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Lower Header" data-value="1" track-type="globalNav" track-name="breadcrumb" track-metadata-position="1" track-metadata-eventdetail="" > Guides and tutorials for learning to use Bazel </a> </li> </ul> </div> </div> <div class="devsite-doc-set-nav-row"> <devsite-tabs class="lower-tabs"> <nav class="devsite-tabs-wrapper" aria-label="Lower tabs"> <tab > <a href="https://bazel.build/release" track-metadata-eventdetail="https://bazel.build/release" class="devsite-tabs-content gc-analytics-event " track-type="nav" track-metadata-position="nav - releases" track-metadata-module="primary nav" data-category="Site-Wide Custom Events" data-label="Tab: Releases" track-name="releases" > Releases </a> </tab> <tab class="devsite-active"> <a href="https://bazel.build/build/style-guide" track-metadata-eventdetail="https://bazel.build/build/style-guide" class="devsite-tabs-content gc-analytics-event " track-type="nav" track-metadata-position="nav - basics" track-metadata-module="primary nav" aria-label="Basics, selected" data-category="Site-Wide Custom Events" data-label="Tab: Basics" track-name="basics" > Basics </a> </tab> <tab > <a href="https://bazel.build/configure/attributes" track-metadata-eventdetail="https://bazel.build/configure/attributes" class="devsite-tabs-content gc-analytics-event " track-type="nav" track-metadata-position="nav - advanced" track-metadata-module="primary nav" data-category="Site-Wide Custom Events" data-label="Tab: Advanced" track-name="advanced" > Advanced </a> </tab> <tab > <a href="https://bazel.build/remote/rbe" track-metadata-eventdetail="https://bazel.build/remote/rbe" class="devsite-tabs-content gc-analytics-event " track-type="nav" track-metadata-position="nav - remote execution" track-metadata-module="primary nav" data-category="Site-Wide Custom Events" data-label="Tab: Remote execution" track-name="remote execution" > Remote execution </a> </tab> <tab > <a href="https://bazel.build/tutorials/cpp-use-cases" track-metadata-eventdetail="https://bazel.build/tutorials/cpp-use-cases" class="devsite-tabs-content gc-analytics-event " track-type="nav" track-metadata-position="nav - tutorials" track-metadata-module="primary nav" data-category="Site-Wide Custom Events" data-label="Tab: Tutorials" track-name="tutorials" > Tutorials </a> </tab> <tab > <a href="https://bazel.build/migrate" track-metadata-eventdetail="https://bazel.build/migrate" class="devsite-tabs-content gc-analytics-event " track-type="nav" track-metadata-position="nav - migrate" track-metadata-module="primary nav" data-category="Site-Wide Custom Events" data-label="Tab: Migrate" track-name="migrate" > Migrate </a> </tab> </nav> </devsite-tabs> </div> </div> </div> </div> </devsite-header> <devsite-book-nav scrollbars > <div class="devsite-book-nav-filter" > <span class="filter-list-icon material-icons" aria-hidden="true"></span> <input type="text" placeholder="Filter" aria-label="Type to filter" role="searchbox"> <span class="filter-clear-button hidden" data-title="Clear filter" aria-label="Clear filter" role="button" tabindex="0"></span> </div> <nav class="devsite-book-nav devsite-nav nocontent" aria-label="Side menu"> <div class="devsite-mobile-header"> <button type="button" id="devsite-close-nav" class="devsite-header-icon-button button-flat material-icons gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Close navigation" aria-label="Close navigation"> </button> <div class="devsite-product-name-wrapper"> <a href="/" class="devsite-site-logo-link gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Site logo" track-type="globalNav" track-name="bazel" track-metadata-position="nav" track-metadata-eventDetail="nav"> <picture> <img src="https://www.gstatic.com/devrel-devsite/prod/v870e399c64f7c43c99a3043db4b3a74327bb93d0914e84a0c3dba90bbfd67625/bazel/images/lockup.svg" class="devsite-site-logo" alt="Bazel"> </picture> </a> <span class="devsite-product-name"> <ul class="devsite-breadcrumb-list" > <li class="devsite-breadcrumb-item "> </li> </ul> </span> </div> </div> <div class="devsite-book-nav-wrapper"> <div class="devsite-mobile-nav-top"> <ul class="devsite-nav-list"> <li class="devsite-nav-item"> <a href="/about" class="devsite-nav-title gc-analytics-event " data-category="Site-Wide Custom Events" data-label="Tab: About Bazel" track-name="about bazel" data-category="Site-Wide Custom Events" data-label="Responsive Tab: About Bazel" track-type="globalNav" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > About Bazel </span> </a> </li> <li class="devsite-nav-item"> <a href="/start" class="devsite-nav-title gc-analytics-event " data-category="Site-Wide Custom Events" data-label="Tab: Getting started" track-name="getting started" data-category="Site-Wide Custom Events" data-label="Responsive Tab: Getting started" track-type="globalNav" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > Getting started </span> </a> </li> <li class="devsite-nav-item"> <a href="/docs" class="devsite-nav-title gc-analytics-event devsite-nav-active" data-category="Site-Wide Custom Events" data-label="Tab: User guide" track-name="user guide" data-category="Site-Wide Custom Events" data-label="Responsive Tab: User guide" track-type="globalNav" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > User guide </span> </a> <ul class="devsite-nav-responsive-tabs"> <li class="devsite-nav-item"> <a href="/release" class="devsite-nav-title gc-analytics-event devsite-nav-has-children " data-category="Site-Wide Custom Events" data-label="Tab: Releases" track-name="releases" data-category="Site-Wide Custom Events" data-label="Responsive Tab: Releases" track-type="globalNav" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > Releases </span> <span class="devsite-nav-icon material-icons" data-icon="forward" > </span> </a> </li> <li class="devsite-nav-item"> <a href="/build/style-guide" class="devsite-nav-title gc-analytics-event devsite-nav-has-children devsite-nav-active" data-category="Site-Wide Custom Events" data-label="Tab: Basics" track-name="basics" data-category="Site-Wide Custom Events" data-label="Responsive Tab: Basics" track-type="globalNav" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip menu="_book"> Basics </span> <span class="devsite-nav-icon material-icons" data-icon="forward" menu="_book"> </span> </a> </li> <li class="devsite-nav-item"> <a href="/configure/attributes" class="devsite-nav-title gc-analytics-event devsite-nav-has-children " data-category="Site-Wide Custom Events" data-label="Tab: Advanced" track-name="advanced" data-category="Site-Wide Custom Events" data-label="Responsive Tab: Advanced" track-type="globalNav" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > Advanced </span> <span class="devsite-nav-icon material-icons" data-icon="forward" > </span> </a> </li> <li class="devsite-nav-item"> <a href="/remote/rbe" class="devsite-nav-title gc-analytics-event devsite-nav-has-children " data-category="Site-Wide Custom Events" data-label="Tab: Remote execution" track-name="remote execution" data-category="Site-Wide Custom Events" data-label="Responsive Tab: Remote execution" track-type="globalNav" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > Remote execution </span> <span class="devsite-nav-icon material-icons" data-icon="forward" > </span> </a> </li> <li class="devsite-nav-item"> <a href="/tutorials/cpp-use-cases" class="devsite-nav-title gc-analytics-event devsite-nav-has-children " data-category="Site-Wide Custom Events" data-label="Tab: Tutorials" track-name="tutorials" data-category="Site-Wide Custom Events" data-label="Responsive Tab: Tutorials" track-type="globalNav" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > Tutorials </span> <span class="devsite-nav-icon material-icons" data-icon="forward" > </span> </a> </li> <li class="devsite-nav-item"> <a href="/migrate" class="devsite-nav-title gc-analytics-event devsite-nav-has-children " data-category="Site-Wide Custom Events" data-label="Tab: Migrate" track-name="migrate" data-category="Site-Wide Custom Events" data-label="Responsive Tab: Migrate" track-type="globalNav" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > Migrate </span> <span class="devsite-nav-icon material-icons" data-icon="forward" > </span> </a> </li> </ul> </li> <li class="devsite-nav-item"> <a href="/reference" class="devsite-nav-title gc-analytics-event " data-category="Site-Wide Custom Events" data-label="Tab: Reference" track-name="reference" data-category="Site-Wide Custom Events" data-label="Responsive Tab: Reference" track-type="globalNav" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > Reference </span> </a> </li> <li class="devsite-nav-item"> <a href="/extending" class="devsite-nav-title gc-analytics-event " data-category="Site-Wide Custom Events" data-label="Tab: Extending" track-name="extending" data-category="Site-Wide Custom Events" data-label="Responsive Tab: Extending" track-type="globalNav" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > Extending </span> </a> </li> <li class="devsite-nav-item"> <a href="/community" class="devsite-nav-title gc-analytics-event " data-category="Site-Wide Custom Events" data-label="Tab: Community" track-name="community" data-category="Site-Wide Custom Events" data-label="Responsive Tab: Community" track-type="globalNav" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > Community </span> </a> </li> <li class="devsite-nav-item"> <a href="/versions" class="devsite-nav-title gc-analytics-event " data-category="Site-Wide Custom Events" data-label="Tab: Versioned docs" track-name="versioned docs" data-category="Site-Wide Custom Events" data-label="Responsive Tab: Versioned docs" track-type="globalNav" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > Versioned docs </span> </a> <ul class="devsite-nav-responsive-tabs devsite-nav-has-menu "> <li class="devsite-nav-item"> <span class="devsite-nav-title" tooltip data-category="Site-Wide Custom Events" data-label="Tab: Versioned docs" track-name="versioned docs" > <span class="devsite-nav-text" tooltip menu="Versioned docs"> More </span> <span class="devsite-nav-icon material-icons" data-icon="forward" menu="Versioned docs"> </span> </span> </li> </ul> </li> <li class="devsite-nav-item"> <a href="//github.com/bazelbuild/bazel/" class="devsite-nav-title gc-analytics-event " data-category="Site-Wide Custom Events" data-label="Responsive Tab: GitHub" track-type="navMenu" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > GitHub </span> </a> </li> </ul> </div> <div class="devsite-mobile-nav-bottom"> <ul class="devsite-nav-list" menu="_book"> <li class="devsite-nav-item devsite-nav-heading"><div class="devsite-nav-title devsite-nav-title-no-path"> <span class="devsite-nav-text" tooltip>Getting started with BUILD files</span> </div></li> <li class="devsite-nav-item"><a href="/build/style-guide" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /build/style-guide" track-type="bookNav" track-name="click" track-metadata-eventdetail="/build/style-guide" ><span class="devsite-nav-text" tooltip>BUILD style guide</span></a></li> <li class="devsite-nav-item"><a href="/build/share-variables" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /build/share-variables" track-type="bookNav" track-name="click" track-metadata-eventdetail="/build/share-variables" ><span class="devsite-nav-text" tooltip>Share variables</span></a></li> <li class="devsite-nav-item"><a href="/community/recommended-rules" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /community/recommended-rules" track-type="bookNav" track-name="click" track-metadata-eventdetail="/community/recommended-rules" ><span class="devsite-nav-text" tooltip>Recommended rules</span></a></li> <li class="devsite-nav-item devsite-nav-heading"><div class="devsite-nav-title devsite-nav-title-no-path"> <span class="devsite-nav-text" tooltip>Running Bazel</span> </div></li> <li class="devsite-nav-item"><a href="/run/build" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /run/build" track-type="bookNav" track-name="click" track-metadata-eventdetail="/run/build" ><span class="devsite-nav-text" tooltip>Build with Bazel</span></a></li> <li class="devsite-nav-item"><a href="/docs/user-manual" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /docs/user-manual" track-type="bookNav" track-name="click" track-metadata-eventdetail="/docs/user-manual" ><span class="devsite-nav-text" tooltip>Commands and options</span></a></li> <li class="devsite-nav-item"><a href="/run/bazelrc" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /run/bazelrc" track-type="bookNav" track-name="click" track-metadata-eventdetail="/run/bazelrc" ><span class="devsite-nav-text" tooltip>Write bazelrc files</span></a></li> <li class="devsite-nav-item"><a href="/run/scripts" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /run/scripts" track-type="bookNav" track-name="click" track-metadata-eventdetail="/run/scripts" ><span class="devsite-nav-text" tooltip>Call Bazel from scripts</span></a></li> <li class="devsite-nav-item"><a href="/run/client-server" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /run/client-server" track-type="bookNav" track-name="click" track-metadata-eventdetail="/run/client-server" ><span class="devsite-nav-text" tooltip>Client/server implementation</span></a></li> <li class="devsite-nav-item devsite-nav-heading"><div class="devsite-nav-title devsite-nav-title-no-path"> <span class="devsite-nav-text" tooltip>External dependencies</span> </div></li> <li class="devsite-nav-item"><a href="/external/overview" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /external/overview" track-type="bookNav" track-name="click" track-metadata-eventdetail="/external/overview" ><span class="devsite-nav-text" tooltip>Overview</span></a></li> <li class="devsite-nav-item"><a href="/external/module" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /external/module" track-type="bookNav" track-name="click" track-metadata-eventdetail="/external/module" ><span class="devsite-nav-text" tooltip>Bazel modules</span></a></li> <li class="devsite-nav-item"><a href="/external/registry" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /external/registry" track-type="bookNav" track-name="click" track-metadata-eventdetail="/external/registry" ><span class="devsite-nav-text" tooltip>Bazel registries</span></a></li> <li class="devsite-nav-item"><a href="/external/extension" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /external/extension" track-type="bookNav" track-name="click" track-metadata-eventdetail="/external/extension" ><span class="devsite-nav-text" tooltip>Module extensions</span></a></li> <li class="devsite-nav-item"><a href="/external/lockfile" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /external/lockfile" track-type="bookNav" track-name="click" track-metadata-eventdetail="/external/lockfile" ><span class="devsite-nav-text" tooltip>Module lockfile</span></a></li> <li class="devsite-nav-item"><a href="/external/vendor" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /external/vendor" track-type="bookNav" track-name="click" track-metadata-eventdetail="/external/vendor" ><span class="devsite-nav-text" tooltip>Vendor mode</span></a></li> <li class="devsite-nav-item"><a href="/external/mod-command" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /external/mod-command" track-type="bookNav" track-name="click" track-metadata-eventdetail="/external/mod-command" ><span class="devsite-nav-text" tooltip>`mod` command</span></a></li> <li class="devsite-nav-item"><a href="/external/migration" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /external/migration" track-type="bookNav" track-name="click" track-metadata-eventdetail="/external/migration" ><span class="devsite-nav-text" tooltip>Bzlmod migration guide</span></a></li> <li class="devsite-nav-item"><a href="/external/advanced" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /external/advanced" track-type="bookNav" track-name="click" track-metadata-eventdetail="/external/advanced" ><span class="devsite-nav-text" tooltip>Advanced topics</span></a></li> <li class="devsite-nav-item devsite-nav-heading"><div class="devsite-nav-title devsite-nav-title-no-path"> <span class="devsite-nav-text" tooltip>Querying your build</span> </div></li> <li class="devsite-nav-item"><a href="/query/quickstart" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /query/quickstart" track-type="bookNav" track-name="click" track-metadata-eventdetail="/query/quickstart" ><span class="devsite-nav-text" tooltip>Query quickstart</span></a></li> <li class="devsite-nav-item"><a href="/query/language" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /query/language" track-type="bookNav" track-name="click" track-metadata-eventdetail="/query/language" ><span class="devsite-nav-text" tooltip>Query language</span></a></li> <li class="devsite-nav-item"><a href="/query/guide" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /query/guide" track-type="bookNav" track-name="click" track-metadata-eventdetail="/query/guide" ><span class="devsite-nav-text" tooltip>Query guide</span></a></li> <li class="devsite-nav-item"><a href="/query/aquery" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /query/aquery" track-type="bookNav" track-name="click" track-metadata-eventdetail="/query/aquery" ><span class="devsite-nav-text" tooltip>Action graph query (aquery)</span></a></li> <li class="devsite-nav-item"><a href="/query/cquery" class="devsite-nav-title gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Book nav link, pathname: /query/cquery" track-type="bookNav" track-name="click" track-metadata-eventdetail="/query/cquery" ><span class="devsite-nav-text" tooltip>Configurable query (cquery)</span></a></li> </ul> <ul class="devsite-nav-list" menu="Versioned docs" aria-label="Side menu" hidden> <li class="devsite-nav-item"> <a href="/versions/7.4.0" class="devsite-nav-title gc-analytics-event " data-category="Site-Wide Custom Events" data-label="Responsive Tab: 7.4" track-type="navMenu" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > 7.4 </span> </a> </li> <li class="devsite-nav-item"> <a href="/versions/7.3.0" class="devsite-nav-title gc-analytics-event " data-category="Site-Wide Custom Events" data-label="Responsive Tab: 7.3" track-type="navMenu" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > 7.3 </span> </a> </li> <li class="devsite-nav-item"> <a href="/versions/7.2.0" class="devsite-nav-title gc-analytics-event " data-category="Site-Wide Custom Events" data-label="Responsive Tab: 7.2" track-type="navMenu" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > 7.2 </span> </a> </li> <li class="devsite-nav-item"> <a href="/versions/7.1.0" class="devsite-nav-title gc-analytics-event " data-category="Site-Wide Custom Events" data-label="Responsive Tab: 7.1" track-type="navMenu" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > 7.1 </span> </a> </li> <li class="devsite-nav-item"> <a href="/versions/7.0.0" class="devsite-nav-title gc-analytics-event " data-category="Site-Wide Custom Events" data-label="Responsive Tab: 7.0" track-type="navMenu" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > 7.0 </span> </a> </li> <li class="devsite-nav-item"> <a href="/versions/6.5.0" class="devsite-nav-title gc-analytics-event " data-category="Site-Wide Custom Events" data-label="Responsive Tab: 6.5" track-type="navMenu" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > 6.5 </span> </a> </li> <li class="devsite-nav-item"> <a href="https://docs.bazel.build/versions/5.4.1/bazel-overview.html" class="devsite-nav-title gc-analytics-event " data-category="Site-Wide Custom Events" data-label="Responsive Tab: 5.4.1" track-type="navMenu" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > 5.4.1 </span> </a> </li> <li class="devsite-nav-item"> <a href="/" class="devsite-nav-title gc-analytics-event " data-category="Site-Wide Custom Events" data-label="Responsive Tab: Nightly" track-type="navMenu" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > Nightly </span> </a> </li> <li class="devsite-nav-item"> <a href="/versions" class="devsite-nav-title gc-analytics-event " data-category="Site-Wide Custom Events" data-label="Responsive Tab: More…" track-type="navMenu" track-metadata-eventDetail="globalMenu" track-metadata-position="nav"> <span class="devsite-nav-text" tooltip > More… </span> </a> </li> </ul> </div> </div> </nav> </devsite-book-nav> <section id="gc-wrapper"> <main role="main" class="devsite-main-content" has-book-nav has-sidebar > <div class="devsite-sidebar"> <div class="devsite-sidebar-content"> <devsite-toc class="devsite-nav" role="navigation" aria-label="On this page" depth="2" scrollbars ></devsite-toc> <devsite-recommendations-sidebar class="nocontent devsite-nav"> </devsite-recommendations-sidebar> </div> </div> <devsite-content> <article class="devsite-article"> <div class="devsite-article-meta nocontent" role="navigation"> <ul class="devsite-breadcrumb-list" aria-label="Breadcrumb"> <li class="devsite-breadcrumb-item "> <a href="https://bazel.build/" class="devsite-breadcrumb-link gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Breadcrumbs" data-value="1" track-type="globalNav" track-name="breadcrumb" track-metadata-position="1" track-metadata-eventdetail="Bazel" > Bazel </a> </li> <li class="devsite-breadcrumb-item "> <div class="devsite-breadcrumb-guillemet material-icons" aria-hidden="true"></div> <a href="https://bazel.build/docs" class="devsite-breadcrumb-link gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Breadcrumbs" data-value="2" track-type="globalNav" track-name="breadcrumb" track-metadata-position="2" track-metadata-eventdetail="" > User guide </a> </li> <li class="devsite-breadcrumb-item "> <div class="devsite-breadcrumb-guillemet material-icons" aria-hidden="true"></div> <a href="https://bazel.build/build/style-guide" class="devsite-breadcrumb-link gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Breadcrumbs" data-value="3" track-type="globalNav" track-name="breadcrumb" track-metadata-position="3" track-metadata-eventdetail="" > Basics </a> </li> </ul> <devsite-thumb-rating position="header"> </devsite-thumb-rating> </div> <devsite-feedback position="header" project-name="Bazel" product-id="5052038" bucket="https-bazel-build" context="" version="t-devsite-webserver-20241114-r00-rc02.464921008191574316" data-label="Send Feedback Button" track-type="feedback" track-name="sendFeedbackLink" track-metadata-position="header" class="nocontent" project-icon="https://www.gstatic.com/devrel-devsite/prod/v870e399c64f7c43c99a3043db4b3a74327bb93d0914e84a0c3dba90bbfd67625/bazel/images/touchicon-180.png" > <button> Send feedback </button> </devsite-feedback> <h1 class="devsite-page-title" tabindex="-1"> Commands and Options </h1> <devsite-feature-tooltip ack-key="AckCollectionsBookmarkTooltipDismiss" analytics-category="Site-Wide Custom Events" analytics-action-show="Callout Profile displayed" analytics-action-close="Callout Profile dismissed" analytics-label="Create Collection Callout" class="devsite-page-bookmark-tooltip nocontent" dismiss-button="true" id="devsite-collections-dropdown" dismiss-button-text="Dismiss" close-button-text="Got it"> <devsite-bookmark></devsite-bookmark> <span slot="popout-heading"> Stay organized with collections </span> <span slot="popout-contents"> Save and categorize content based on your preferences. </span> </devsite-feature-tooltip> <div class="devsite-page-title-meta"><devsite-view-release-notes></devsite-view-release-notes></div> <devsite-toc class="devsite-nav" depth="2" devsite-toc-embedded > </devsite-toc> <div class="devsite-article-body clearfix "> <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/issues/new?title=%5Bbazel.build%5D+Problem+with+/docs/user-manual&template=doc_issue.yml&link=https%3A%2F%2Fbazel.build/docs/user-manual" target="_blank"> Report an issue<span class="material-icons icon-after" aria-hidden="true" translate="no">open_in_new</span> </a> <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/tree/master/site/en/docs/user-manual.md" target="_blank"> View source<span class="material-icons icon-after" aria-hidden="true" translate="no">open_in_new</span> </a> <span style="float: right; line-height: 36px"> <strong>Nightly</strong>   · <a href="/versions/7.4.0/docs/user-manual">7.4</a> . <a href="/versions/7.3.0/docs/user-manual">7.3</a> · <a href="/versions/7.2.0/docs/user-manual">7.2</a> · <a href="/versions/7.1.0/docs/user-manual">7.1</a> · <a href="/versions/7.0.0/docs/user-manual">7.0</a> · <a href="/versions/6.5.0/docs/user-manual">6.5</a>  </span> <p/> <p>This page covers the options that are available with various Bazel commands, such as <code translate="no" dir="ltr">bazel build</code>, <code translate="no" dir="ltr">bazel run</code>, and <code translate="no" dir="ltr">bazel test</code>. This page is a companion to the list of Bazel's commands in <a href="/run/build">Build with Bazel</a>.</p> <h2 id="target-syntax" data-text="Target syntax" tabindex="-1">Target syntax</h2> <p>Some commands, like <code translate="no" dir="ltr">build</code> or <code translate="no" dir="ltr">test</code>, can operate on a list of targets. They use a syntax more flexible than labels, which is documented in <a href="/run/build#specifying-build-targets">Specifying targets to build</a>.</p> <h2 id="build-options" data-text="Options" tabindex="-1">Options</h2> <p>The following sections describe the options available during a build. When <code translate="no" dir="ltr">--long</code> is used on a help command, the on-line help messages provide summary information about the meaning, type and default value for each option.</p> <p>Most options can only be specified once. When specified multiple times, the last instance wins. Options that can be specified multiple times are identified in the on-line help with the text 'may be used multiple times'.</p> <h3 id="package-location" data-text="Package location" tabindex="-1">Package location</h3> <h4 id="package-path" data-text="--package_path" tabindex="-1"><code translate="no" dir="ltr">--package_path</code></h4> <p><strong>WARNING:</strong> The <code translate="no" dir="ltr">--package_path</code> option is deprecated. Bazel prefers packages in the main repository to be under the workspace root.</p> <p>This option specifies the set of directories that are searched to find the BUILD file for a given package.</p> <p>Bazel finds its packages by searching the package path. This is a colon separated ordered list of bazel directories, each being the root of a partial source tree.</p> <p><em>To specify a custom package path</em> using the <code translate="no" dir="ltr">--package_path</code> option:</p> <pre translate="no" dir="ltr"> % bazel build --package_path %workspace%:/some/other/root </pre> <p>Package path elements may be specified in three formats:</p> <ol> <li>If the first character is <code translate="no" dir="ltr">/</code>, the path is absolute.</li> <li>If the path starts with <code translate="no" dir="ltr">%workspace%</code>, the path is taken relative to the nearest enclosing bazel directory. For instance, if your working directory is <code translate="no" dir="ltr">/home/bob/clients/bob_client/bazel/foo</code>, then the string <code translate="no" dir="ltr">%workspace%</code> in the package-path is expanded to <code translate="no" dir="ltr">/home/bob/clients/bob_client/bazel</code>.</li> <li>Anything else is taken relative to the working directory. This is usually not what you mean to do, and may behave unexpectedly if you use Bazel from directories below the bazel workspace. For instance, if you use the package-path element <code translate="no" dir="ltr">.</code>, and then cd into the directory <code translate="no" dir="ltr">/home/bob/clients/bob_client/bazel/foo</code>, packages will be resolved from the <code translate="no" dir="ltr">/home/bob/clients/bob_client/bazel/foo</code> directory.</li> </ol> <p>If you use a non-default package path, specify it in your <a href="/run/bazelrc">Bazel configuration file</a> for convenience.</p> <p><em>Bazel doesn't require any packages to be in the current directory</em>, so you can do a build from an empty bazel workspace if all the necessary packages can be found somewhere else on the package path.</p> <p>Example: Building from an empty client</p> <pre translate="no" dir="ltr"> % mkdir -p foo/bazel % cd foo/bazel % touch MODULE.bazel % bazel build --package_path /some/other/path //foo </pre> <h4 id="--deleted_packages" data-text="--deleted_packages" tabindex="-1"><code translate="no" dir="ltr">--deleted_packages</code></h4> <p>This option specifies a comma-separated list of packages which Bazel should consider deleted, and not attempt to load from any directory on the package path. This can be used to simulate the deletion of packages without actually deleting them. This option can be passed multiple times, in which case the individual lists are concatenated.</p> <h3 id="error-checking" data-text="Error checking" tabindex="-1">Error checking</h3> <p>These options control Bazel's error-checking and/or warnings.</p> <h4 id="check-visibility" data-text="--[no]check_visibility" tabindex="-1"><code translate="no" dir="ltr">--[no]check_visibility</code></h4> <p>If this option is set to false, visibility checks are demoted to warnings. The default value of this option is true, so that by default, visibility checking is done.</p> <h4 id="output-filter" data-text="--output_filter=regex" tabindex="-1"><code translate="no" dir="ltr">--output_filter=<var translate="no">regex</var></code></h4> <p>The <code translate="no" dir="ltr">--output_filter</code> option will only show build and compilation warnings for targets that match the regular expression. If a target does not match the given regular expression and its execution succeeds, its standard output and standard error are thrown away.</p> <p>Here are some typical values for this option:</p> <table> <tr> <td>`--output_filter='^//(first/project|second/project):'`</td> <td>Show the output for the specified packages.</td> </tr> <tr> <td>`--output_filter='^//((?!(first/bad_project|second/bad_project):).)*$'`</td> <td>Don't show output for the specified packages.</td> </tr> <tr> <td>`--output_filter=`</td> <td>Show everything. </td> </tr> <tr> <td>`--output_filter=DONT_MATCH_ANYTHING`</td> <td>Show nothing. </td> </tr> </table> <h3 id="tool-flags" data-text="Tool flags" tabindex="-1">Tool flags</h3> <p>These options control which options Bazel will pass to other tools.</p> <h4 id="copt" data-text="--copt=cc-option" tabindex="-1"><code translate="no" dir="ltr">--copt=<var translate="no">cc-option</var></code></h4> <p>This option takes an argument which is to be passed to the compiler. The argument will be passed to the compiler whenever it is invoked for preprocessing, compiling, and/or assembling C, C++, or assembler code. It will not be passed when linking.</p> <p>This option can be used multiple times. For example:</p> <pre translate="no" dir="ltr"> % bazel build --copt="-g0" --copt="-fpic" //foo </pre> <p>will compile the <code translate="no" dir="ltr">foo</code> library without debug tables, generating position-independent code.</p> <aside class="note"><strong>Note:</strong><span> Changing <code translate="no" dir="ltr">--copt</code> settings will force a recompilation of all affected object files. Also note that copts values listed in specific cc_library or cc_binary build rules will be placed on the compiler command line <em>after</em> these options.</span></aside><aside class="warning"><strong>Warning:</strong><span> C++-specific options (such as <code translate="no" dir="ltr">-fno-implicit-templates</code>) should be specified in <code translate="no" dir="ltr">--cxxopt</code>, not in <code translate="no" dir="ltr">--copt</code>. Likewise, C-specific options (such as -Wstrict-prototypes) should be specified in <code translate="no" dir="ltr">--conlyopt</code>, not in <code translate="no" dir="ltr">copt</code>. Similarly, compiler options that only have an effect at link time (such as <code translate="no" dir="ltr">-l</code>) should be specified in <code translate="no" dir="ltr">--linkopt</code>, not in <code translate="no" dir="ltr">--copt</code>.</span></aside> <h4 id="host-copt" data-text="--host_copt=cc-option" tabindex="-1"><code translate="no" dir="ltr">--host_copt=<var translate="no">cc-option</var></code></h4> <p>This option takes an argument which is to be passed to the compiler for source files that are compiled in the exec configuration. This is analogous to the <a href="#copt"><code translate="no" dir="ltr">--copt</code></a> option, but applies only to the exec configuration.</p> <h4 id="host-conlyopt" data-text="--host_conlyopt=cc-option" tabindex="-1"><code translate="no" dir="ltr">--host_conlyopt=<var translate="no">cc-option</var></code></h4> <p>This option takes an argument which is to be passed to the compiler for C source files that are compiled in the exec configuration. This is analogous to the <a href="#cconlyopt"><code translate="no" dir="ltr">--conlyopt</code></a> option, but applies only to the exec configuration.</p> <h4 id="host-cxxopt" data-text="--host_cxxopt=cc-option" tabindex="-1"><code translate="no" dir="ltr">--host_cxxopt=<var translate="no">cc-option</var></code></h4> <p>This option takes an argument which is to be passed to the compiler for C++ source files that are compiled in the exec configuration. This is analogous to the <a href="#cxxopt"><code translate="no" dir="ltr">--cxxopt</code></a> option, but applies only to the exec configuration.</p> <h4 id="host-linkopt" data-text="--host_linkopt=linker-option" tabindex="-1"><code translate="no" dir="ltr">--host_linkopt=<var translate="no">linker-option</var></code></h4> <p>This option takes an argument which is to be passed to the linker for source files that are compiled in the exec configuration. This is analogous to the <a href="#linkopt"><code translate="no" dir="ltr">--linkopt</code></a> option, but applies only to the exec configuration.</p> <h4 id="cconlyopt" data-text="--conlyopt=cc-option" tabindex="-1"><code translate="no" dir="ltr">--conlyopt=<var translate="no">cc-option</var></code></h4> <p>This option takes an argument which is to be passed to the compiler when compiling C source files.</p> <p>This is similar to <code translate="no" dir="ltr">--copt</code>, but only applies to C compilation, not to C++ compilation or linking. So you can pass C-specific options (such as <code translate="no" dir="ltr">-Wno-pointer-sign</code>) using <code translate="no" dir="ltr">--conlyopt</code>.</p> <aside class="note"><strong>Note:</strong><span> copts parameters listed in specific cc_library or cc_binary build rules are placed on the compiler command line <em>after</em> these options.</span></aside> <h4 id="cxxopt" data-text="--cxxopt=cc-option" tabindex="-1"><code translate="no" dir="ltr">--cxxopt=<var translate="no">cc-option</var></code></h4> <p>This option takes an argument which is to be passed to the compiler when compiling C++ source files.</p> <p>This is similar to <code translate="no" dir="ltr">--copt</code>, but only applies to C++ compilation, not to C compilation or linking. So you can pass C++-specific options (such as <code translate="no" dir="ltr">-fpermissive</code> or <code translate="no" dir="ltr">-fno-implicit-templates</code>) using <code translate="no" dir="ltr">--cxxopt</code>.</p> <p>For example:</p> <pre translate="no" dir="ltr"> % bazel build --cxxopt="-fpermissive" --cxxopt="-Wno-error" //foo/cruddy_code </pre> <aside class="note"><strong>Note:</strong><span> copts parameters listed in specific cc_library or cc_binary build rules are placed on the compiler command line <em>after</em> these options.</span></aside> <h4 id="linkopt" data-text="--linkopt=linker-option" tabindex="-1"><code translate="no" dir="ltr">--linkopt=<var translate="no">linker-option</var></code></h4> <p>This option takes an argument which is to be passed to the compiler when linking.</p> <p>This is similar to <code translate="no" dir="ltr">--copt</code>, but only applies to linking, not to compilation. So you can pass compiler options that only make sense at link time (such as <code translate="no" dir="ltr">-lssp</code> or <code translate="no" dir="ltr">-Wl,--wrap,abort</code>) using <code translate="no" dir="ltr">--linkopt</code>. For example:</p> <pre translate="no" dir="ltr"> % bazel build --copt="-fmudflap" --linkopt="-lmudflap" //foo/buggy_code </pre> <p>Build rules can also specify link options in their attributes. This option's settings always take precedence. Also see <a href="/reference/be/c-cpp#cc_library.linkopts">cc_library.linkopts</a>.</p> <h4 id="strip" data-text="--strip (always|never|sometimes)" tabindex="-1"><code translate="no" dir="ltr">--strip (always|never|sometimes)</code></h4> <p>This option determines whether Bazel will strip debugging information from all binaries and shared libraries, by invoking the linker with the <code translate="no" dir="ltr">-Wl,--strip-debug</code> option. <code translate="no" dir="ltr">--strip=always</code> means always strip debugging information. <code translate="no" dir="ltr">--strip=never</code> means never strip debugging information. The default value of <code translate="no" dir="ltr">--strip=sometimes</code> means strip if the <code translate="no" dir="ltr">--compilation_mode</code> is <code translate="no" dir="ltr">fastbuild</code>.</p> <pre translate="no" dir="ltr"> % bazel build --strip=always //foo:bar </pre> <p>will compile the target while stripping debugging information from all generated binaries.</p> <aside class="note"><strong>Note:</strong><span> If you want debugging information, it's not enough to disable stripping; you also need to make sure that the debugging information was generated by the compiler, which you can do by using either <code translate="no" dir="ltr">-c dbg</code> or <code translate="no" dir="ltr">--copt -g</code>.</span></aside> <p>Bazel's <code translate="no" dir="ltr">--strip</code> option corresponds with ld's <code translate="no" dir="ltr">--strip-debug</code> option: it only strips debugging information. If for some reason you want to strip <em>all</em> symbols, not just <em>debug</em> symbols, you would need to use ld's <code translate="no" dir="ltr">--strip-all</code> option, which you can do by passing <code translate="no" dir="ltr">--linkopt=-Wl,--strip-all</code> to Bazel. Also be aware that setting Bazel's <code translate="no" dir="ltr">--strip</code> flag will override <code translate="no" dir="ltr">--linkopt=-Wl,--strip-all</code>, so you should only set one or the other.</p> <p>If you are only building a single binary and want all symbols stripped, you could also pass <code translate="no" dir="ltr">--stripopt=--strip-all</code> and explicitly build the <code translate="no" dir="ltr">//foo:bar.stripped</code> version of the target. As described in the section on <code translate="no" dir="ltr">--stripopt</code>, this applies a strip action after the final binary is linked rather than including stripping in all of the build's link actions.</p> <h4 id="stripopt" data-text="--stripopt=strip-option" tabindex="-1"><code translate="no" dir="ltr">--stripopt=<var translate="no">strip-option</var></code></h4> <p>This is an additional option to pass to the <code translate="no" dir="ltr">strip</code> command when generating a <a href="/reference/be/c-cpp#cc_binary_implicit_outputs"><code translate="no" dir="ltr">*.stripped</code> binary</a>. The default is <code translate="no" dir="ltr">-S -p</code>. This option can be used multiple times.</p> <aside class="note"><strong>Note:</strong><span> <code translate="no" dir="ltr">--stripopt</code> does not apply to the stripping of the main binary with <code translate="no" dir="ltr">[--strip](#flag--strip)=(always|sometimes)</code>.</span></aside> <h4 id="fdo-instrument" data-text="--fdo_instrument=profile-output-dir" tabindex="-1"><code translate="no" dir="ltr">--fdo_instrument=<var translate="no">profile-output-dir</var></code></h4> <p>The <code translate="no" dir="ltr">--fdo_instrument</code> option enables the generation of FDO (feedback directed optimization) profile output when the built C/C++ binary is executed. For GCC, the argument provided is used as a directory prefix for a per-object file directory tree of .gcda files containing profile information for each .o file.</p> <p>Once the profile data tree has been generated, the profile tree should be zipped up, and provided to the <code translate="no" dir="ltr">--fdo_optimize=<var translate="no">profile-zip</var></code> Bazel option to enable the FDO-optimized compilation.</p> <p>For the LLVM compiler the argument is also the directory under which the raw LLVM profile data file(s) is dumped. For example: <code translate="no" dir="ltr">--fdo_instrument=<var translate="no">/path/to/rawprof/dir/</var></code>.</p> <p>The options <code translate="no" dir="ltr">--fdo_instrument</code> and <code translate="no" dir="ltr">--fdo_optimize</code> cannot be used at the same time.</p> <h4 id="fdo-optimize" data-text="--fdo_optimize=profile-zip" tabindex="-1"><code translate="no" dir="ltr">--fdo_optimize=<var translate="no">profile-zip</var></code></h4> <p>The <code translate="no" dir="ltr">--fdo_optimize</code> option enables the use of the per-object file profile information to perform FDO (feedback directed optimization) optimizations when compiling. For GCC, the argument provided is the zip file containing the previously-generated file tree of .gcda files containing profile information for each .o file.</p> <p>Alternatively, the argument provided can point to an auto profile identified by the extension .afdo.</p> <aside class="note"><strong>Note:</strong><span> This option also accepts labels that resolve to source files. You may need to add an <code translate="no" dir="ltr">exports_files</code> directive to the corresponding package to make the file visible to Bazel.</span></aside> <p>For the LLVM compiler the argument provided should point to the indexed LLVM profile output file prepared by the llvm-profdata tool, and should have a .profdata extension.</p> <p>The options <code translate="no" dir="ltr">--fdo_instrument</code> and <code translate="no" dir="ltr">--fdo_optimize</code> cannot be used at the same time.</p> <h4 id="java-language-version" data-text="--java_language_version=version" tabindex="-1"><code translate="no" dir="ltr">--java_language_version=<var translate="no">version</var></code></h4> <p>This option specifies the version of Java sources. For example:</p> <pre translate="no" dir="ltr"> % bazel build --java_language_version=8 java/com/example/common/foo:all </pre> <p>compiles and allows only constructs compatible with Java 8 specification. Default value is 11. --> Possible values are: 8, 9, 10, 11, 17, and 21 and may be extended by registering custom Java toolchains using <code translate="no" dir="ltr">default_java_toolchain</code>.</p> <h4 id="tool-java-language-version" data-text="--tool_java_language_version=version" tabindex="-1"><code translate="no" dir="ltr">--tool_java_language_version=<var translate="no">version</var></code></h4> <p>The Java language version used to build tools that are executed during a build. Default value is 11.</p> <h4 id="java-runtime-version" data-text="--java_runtime_version=version" tabindex="-1"><code translate="no" dir="ltr">--java_runtime_version=<var translate="no">version</var></code></h4> <p>This option specifies the version of JVM to use to execute the code and run the tests. For example:</p> <pre translate="no" dir="ltr"> % bazel run --java_runtime_version=remotejdk_11 java/com/example/common/foo:java_application </pre> <p>downloads JDK 11 from a remote repository and run the Java application using it.</p> <p>Default value is <code translate="no" dir="ltr">local_jdk</code>. Possible values are: <code translate="no" dir="ltr">local_jdk</code>, <code translate="no" dir="ltr">local_jdk_<var translate="no">version</var></code>, <code translate="no" dir="ltr">remotejdk_11</code>, <code translate="no" dir="ltr">remotejdk_17</code>, and <code translate="no" dir="ltr">remotejdk_21</code>. You can extend the values by registering custom JVM using either <code translate="no" dir="ltr">local_java_repository</code> or <code translate="no" dir="ltr">remote_java_repository</code> repository rules.</p> <h4 id="tool-java-runtime-version" data-text="--tool_java_runtime_version=version" tabindex="-1"><code translate="no" dir="ltr">--tool_java_runtime_version=<var translate="no">version</var></code></h4> <p>The version of JVM used to execute tools that are needed during a build. Default value is <code translate="no" dir="ltr">remotejdk_11</code>.</p> <h4 id="jvmopt" data-text="--jvmopt=jvm-option" tabindex="-1"><code translate="no" dir="ltr">--jvmopt=<var translate="no">jvm-option</var></code></h4> <p>This option allows option arguments to be passed to the Java VM. It can be used with one big argument, or multiple times with individual arguments. For example:</p> <pre translate="no" dir="ltr"> % bazel build --jvmopt="-server -Xms256m" java/com/example/common/foo:all </pre> <p>will use the server VM for launching all Java binaries and set the startup heap size for the VM to 256 MB.</p> <h4 id="javacopt" data-text="--javacopt=javac-option" tabindex="-1"><code translate="no" dir="ltr">--javacopt=<var translate="no">javac-option</var></code></h4> <p>This option allows option arguments to be passed to javac. It can be used with one big argument, or multiple times with individual arguments. For example:</p> <pre translate="no" dir="ltr"> % bazel build --javacopt="-g:source,lines" //myprojects:prog </pre> <p>will rebuild a java_binary with the javac default debug info (instead of the bazel default).</p> <p>The option is passed to javac after the Bazel built-in default options for javac and before the per-rule options. The last specification of any option to javac wins. The default options for javac are:</p> <pre translate="no" dir="ltr"> -source 8 -target 8 -encoding UTF-8 </pre> <aside class="note"><strong>Note:</strong><span> Changing <code translate="no" dir="ltr">--javacopt</code> settings will force a recompilation of all affected classes. Also note that javacopts parameters listed in specific java_library or java_binary build rules will be placed on the javac command line <em>after</em> these options.</span></aside> <h4 id="strict-java-deps" data-text="--strict_java_deps (default|strict|off|warn|error)" tabindex="-1"><code translate="no" dir="ltr">--strict_java_deps (default|strict|off|warn|error)</code></h4> <p>This option controls whether javac checks for missing direct dependencies. Java targets must explicitly declare all directly used targets as dependencies. This flag instructs javac to determine the jars actually used for type checking each java file, and warn/error if they are not the output of a direct dependency of the current target.</p> <ul> <li><code translate="no" dir="ltr">off</code> means checking is disabled.</li> <li><code translate="no" dir="ltr">warn</code> means javac will generate standard java warnings of type <code translate="no" dir="ltr">[strict]</code> for each missing direct dependency.</li> <li><code translate="no" dir="ltr">default</code>, <code translate="no" dir="ltr">strict</code> and <code translate="no" dir="ltr">error</code> all mean javac will generate errors instead of warnings, causing the current target to fail to build if any missing direct dependencies are found. This is also the default behavior when the flag is unspecified.</li> </ul> <h3 id="build-semantics" data-text="Build semantics" tabindex="-1">Build semantics</h3> <p>These options affect the build commands and/or the output file contents.</p> <h4 id="compilation-mode" data-text="--compilation_mode (fastbuild|opt|dbg) (-c)" tabindex="-1"><code translate="no" dir="ltr">--compilation_mode (fastbuild|opt|dbg)</code> (-c)</h4> <p>The <code translate="no" dir="ltr">--compilation_mode</code> option (often shortened to <code translate="no" dir="ltr">-c</code>, especially <code translate="no" dir="ltr">-c opt</code>) takes an argument of <code translate="no" dir="ltr">fastbuild</code>, <code translate="no" dir="ltr">dbg</code> or <code translate="no" dir="ltr">opt</code>, and affects various C/C++ code-generation options, such as the level of optimization and the completeness of debug tables. Bazel uses a different output directory for each different compilation mode, so you can switch between modes without needing to do a full rebuild <em>every</em> time.</p> <ul> <li><code translate="no" dir="ltr">fastbuild</code> means build as fast as possible: generate minimal debugging information (<code translate="no" dir="ltr">-gmlt -Wl,-S</code>), and don't optimize. This is the default. Note: <code translate="no" dir="ltr">-DNDEBUG</code> will <strong>not</strong> be set.</li> <li><code translate="no" dir="ltr">dbg</code> means build with debugging enabled (<code translate="no" dir="ltr">-g</code>), so that you can use gdb (or another debugger).</li> <li><code translate="no" dir="ltr">opt</code> means build with optimization enabled and with <code translate="no" dir="ltr">assert()</code> calls disabled (<code translate="no" dir="ltr">-O2 -DNDEBUG</code>). Debugging information will not be generated in <code translate="no" dir="ltr">opt</code> mode unless you also pass <code translate="no" dir="ltr">--copt -g</code>.</li> </ul> <h4 id="cpu" data-text="--cpu=cpu" tabindex="-1"><code translate="no" dir="ltr">--cpu=<var translate="no">cpu</var></code></h4> <p>This option specifies the target CPU architecture to be used for the compilation of binaries during the build.</p> <aside class="note"><strong>Note:</strong><span> A particular combination of crosstool version, compiler version, and target CPU is allowed only if it has been specified in the currently used CROSSTOOL file.</span></aside> <h4 id="action-env" data-text="--action_env=VAR=VALUE" tabindex="-1"><code translate="no" dir="ltr">--action_env=<var translate="no">VAR=VALUE</var></code></h4> <p>Specifies the set of environment variables available during the execution of all actions. Variables can be either specified by name, in which case the value will be taken from the invocation environment, or by the <code translate="no" dir="ltr">name=value</code> pair which sets the value independent of the invocation environment.</p> <p>This <code translate="no" dir="ltr">--action_env</code> flag can be specified multiple times. If a value is assigned to the same variable across multiple <code translate="no" dir="ltr">--action_env</code> flags, the latest assignment wins.</p> <h4 id="experimental-action-listener" data-text="--experimental_action_listener=label" tabindex="-1"><code translate="no" dir="ltr">--experimental_action_listener=<var translate="no">label</var></code></h4> <aside class="warning"><strong>Warning:</strong><span> Extra actions are deprecated. Use <a href="/extending/aspects">aspects</a> instead.</span></aside> <p>The <code translate="no" dir="ltr">experimental_action_listener</code> option instructs Bazel to use details from the <a href="/reference/be/extra-actions#action_listener"><code translate="no" dir="ltr">action_listener</code></a> rule specified by <var translate="no">label</var> to insert <a href="/reference/be/extra-actions#extra_action"><code translate="no" dir="ltr">extra_actions</code></a> into the build graph.</p> <h4 id="--noexperimental_extra_action_top_level_only" data-text="--[no]experimental_extra_action_top_level_only" tabindex="-1"><code translate="no" dir="ltr">--[no]experimental_extra_action_top_level_only</code></h4> <aside class="warning"><strong>Warning:</strong><span> Extra actions are deprecated. Use <a href="/extending/aspects">aspects</a> instead.</span></aside> <p>If this option is set to true, extra actions specified by the <a href="#experimental-action-listener"> <code translate="no" dir="ltr">--experimental_action_listener</code></a> command line option will only be scheduled for top level targets.</p> <h4 id="experimental-extra-action-filter" data-text="--experimental_extra_action_filter=regex" tabindex="-1"><code translate="no" dir="ltr">--experimental_extra_action_filter=<var translate="no">regex</var></code></h4> <aside class="warning"><strong>Warning:</strong><span> Extra actions are deprecated. Use <a href="/extending/aspects">aspects</a> instead.</span></aside> <p>The <code translate="no" dir="ltr">experimental_extra_action_filter</code> option instructs Bazel to filter the set of targets to schedule <code translate="no" dir="ltr">extra_actions</code> for.</p> <p>This flag is only applicable in combination with the <a href="#experimental-action-listener"><code translate="no" dir="ltr">--experimental_action_listener</code></a> flag.</p> <p>By default all <code translate="no" dir="ltr">extra_actions</code> in the transitive closure of the requested targets-to-build get scheduled for execution. <code translate="no" dir="ltr">--experimental_extra_action_filter</code> will restrict scheduling to <code translate="no" dir="ltr">extra_actions</code> of which the owner's label matches the specified regular expression.</p> <p>The following example will limit scheduling of <code translate="no" dir="ltr">extra_actions</code> to only apply to actions of which the owner's label contains '/bar/':</p> <pre translate="no" dir="ltr">% bazel build --experimental_action_listener=//test:al //foo/... \ --experimental_extra_action_filter=.*/bar/.* </pre> <h4 id="host-cpu" data-text="--host_cpu=cpu" tabindex="-1"><code translate="no" dir="ltr">--host_cpu=<var translate="no">cpu</var></code></h4> <p>This option specifies the name of the CPU architecture that should be used to build host tools.</p> <h4 id="android-platforms" data-text="--android_platforms=platform[,platform]*" tabindex="-1"><code translate="no" dir="ltr">--android_platforms=<var translate="no">platform[,platform]*</var></code></h4> <p>The platforms to build the transitive <code translate="no" dir="ltr">deps</code> of <code translate="no" dir="ltr">android_binary</code> rules (specifically for native dependencies like C++). For example, if a <code translate="no" dir="ltr">cc_library</code> appears in the transitive <code translate="no" dir="ltr">deps</code> of an <code translate="no" dir="ltr">android_binary</code> rule it is be built once for each platform specified with <code translate="no" dir="ltr">--android_platforms</code> for the <code translate="no" dir="ltr">android_binary</code> rule, and included in the final output.</p> <p>There is no default value for this flag: a custom Android platform must be defined and used.</p> <p>One <code translate="no" dir="ltr">.so</code> file is created and packaged in the APK for each platform specified with <code translate="no" dir="ltr">--android_platforms</code>. The <code translate="no" dir="ltr">.so</code> file's name prefixes the name of the <code translate="no" dir="ltr">android_binary</code> rule with "lib". For example, if the name of the <code translate="no" dir="ltr">android_binary</code> is "foo", then the file is <code translate="no" dir="ltr">libfoo.so</code>.</p> <h4 id="per-file-copt" data-text="--per_file_copt=[+-]regex[,[+-]regex]...@option[,option]..." tabindex="-1"><code translate="no" dir="ltr">--per_file_copt=<var translate="no">[+-]regex[,[+-]regex]...@option[,option]...</var></code></h4> <p>When present, any C++ file with a label or an execution path matching one of the inclusion regex expressions and not matching any of the exclusion expressions will be built with the given options. The label matching uses the canonical form of the label (i.e //<code translate="no" dir="ltr">package</code>:<code translate="no" dir="ltr">label_name</code>).</p> <p>The execution path is the relative path to your workspace directory including the base name (including extension) of the C++ file. It also includes any platform dependent prefixes.</p> <aside class="note"><strong>Note:</strong><span> If only one of the label or the execution path matches the options will be used.</span></aside> <p>To match the generated files (such as genrule outputs) Bazel can only use the execution path. In this case the regexp shouldn't start with '//' since that doesn't match any execution paths. Package names can be used like this: <code translate="no" dir="ltr">--per_file_copt=base/.*\.pb\.cc@-g0</code>. This will match every <code translate="no" dir="ltr">.pb.cc</code> file under a directory called <code translate="no" dir="ltr">base</code>.</p> <p>This option can be used multiple times.</p> <p>The option is applied regardless of the compilation mode used. For example, it is possible to compile with <code translate="no" dir="ltr">--compilation_mode=opt</code> and selectively compile some files with stronger optimization turned on, or with optimization disabled.</p> <p><strong>Caveat</strong>: If some files are selectively compiled with debug symbols the symbols might be stripped during linking. This can be prevented by setting <code translate="no" dir="ltr">--strip=never</code>.</p> <p><strong>Syntax</strong>: <code translate="no" dir="ltr">[+-]regex[,[+-]regex]...@option[,option]...</code> Where <code translate="no" dir="ltr">regex</code> stands for a regular expression that can be prefixed with a <code translate="no" dir="ltr">+</code> to identify include patterns and with <code translate="no" dir="ltr">-</code> to identify exclude patterns. <code translate="no" dir="ltr">option</code> stands for an arbitrary option that is passed to the C++ compiler. If an option contains a <code translate="no" dir="ltr">,</code> it has to be quoted like so <code translate="no" dir="ltr">\,</code>. Options can also contain <code translate="no" dir="ltr">@</code>, since only the first <code translate="no" dir="ltr">@</code> is used to separate regular expressions from options.</p> <p><strong>Example</strong>: <code translate="no" dir="ltr">--per_file_copt=//foo:.*\.cc,-//foo:file\.cc@-O0,-fprofile-arcs</code> adds the <code translate="no" dir="ltr">-O0</code> and the <code translate="no" dir="ltr">-fprofile-arcs</code> options to the command line of the C++ compiler for all <code translate="no" dir="ltr">.cc</code> files in <code translate="no" dir="ltr">//foo/</code> except <code translate="no" dir="ltr">file.cc</code>.</p> <h4 id="dynamic-mode" data-text="--dynamic_mode=mode" tabindex="-1"><code translate="no" dir="ltr">--dynamic_mode=<var translate="no">mode</var></code></h4> <p>Determines whether C++ binaries will be linked dynamically, interacting with the <a href="/reference/be/c-cpp#cc_binary.linkstatic">linkstatic attribute</a> on build rules.</p> <p>Modes:</p> <ul> <li><code translate="no" dir="ltr">default</code>: Allows bazel to choose whether to link dynamically. See <a href="/reference/be/c-cpp#cc_binary.linkstatic">linkstatic</a> for more information.</li> <li><code translate="no" dir="ltr">fully</code>: Links all targets dynamically. This will speed up linking time, and reduce the size of the resulting binaries.</li> <li><code translate="no" dir="ltr">off</code>: Links all targets in <a href="/reference/be/c-cpp#cc_binary.linkstatic">mostly static</a> mode. If <code translate="no" dir="ltr">-static</code> is set in linkopts, targets will change to fully static.</li> </ul> <h4 id="fission" data-text="--fission (yes|no|[dbg][,opt][,fastbuild])" tabindex="-1"><code translate="no" dir="ltr">--fission (yes|no|[dbg][,opt][,fastbuild])</code></h4> <p>Enables <a href="https://gcc.gnu.org/wiki/DebugFission" class="external">Fission</a>, which writes C++ debug information to dedicated .dwo files instead of .o files, where it would otherwise go. This substantially reduces the input size to links and can reduce link times.</p> <p>When set to <code translate="no" dir="ltr">[dbg][,opt][,fastbuild]</code> (example: <code translate="no" dir="ltr">--fission=dbg,fastbuild</code>), Fission is enabled only for the specified set of compilation modes. This is useful for bazelrc settings. When set to <code translate="no" dir="ltr">yes</code>, Fission is enabled universally. When set to <code translate="no" dir="ltr">no</code>, Fission is disabled universally. Default is <code class='flag' translate="no" dir="ltr">no</code>.</p> <h4 id="force-ignore-dash-static" data-text="--force_ignore_dash_static" tabindex="-1"><code translate="no" dir="ltr">--force_ignore_dash_static</code></h4> <p>If this flag is set, any <code translate="no" dir="ltr">-static</code> options in linkopts of <code translate="no" dir="ltr">cc_*</code> rules BUILD files are ignored. This is only intended as a workaround for C++ hardening builds.</p> <h4 id="force-pic" data-text="--[no]force_pic" tabindex="-1"><code translate="no" dir="ltr">--[no]force_pic</code></h4> <p>If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). Default is disabled.</p> <aside class="note"><strong>Note:</strong><span> Dynamically linked binaries (for example <code translate="no" dir="ltr">--dynamic_mode fully</code>) generate PIC code regardless of this flag's setting. So this flag is for cases where users want PIC code explicitly generated for static links.</span></aside> <h4 id="flag--android_resource_shrinking" data-text="--android_resource_shrinking" tabindex="-1"><code translate="no" dir="ltr">--android_resource_shrinking</code></h4> <p>Selects whether to perform resource shrinking for android_binary rules. Sets the default for the <a href="/reference/be/android#android_binary.shrink_resources">shrink_resources attribute</a> on android_binary rules; see the documentation for that rule for further details. Defaults to off.</p> <h4 id="custom-malloc" data-text="--custom_malloc=malloc-library-target" tabindex="-1"><code translate="no" dir="ltr">--custom_malloc=<var translate="no">malloc-library-target</var></code></h4> <p>When specified, always use the given malloc implementation, overriding all <code translate="no" dir="ltr">malloc="target"</code> attributes, including in those targets that use the default (by not specifying any <code translate="no" dir="ltr">malloc</code>).</p> <h4 id="crosstool-top" data-text="--crosstool_top=label" tabindex="-1"><code translate="no" dir="ltr">--crosstool_top=<var translate="no">label</var></code></h4> <p>This option specifies the location of the crosstool compiler suite to be used for all C++ compilation during a build. Bazel will look in that location for a CROSSTOOL file and uses that to automatically determine settings for <code translate="no" dir="ltr">--compiler</code>.</p> <h4 id="host-crosstool-top" data-text="--host_crosstool_top=label" tabindex="-1"><code translate="no" dir="ltr">--host_crosstool_top=<var translate="no">label</var></code></h4> <p>If not specified, Bazel uses the value of <code translate="no" dir="ltr">--crosstool_top</code> to compile code in the exec configuration, such as tools run during the build. The main purpose of this flag is to enable cross-compilation.</p> <h4 id="apple-crosstool-top" data-text="--apple_crosstool_top=label" tabindex="-1"><code translate="no" dir="ltr">--apple_crosstool_top=<var translate="no">label</var></code></h4> <p>The crosstool to use for compiling C/C++ rules in the transitive <code translate="no" dir="ltr">deps</code> of objc<em>*, ios</em><em>*, and apple</em>* rules. For those targets, this flag overwrites <code translate="no" dir="ltr">--crosstool_top</code>.</p> <h4 id="compiler" data-text="--compiler=version" tabindex="-1"><code translate="no" dir="ltr">--compiler=<var translate="no">version</var></code></h4> <p>This option specifies the C/C++ compiler version (such as <code translate="no" dir="ltr">gcc-4.1.0</code>) to be used for the compilation of binaries during the build. If you want to build with a custom crosstool, you should use a CROSSTOOL file instead of specifying this flag.</p> <aside class="note"><strong>Note:</strong><span> Only certain combinations of crosstool version, compiler version, and target CPU are allowed.</span></aside> <h4 id="android-sdk" data-text="--android_sdk=label" tabindex="-1"><code translate="no" dir="ltr">--android_sdk=<var translate="no">label</var></code></h4> <p>Deprecated. This shouldn't be directly specified.</p> <p>This option specifies the Android SDK/platform toolchain and Android runtime library that will be used to build any Android-related rule.</p> <p>The Android SDK will be automatically selected if an <code translate="no" dir="ltr">android_sdk_repository</code> rule is defined in the WORKSPACE file.</p> <h4 id="java-toolchain" data-text="--java_toolchain=label" tabindex="-1"><code translate="no" dir="ltr">--java_toolchain=<var translate="no">label</var></code></h4> <p>No-op. Kept only for backwards compatibility.</p> <h4 id="host-java-toolchain" data-text="--host_java_toolchain=label" tabindex="-1"><code translate="no" dir="ltr">--host_java_toolchain=<var translate="no">label</var></code></h4> <p>No-op. Kept only for backwards compatibility.</p> <h4 id="javabase" data-text="--javabase=(label)" tabindex="-1"><code translate="no" dir="ltr">--javabase=(<var translate="no">label</var>)</code></h4> <p>No-op. Kept only for backwards compatibility.</p> <h4 id="host-javabase" data-text="--host_javabase=label" tabindex="-1"><code translate="no" dir="ltr">--host_javabase=<var translate="no">label</var></code></h4> <p>No-op. Kept only for backwards compatibility.</p> <h3 id="execution-strategy" data-text="Execution strategy" tabindex="-1">Execution strategy</h3> <p>These options affect how Bazel will execute the build. They should not have any significant effect on the output files generated by the build. Typically their main effect is on the speed of the build.</p> <h4 id="spawn-strategy" data-text="--spawn_strategy=strategy" tabindex="-1"><code translate="no" dir="ltr">--spawn_strategy=<var translate="no">strategy</var></code></h4> <p>This option controls where and how commands are executed.</p> <ul> <li><code translate="no" dir="ltr">standalone</code> causes commands to be executed as local subprocesses. This value is deprecated. Please use <code translate="no" dir="ltr">local</code> instead.</li> <li><code translate="no" dir="ltr">sandboxed</code> causes commands to be executed inside a sandbox on the local machine. This requires that all input files, data dependencies and tools are listed as direct dependencies in the <code translate="no" dir="ltr">srcs</code>, <code translate="no" dir="ltr">data</code> and <code translate="no" dir="ltr">tools</code> attributes. Bazel enables local sandboxing by default, on systems that support sandboxed execution.</li> <li><code translate="no" dir="ltr">local</code> causes commands to be executed as local subprocesses.</li> <li><code translate="no" dir="ltr">worker</code> causes commands to be executed using a persistent worker, if available.</li> <li><code translate="no" dir="ltr">docker</code> causes commands to be executed inside a docker sandbox on the local machine. This requires that docker is installed.</li> <li><code translate="no" dir="ltr">remote</code> causes commands to be executed remotely; this is only available if a remote executor has been configured separately.</li> </ul> <h4 id="strategy" data-text="--strategy mnemonic=strategy" tabindex="-1"><code translate="no" dir="ltr">--strategy <var translate="no">mnemonic</var>=<var translate="no">strategy</var></code></h4> <p>This option controls where and how commands are executed, overriding the <a href="#spawn-strategy">--spawn_strategy</a> (and <a href="#genrule-strategy">--genrule_strategy</a> with mnemonic Genrule) on a per-mnemonic basis. See <a href="#spawn-strategy">--spawn_strategy</a> for the supported strategies and their effects.</p> <h4 id="strategy-regexp" data-text="--strategy_regexp=<filter,filter,...>=<strategy>" tabindex="-1"><code translate="no" dir="ltr">--strategy_regexp=<var translate="no"><filter,filter,...>=<strategy></var></code></h4> <p>This option specifies which strategy should be used to execute commands that have descriptions matching a certain <code translate="no" dir="ltr">regex_filter</code>. See <a href="#per-file-copt">--per_file_copt</a> for details on regex_filter matching. See <a href="#spawn-strategy">--spawn_strategy</a> for the supported strategies and their effects.</p> <p>The last <code translate="no" dir="ltr">regex_filter</code> that matches the description is used. This option overrides other flags for specifying strategy.</p> <ul> <li>Example: <code translate="no" dir="ltr">--strategy_regexp=//foo.*\\.cc,-//foo/bar=local</code> means to run actions using <code translate="no" dir="ltr">local</code> strategy if their descriptions match //foo.*.cc but not //foo/bar.</li> <li>Example: <code translate="no" dir="ltr">--strategy_regexp='Compiling.*/bar=local' --strategy_regexp=Compiling=sandboxed</code> runs 'Compiling //foo/bar/baz' with the <code translate="no" dir="ltr">sandboxed</code> strategy, but reversing the order runs it with <code translate="no" dir="ltr">local</code>.</li> <li>Example: <code translate="no" dir="ltr">--strategy_regexp='Compiling.*/bar=local,sandboxed'</code> runs 'Compiling //foo/bar/baz' with the <code translate="no" dir="ltr">local</code> strategy and falls back to <code translate="no" dir="ltr">sandboxed</code> if it fails.</li> </ul> <h4 id="genrule-strategy" data-text="--genrule_strategy=strategy" tabindex="-1"><code translate="no" dir="ltr">--genrule_strategy=<var translate="no">strategy</var></code></h4> <p>This is a deprecated short-hand for <code translate="no" dir="ltr">--strategy=Genrule=<var translate="no">strategy</var></code>.</p> <h4 id="jobs" data-text="--jobs=n (-j)" tabindex="-1"><code translate="no" dir="ltr">--jobs=<var translate="no">n</var></code> (-j)</h4> <p>This option, which takes an integer argument, specifies a limit on the number of jobs that should be executed concurrently during the execution phase of the build.</p> <aside class="note"><strong>Note:</strong><span> The number of concurrent jobs that Bazel will run is determined not only by the <code translate="no" dir="ltr">--jobs</code> setting, but also by Bazel's scheduler, which tries to avoid running concurrent jobs that will use up more resources (RAM or CPU) than are available, based on some (very crude) estimates of the resource consumption of each job. The behavior of the scheduler can be controlled by the <code translate="no" dir="ltr">--local_ram_resources</code> option.</span></aside> <h4 id="--progress_report_intervaln" data-text="--progress_report_interval=n" tabindex="-1"><code translate="no" dir="ltr">--progress_report_interval=<var translate="no">n</var></code></h4> <p>Bazel periodically prints a progress report on jobs that are not finished yet (such as long running tests). This option sets the reporting frequency, progress will be printed every <code translate="no" dir="ltr">n</code> seconds.</p> <p>The default is 0, that means an incremental algorithm: the first report will be printed after 10 seconds, then 30 seconds and after that progress is reported once every minute.</p> <p>When bazel is using cursor control, as specified by <a href="#curses"><code translate="no" dir="ltr">--curses</code></a>, progress is reported every second.</p> <h4 id="local-resources" data-text="--local_{ram,cpu}_resources resources or resource expression" tabindex="-1"><code translate="no" dir="ltr">--local_{ram,cpu}_resources <var translate="no">resources or resource expression</var></code></h4> <p>These options specify the amount of local resources (RAM in MB and number of CPU logical cores) that Bazel can take into consideration when scheduling build and test activities to run locally. They take an integer, or a keyword (HOST_RAM or HOST_CPUS) optionally followed by <code translate="no" dir="ltr">[-|*</code>float<code translate="no" dir="ltr">]</code> (for example, <code translate="no" dir="ltr">--local_cpu_resources=2</code>, <code translate="no" dir="ltr">--local_ram_resources=HOST_RAM*.5</code>, <code translate="no" dir="ltr">--local_cpu_resources=HOST_CPUS-1</code>). The flags are independent; one or both may be set. By default, Bazel estimates the amount of RAM and number of CPU cores directly from the local system's configuration.</p> <h4 id="build-runfile-links" data-text="--[no]build_runfile_links" tabindex="-1"><code translate="no" dir="ltr">--[no]build_runfile_links</code></h4> <p>This option, which is enabled by default, specifies whether the runfiles symlinks for tests and binaries should be built in the output directory. Using <code translate="no" dir="ltr">--nobuild_runfile_links</code> can be useful to validate if all targets compile without incurring the overhead for building the runfiles trees.</p> <p>When tests (or applications) are executed, their run-time data dependencies are gathered together in one place. Within Bazel's output tree, this "runfiles" tree is typically rooted as a sibling of the corresponding binary or test. During test execution, runfiles may be accessed using paths of the form <code translate="no" dir="ltr">$TEST_SRCDIR/<var translate="no">canonical_repo_name</var>/<var translate="no">packagename</var>/<var translate="no">filename</var></code>. The runfiles tree ensures that tests have access to all the files upon which they have a declared dependence, and nothing more. By default, the runfiles tree is implemented by constructing a set of symbolic links to the required files. As the set of links grows, so does the cost of this operation, and for some large builds it can contribute significantly to overall build time, particularly because each individual test (or application) requires its own runfiles tree.</p> <h4 id="build-runfile-manifests" data-text="--[no]build_runfile_manifests" tabindex="-1"><code translate="no" dir="ltr">--[no]build_runfile_manifests</code></h4> <p>This option, which is enabled by default, specifies whether runfiles manifests should be written to the output tree. Disabling it implies <code translate="no" dir="ltr">--nobuild_runfile_links</code>.</p> <p>It can be disabled when executing tests remotely, as runfiles trees will be created remotely from in-memory manifests.</p> <h4 id="discard-analysis-cache" data-text="--[no]discard_analysis_cache" tabindex="-1"><code translate="no" dir="ltr">--[no]discard_analysis_cache</code></h4> <p>When this option is enabled, Bazel will discard the analysis cache right before execution starts, thus freeing up additional memory (around 10%) for the <a href="/run/build#execution">execution phase</a>. The drawback is that further incremental builds will be slower. See also <a href="/configure/memory">memory-saving mode</a>.</p> <h4 id="keep-going" data-text="--[no]keep_going (-k)" tabindex="-1"><code translate="no" dir="ltr">--[no]keep_going</code> (-k)</h4> <p>As in GNU Make, the execution phase of a build stops when the first error is encountered. Sometimes it is useful to try to build as much as possible even in the face of errors. This option enables that behavior, and when it is specified, the build will attempt to build every target whose prerequisites were successfully built, but will ignore errors.</p> <p>While this option is usually associated with the execution phase of a build, it also affects the analysis phase: if several targets are specified in a build command, but only some of them can be successfully analyzed, the build will stop with an error unless <code translate="no" dir="ltr">--keep_going</code> is specified, in which case the build will proceed to the execution phase, but only for the targets that were successfully analyzed.</p> <h4 id="use-ijars" data-text="--[no]use_ijars" tabindex="-1"><code translate="no" dir="ltr">--[no]use_ijars</code></h4> <p>This option changes the way <code translate="no" dir="ltr">java_library</code> targets are compiled by Bazel. Instead of using the output of a <code translate="no" dir="ltr">java_library</code> for compiling dependent <code translate="no" dir="ltr">java_library</code> targets, Bazel will create interface jars that contain only the signatures of non-private members (public, protected, and default (package) access methods and fields) and use the interface jars to compile the dependent targets. This makes it possible to avoid recompilation when changes are only made to method bodies or private members of a class.</p> <aside class="note"><strong>Note:</strong><span> Using <code translate="no" dir="ltr">--use_ijars</code> might give you a different error message when you are accidentally referring to a non visible member of another class: Instead of getting an error that the member is not visible you will get an error that the member does not exist. Changing the <code translate="no" dir="ltr">--use_ijars</code> setting will force a recompilation of all affected classes.</span></aside> <h4 id="interface-shared-objects" data-text="--[no]interface_shared_objects" tabindex="-1"><code translate="no" dir="ltr">--[no]interface_shared_objects</code></h4> <p>This option enables <em>interface shared objects</em>, which makes binaries and other shared libraries depend on the <em>interface</em> of a shared object, rather than its implementation. When only the implementation changes, Bazel can avoid rebuilding targets that depend on the changed shared library unnecessarily.</p> <h3 id="output-selection" data-text="Output selection" tabindex="-1">Output selection</h3> <p>These options determine what to build or test.</p> <h4 id="build" data-text="--[no]build" tabindex="-1"><code translate="no" dir="ltr">--[no]build</code></h4> <p>This option causes the execution phase of the build to occur; it is on by default. When it is switched off, the execution phase is skipped, and only the first two phases, loading and analysis, occur.</p> <p>This option can be useful for validating BUILD files and detecting errors in the inputs, without actually building anything.</p> <h4 id="build-tests-only" data-text="--[no]build_tests_only" tabindex="-1"><code translate="no" dir="ltr">--[no]build_tests_only</code></h4> <p>If specified, Bazel will build only what is necessary to run the <code translate="no" dir="ltr">*_test</code> and <code translate="no" dir="ltr">test_suite</code> rules that were not filtered due to their <a href="#test-size-filters">size</a>, <a href="#test-timeout-filters">timeout</a>, <a href="#test-tag-filters">tag</a>, or <a href="#test-lang-filters">language</a>. If specified, Bazel will ignore other targets specified on the command line. By default, this option is disabled and Bazel will build everything requested, including <code translate="no" dir="ltr">*_test</code> and <code translate="no" dir="ltr">test_suite</code> rules that are filtered out from testing. This is useful because running <code translate="no" dir="ltr">bazel test --build_tests_only foo/...</code> may not detect all build breakages in the <code translate="no" dir="ltr">foo</code> tree.</p> <h4 id="check-up-to-date" data-text="--[no]check_up_to_date" tabindex="-1"><code translate="no" dir="ltr">--[no]check_up_to_date</code></h4> <p>This option causes Bazel not to perform a build, but merely check whether all specified targets are up-to-date. If so, the build completes successfully, as usual. However, if any files are out of date, instead of being built, an error is reported and the build fails. This option may be useful to determine whether a build has been performed more recently than a source edit (for example, for pre-submit checks) without incurring the cost of a build.</p> <p>See also <a href="#check-tests-up-to-date"><code translate="no" dir="ltr">--check_tests_up_to_date</code></a>.</p> <h4 id="compile-one-dependency" data-text="--[no]compile_one_dependency" tabindex="-1"><code translate="no" dir="ltr">--[no]compile_one_dependency</code></h4> <p>Compile a single dependency of the argument files. This is useful for syntax checking source files in IDEs, for example, by rebuilding a single target that depends on the source file to detect errors as early as possible in the edit/build/test cycle. This argument affects the way all non-flag arguments are interpreted: each argument must be a file target label or a plain filename relative to the current working directory, and one rule that depends on each source filename is built. For C++ and Java sources, rules in the same language space are preferentially chosen. For multiple rules with the same preference, the one that appears first in the BUILD file is chosen. An explicitly named target pattern which does not reference a source file results in an error.</p> <h4 id="save-temps" data-text="--save_temps" tabindex="-1"><code translate="no" dir="ltr">--save_temps</code></h4> <p>The <code translate="no" dir="ltr">--save_temps</code> option causes temporary outputs from the compiler to be saved. These include .s files (assembler code), .i (preprocessed C) and .ii (preprocessed C++) files. These outputs are often useful for debugging. Temps will only be generated for the set of targets specified on the command line.</p> <aside class="note"><strong>Note:</strong><span> The implementation of <code translate="no" dir="ltr">--save_temps</code> does not use the compiler's <code translate="no" dir="ltr">-save-temps</code> flag. Instead, there are two passes, one with <code translate="no" dir="ltr">-S</code> and one with <code translate="no" dir="ltr">-E</code>. A consequence of this is that if your build fails, Bazel may not yet have produced the ".i" or ".ii" and ".s" files. If you're trying to use <code translate="no" dir="ltr">--save_temps</code> to debug a failed compilation, you may need to also use <code translate="no" dir="ltr">--keep_going</code> so that Bazel will still try to produce the preprocessed files after the compilation fails.</span></aside> <p>The <code translate="no" dir="ltr">--save_temps</code> flag currently works only for cc_* rules.</p> <p>To ensure that Bazel prints the location of the additional output files, check that your <a href="#show-result"><code translate="no" dir="ltr">--show_result <var translate="no">n</var></code></a> setting is high enough.</p> <h4 id="build-tag-filters" data-text="--build_tag_filters=tag[,tag]*" tabindex="-1"><code translate="no" dir="ltr">--build_tag_filters=<var translate="no">tag[,tag]*</var></code></h4> <p>If specified, Bazel will build only targets that have at least one required tag (if any of them are specified) and does not have any excluded tags. Build tag filter is specified as comma delimited list of tag keywords, optionally preceded with '-' sign used to denote excluded tags. Required tags may also have a preceding '+' sign.</p> <p>When running tests, Bazel ignores <code translate="no" dir="ltr">--build_tag_filters</code> for test targets, which are built and run even if they do not match this filter. To avoid building them, filter test targets using <code translate="no" dir="ltr">--test_tag_filters</code> or by explicitly excluding them.</p> <h4 id="test-size-filters" data-text="--test_size_filters=size[,size]*" tabindex="-1"><code translate="no" dir="ltr">--test_size_filters=<var translate="no">size[,size]*</var></code></h4> <p>If specified, Bazel will test (or build if <code translate="no" dir="ltr">--build_tests_only</code> is also specified) only test targets with the given size. Test size filter is specified as comma delimited list of allowed test size values (small, medium, large or enormous), optionally preceded with '-' sign used to denote excluded test sizes. For example,</p> <pre translate="no" dir="ltr"> % bazel test --test_size_filters=small,medium //foo:all </pre> <p>and</p> <pre translate="no" dir="ltr"> % bazel test --test_size_filters=-large,-enormous //foo:all </pre> <p>will test only small and medium tests inside //foo.</p> <p>By default, test size filtering is not applied.</p> <h4 id="test-timeout-filters" data-text="--test_timeout_filters=timeout[,timeout]*" tabindex="-1"><code translate="no" dir="ltr">--test_timeout_filters=<var translate="no">timeout[,timeout]*</var></code></h4> <p>If specified, Bazel will test (or build if <code translate="no" dir="ltr">--build_tests_only</code> is also specified) only test targets with the given timeout. Test timeout filter is specified as comma delimited list of allowed test timeout values (short, moderate, long or eternal), optionally preceded with '-' sign used to denote excluded test timeouts. See <a href="#test-size-filters">--test_size_filters</a> for example syntax.</p> <p>By default, test timeout filtering is not applied.</p> <h4 id="test-tag-filters" data-text="--test_tag_filters=tag[,tag]*" tabindex="-1"><code translate="no" dir="ltr">--test_tag_filters=<var translate="no">tag[,tag]*</var></code></h4> <p>If specified, Bazel will test (or build if <code translate="no" dir="ltr">--build_tests_only</code> is also specified) only test targets that have at least one required tag (if any of them are specified) and does not have any excluded tags. Test tag filter is specified as comma delimited list of tag keywords, optionally preceded with '-' sign used to denote excluded tags. Required tags may also have a preceding '+' sign.</p> <p>For example,</p> <pre translate="no" dir="ltr"> % bazel test --test_tag_filters=performance,stress,-flaky //myproject:all </pre> <p>will test targets that are tagged with either <code translate="no" dir="ltr">performance</code> or <code translate="no" dir="ltr">stress</code> tag but are <strong>not</strong> tagged with the <code translate="no" dir="ltr">flaky</code> tag.</p> <p>By default, test tag filtering is not applied. Note that you can also filter on test's <code translate="no" dir="ltr">size</code> and <code translate="no" dir="ltr">local</code> tags in this manner.</p> <h4 id="test-lang-filters" data-text="--test_lang_filters=string[,string]*" tabindex="-1"><code translate="no" dir="ltr">--test_lang_filters=<var translate="no">string[,string]*</var></code></h4> <p>Specifies a comma-separated list of strings referring to names of test rule classes. To refer to the rule class <code translate="no" dir="ltr">foo_test</code>, use the string "foo". Bazel will test (or build if <code translate="no" dir="ltr">--build_tests_only</code> is also specified) only targets of the referenced rule classes. To instead exclude those targets, use the string "-foo". For example,</p> <p></p> <pre translate="no" dir="ltr"> % bazel test --test_lang_filters=foo,bar //baz/... </pre> <p> will test only targets that are instances of <code translate="no" dir="ltr">foo_test</code> or <code translate="no" dir="ltr">bar_test</code> in <code translate="no" dir="ltr">//baz/...</code>, while </p> <pre translate="no" dir="ltr"> % bazel test --test_lang_filters=-foo,-bar //baz/... </pre> <p> will test all the targets in <code translate="no" dir="ltr">//baz/...</code> except for the <code translate="no" dir="ltr">foo_test</code> and <code translate="no" dir="ltr">bar_test</code> instances. </p></p> <aside class="tip"><strong>Tip:</strong><span> You can use <code translate="no" dir="ltr">bazel query --output=label_kind "//p:t"</code> to learn the rule class name of the target <code translate="no" dir="ltr">//p:t</code>. And you can look at the pair of instantiation stacks in the output of <code translate="no" dir="ltr">bazel query --output=build "//p:t"</code> to learn why that target is an instance of that rule class.</span></aside><aside class="warning"><strong>Warning:</strong><span> The option name "--test_lang_filter" is vestigal and is therefore unfortunately misleading; don't make assumptions about the semantics based on the name.</span></aside> <h4 id="test-filter" data-text="--test_filter=filter-expression" tabindex="-1"><code translate="no" dir="ltr">--test_filter=<var translate="no">filter-expression</var></code></h4> <p>Specifies a filter that the test runner may use to pick a subset of tests for running. All targets specified in the invocation are built, but depending on the expression only some of them may be executed; in some cases, only certain test methods are run.</p> <p>The particular interpretation of <var translate="no">filter-expression</var> is up to the test framework responsible for running the test. It may be a glob, substring, or regexp. <code translate="no" dir="ltr">--test_filter</code> is a convenience over passing different <code translate="no" dir="ltr">--test_arg</code> filter arguments, but not all frameworks support it.</p> <h3 id="verbosity" data-text="Verbosity" tabindex="-1">Verbosity</h3> <p>These options control the verbosity of Bazel's output, either to the terminal, or to additional log files.</p> <h4 id="explain" data-text="--explain=logfile" tabindex="-1"><code translate="no" dir="ltr">--explain=<var translate="no">logfile</var></code></h4> <p>This option, which requires a filename argument, causes the dependency checker in <code translate="no" dir="ltr">bazel build</code>'s execution phase to explain, for each build step, either why it is being executed, or that it is up-to-date. The explanation is written to <em>logfile</em>.</p> <p>If you are encountering unexpected rebuilds, this option can help to understand the reason. Add it to your <code translate="no" dir="ltr">.bazelrc</code> so that logging occurs for all subsequent builds, and then inspect the log when you see an execution step executed unexpectedly. This option may carry a small performance penalty, so you might want to remove it when it is no longer needed.</p> <h4 id="verbose-explanations" data-text="--verbose_explanations" tabindex="-1"><code translate="no" dir="ltr">--verbose_explanations</code></h4> <p>This option increases the verbosity of the explanations generated when the <a href="#explain">--explain</a> option is enabled.</p> <p>In particular, if verbose explanations are enabled, and an output file is rebuilt because the command used to build it has changed, then the output in the explanation file will include the full details of the new command (at least for most commands).</p> <p>Using this option may significantly increase the length of the generated explanation file and the performance penalty of using <code translate="no" dir="ltr">--explain</code>.</p> <p>If <code translate="no" dir="ltr">--explain</code> is not enabled, then <code translate="no" dir="ltr">--verbose_explanations</code> has no effect.</p> <h4 id="profile" data-text="--profile=file" tabindex="-1"><code translate="no" dir="ltr">--profile=<var translate="no">file</var></code></h4> <p>This option, which takes a filename argument, causes Bazel to write profiling data into a file. The data then can be analyzed or parsed using the <code translate="no" dir="ltr">bazel analyze-profile</code> command. The Build profile can be useful in understanding where Bazel's <code translate="no" dir="ltr">build</code> command is spending its time.</p> <h4 id="show-loading-progress" data-text="--[no]show_loading_progress" tabindex="-1"><code translate="no" dir="ltr">--[no]show_loading_progress</code></h4> <p>This option causes Bazel to output package-loading progress messages. If it is disabled, the messages won't be shown.</p> <h4 id="show-progress" data-text="--[no]show_progress" tabindex="-1"><code translate="no" dir="ltr">--[no]show_progress</code></h4> <p>This option causes progress messages to be displayed; it is on by default. When disabled, progress messages are suppressed.</p> <h4 id="show-progress-rate" data-text="--show_progress_rate_limit=n" tabindex="-1"><code translate="no" dir="ltr">--show_progress_rate_limit=<var translate="no">n</var></code></h4> <p>This option causes bazel to display at most one progress message per <code translate="no" dir="ltr">n</code> seconds, where <var translate="no">n</var> is a real number. The default value for this option is 0.02, meaning bazel will limit the progress messages to one per every 0.02 seconds.</p> <h4 id="show-result" data-text="--show_result=n" tabindex="-1"><code translate="no" dir="ltr">--show_result=<var translate="no">n</var></code></h4> <p>This option controls the printing of result information at the end of a <code translate="no" dir="ltr">bazel build</code> command. By default, if a single build target was specified, Bazel prints a message stating whether or not the target was successfully brought up-to-date, and if so, the list of output files that the target created. If multiple targets were specified, result information is not displayed.</p> <p>While the result information may be useful for builds of a single target or a few targets, for large builds (such as an entire top-level project tree), this information can be overwhelming and distracting; this option allows it to be controlled. <code translate="no" dir="ltr">--show_result</code> takes an integer argument, which is the maximum number of targets for which full result information should be printed. By default, the value is 1. Above this threshold, no result information is shown for individual targets. Thus zero causes the result information to be suppressed always, and a very large value causes the result to be printed always.</p> <p>Users may wish to choose a value in-between if they regularly alternate between building a small group of targets (for example, during the compile-edit-test cycle) and a large group of targets (for example, when establishing a new workspace or running regression tests). In the former case, the result information is very useful whereas in the latter case it is less so. As with all options, this can be specified implicitly via the <a href="/run/bazelrc"><code translate="no" dir="ltr">.bazelrc</code></a> file.</p> <p>The files are printed so as to make it easy to copy and paste the filename to the shell, to run built executables. The "up-to-date" or "failed" messages for each target can be easily parsed by scripts which drive a build.</p> <h4 id="sandbox-debug" data-text="--sandbox_debug" tabindex="-1"><code translate="no" dir="ltr">--sandbox_debug</code></h4> <p>This option causes Bazel to print extra debugging information when using sandboxing for action execution. This option also preserves sandbox directories, so that the files visible to actions during execution can be examined.</p> <h4 id="subcommands" data-text="--subcommands (-s)" tabindex="-1"><code translate="no" dir="ltr">--subcommands</code> (<code translate="no" dir="ltr">-s</code>)</h4> <p>This option causes Bazel's execution phase to print the full command line for each command prior to executing it.</p> <pre translate="no" dir="ltr"> >>>>> # //examples/cpp:hello-world [action 'Linking examples/cpp/hello-world'] (cd /home/johndoe/.cache/bazel/_bazel_johndoe/4c084335afceb392cfbe7c31afee3a9f/bazel && \ exec env - \ /usr/bin/gcc -o bazel-out/local-fastbuild/bin/examples/cpp/hello-world -B/usr/bin/ -Wl,-z,relro,-z,now -no-canonical-prefixes -pass-exit-codes -Wl,-S -Wl,@bazel-out/local_linux-fastbuild/bin/examples/cpp/hello-world-2.params) </pre> <p>Where possible, commands are printed in a Bourne shell compatible syntax, so that they can be easily copied and pasted to a shell command prompt. (The surrounding parentheses are provided to protect your shell from the <code translate="no" dir="ltr">cd</code> and <code translate="no" dir="ltr">exec</code> calls; be sure to copy them!) However some commands are implemented internally within Bazel, such as creating symlink trees. For these there's no command line to display.</p> <p><code translate="no" dir="ltr">--subcommands=pretty_print</code> may be passed to print the arguments of the command as a list rather than as a single line. This may help make long command lines more readable.</p> <p>See also <a href="#verbose-failures">--verbose_failures</a>, below.</p> <p>For logging subcommands to a file in a tool-friendly format, see <a href="/reference/command-line-reference#flag--execution_log_json_file">--execution_log_json_file</a> and <a href="/reference/command-line-reference#flag--execution_log_binary_file">--execution_log_binary_file</a>.</p> <h4 id="verbose-failures" data-text="--verbose_failures" tabindex="-1"><code translate="no" dir="ltr">--verbose_failures</code></h4> <p>This option causes Bazel's execution phase to print the full command line for commands that failed. This can be invaluable for debugging a failing build.</p> <p>Failing commands are printed in a Bourne shell compatible syntax, suitable for copying and pasting to a shell prompt.</p> <h3 id="workspace-status" data-text="Workspace status" tabindex="-1">Workspace status</h3> <p>Use these options to "stamp" Bazel-built binaries: to embed additional information into the binaries, such as the source control revision or other workspace-related information. You can use this mechanism with rules that support the <code translate="no" dir="ltr">stamp</code> attribute, such as <code translate="no" dir="ltr">genrule</code>, <code translate="no" dir="ltr">cc_binary</code>, and more.</p> <h4 id="workspace-status-command" data-text="--workspace_status_command=program" tabindex="-1"><code translate="no" dir="ltr">--workspace_status_command=<var translate="no">program</var></code></h4> <p>This flag lets you specify a binary that Bazel runs before each build. The program can report information about the status of the workspace, such as the current source control revision.</p> <p>The flag's value must be a path to a native program. On Linux/macOS this may be any executable. On Windows this must be a native binary, typically an ".exe", ".bat", or a ".cmd" file.</p> <p>The program should print zero or more key/value pairs to standard output, one entry on each line, then exit with zero (otherwise the build fails). The key names can be anything but they may only use upper case letters and underscores. The first space after the key name separates it from the value. The value is the rest of the line (including additional whitespaces). Neither the key nor the value may span multiple lines. Keys must not be duplicated.</p> <p>Bazel partitions the keys into two buckets: "stable" and "volatile". (The names "stable" and "volatile" are a bit counter-intuitive, so don't think much about them.)</p> <p>Bazel then writes the key-value pairs into two files:</p> <ul> <li><code translate="no" dir="ltr">bazel-out/stable-status.txt</code> contains all keys and values where the key's name starts with <code translate="no" dir="ltr">STABLE_</code></li> <li><code translate="no" dir="ltr">bazel-out/volatile-status.txt</code> contains the rest of the keys and their values</li> </ul> <p>The contract is:</p> <ul> <li><p>"stable" keys' values should change rarely, if possible. If the contents of <code translate="no" dir="ltr">bazel-out/stable-status.txt</code> change, Bazel invalidates the actions that depend on them. In other words, if a stable key's value changes, Bazel will rerun stamped actions. Therefore the stable status should not contain things like timestamps, because they change all the time, and would make Bazel rerun stamped actions with each build.</p> <p>Bazel always outputs the following stable keys:</p> <ul> <li><code translate="no" dir="ltr">BUILD_EMBED_LABEL</code>: value of <code translate="no" dir="ltr">--embed_label</code></li> <li><code translate="no" dir="ltr">BUILD_HOST</code>: the name of the host machine that Bazel is running on</li> <li><code translate="no" dir="ltr">BUILD_USER</code>: the name of the user that Bazel is running as</li> </ul></li> <li><p>"volatile" keys' values may change often. Bazel expects them to change all the time, like timestamps do, and duly updates the <code translate="no" dir="ltr">bazel-out/volatile-status.txt</code> file. In order to avoid rerunning stamped actions all the time though, <strong>Bazel pretends that the volatile file never changes</strong>. In other words, if the volatile status file is the only file whose contents has changed, Bazel will not invalidate actions that depend on it. If other inputs of the actions have changed, then Bazel reruns that action, and the action will see the updated volatile status, but just the volatile status changing alone will not invalidate the action.</p> <p>Bazel always outputs the following volatile keys:</p> <ul> <li><code translate="no" dir="ltr">BUILD_TIMESTAMP</code>: time of the build in seconds since the Unix Epoch (the value of <code translate="no" dir="ltr">System.currentTimeMillis()</code> divided by a thousand)</li> <li><code translate="no" dir="ltr">FORMATTED_DATE</code>: time of the build Formatted as <code translate="no" dir="ltr">yyyy MMM d HH mm ss EEE</code>(for example 2023 Jun 2 01 44 29 Fri) in UTC.</li> </ul></li> </ul> <p>On Linux/macOS you can pass <code translate="no" dir="ltr">--workspace_status_command=/bin/true</code> to disable retrieving workspace status, because <code translate="no" dir="ltr">true</code> does nothing, successfully (exits with zero) and prints no output. On Windows you can pass the path of MSYS's <code translate="no" dir="ltr">true.exe</code> for the same effect.</p> <p>If the workspace status command fails (exits non-zero) for any reason, the build will fail.</p> <p>Example program on Linux using Git:</p> <pre translate="no" dir="ltr"> #!/bin/bash echo "CURRENT_TIME $(date +%s)" echo "RANDOM_HASH $(cat /proc/sys/kernel/random/uuid)" echo "STABLE_GIT_COMMIT $(git rev-parse HEAD)" echo "STABLE_USER_NAME $USER" </pre> <p>Pass this program's path with <code translate="no" dir="ltr">--workspace_status_command</code>, and the stable status file will include the STABLE lines and the volatile status file will include the rest of the lines.</p> <h4 id="stamp" data-text="--[no]stamp" tabindex="-1"><code translate="no" dir="ltr">--[no]stamp</code></h4> <p>This option, in conjunction with the <code translate="no" dir="ltr">stamp</code> rule attribute, controls whether to embed build information in binaries.</p> <p>Stamping can be enabled or disabled explicitly on a per-rule basis using the <code translate="no" dir="ltr">stamp</code> attribute. Please refer to the Build Encyclopedia for details. When a rule sets <code translate="no" dir="ltr">stamp = -1</code> (the default for <code translate="no" dir="ltr">*_binary</code> rules), this option determines whether stamping is enabled.</p> <p>Bazel never stamps binaries that are built for the exec configuration, regardless of this option or the <code translate="no" dir="ltr">stamp</code> attribute. For rules that set <code translate="no" dir="ltr">stamp = 0</code> (the default for <code translate="no" dir="ltr">*_test</code> rules), stamping is disabled regardless of <code translate="no" dir="ltr">--[no]stamp</code>. Specifying <code translate="no" dir="ltr">--stamp</code> does not force targets to be rebuilt if their dependencies have not changed.</p> <p>Setting <code translate="no" dir="ltr">--nostamp</code> is generally desireable for build performance, as it reduces input volatility and maximizes build caching.</p> <h3 id="platform" data-text="Platform" tabindex="-1">Platform</h3> <p>Use these options to control the host and target platforms that configure how builds work, and to control what execution platforms and toolchains are available to Bazel rules.</p> <p>Please see background information on <a href="/extending/platforms">Platforms</a> and <a href="/extending/toolchains">Toolchains</a>.</p> <h4 id="platforms" data-text="--platforms=labels" tabindex="-1"><code translate="no" dir="ltr">--platforms=<var translate="no">labels</var></code></h4> <p>The labels of the platform rules describing the target platforms for the current command.</p> <h4 id="host-platform" data-text="--host_platform=label" tabindex="-1"><code translate="no" dir="ltr">--host_platform=<var translate="no">label</var></code></h4> <p>The label of a platform rule that describes the host system.</p> <h4 id="extra-execution-platforms" data-text="--extra_execution_platforms=labels" tabindex="-1"><code translate="no" dir="ltr">--extra_execution_platforms=<var translate="no">labels</var></code></h4> <p>The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in MODULE.bazel files by <a href="/rules/lib/globals/module#register_execution_platforms">register_execution_platforms()</a>. This option accepts a comma-separated list of platforms in order of priority. If the flag is passed multiple times, the most recent overrides.</p> <h4 id="extra-toolchains" data-text="--extra_toolchains=labels" tabindex="-1"><code translate="no" dir="ltr">--extra_toolchains=<var translate="no">labels</var></code></h4> <p>The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in MODULE.bazel files by <a href="/rules/lib/globals/module#register_toolchains">register_toolchains()</a>.</p> <h4 id="toolchain-resolution-debug" data-text="--toolchain_resolution_debug=regex" tabindex="-1"><code translate="no" dir="ltr">--toolchain_resolution_debug=<var translate="no">regex</var></code></h4> <p>Print debug information while finding toolchains if the toolchain type matches the regex. Multiple regexes can be separated by commas. The regex can be negated by using a <code translate="no" dir="ltr">-</code> at the beginning. This might help developers of Bazel or Starlark rules with debugging failures due to missing toolchains.</p> <h3 id="miscellaneous" data-text="Miscellaneous" tabindex="-1">Miscellaneous</h3> <h4 id="flag-alias" data-text="--flag_alias=alias_name=target_path" tabindex="-1"><code translate="no" dir="ltr">--flag_alias=<var translate="no">alias_name=target_path</var></code></h4> <p>A convenience flag used to bind longer Starlark build settings to a shorter name. For more details, see the <a href="/extending/config#using-build-setting-aliases">Starlark Configurations</a>.</p> <h4 id="symlink-prefix" data-text="--symlink_prefix=string" tabindex="-1"><code translate="no" dir="ltr">--symlink_prefix=<var translate="no">string</var></code></h4> <p>Changes the prefix of the generated convenience symlinks. The default value for the symlink prefix is <code translate="no" dir="ltr">bazel-</code> which will create the symlinks <code translate="no" dir="ltr">bazel-bin</code>, <code translate="no" dir="ltr">bazel-testlogs</code>, and <code translate="no" dir="ltr">bazel-genfiles</code>.</p> <p>If the symbolic links cannot be created for any reason, a warning is issued but the build is still considered a success. In particular, this allows you to build in a read-only directory or one that you have no permission to write into. Any paths printed in informational messages at the conclusion of a build will only use the symlink-relative short form if the symlinks point to the expected location; in other words, you can rely on the correctness of those paths, even if you cannot rely on the symlinks being created.</p> <p>Some common values of this option:</p> <ul> <li><p><strong>Suppress symlink creation:</strong> <code translate="no" dir="ltr">--symlink_prefix=/</code> will cause Bazel to not create or update any symlinks, including the <code translate="no" dir="ltr">bazel-out</code> and <code translate="no" dir="ltr">bazel-<workspace></code> symlinks. Use this option to suppress symlink creation entirely.</p></li> <li><p><strong>Reduce clutter:</strong> <code translate="no" dir="ltr">--symlink_prefix=.bazel/</code> will cause Bazel to create symlinks called <code translate="no" dir="ltr">bin</code> (etc) inside a hidden directory <code translate="no" dir="ltr">.bazel</code>.</p></li> </ul> <h4 id="platform-suffix" data-text="--platform_suffix=string" tabindex="-1"><code translate="no" dir="ltr">--platform_suffix=<var translate="no">string</var></code></h4> <p>Adds a suffix to the configuration short name, which is used to determine the output directory. Setting this option to different values puts the files into different directories, for example to improve cache hit rates for builds that otherwise clobber each others output files, or to keep the output files around for comparisons.</p> <h4 id="default-visibility" data-text="--default_visibility=(private|public)" tabindex="-1"><code translate="no" dir="ltr">--default_visibility=<var translate="no">(private|public)</var></code></h4> <p>Temporary flag for testing bazel default visibility changes. Not intended for general use but documented for completeness' sake.</p> <h4 id="starlark-cpu-profile" data-text="--starlark_cpu_profile=_file_" tabindex="-1"><code translate="no" dir="ltr">--starlark_cpu_profile=_file_</code></h4> <p>This flag, whose value is the name of a file, causes Bazel to gather statistics about CPU usage by all Starlark threads, and write the profile, in <a href="https://github.com/google/pprof" class="external">pprof</a> format, to the named file.</p> <p>Use this option to help identify Starlark functions that make loading and analysis slow due to excessive computation. For example:</p> <pre translate="no" dir="ltr"> $ bazel build --nobuild --starlark_cpu_profile=/tmp/pprof.gz my/project/... $ pprof /tmp/pprof.gz (pprof) top Type: CPU Time: Feb 6, 2020 at 12:06pm (PST) Duration: 5.26s, Total samples = 3.34s (63.55%) Showing nodes accounting for 3.34s, 100% of 3.34s total flat flat% sum% cum cum% 1.86s 55.69% 55.69% 1.86s 55.69% sort_source_files 1.02s 30.54% 86.23% 1.02s 30.54% expand_all_combinations 0.44s 13.17% 99.40% 0.44s 13.17% range 0.02s 0.6% 100% 3.34s 100% sorted 0 0% 100% 1.38s 41.32% my/project/main/BUILD 0 0% 100% 1.96s 58.68% my/project/library.bzl 0 0% 100% 3.34s 100% main </pre> <p>For different views of the same data, try the <code translate="no" dir="ltr">pprof</code> commands <code translate="no" dir="ltr">svg</code>, <code translate="no" dir="ltr">web</code>, and <code translate="no" dir="ltr">list</code>.</p> <h2 id="bazel-for-releases" data-text="Using Bazel for releases" tabindex="-1">Using Bazel for releases</h2> <p>Bazel is used both by software engineers during the development cycle, and by release engineers when preparing binaries for deployment to production. This section provides a list of tips for release engineers using Bazel.</p> <h3 id="significant-options" data-text="Significant options" tabindex="-1">Significant options</h3> <p>When using Bazel for release builds, the same issues arise as for other scripts that perform a build. For more details, see <a href="/run/scripts">Call Bazel from scripts</a>. In particular, the following options are strongly recommended:</p> <ul> <li><a href="/run/bazelrc"><code translate="no" dir="ltr">--bazelrc=/dev/null</code></a></li> <li><a href="/reference/command-line-reference#flag--keep_state_after_build"><code translate="no" dir="ltr">--nokeep_state_after_build</code></a></li> </ul> <p>These options are also important:</p> <ul> <li><a href="#package-path"><code translate="no" dir="ltr">--package_path</code></a></li> <li><a href="#symlink-prefix"><code translate="no" dir="ltr">--symlink_prefix</code></a>: for managing builds for multiple configurations, it may be convenient to distinguish each build with a distinct identifier, such as "64bit" vs. "32bit". This option differentiates the <code translate="no" dir="ltr">bazel-bin</code> (etc.) symlinks.</li> </ul> <h2 id="running-tests" data-text="Running tests" tabindex="-1">Running tests</h2> <p>To build and run tests with bazel, type <code translate="no" dir="ltr">bazel test</code> followed by the name of the test targets.</p> <p>By default, this command performs simultaneous build and test activity, building all specified targets (including any non-test targets specified on the command line) and testing <code translate="no" dir="ltr">*_test</code> and <code translate="no" dir="ltr">test_suite</code> targets as soon as their prerequisites are built, meaning that test execution is interleaved with building. Doing so usually results in significant speed gains.</p> <h3 id="bazel-test-options" data-text="Options for bazel test" tabindex="-1">Options for <code translate="no" dir="ltr">bazel test</code></h3> <h4 id="cache-test-results" data-text="--cache_test_results=(yes|no|auto) (-t)" tabindex="-1"><code translate="no" dir="ltr">--cache_test_results=(yes|no|auto)</code> (<code translate="no" dir="ltr">-t</code>)</h4> <p>If this option is set to 'auto' (the default) then Bazel will only rerun a test if any of the following conditions applies:</p> <ul> <li>Bazel detects changes in the test or its dependencies</li> <li>the test is marked as <code translate="no" dir="ltr">external</code></li> <li>multiple test runs were requested with <code translate="no" dir="ltr">--runs_per_test</code></li> <li>the test failed.</li> </ul> <p>If 'no', all tests will be executed unconditionally.</p> <p>If 'yes', the caching behavior will be the same as auto except that it may cache test failures and test runs with <code translate="no" dir="ltr">--runs_per_test</code>.</p> <aside class="note"><strong>Note:</strong><span> Test results are <em>always</em> saved in Bazel's output tree, regardless of whether this option is enabled, so you needn't have used <code translate="no" dir="ltr">--cache_test_results</code> on the prior run(s) of <code translate="no" dir="ltr">bazel test</code> in order to get cache hits. The option only affects whether Bazel will <em>use</em> previously saved results, not whether it will save results of the current run.</span></aside> <p>Users who have enabled this option by default in their <code translate="no" dir="ltr">.bazelrc</code> file may find the abbreviations <code translate="no" dir="ltr">-t</code> (on) or <code translate="no" dir="ltr">-t-</code> (off) convenient for overriding the default on a particular run.</p> <h4 id="check-tests-up-to-date" data-text="--check_tests_up_to_date" tabindex="-1"><code translate="no" dir="ltr">--check_tests_up_to_date</code></h4> <p>This option tells Bazel not to run the tests, but to merely check and report the cached test results. If there are any tests which have not been previously built and run, or whose tests results are out-of-date (for example, because the source code or the build options have changed), then Bazel will report an error message ("test result is not up-to-date"), will record the test's status as "NO STATUS" (in red, if color output is enabled), and will return a non-zero exit code.</p> <p>This option also implies <a href="#check-up-to-date"><code translate="no" dir="ltr">--check_up_to_date</code></a> behavior.</p> <p>This option may be useful for pre-submit checks.</p> <h4 id="test-verbose-timeout-warnings" data-text="--test_verbose_timeout_warnings" tabindex="-1"><code translate="no" dir="ltr">--test_verbose_timeout_warnings</code></h4> <p>This option tells Bazel to explicitly warn the user if a test's timeout is significantly longer than the test's actual execution time. While a test's timeout should be set such that it is not flaky, a test that has a highly over-generous timeout can hide real problems that crop up unexpectedly.</p> <p>For instance, a test that normally executes in a minute or two should not have a timeout of ETERNAL or LONG as these are much, much too generous.</p> <p>This option is useful to help users decide on a good timeout value or sanity check existing timeout values.</p> <aside class="note"><strong>Note:</strong><span> Each test shard is allotted the timeout of the entire <code translate="no" dir="ltr">XX_test</code> target. Using this option does not affect a test's timeout value, merely warns if Bazel thinks the timeout could be restricted further.</span></aside> <h4 id="test-keep-going" data-text="--[no]test_keep_going" tabindex="-1"><code translate="no" dir="ltr">--[no]test_keep_going</code></h4> <p>By default, all tests are run to completion. If this flag is disabled, however, the build is aborted on any non-passing test. Subsequent build steps and test invocations are not run, and in-flight invocations are canceled. Do not specify both <code translate="no" dir="ltr">--notest_keep_going</code> and <code translate="no" dir="ltr">--keep_going</code>.</p> <h4 id="flaky-test-attempts" data-text="--flaky_test_attempts=attempts" tabindex="-1"><code translate="no" dir="ltr">--flaky_test_attempts=<var translate="no">attempts</var></code></h4> <p>This option specifies the maximum number of times a test should be attempted if it fails for any reason. A test that initially fails but eventually succeeds is reported as <code translate="no" dir="ltr">FLAKY</code> on the test summary. It is, however, considered to be passed when it comes to identifying Bazel exit code or total number of passed tests. Tests that fail all allowed attempts are considered to be failed.</p> <p>By default (when this option is not specified, or when it is set to default), only a single attempt is allowed for regular tests, and 3 for test rules with the <code translate="no" dir="ltr">flaky</code> attribute set. You can specify an integer value to override the maximum limit of test attempts. Bazel allows a maximum of 10 test attempts in order to prevent abuse of the system.</p> <h4 id="runs-per-test" data-text="--runs_per_test=[regex@]number" tabindex="-1"><code translate="no" dir="ltr">--runs_per_test=<var translate="no">[regex@]number</var></code></h4> <p>This option specifies the number of times each test should be executed. All test executions are treated as separate tests (fallback functionality will apply to each of them independently).</p> <p>The status of a target with failing runs depends on the value of the <code translate="no" dir="ltr">--runs_per_test_detects_flakes</code> flag:</p> <ul> <li>If absent, any failing run causes the entire test to fail.</li> <li>If present and two runs from the same shard return PASS and FAIL, the test will receive a status of flaky (unless other failing runs cause it to fail).</li> </ul> <p>If a single number is specified, all tests will run that many times. Alternatively, a regular expression may be specified using the syntax regex@number. This constrains the effect of <code translate="no" dir="ltr">--runs_per_test</code> to targets which match the regex (<code translate="no" dir="ltr">--runs_per_test=^//pizza:.*@4</code> runs all tests under <code translate="no" dir="ltr">//pizza/</code> 4 times). This form of <code translate="no" dir="ltr">--runs_per_test</code> may be specified more than once.</p> <h4 id="run-per-test-detects-flakes" data-text="--[no]runs_per_test_detects_flakes" tabindex="-1"><code translate="no" dir="ltr">--[no]runs_per_test_detects_flakes</code></h4> <p>If this option is specified (by default it is not), Bazel will detect flaky test shards through <code translate="no" dir="ltr">--runs_per_test</code>. If one or more runs for a single shard fail and one or more runs for the same shard pass, the target will be considered flaky with the flag. If unspecified, the target will report a failing status.</p> <h4 id="test-summary" data-text="--test_summary=output_style" tabindex="-1"><code translate="no" dir="ltr">--test_summary=<var translate="no">output_style</var></code></h4> <p>Specifies how the test result summary should be displayed.</p> <ul> <li><code translate="no" dir="ltr">short</code> prints the results of each test along with the name of the file containing the test output if the test failed. This is the default value.</li> <li><code translate="no" dir="ltr">terse</code> like <code translate="no" dir="ltr">short</code>, but even shorter: only print information about tests which did not pass.</li> <li><code translate="no" dir="ltr">detailed</code> prints each individual test case that failed, not only each test. The names of test output files are omitted.</li> <li><code translate="no" dir="ltr">none</code> does not print test summary.</li> </ul> <h4 id="test-output" data-text="--test_output=output_style" tabindex="-1"><code translate="no" dir="ltr">--test_output=<var translate="no">output_style</var></code></h4> <p>Specifies how test output should be displayed:</p> <ul> <li><code translate="no" dir="ltr">summary</code> shows a summary of whether each test passed or failed. Also shows the output log file name for failed tests. The summary will be printed at the end of the build (during the build, one would see just simple progress messages when tests start, pass or fail). This is the default behavior.</li> <li><code translate="no" dir="ltr">errors</code> sends combined stdout/stderr output from failed tests only into the stdout immediately after test is completed, ensuring that test output from simultaneous tests is not interleaved with each other. Prints a summary at the build as per summary output above.</li> <li><code translate="no" dir="ltr">all</code> is similar to <code translate="no" dir="ltr">errors</code> but prints output for all tests, including those which passed.</li> <li><code translate="no" dir="ltr">streamed</code> streams stdout/stderr output from each test in real-time.</li> </ul> <h4 id="java-debug" data-text="--java_debug" tabindex="-1"><code translate="no" dir="ltr">--java_debug</code></h4> <p>This option causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger before starting the test. This option implies <code translate="no" dir="ltr">--test_output=streamed</code>.</p> <h4 id="verbose-test-summary" data-text="--[no]verbose_test_summary" tabindex="-1"><code translate="no" dir="ltr">--[no]verbose_test_summary</code></h4> <p>By default this option is enabled, causing test times and other additional information (such as test attempts) to be printed to the test summary. If <code translate="no" dir="ltr">--noverbose_test_summary</code> is specified, test summary will include only test name, test status and cached test indicator and will be formatted to stay within 80 characters when possible.</p> <h4 id="test-tmpdir" data-text="--test_tmpdir=path" tabindex="-1"><code translate="no" dir="ltr">--test_tmpdir=<var translate="no">path</var></code></h4> <p>Specifies temporary directory for tests executed locally. Each test will be executed in a separate subdirectory inside this directory. The directory will be cleaned at the beginning of the each <code translate="no" dir="ltr">bazel test</code> command. By default, bazel will place this directory under Bazel output base directory.</p> <aside class="note"><strong>Note:</strong><span> This is a directory for running tests, not storing test results (those are always stored under the <code translate="no" dir="ltr">bazel-out</code> directory).</span></aside> <h4 id="test-timeout" data-text="--test_timeout=seconds OR --test_timeout=seconds,seconds,seconds,seconds" tabindex="-1"><code translate="no" dir="ltr">--test_timeout=<var translate="no">seconds</var></code> OR <code translate="no" dir="ltr">--test_timeout=<var translate="no">seconds</var>,<var translate="no">seconds</var>,<var translate="no">seconds</var>,<var translate="no">seconds</var></code></h4> <p>Overrides the timeout value for all tests by using specified number of seconds as a new timeout value. If only one value is provided, then it will be used for all test timeout categories.</p> <p>Alternatively, four comma-separated values may be provided, specifying individual timeouts for short, moderate, long and eternal tests (in that order). In either form, zero or a negative value for any of the test sizes will be substituted by the default timeout for the given timeout categories as defined by the page <a href="/reference/test-encyclopedia">Writing Tests</a>. By default, Bazel will use these timeouts for all tests by inferring the timeout limit from the test's size whether the size is implicitly or explicitly set.</p> <p>Tests which explicitly state their timeout category as distinct from their size will receive the same value as if that timeout had been implicitly set by the size tag. So a test of size 'small' which declares a 'long' timeout will have the same effective timeout that a 'large' tests has with no explicit timeout.</p> <h4 id="test-arg" data-text="--test_arg=arg" tabindex="-1"><code translate="no" dir="ltr">--test_arg=<var translate="no">arg</var></code></h4> <p>Passes command-line options/flags/arguments to each test process. This option can be used multiple times to pass several arguments. For example, <code translate="no" dir="ltr">--test_arg=--logtostderr --test_arg=--v=3</code>.</p> <p>Note that, unlike the <code translate="no" dir="ltr">bazel run</code> command, you can't pass test arguments directly as in <code translate="no" dir="ltr">bazel test -- target --logtostderr --v=3</code>. That's because extraneous arguments passed to <code translate="no" dir="ltr">bazel test</code> are interpreted as additional test targets. That is, <code translate="no" dir="ltr">--logtostderr</code> and <code translate="no" dir="ltr">--v=3</code> would each be interpreted as a test target. This ambiguity doesn't exist for a <code translate="no" dir="ltr">bazel run</code> command, which only accepts one target.</p> <p><code translate="no" dir="ltr">--test_arg</code> can be passed to a <code translate="no" dir="ltr">bazel run</code> command, but it's ignored unless the target being run is a test target. (As with any other flag, if it's passed in a <code translate="no" dir="ltr">bazel run</code> command after a <code translate="no" dir="ltr">--</code> token, it's not processed by Bazel but forwarded verbatim to the executed target.)</p> <h4 id="test-env" data-text="--test_env=variable=_value_ OR --test_env=variable" tabindex="-1"><code translate="no" dir="ltr">--test_env=<var translate="no">variable</var>=_value_</code> OR <code translate="no" dir="ltr">--test_env=<var translate="no">variable</var></code></h4> <p>Specifies additional variables that must be injected into the test environment for each test. If <var translate="no">value</var> is not specified it will be inherited from the shell environment used to start the <code translate="no" dir="ltr">bazel test</code> command.</p> <p>The environment can be accessed from within a test by using <code translate="no" dir="ltr">System.getenv("var")</code> (Java), <code translate="no" dir="ltr">getenv("var")</code> (C or C++),</p> <h4 id="test-run-under" data-text="--run_under=command-prefix" tabindex="-1"><code translate="no" dir="ltr">--run_under=<var translate="no">command-prefix</var></code></h4> <p>This specifies a prefix that the test runner will insert in front of the test command before running it. The <var translate="no">command-prefix</var> is split into words using Bourne shell tokenization rules, and then the list of words is prepended to the command that will be executed.</p> <p>If the first word is a fully-qualified label (starts with <code translate="no" dir="ltr">//</code>) it is built. Then the label is substituted by the corresponding executable location that is prepended to the command that will be executed along with the other words.</p> <p>Some caveats apply:</p> <ul> <li>The PATH used for running tests may be different than the PATH in your environment, so you may need to use an <strong>absolute path</strong> for the <code translate="no" dir="ltr">--run_under</code> command (the first word in <var translate="no">command-prefix</var>).</li> <li><strong><code translate="no" dir="ltr">stdin</code> is not connected</strong>, so <code translate="no" dir="ltr">--run_under</code> can't be used for interactive commands.</li> </ul> <p>Examples:</p> <pre translate="no" dir="ltr"> --run_under=/usr/bin/strace --run_under='/usr/bin/strace -c' --run_under=/usr/bin/valgrind --run_under='/usr/bin/valgrind --quiet --num-callers=20' </pre> <h4 id="test-selection" data-text="Test selection" tabindex="-1">Test selection</h4> <p>As documented under <a href="#output-selection">Output selection options</a>, you can filter tests by <a href="#test-size-filters">size</a>, <a href="#test-timeout-filters">timeout</a>, <a href="#test-tag-filters">tag</a>, or <a href="#test-lang-filters">language</a>. A convenience <a href="#test-filter">general name filter</a> can forward particular filter args to the test runner.</p> <h4 id="bazel-test-other-options" data-text="Other options for bazel test" tabindex="-1">Other options for <code translate="no" dir="ltr">bazel test</code></h4> <p>The syntax and the remaining options are exactly like <a href="/run/build"><code translate="no" dir="ltr">bazel build</code></a>.</p> <h2 id="running-executables" data-text="Running executables" tabindex="-1">Running executables</h2> <p>The <code translate="no" dir="ltr">bazel run</code> command is similar to <code translate="no" dir="ltr">bazel build</code>, except it is used to build <em>and run</em> a single target. Here is a typical session (<code translate="no" dir="ltr">//java/myapp:myapp</code> says hello and prints out its args):</p> <pre translate="no" dir="ltr"> % bazel run java/myapp:myapp -- --arg1 --arg2 INFO: Analyzed target //java/myapp:myapp (13 packages loaded, 27 targets configured). INFO: Found 1 target... Target //java/myapp:myapp up-to-date: bazel-bin/java/myapp/myapp INFO: Elapsed time: 14.290s, Critical Path: 5.54s, ... INFO: Build completed successfully, 4 total actions INFO: Running command line: bazel-bin/java/myapp/myapp <args omitted> Hello there $EXEC_ROOT/java/myapp/myapp --arg1 --arg2 </pre> <aside class="note"><strong>Note:</strong><span> <code translate="no" dir="ltr">--</code> is needed so that Bazel does not interpret <code translate="no" dir="ltr">--arg1</code> and <code translate="no" dir="ltr">--arg2</code> as Bazel options, but rather as part of the command line for running the binary. Additionally, Bazel will avoid logging these arguments to the console in case they contain sensitive information.</span></aside> <p><code translate="no" dir="ltr">bazel run</code> is similar, but not identical, to directly invoking the binary built by Bazel and its behavior is different depending on whether the binary to be invoked is a test or not.</p> <p>When the binary is not a test, the current working directory will be the runfiles tree of the binary.</p> <p>When the binary is a test, the current working directory will be the exec root and a good-faith attempt is made to replicate the environment tests are usually run in. The emulation is not perfect, though, and tests that have multiple shards cannot be run this way (the <code translate="no" dir="ltr">--test_sharding_strategy=disabled</code> command line option can be used to work around this)</p> <p>The following extra environment variables are also available to the binary:</p> <ul> <li><code translate="no" dir="ltr">BUILD_WORKSPACE_DIRECTORY</code>: the root of the workspace where the build was run.</li> <li><code translate="no" dir="ltr">BUILD_WORKING_DIRECTORY</code>: the current working directory where Bazel was run from.</li> <li><code translate="no" dir="ltr">BUILD_ID</code>: the build ID of the <code translate="no" dir="ltr">bazel run</code> invocation. This is usually unique, except if Bazel was run with <code translate="no" dir="ltr">--script_path</code> and the resulting script is re-used.</li> <li><code translate="no" dir="ltr">BUILD_EXECROOT</code>: the execution root of the <code translate="no" dir="ltr">bazel run</code> invocation.</li> </ul> <p>These can be used, for example, to interpret file names on the command line in a user-friendly way.</p> <h3 id="bazel-run-options" data-text="Options for bazel run" tabindex="-1">Options for <code translate="no" dir="ltr">bazel run</code></h3> <h4 id="run-run-under" data-text="--run_under=command-prefix" tabindex="-1"><code translate="no" dir="ltr">--run_under=<var translate="no">command-prefix</var></code></h4> <p>This has the same effect as the <code translate="no" dir="ltr">--run_under</code> option for <code translate="no" dir="ltr">bazel test</code> (<a href="#test-run-under">see above</a>), except that it applies to the command being run by <code translate="no" dir="ltr">bazel run</code> rather than to the tests being run by <code translate="no" dir="ltr">bazel test</code> and cannot run under label.</p> <h4 id="filtering_logging_outputs_from_bazel" data-text="Filtering logging outputs from Bazel" tabindex="-1">Filtering logging outputs from Bazel</h4> <p>When invoking a binary with <code translate="no" dir="ltr">bazel run</code>, Bazel prints logging output from Bazel itself and the binary under invocation. To make the logs less noisy, you can suppress the outputs from Bazel itself with the <code translate="no" dir="ltr">--ui_event_filters</code> and <code translate="no" dir="ltr">--noshow_progress</code> flags.</p> <p>For example: <code translate="no" dir="ltr">bazel run --ui_event_filters=-info,-stdout,-stderr --noshow_progress //java/myapp:myapp</code></p> <h3 id="executing-tests" data-text="Executing tests" tabindex="-1">Executing tests</h3> <p><code translate="no" dir="ltr">bazel run</code> can also execute test binaries, which has the effect of running the test in a close approximation of the environment described at <a href="/reference/test-encyclopedia">Writing Tests</a>. Note that none of the <code translate="no" dir="ltr">--test_*</code> arguments have an effect when running a test in this manner except <code translate="no" dir="ltr">--test_arg</code> .</p> <h2 id="cleaning-build-outputs" data-text="Cleaning build outputs" tabindex="-1">Cleaning build outputs</h2> <h3 id="clean" data-text="The clean command" tabindex="-1">The <code translate="no" dir="ltr">clean</code> command</h3> <p>Bazel has a <code translate="no" dir="ltr">clean</code> command, analogous to that of Make. It deletes the output directories for all build configurations performed by this Bazel instance, or the entire working tree created by this Bazel instance, and resets internal caches. If executed without any command-line options, then the output directory for all configurations will be cleaned.</p> <p>Recall that each Bazel instance is associated with a single workspace, thus the <code translate="no" dir="ltr">clean</code> command will delete all outputs from all builds you've done with that Bazel instance in that workspace.</p> <p>To completely remove the entire working tree created by a Bazel instance, you can specify the <code translate="no" dir="ltr">--expunge</code> option. When executed with <code translate="no" dir="ltr">--expunge</code>, the clean command simply removes the entire output base tree which, in addition to the build output, contains all temp files created by Bazel. It also stops the Bazel server after the clean, equivalent to the <a href="#shutdown"><code translate="no" dir="ltr">shutdown</code></a> command. For example, to clean up all disk and memory traces of a Bazel instance, you could specify:</p> <pre translate="no" dir="ltr"> % bazel clean --expunge </pre> <p>Alternatively, you can expunge in the background by using <code translate="no" dir="ltr">--expunge_async</code>. It is safe to invoke a Bazel command in the same client while the asynchronous expunge continues to run.</p> <aside class="note"><strong>Note:</strong><span> This may introduce IO contention.</span></aside> <p>The <code translate="no" dir="ltr">clean</code> command is provided primarily as a means of reclaiming disk space for workspaces that are no longer needed. Bazel's incremental rebuilds may not be perfect so <code translate="no" dir="ltr">clean</code> can be used to recover a consistent state when problems arise.</p> <p>Bazel's design is such that these problems are fixable and these bugs are a high priority to be fixed. If you ever find an incorrect incremental build, file a bug report, and report bugs in the tools rather than using <code translate="no" dir="ltr">clean</code>.</p> <h2 id="querying-dependency-graph" data-text="Querying the dependency graph" tabindex="-1">Querying the dependency graph</h2> <p>Bazel includes a query language for asking questions about the dependency graph used during the build. The query language is used by two commands: query and cquery. The major difference between the two commands is that query runs after the <a href="/run/build#loading">loading phase</a> and cquery runs after the <a href="/run/build#analysis">analysis phase</a>. These tools are an invaluable aid to many software engineering tasks.</p> <p>The query language is based on the idea of algebraic operations over graphs; it is documented in detail in</p> <p><a href="/query/language">Bazel Query Reference</a>. Please refer to that document for reference, for examples, and for query-specific command-line options.</p> <p>The query tool accepts several command-line option. <code translate="no" dir="ltr">--output</code> selects the output format. <code translate="no" dir="ltr">--[no]keep_going</code> (disabled by default) causes the query tool to continue to make progress upon errors; this behavior may be disabled if an incomplete result is not acceptable in case of errors.</p> <p>The <code translate="no" dir="ltr">--[no]tool_deps</code> option, enabled by default, causes dependencies in non-target configurations to be included in the dependency graph over which the query operates.</p> <p>The <code translate="no" dir="ltr">--[no]implicit_deps</code> option, enabled by default, causes implicit dependencies to be included in the dependency graph over which the query operates. An implicit dependency is one that is not explicitly specified in the BUILD file but added by bazel.</p> <p>Example: "Show the locations of the definitions (in BUILD files) of all genrules required to build all the tests in the PEBL tree."</p> <pre translate="no" dir="ltr"> bazel query --output location 'kind(genrule, deps(kind(".*_test rule", foo/bar/pebl/...)))' </pre> <h2 id="aquery" data-text="Querying the action graph" tabindex="-1">Querying the action graph</h2> <aside class="caution"><strong>Caution:</strong><span> The aquery command is still experimental and its API will change.</span></aside> <p>The <code translate="no" dir="ltr">aquery</code> command allows you to query for actions in your build graph. It operates on the post-analysis configured target graph and exposes information about actions, artifacts and their relationships.</p> <p>The tool accepts several command-line options. <code translate="no" dir="ltr">--output</code> selects the output format. The default output format (<code translate="no" dir="ltr">text</code>) is human-readable, use <code translate="no" dir="ltr">proto</code> or <code translate="no" dir="ltr">textproto</code> for machine-readable format. Notably, the aquery command runs on top of a regular Bazel build and inherits the set of options available during a build.</p> <p>It supports the same set of functions that is also available to traditional <code translate="no" dir="ltr">query</code> but <code translate="no" dir="ltr">siblings</code>, <code translate="no" dir="ltr">buildfiles</code> and <code translate="no" dir="ltr">tests</code>.</p> <p>For more details, see <a href="/query/aquery">Action Graph Query</a>.</p> <h2 id="misc-commands-options" data-text="Miscellaneous commands and options" tabindex="-1">Miscellaneous commands and options</h2> <h3 id="help" data-text="help" tabindex="-1"><code translate="no" dir="ltr">help</code></h3> <p>The <code translate="no" dir="ltr">help</code> command provides on-line help. By default, it shows a summary of available commands and help topics, as shown in <a href="/run/build#quickstart">Building with Bazel</a>. Specifying an argument displays detailed help for a particular topic. Most topics are Bazel commands, such as <code translate="no" dir="ltr">build</code> or <code translate="no" dir="ltr">query</code>, but there are some additional help topics that do not correspond to commands.</p> <h4 id="long" data-text="--[no]long (-l)" tabindex="-1"><code translate="no" dir="ltr">--[no]long</code> (<code translate="no" dir="ltr">-l</code>)</h4> <p>By default, <code translate="no" dir="ltr">bazel help [<var translate="no">topic</var>]</code> prints only a summary of the relevant options for a topic. If the <code translate="no" dir="ltr">--long</code> option is specified, the type, default value and full description of each option is also printed.</p> <h3 id="shutdown" data-text="shutdown" tabindex="-1"><code translate="no" dir="ltr">shutdown</code></h3> <p>Bazel server processes may be stopped by using the <code translate="no" dir="ltr">shutdown</code> command. This command causes the Bazel server to exit as soon as it becomes idle (for example, after the completion of any builds or other commands that are currently in progress). For more details, see <a href="/run/client-server">Client/server implementation</a>.</p> <p>Bazel servers stop themselves after an idle timeout, so this command is rarely necessary; however, it can be useful in scripts when it is known that no further builds will occur in a given workspace.</p> <p><code translate="no" dir="ltr">shutdown</code> accepts one option, <code translate="no" dir="ltr">--iff_heap_size_greater_than _n_</code>, which requires an integer argument (in MB). If specified, this makes the shutdown conditional on the amount of memory already consumed. This is useful for scripts that initiate a lot of builds, as any memory leaks in the Bazel server could cause it to crash spuriously on occasion; performing a conditional restart preempts this condition.</p> <h3 id="info" data-text="info" tabindex="-1"><code translate="no" dir="ltr">info</code></h3> <p>The <code translate="no" dir="ltr">info</code> command prints various values associated with the Bazel server instance, or with a specific build configuration. (These may be used by scripts that drive a build.)</p> <p>The <code translate="no" dir="ltr">info</code> command also permits a single (optional) argument, which is the name of one of the keys in the list below. In this case, <code translate="no" dir="ltr">bazel info <var translate="no">key</var></code> will print only the value for that one key. (This is especially convenient when scripting Bazel, as it avoids the need to pipe the result through <code translate="no" dir="ltr">sed -ne /key:/s/key://p</code>:</p> <h4 id="configuration-independent-data" data-text="Configuration-independent data" tabindex="-1">Configuration-independent data</h4> <ul> <li><code translate="no" dir="ltr">release</code>: the release label for this Bazel instance, or "development version" if this is not a released binary.</li> <li><code translate="no" dir="ltr">workspace</code> the absolute path to the base workspace directory.</li> <li><p><code translate="no" dir="ltr">install_base</code>: the absolute path to the installation directory used by this Bazel instance for the current user. Bazel installs its internally required executables below this directory.</p></li> <li><p><code translate="no" dir="ltr">output_base</code>: the absolute path to the base output directory used by this Bazel instance for the current user and workspace combination. Bazel puts all of its scratch and build output below this directory.</p></li> <li><p><code translate="no" dir="ltr">execution_root</code>: the absolute path to the execution root directory under output_base. This directory is the root for all files accessible to commands executed during the build, and is the working directory for those commands. If the workspace directory is writable, a symlink named <code translate="no" dir="ltr">bazel-<workspace></code> is placed there pointing to this directory.</p></li> <li><p><code translate="no" dir="ltr">output_path</code>: the absolute path to the output directory beneath the execution root used for all files actually generated as a result of build commands. If the workspace directory is writable, a symlink named <code translate="no" dir="ltr">bazel-out</code> is placed there pointing to this directory.</p></li> <li><p><code translate="no" dir="ltr">server_pid</code>: the process ID of the Bazel server process.</p></li> <li><p><code translate="no" dir="ltr">server_log</code>: the absolute path to the Bazel server's debug log file. This file contains debugging information for all commands over the lifetime of the Bazel server, and is intended for human consumption by Bazel developers and power users.</p></li> <li><p><code translate="no" dir="ltr">command_log</code>: the absolute path to the command log file; this contains the interleaved stdout and stderr streams of the most recent Bazel command. Note that running <code translate="no" dir="ltr">bazel info</code> will overwrite the contents of this file, since it then becomes the most recent Bazel command. However, the location of the command log file will not change unless you change the setting of the <code translate="no" dir="ltr">--output_base</code> or <code translate="no" dir="ltr">--output_user_root</code> options.</p></li> <li><p><code translate="no" dir="ltr">used-heap-size</code>, <code translate="no" dir="ltr">committed-heap-size</code>, <code translate="no" dir="ltr">max-heap-size</code>: reports various JVM heap size parameters. Respectively: memory currently used, memory currently guaranteed to be available to the JVM from the system, maximum possible allocation.</p></li> <li><p><code translate="no" dir="ltr">gc-count</code>, <code translate="no" dir="ltr">gc-time</code>: The cumulative count of garbage collections since the start of this Bazel server and the time spent to perform them. Note that these values are not reset at the start of every build.</p></li> <li><p><code translate="no" dir="ltr">package_path</code>: A colon-separated list of paths which would be searched for packages by bazel. Has the same format as the <code translate="no" dir="ltr">--package_path</code> build command line argument.</p></li> </ul> <p>Example: the process ID of the Bazel server.</p> <pre translate="no" dir="ltr">% bazel info server_pid 1285 </pre> <h4 id="configuration-specific-data" data-text="Configuration-specific data" tabindex="-1">Configuration-specific data</h4> <p>These data may be affected by the configuration options passed to <code translate="no" dir="ltr">bazel info</code>, for example <code translate="no" dir="ltr">--cpu</code>, <code translate="no" dir="ltr">--compilation_mode</code>, etc. The <code translate="no" dir="ltr">info</code> command accepts all the options that control dependency analysis, since some of these determine the location of the output directory of a build, the choice of compiler, etc.</p> <ul> <li><code translate="no" dir="ltr">bazel-bin</code>, <code translate="no" dir="ltr">bazel-testlogs</code>, <code translate="no" dir="ltr">bazel-genfiles</code>: reports the absolute path to the <code translate="no" dir="ltr">bazel-*</code> directories in which programs generated by the build are located. This is usually, though not always, the same as the <code translate="no" dir="ltr">bazel-*</code> symlinks created in the base workspace directory after a successful build. However, if the workspace directory is read-only, no <code translate="no" dir="ltr">bazel-*</code> symlinks can be created. Scripts that use the value reported by <code translate="no" dir="ltr">bazel info</code>, instead of assuming the existence of the symlink, will be more robust.</li> <li>The complete <a href="/reference/be/make-variables">"Make" environment</a>. If the <code translate="no" dir="ltr">--show_make_env</code> flag is specified, all variables in the current configuration's "Make" environment are also displayed (such as <code translate="no" dir="ltr">CC</code>, <code translate="no" dir="ltr">GLIBC_VERSION</code>, etc). These are the variables accessed using the <code translate="no" dir="ltr">$(CC)</code> or <code translate="no" dir="ltr">varref("CC")</code> syntax inside BUILD files.</li> </ul> <p>Example: the C++ compiler for the current configuration. This is the <code translate="no" dir="ltr">$(CC)</code> variable in the "Make" environment, so the <code translate="no" dir="ltr">--show_make_env</code> flag is needed.</p> <pre translate="no" dir="ltr"> % bazel info --show_make_env -c opt COMPILATION_MODE opt </pre> <p>Example: the <code translate="no" dir="ltr">bazel-bin</code> output directory for the current configuration. This is guaranteed to be correct even in cases where the <code translate="no" dir="ltr">bazel-bin</code> symlink cannot be created for some reason (such as if you are building from a read-only directory).</p> <pre translate="no" dir="ltr">% bazel info --cpu=piii bazel-bin /var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/piii-opt/bin % bazel info --cpu=k8 bazel-bin /var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/k8-opt/bin </pre> <h3 id="version" data-text="version and --version" tabindex="-1"><code translate="no" dir="ltr">version</code> and <code translate="no" dir="ltr">--version</code></h3> <p>The version command prints version details about the built Bazel binary, including the changelist at which it was built and the date. These are particularly useful in determining if you have the latest Bazel, or if you are reporting bugs. Some of the interesting values are:</p> <ul> <li><code translate="no" dir="ltr">changelist</code>: the changelist at which this version of Bazel was released.</li> <li><code translate="no" dir="ltr">label</code>: the release label for this Bazel instance, or "development version" if this is not a released binary. Very useful when reporting bugs.</li> </ul> <p><code translate="no" dir="ltr">bazel --version</code>, with no other args, will emit the same output as <code translate="no" dir="ltr">bazel version --gnu_format</code>, except without the side-effect of potentially starting a Bazel server or unpacking the server archive. <code translate="no" dir="ltr">bazel --version</code> can be run from anywhere - it does not require a workspace directory.</p> <h3 id="mobile-install" data-text="mobile-install" tabindex="-1"><code translate="no" dir="ltr">mobile-install</code></h3> <p>The <code translate="no" dir="ltr">mobile-install</code> command installs apps to mobile devices. Currently only Android devices running ART are supported.</p> <p>See <a href="/docs/mobile-install">bazel mobile-install</a> for more information.</p> <aside class="note"><strong>Note:</strong><span> This command does not install the same thing that <code translate="no" dir="ltr">bazel build</code> produces: Bazel tweaks the app so that it can be built, installed and re-installed quickly. This should, however, be mostly transparent to the app.</span></aside> <p>The following options are supported:</p> <h4 id="incremental" data-text="--incremental" tabindex="-1"><code translate="no" dir="ltr">--incremental</code></h4> <p>If set, Bazel tries to install the app incrementally, that is, only those parts that have changed since the last build. This cannot update resources referenced from <code translate="no" dir="ltr">AndroidManifest.xml</code>, native code or Java resources (such as those referenced by <code translate="no" dir="ltr">Class.getResource()</code>). If these things change, this option must be omitted. Contrary to the spirit of Bazel and due to limitations of the Android platform, it is the <strong>responsibility of the user</strong> to know when this command is good enough and when a full install is needed.</p> <p>If you are using a device with Marshmallow or later, consider the <a href="#split-apks"><code translate="no" dir="ltr">--split_apks</code></a> flag.</p> <h4 id="split-apks" data-text="--split_apks" tabindex="-1"><code translate="no" dir="ltr">--split_apks</code></h4> <p>Whether to use split apks to install and update the application on the device. Works only with devices with Marshmallow or later. Note that the <a href="#incremental"><code translate="no" dir="ltr">--incremental</code></a> flag is not necessary when using <code translate="no" dir="ltr">--split_apks</code>.</p> <h4 id="start-app" data-text="--start_app" tabindex="-1"><code translate="no" dir="ltr">--start_app</code></h4> <p>Starts the app in a clean state after installing. Equivalent to <code translate="no" dir="ltr">--start=COLD</code>.</p> <h4 id="debug-app" data-text="--debug_app" tabindex="-1"><code translate="no" dir="ltr">--debug_app</code></h4> <p>Waits for debugger to be attached before starting the app in a clean state after installing. Equivalent to <code translate="no" dir="ltr">--start=DEBUG</code>.</p> <h4 id="start" data-text="--start=_start_type_" tabindex="-1"><code translate="no" dir="ltr">--start=_start_type_</code></h4> <p>How the app should be started after installing it. Supported _start_type_s are:</p> <ul> <li><code translate="no" dir="ltr">NO</code> Does not start the app. This is the default.</li> <li><code translate="no" dir="ltr">COLD</code> Starts the app from a clean state after install.</li> <li><code translate="no" dir="ltr">WARM</code> Preserves and restores the application state on incremental installs.</li> <li><code translate="no" dir="ltr">DEBUG</code> Waits for the debugger before starting the app in a clean state after install.</li> </ul> <aside class="note"><strong>Note:</strong><span> If more than one of <code translate="no" dir="ltr">--start=_start_type_</code>, <code translate="no" dir="ltr">--start_app</code> or <code translate="no" dir="ltr">--debug_app</code> is set, the last value is used.</span></aside> <h4 id="adb" data-text="--adb=path" tabindex="-1"><code translate="no" dir="ltr">--adb=<var translate="no">path</var></code></h4> <p>Indicates the <code translate="no" dir="ltr">adb</code> binary to be used.</p> <p>The default is to use the adb in the Android SDK specified by <a href="#android-sdk"><code translate="no" dir="ltr">--android_sdk</code></a>.</p> <h4 id="adb-arg" data-text="--adb_arg=serial" tabindex="-1"><code translate="no" dir="ltr">--adb_arg=<var translate="no">serial</var></code></h4> <p>Extra arguments to <code translate="no" dir="ltr">adb</code>. These come before the subcommand in the command line and are typically used to specify which device to install to. For example, to select the Android device or emulator to use:</p> <pre translate="no" dir="ltr">% bazel mobile-install --adb_arg=-s --adb_arg=deadbeef </pre> <p>invokes <code translate="no" dir="ltr">adb</code> as</p> <pre translate="no" dir="ltr"> adb -s deadbeef install ... </pre> <h4 id="incremental-install-verbosity" data-text="--incremental_install_verbosity=number" tabindex="-1"><code translate="no" dir="ltr">--incremental_install_verbosity=<var translate="no">number</var></code></h4> <p>The verbosity for incremental install. Set to 1 for debug logging to be printed to the console.</p> <h3 id="dump" data-text="dump" tabindex="-1"><code translate="no" dir="ltr">dump</code></h3> <p>The <code translate="no" dir="ltr">dump</code> command prints to stdout a dump of the internal state of the Bazel server. This command is intended primarily for use by Bazel developers, so the output of this command is not specified, and is subject to change.</p> <p>By default, command will just print help message outlining possible options to dump specific areas of the Bazel state. In order to dump internal state, at least one of the options must be specified.</p> <p>Following options are supported:</p> <ul> <li><code translate="no" dir="ltr">--action_cache</code> dumps action cache content.</li> <li><code translate="no" dir="ltr">--packages</code> dumps package cache content.</li> <li><code translate="no" dir="ltr">--skyframe</code> dumps state of internal Bazel dependency graph.</li> <li><code translate="no" dir="ltr">--rules</code> dumps rule summary for each rule and aspect class, including counts and action counts. This includes both native and Starlark rules. If memory tracking is enabled, then the rules' memory consumption is also printed.</li> <li><code translate="no" dir="ltr">--skylark_memory</code> dumps a <a href="https://github.com/google/pprof">pprof</a> compatible .gz file to the specified path. You must enable memory tracking for this to work.</li> </ul> <h4 id="memory-tracking" data-text="Memory tracking" tabindex="-1">Memory tracking</h4> <p>Some <code translate="no" dir="ltr">dump</code> commands require memory tracking. To turn this on, you have to pass startup flags to Bazel:</p> <ul> <li><code translate="no" dir="ltr">--host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar</code></li> <li><code translate="no" dir="ltr">--host_jvm_args=-DRULE_MEMORY_TRACKER=1</code></li> </ul> <p>The java-agent is checked into Bazel at <code translate="no" dir="ltr">third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar</code>, so make sure you adjust <code translate="no" dir="ltr">$BAZEL</code> for where you keep your Bazel repository.</p> <p>Do not forget to keep passing these options to Bazel for every command or the server will restart.</p> <p>Example:</p> <pre translate="no" dir="ltr"> % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar \ --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \ build --nobuild <targets> # Dump rules % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar \ --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \ dump --rules # Dump Starlark heap and analyze it with pprof % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar \ --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \ dump --skylark_memory=$HOME/prof.gz % pprof -flame $HOME/prof.gz </pre> <h3 id="analyze-profile" data-text="analyze-profile" tabindex="-1"><code translate="no" dir="ltr">analyze-profile</code></h3> <p>The <code translate="no" dir="ltr">analyze-profile</code> command analyzes a <a href="/advanced/performance/json-trace-profile">JSON trace profile</a> previously gathered during a Bazel invocation.</p> <h3 id="canonicalize-flags" data-text="canonicalize-flags" tabindex="-1"><code translate="no" dir="ltr">canonicalize-flags</code></h3> <p>The <a href="/reference/command-line-reference#canonicalize-flags-options"><code translate="no" dir="ltr">canonicalize-flags</code></a> command, which takes a list of options for a Bazel command and returns a list of options that has the same effect. The new list of options is canonical. For example, two lists of options with the same effect are canonicalized to the same new list.</p> <p>The <code translate="no" dir="ltr">--for_command</code> option can be used to select between different commands. At this time, only <code translate="no" dir="ltr">build</code> and <code translate="no" dir="ltr">test</code> are supported. Options that the given command does not support cause an error.</p> <aside class="note"><strong>Note:</strong><span> A small number of options cannot be reordered, because Bazel cannot ensure that the effect is identical. Also note that this command <em>does not</em> expand flags from <code translate="no" dir="ltr">--config</code>.</span></aside> <p>As an example:</p> <pre translate="no" dir="ltr"> % bazel canonicalize-flags -- --config=any_name --test_tag_filters="-lint" --config=any_name --test_tag_filters=-lint </pre> <h3 id="startup-options" data-text="Startup options" tabindex="-1">Startup options</h3> <p>The options described in this section affect the startup of the Java virtual machine used by Bazel server process, and they apply to all subsequent commands handled by that server. If there is an already running Bazel server and the startup options do not match, it will be restarted.</p> <p>All of the options described in this section must be specified using the <code translate="no" dir="ltr">--key=value</code> or <code translate="no" dir="ltr">--key value</code> syntax. Also, these options must appear <em>before</em> the name of the Bazel command. Use <code translate="no" dir="ltr">startup --key=value</code> to list these in a <code translate="no" dir="ltr">.bazelrc</code> file.</p> <h4 id="output-base" data-text="--output_base=dir" tabindex="-1"><code translate="no" dir="ltr">--output_base=<var translate="no">dir</var></code></h4> <p>This option requires a path argument, which must specify a writable directory. Bazel will use this location to write all its output. The output base is also the key by which the client locates the Bazel server. By changing the output base, you change the server which will handle the command.</p> <p>By default, the output base is derived from the user's login name, and the name of the workspace directory (actually, its MD5 digest), so a typical value looks like: <code translate="no" dir="ltr">/var/tmp/google/_bazel_johndoe/d41d8cd98f00b204e9800998ecf8427e</code>.</p> <aside class="note"><strong>Note:</strong><span> The client uses the output base to find the Bazel server instance, so if you specify a different output base in a Bazel command, a different server will be found (or started) to handle the request. It's possible to perform two concurrent builds in the same workspace directory by varying the output base.</span></aside> <p>For example:</p> <pre translate="no" dir="ltr"> OUTPUT_BASE=/var/tmp/google/_bazel_johndoe/custom_output_base % bazel --output_base ${OUTPUT_BASE}1 build //foo & bazel --output_base ${OUTPUT_BASE}2 build //bar </pre> <p>In this command, the two Bazel commands run concurrently (because of the shell <code translate="no" dir="ltr">&amp;</code> operator), each using a different Bazel server instance (because of the different output bases). In contrast, if the default output base was used in both commands, then both requests would be sent to the same server, which would handle them sequentially: building <code translate="no" dir="ltr">//foo</code> first, followed by an incremental build of <code translate="no" dir="ltr">//bar</code>.</p> <aside class="note"><strong>Note:</strong><span> We recommend you do not use an NFS or similar networked file system for the root directory, as the higher access latency will cause noticeably slower builds.</span></aside> <h4 id="output-user-root" data-text="--output_user_root=dir" tabindex="-1"><code translate="no" dir="ltr">--output_user_root=<var translate="no">dir</var></code></h4> <p>Points to the root directory where output and install bases are created. The directory must either not exist or be owned by the calling user. In the past, this was allowed to point to a directory shared among various users but it's not allowed any longer. This may be allowed once <a href="https://github.com/bazelbuild/bazel/issues/11100" class="external">issue #11100</a> is addressed.</p> <p>If the <code translate="no" dir="ltr">--output_base</code> option is specified, it overrides using <code translate="no" dir="ltr">--output_user_root</code> to calculate the output base.</p> <p>The install base location is calculated based on <code translate="no" dir="ltr">--output_user_root</code>, plus the MD5 identity of the Bazel embedded binaries.</p> <p>You can use the <code translate="no" dir="ltr">--output_user_root</code> option to choose an alternate base location for all of Bazel's output (install base and output base) if there is a better location in your filesystem layout.</p> <aside class="note"><strong>Note:</strong><span> We recommend you do not use an NFS or similar networked file system for the root directory, as the higher access latency will cause noticeably slower builds.</span></aside> <h4 id="server-javabase" data-text="--server_javabase=dir" tabindex="-1"><code translate="no" dir="ltr">--server_javabase=<var translate="no">dir</var></code></h4> <p>Specifies the Java virtual machine in which <em>Bazel itself</em> runs. The value must be a path to the directory containing a JDK or JRE. It should not be a label. This option should appear before any Bazel command, for example:</p> <pre translate="no" dir="ltr"> % bazel --server_javabase=/usr/local/buildtools/java/jdk build //foo </pre> <p>This flag does <em>not</em> affect the JVMs used by Bazel subprocesses such as applications, tests, tools, and so on. Use build options <a href="#javabase">--javabase</a> or <a href="#host-javabase">--host_javabase</a> instead.</p> <p>This flag was previously named <code translate="no" dir="ltr">--host_javabase</code> (sometimes referred to as the 'left-hand side' <code translate="no" dir="ltr">--host_javabase</code>), but was renamed to avoid confusion with the build flag <a href="#host-javabase">--host_javabase</a> (sometimes referred to as the 'right-hand side' <code translate="no" dir="ltr">--host_javabase</code>).</p> <h4 id="host-jvm-args" data-text="--host_jvm_args=string" tabindex="-1"><code translate="no" dir="ltr">--host_jvm_args=<var translate="no">string</var></code></h4> <p>Specifies a startup option to be passed to the Java virtual machine in which <em>Bazel itself</em> runs. This can be used to set the stack size, for example:</p> <pre translate="no" dir="ltr"> % bazel --host_jvm_args="-Xss256K" build //foo </pre> <p>This option can be used multiple times with individual arguments. Note that setting this flag should rarely be needed. You can also pass a space-separated list of strings, each of which will be interpreted as a separate JVM argument, but this feature will soon be deprecated.</p> <p>That this does <em>not</em> affect any JVMs used by subprocesses of Bazel: applications, tests, tools, and so on. To pass JVM options to executable Java programs, whether run by <code translate="no" dir="ltr">bazel run</code> or on the command-line, you should use the <code translate="no" dir="ltr">--jvm_flags</code> argument which all <code translate="no" dir="ltr">java_binary</code> and <code translate="no" dir="ltr">java_test</code> programs support. Alternatively for tests, use <code translate="no" dir="ltr">bazel test --test_arg=--jvm_flags=foo ...</code>.</p> <h4 id="host-java-debug" data-text="--host_jvm_debug" tabindex="-1"><code translate="no" dir="ltr">--host_jvm_debug</code></h4> <p>This option causes the Java virtual machine to wait for a connection from a JDWP-compliant debugger before calling the main method of <em>Bazel itself</em>. This is primarily intended for use by Bazel developers.</p> <aside class="note"><strong>Note:</strong><span> This does <em>not</em> affect any JVMs used by subprocesses of Bazel: applications, tests, tools, etc.</span></aside> <h4 id="autodetect-server-javabase" data-text="--autodetect_server_javabase" tabindex="-1"><code translate="no" dir="ltr">--autodetect_server_javabase</code></h4> <p>This option causes Bazel to automatically search for an installed JDK on startup, and to fall back to the installed JRE if the embedded JRE isn't available. <code translate="no" dir="ltr">--explicit_server_javabase</code> can be used to pick an explicit JRE to run Bazel with.</p> <h4 id="batch" data-text="--batch" tabindex="-1"><code translate="no" dir="ltr">--batch</code></h4> <p>Batch mode causes Bazel to not use the <a href="/run/client-server">standard client/server mode</a>, but instead runs a bazel java process for a single command, which has been used for more predictable semantics with respect to signal handling, job control, and environment variable inheritance, and is necessary for running bazel in a chroot jail.</p> <p>Batch mode retains proper queueing semantics within the same output_base. That is, simultaneous invocations will be processed in order, without overlap. If a batch mode Bazel is run on a client with a running server, it first kills the server before processing the command.</p> <p>Bazel will run slower in batch mode, or with the alternatives described above. This is because, among other things, the build file cache is memory-resident, so it is not preserved between sequential batch invocations. Therefore, using batch mode often makes more sense in cases where performance is less critical, such as continuous builds.</p> <aside class="warning"><strong>Warning:</strong><span> <code translate="no" dir="ltr">--batch</code> is sufficiently slower than standard client/server mode. Additionally it might not support all of the features and optimizations which are made possible by a persistent Bazel server. If you're using <code translate="no" dir="ltr">--batch</code> for the purpose of build isolation, you should use the command option <code translate="no" dir="ltr">--nokeep_state_after_build</code>, which guarantees that no incremental in-memory state is kept between builds. In order to restart the Bazel server and JVM after a build, please explicitly do so using the "shutdown" command.</span></aside> <h4 id="max-idle-secs" data-text="--max_idle_secs=n" tabindex="-1"><code translate="no" dir="ltr">--max_idle_secs=<var translate="no">n</var></code></h4> <p>This option specifies how long, in seconds, the Bazel server process should wait after the last client request, before it exits. The default value is 10800 (3 hours). <code translate="no" dir="ltr">--max_idle_secs=0</code> will cause the Bazel server process to persist indefinitely.</p> <aside class="note"><strong>Note:</strong><span> this flag is only read if Bazel needs to start a new server. Changing this option will not cause the server to restart.</span></aside> <p>This option may be used by scripts that invoke Bazel to ensure that they do not leave Bazel server processes on a user's machine when they would not be running otherwise. For example, a presubmit script might wish to invoke <code translate="no" dir="ltr">bazel query</code> to ensure that a user's pending change does not introduce unwanted dependencies. However, if the user has not done a recent build in that workspace, it would be undesirable for the presubmit script to start a Bazel server just for it to remain idle for the rest of the day. By specifying a small value of <code translate="no" dir="ltr">--max_idle_secs</code> in the query request, the script can ensure that <em>if</em> it caused a new server to start, that server will exit promptly, but if instead there was already a server running, that server will continue to run until it has been idle for the usual time. Of course, the existing server's idle timer will be reset.</p> <h4 id="shutdown-on-low-sys-mem" data-text="--[no]shutdown_on_low_sys_mem" tabindex="-1"><code translate="no" dir="ltr">--[no]shutdown_on_low_sys_mem</code></h4> <p>If enabled and <code translate="no" dir="ltr">--max_idle_secs</code> is set to a positive duration, after the build server has been idle for a while, shut down the server when the system is low on memory. Linux only.</p> <p>In addition to running an idle check corresponding to max_idle_secs, the build server will starts monitoring available system memory after the server has been idle for some time. If the available system memory becomes critically low, the server will exit.</p> <h4 id="block-for-lock" data-text="--[no]block_for_lock" tabindex="-1"><code translate="no" dir="ltr">--[no]block_for_lock</code></h4> <p>If enabled, Bazel will wait for other Bazel commands holding the server lock to complete before progressing. If disabled, Bazel will exit in error if it cannot immediately acquire the lock and proceed.</p> <p>Developers might use this in presubmit checks to avoid long waits caused by another Bazel command in the same client.</p> <h4 id="io-nice-level" data-text="--io_nice_level=n" tabindex="-1"><code translate="no" dir="ltr">--io_nice_level=<var translate="no">n</var></code></h4> <p>Sets a level from 0-7 for best-effort IO scheduling. 0 is highest priority, 7 is lowest. The anticipatory scheduler may only honor up to priority 4. Negative values are ignored.</p> <h4 id="batch-cpu-scheduling" data-text="--batch_cpu_scheduling" tabindex="-1"><code translate="no" dir="ltr">--batch_cpu_scheduling</code></h4> <p>Use <code translate="no" dir="ltr">batch</code> CPU scheduling for Bazel. This policy is useful for workloads that are non-interactive, but do not want to lower their nice value. See 'man 2 sched_setscheduler'. This policy may provide for better system interactivity at the expense of Bazel throughput.</p> <h3 id="misc-options" data-text="Miscellaneous options" tabindex="-1">Miscellaneous options</h3> <h4 id="announce-rc" data-text="--[no]announce_rc" tabindex="-1"><code translate="no" dir="ltr">--[no]announce_rc</code></h4> <p>Controls whether Bazel announces startup options and command options read from the bazelrc files when starting up.</p> <h4 id="color" data-text="--color (yes|no|auto)" tabindex="-1"><code translate="no" dir="ltr">--color (yes|no|auto)</code></h4> <p>This option determines whether Bazel will use colors to highlight its output on the screen.</p> <p>If this option is set to <code translate="no" dir="ltr">yes</code>, color output is enabled. If this option is set to <code translate="no" dir="ltr">auto</code>, Bazel will use color output only if the output is being sent to a terminal and the TERM environment variable is set to a value other than <code translate="no" dir="ltr">dumb</code>, <code translate="no" dir="ltr">emacs</code>, or <code translate="no" dir="ltr">xterm-mono</code>. If this option is set to <code translate="no" dir="ltr">no</code>, color output is disabled, regardless of whether the output is going to a terminal and regardless of the setting of the TERM environment variable.</p> <h4 id="config" data-text="--config=name" tabindex="-1"><code translate="no" dir="ltr">--config=<var translate="no">name</var></code></h4> <p>Selects additional config section from <a href="/run/bazelrc#bazelrc-file-locations">the rc files</a>; for the current <code translate="no" dir="ltr">command</code>, it also pulls in the options from <code translate="no" dir="ltr">command:name</code> if such a section exists. Can be specified multiple times to add flags from several config sections. Expansions can refer to other definitions (for example, expansions can be chained).</p> <h4 id="curses" data-text="--curses (yes|no|auto)" tabindex="-1"><code translate="no" dir="ltr">--curses (yes|no|auto)</code></h4> <p>This option determines whether Bazel will use cursor controls in its screen output. This results in less scrolling data, and a more compact, easy-to-read stream of output from Bazel. This works well with <code translate="no" dir="ltr">--color</code>.</p> <p>If this option is set to <code translate="no" dir="ltr">yes</code>, use of cursor controls is enabled. If this option is set to <code translate="no" dir="ltr">no</code>, use of cursor controls is disabled. If this option is set to <code translate="no" dir="ltr">auto</code>, use of cursor controls will be enabled under the same conditions as for <code translate="no" dir="ltr">--color=auto</code>.</p> <h4 id="show-timestamps" data-text="--[no]show_timestamps" tabindex="-1"><code translate="no" dir="ltr">--[no]show_timestamps</code></h4> <p>If specified, a timestamp is added to each message generated by Bazel specifying the time at which the message was displayed.</p> </div> <devsite-thumb-rating position="footer"> </devsite-thumb-rating> <devsite-feedback position="footer" project-name="Bazel" product-id="5052038" bucket="https-bazel-build" context="" version="t-devsite-webserver-20241114-r00-rc02.464921008191574316" data-label="Send Feedback Button" track-type="feedback" track-name="sendFeedbackLink" track-metadata-position="footer" class="nocontent" project-icon="https://www.gstatic.com/devrel-devsite/prod/v870e399c64f7c43c99a3043db4b3a74327bb93d0914e84a0c3dba90bbfd67625/bazel/images/touchicon-180.png" > <button> Send feedback </button> </devsite-feedback> <div class="devsite-floating-action-buttons"> </div> </article> <devsite-content-footer class="nocontent"> <p>Except as otherwise noted, the content of this page is licensed under the <a href="https://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 License</a>, and code samples are licensed under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache 2.0 License</a>. For details, see the <a href="https://developers.google.com/site-policies">Google Developers Site Policies</a>. Java is a registered trademark of Oracle and/or its affiliates.</p> <p>Last updated 2024-11-13 UTC.</p> </devsite-content-footer> <devsite-notification > </devsite-notification> <div class="devsite-content-data"> <template class="devsite-thumb-rating-feedback"> <devsite-feedback position="thumb-rating" project-name="Bazel" product-id="5052038" bucket="https-bazel-build" context="" version="t-devsite-webserver-20241114-r00-rc02.464921008191574316" data-label="Send Feedback Button" track-type="feedback" track-name="sendFeedbackLink" track-metadata-position="thumb-rating" class="nocontent" project-icon="https://www.gstatic.com/devrel-devsite/prod/v870e399c64f7c43c99a3043db4b3a74327bb93d0914e84a0c3dba90bbfd67625/bazel/images/touchicon-180.png" > <button> Need to tell us more? </button> </devsite-feedback> </template> <template class="devsite-content-data-template"> [[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-11-13 UTC."],[],[]] </template> </div> </devsite-content> </main> <devsite-footer-promos class="devsite-footer"> </devsite-footer-promos> <devsite-footer-linkboxes class="devsite-footer"> <nav class="devsite-footer-linkboxes nocontent" aria-label="Footer links"> <ul class="devsite-footer-linkboxes-list"> <li class="devsite-footer-linkbox "> <h3 class="devsite-footer-linkbox-heading no-link">About</h3> <ul class="devsite-footer-linkbox-list"> <li class="devsite-footer-linkbox-item"> <a href="/community/users" class="devsite-footer-linkbox-link gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Footer Link (index 1)" > Who's using Bazel </a> </li> <li class="devsite-footer-linkbox-item"> <a href="/contribute/" class="devsite-footer-linkbox-link gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Footer Link (index 2)" > Contribute </a> </li> <li class="devsite-footer-linkbox-item"> <a href="/contribute/contribution-policy" class="devsite-footer-linkbox-link gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Footer Link (index 3)" > Governance model </a> </li> <li class="devsite-footer-linkbox-item"> <a href="/release" class="devsite-footer-linkbox-link gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Footer Link (index 4)" > Release model </a> </li> <li class="devsite-footer-linkbox-item"> <a href="/brand" class="devsite-footer-linkbox-link gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Footer Link (index 5)" > Brand guidelines </a> </li> </ul> </li> <li class="devsite-footer-linkbox "> <h3 class="devsite-footer-linkbox-heading no-link">Stay connected</h3> <ul class="devsite-footer-linkbox-list"> <li class="devsite-footer-linkbox-item"> <a href="//blog.bazel.build" class="devsite-footer-linkbox-link gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Footer Link (index 1)" > Blog </a> </li> <li class="devsite-footer-linkbox-item"> <a href="//github.com/bazelbuild/bazel" class="devsite-footer-linkbox-link gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Footer Link (index 2)" > GitHub </a> </li> <li class="devsite-footer-linkbox-item"> <a href="//twitter.com/bazelbuild" class="devsite-footer-linkbox-link gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Footer Link (index 3)" > Twitter </a> </li> <li class="devsite-footer-linkbox-item"> <a href="//youtube.com/user/googleOSPO" class="devsite-footer-linkbox-link gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Footer Link (index 4)" > YouTube </a> </li> </ul> </li> <li class="devsite-footer-linkbox "> <h3 class="devsite-footer-linkbox-heading no-link">Support</h3> <ul class="devsite-footer-linkbox-list"> <li class="devsite-footer-linkbox-item"> <a href="/help" class="devsite-footer-linkbox-link gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Footer Link (index 1)" > Support </a> </li> <li class="devsite-footer-linkbox-item"> <a href="//github.com/bazelbuild/bazel/issues" class="devsite-footer-linkbox-link gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Footer Link (index 2)" > Issue tracker </a> </li> <li class="devsite-footer-linkbox-item"> <a href="//slack.bazel.build" class="devsite-footer-linkbox-link gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Footer Link (index 3)" > Slack </a> </li> <li class="devsite-footer-linkbox-item"> <a href="//stackoverflow.com/questions/tagged/bazel" class="devsite-footer-linkbox-link gc-analytics-event" data-category="Site-Wide Custom Events" data-label="Footer Link (index 4)" > Stack Overflow </a> </li> </ul> </li> </ul> </nav> </devsite-footer-linkboxes> <devsite-footer-utility class="devsite-footer"> <div class="devsite-footer-utility nocontent"> <nav class="devsite-footer-utility-links" aria-label="Utility links"> <ul class="devsite-footer-utility-list"> <li class="devsite-footer-utility-item "> <a class="devsite-footer-utility-link gc-analytics-event" href="//policies.google.com/terms" data-category="Site-Wide Custom Events" data-label="Footer Terms link" > Terms </a> </li> <li class="devsite-footer-utility-item "> <a class="devsite-footer-utility-link gc-analytics-event" href="//policies.google.com/privacy" data-category="Site-Wide Custom Events" data-label="Footer Privacy link" > Privacy </a> </li> <li class="devsite-footer-utility-item glue-cookie-notification-bar-control"> <a class="devsite-footer-utility-link gc-analytics-event" href="#" data-category="Site-Wide Custom Events" data-label="Footer Manage cookies link" aria-hidden="true" > Manage cookies </a> </li> </ul> <devsite-language-selector> <ul role="presentation"> <li role="presentation"> <a role="menuitem" lang="en" >English</a> </li> <li role="presentation"> <a role="menuitem" lang="es_419" >Español – América Latina</a> </li> <li role="presentation"> <a role="menuitem" lang="id" >Indonesia</a> </li> <li role="presentation"> <a role="menuitem" lang="pt_br" >Português – Brasil</a> </li> <li role="presentation"> <a role="menuitem" lang="vi" >Tiếng Việt</a> </li> <li role="presentation"> <a role="menuitem" lang="tr" >Türkçe</a> </li> <li role="presentation"> <a role="menuitem" lang="he" >עברית</a> </li> <li role="presentation"> <a role="menuitem" lang="ar" >العربيّة</a> </li> <li role="presentation"> <a role="menuitem" lang="fa" >فارسی</a> </li> <li role="presentation"> <a role="menuitem" lang="hi" >हिंदी</a> </li> <li role="presentation"> <a role="menuitem" lang="bn" >বাংলা</a> </li> <li role="presentation"> <a role="menuitem" lang="th" >ภาษาไทย</a> </li> <li role="presentation"> <a role="menuitem" lang="zh_cn" >中文 – 简体</a> </li> <li role="presentation"> <a role="menuitem" lang="zh_tw" >中文 – 繁體</a> </li> <li role="presentation"> <a role="menuitem" lang="ja" >日本語</a> </li> <li role="presentation"> <a role="menuitem" lang="ko" >한국어</a> </li> </ul> </devsite-language-selector> </nav> </div> </devsite-footer-utility> <devsite-panel></devsite-panel> </section></section> <devsite-sitemask></devsite-sitemask> <devsite-snackbar></devsite-snackbar> <devsite-tooltip ></devsite-tooltip> <devsite-heading-link></devsite-heading-link> <devsite-analytics> <script type="application/json" analytics>[{"dimensions": {"dimension4": "en", "dimension1": "Signed out", "dimension3": "en", "dimension5": false, "dimension2": false}, "gaid": "UA-61082125-3", "metrics": {}, "purpose": 0}]</script> <script type="application/json" tag-management>{"at": "True", "ga4": [{"id": "G-GBZW986TQ3", "purpose": 0}], "ga4p": [{"id": "G-GBZW986TQ3", "purpose": 0}], "gtm": [], "parameters": {"internalUser": "False", "language": {"machineTranslated": "False", "requested": "en", "served": "en"}, "pageType": "article", "projectName": "Bazel", "signedIn": "False", "tenant": "bazel", "recommendations": {"sourcePage": "", "sourceType": 0, "sourceRank": 0, "sourceIdenticalDescriptions": 0, "sourceTitleWords": 0, "sourceDescriptionWords": 0, "experiment": ""}, "experiment": {"ids": ""}}}</script> </devsite-analytics> <devsite-badger></devsite-badger> <script nonce="tUa/Q5EzWbQHo3OucL7ZnrndUwP8VS"> (function(d,e,v,s,i,t,E){d['GoogleDevelopersObject']=i; t=e.createElement(v);t.async=1;t.src=s;E=e.getElementsByTagName(v)[0]; E.parentNode.insertBefore(t,E);})(window, document, 'script', 'https://www.gstatic.com/devrel-devsite/prod/v870e399c64f7c43c99a3043db4b3a74327bb93d0914e84a0c3dba90bbfd67625/bazel/js/app_loader.js', '[40,"en",null,"/js/devsite_app_module.js","https://www.gstatic.com/devrel-devsite/prod/v870e399c64f7c43c99a3043db4b3a74327bb93d0914e84a0c3dba90bbfd67625","https://www.gstatic.com/devrel-devsite/prod/v870e399c64f7c43c99a3043db4b3a74327bb93d0914e84a0c3dba90bbfd67625/bazel","https://bazel-dot-devsite-v2-prod-3p.appspot.com",null,null,["/_pwa/bazel/manifest.json","https://www.gstatic.com/devrel-devsite/prod/v870e399c64f7c43c99a3043db4b3a74327bb93d0914e84a0c3dba90bbfd67625/images/video-placeholder.svg","https://www.gstatic.com/devrel-devsite/prod/v870e399c64f7c43c99a3043db4b3a74327bb93d0914e84a0c3dba90bbfd67625/bazel/images/favicon-prod.png","https://www.gstatic.com/devrel-devsite/prod/v870e399c64f7c43c99a3043db4b3a74327bb93d0914e84a0c3dba90bbfd67625/bazel/images/lockup.svg","https://fonts.googleapis.com/css?family=Roboto:300,400,400italic,500,500italic,700,700italic|Roboto+Mono:400,500,700&display=swap"],1,null,[1,6,8,12,14,17,21,25,50,52,63,70,75,76,80,87,91,92,93,97,98,100,101,102,103,104,105,107,108,109,110,112,113,117,118,120,122,124,125,126,127,129,130,131,132,133,134,135,136,138,140,141,147,148,149,151,152,156,157,158,159,161,163,164,168,169,170,179,180,182,183,186,191,193,196],"AIzaSyCNm9YxQumEXwGJgTDjxoxXK6m1F-9720Q","AIzaSyCc76DZePGtoyUjqKrLdsMGk_ry7sljLbY","bazel.build","AIzaSyB9bqgQ2t11WJsOX8qNsCQ6U-w91mmqF-I","AIzaSyAdYnStPdzjcJJtQ0mvIaeaMKj7_t6J_Fg",null,null,null,["MiscFeatureFlags__emergency_css","SignIn__enable_oauth_multi_account_support","MiscFeatureFlags__enable_variable_operator","Profiles__enable_release_notes_notifications","Cloud__enable_cloudx_ping","Cloud__enable_cloud_shell","Cloud__enable_legacy_calculator_redirect","Cloud__enable_llm_concierge_chat","Profiles__enable_profile_collections","Concierge__enable_pushui","Search__enable_page_map","MiscFeatureFlags__enable_firebase_utm","Search__enable_ai_eligibility_checks","Search__enable_suggestions_from_borg","Profiles__enable_page_saving","Profiles__enable_complete_playlist_endpoint","CloudShell__cloud_shell_button","TpcFeatures__enable_required_headers","DevPro__enable_cloud_innovators_plus","CloudShell__cloud_code_overflow_menu","BookNav__enable_tenant_cache_key","Profiles__require_profile_eligibility_for_signin","Profiles__enable_developer_profiles_callout","Profiles__enable_completecodelab_endpoint","Analytics__enable_clearcut_logging","Cloud__enable_cloud_shell_fte_user_flow","Profiles__enable_awarding_url","Profiles__enable_recognition_badges","Profiles__enable_public_developer_profiles","Cloud__enable_cloud_facet_chat","OnSwitch__enable","Cloud__enable_cloudx_experiment_ids","MiscFeatureFlags__developers_footer_image","DevPro__enable_developer_subscriptions","TpcFeatures__enable_mirror_tenant_redirects","Cloud__enable_cloud_dlp_service","SignIn__enable_refresh_access_tokens","MiscFeatureFlags__enable_view_transitions","Search__enable_dynamic_content_confidential_banner","Experiments__reqs_query_experiments","MiscFeatureFlags__enable_project_variables","MiscFeatureFlags__enable_explain_this_code","Cloud__enable_free_trial_server_call","EngEduTelemetry__enable_engedu_telemetry","SignIn__enable_auto_login_multi_account","MiscFeatureFlags__developers_footer_dark_image","Profiles__enable_dashboard_curated_recommendations"],null,null,"AIzaSyA58TaKli1DculwmAmbpzLVGuWc8eCQgQc","https://developerscontentserving-pa.googleapis.com","AIzaSyDWBU60w0P9hEkr29kkksYs8Z7gvZ8u_wc","https://developerscontentsearch-pa.googleapis.com",2,4,null,"https://developerprofiles-pa.googleapis.com",[40,"bazel","Bazel","bazel.build",null,"bazel-dot-devsite-v2-prod-3p.appspot.com",null,null,[null,1,null,null,null,null,null,null,null,null,null,[1],null,null,null,null,null,null,[1],null,null,null,null,[1,1,1],[1,1,null,1,1]],null,[56,null,null,null,null,null,"/images/lockup.svg",null,null,null,null,1,null,null,null,null,null,null,null,null,null,1,null,null,null,null,[]],[],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[6,7,1,18,20,22,23,29,37,39,40,43],null,[[],[1,1]],[[["UA-61082125-3"],["UA-61082125-4"],null,null,["UA-61082125-5"],null,null,[["G-GBZW986TQ3"],null,null,[["G-GBZW986TQ3",1]]],[["UA-61082125-3",1]],null,[["UA-61082125-5",1]],null,1],[[5,8],[3,4],[4,5],[2,2],[1,1]]],null,4]]') </script> <devsite-a11y-announce></devsite-a11y-announce> </body> </html>

CINXE.COM

Commands and Options | Bazel