Bazel online document;Note=Erxin.txt

Bazel online document;Note=Erxin

# introduction 
- reference 

https://docs.bazel.build/versions/main/tutorial/cpp.html#home




# IDE
- vscode 
https://marketplace.visualstudio.com/items?itemName=BazelBuild.vscode-bazel
- emacs 
https://github.com/bazelbuild/emacs-bazel-mode
- vim 
https://github.com/bazelbuild/vim-bazel
- autocompelete for source code 
c language family
https://github.com/hedronvision/bazel-compile-commands-extractor





# install
- reference  
https://docs.bazel.build/versions/main/install-windows.html
- install prerequest cv redistributable 
- install bazel 
- add bazel*.exe to PATH
- install compiler for 
    + MSYS2 x64 provide bash for windows 
    
    Common MSYS2 packages
    
    + VS 2019 
    + jdk 
    + python 

- Bazelisk is a wrapper for Bazel written in Go. It automatically picks a good version of Bazel given your current working directory, downloads it from the official server 

On macOS: brew install bazelisk.

On Windows: choco install bazelisk.

supports a .bazeliskrc file in the root directory of a workspace and the user home directory. 

BAZELISK_BASE_URL
BAZELISK_CLEAN
BAZELISK_GITHUB_TOKEN
BAZELISK_HOME
BAZELISK_INCOMPATIBLE_FLAGS
BAZELISK_SHUTDOWN
BAZELISK_SKIP_WRAPPER
BAZELISK_USER_AGENT
USE_BAZEL_VERSION

- https://github.com/bazelbuild/bazel-toolchains is a repository where Google hosts the source code for a CLI tool that can be used to generate Bazel toolchain configs.

C/C++ CROSSTOOL file,
BUILD file with toolchain rules, and
wrapper scripts.

- Starlark (formerly known as Skylark) is a language intended for use as a configuration language. It was designed for the Bazel build system

https://github.com/bazelbuild/starlark

```
# Define a number
number = 18

# Define a dictionary
people = {
    "Alice": 22,
    "Bob": 40,
    "Charlie": 55,
    "Dave": 14,
}

names = ", ".join(people.keys())  # Alice, Bob, Charlie, Dave
```


- startlark source code 
```
case WINDOWS:
    switch (CPU.getCurrent()) {
        case X86_64:
            return "x64_windows";
            ...
case LINUX:
    switch (CPU.getCurrent()) {
        case X86_64:
            return "k8";
```



# Define a function
```
def greet(name):
    """Return a greeting."""
    return "Hello {}!".format(name)

greeting = greet(names)

above30 = [name for name, age in people.items() if age >= 30]

print("{} people are above 30.".format(len(above30)))

def fizz_buzz(n):
    """Print Fizz Buzz numbers from 1 to n."""
    for i in range(1, n + 1):
        s = ""
        if i % 3 == 0:
            s += "Fizz"
        if i % 5 == 0:
            s += "Buzz"
        print(s if s else i)

fizz_buzz(20)
```

- Skylib is a library of Starlark functions for manipulating collections, file paths, and various other data types in the domain of Bazel build rules.

https://github.com/bazelbuild/bazel-skylib

.bzl files in the lib directory defines a "module"—a struct that contains a set of related functions and/or other symbols that can be loaded

``` 
load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")

bazel_skylib_workspace()
```

    + modules (in lib/)
    
collections
dicts
partial
paths
selects
sets - deprecated, use new_sets
new_sets
shell
structs
subpackages
types
unittest
versions

    + rules (in rules/)
analysis_test
build_test
common_settings
copy_directory
copy_file
diff_test
expand_template
native_binary and native_test
run_binary
select_file
write_file

    + add a module to Skylib:

Create a new .bzl file in the lib directory.

Write the functions or other symbols (such as constants) in that file, defining them privately (prefixed by an underscore).

Create the exported module struct, mapping the public names of the symbols to their implementations

Add unit test for your module in the tests directory 

```
def _manipulate():
  ...

things = struct(
    manipulate=_manipulate,
)
```




# Bazel tutorial, build a c++ project 
- examples 

git clone https://github.com/bazelbuild/examples

- a single target residing in a single package.

- The WORKSPACE file , which identifies the directory and its contents as a Bazel workspace

- One or more BUILD files , which tell Bazel how to build different parts of the project. A directory within the workspace that contains a BUILD file is a package.

- BUILD file requires at least one rule as a set of instructions

- Each instance of a build rule in the BUILD file is called a target and points to a specific set of source files and dependencies

    + c build file 

cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
)

cc_binary rule. The rule tells Bazel to build a self-contained executable binary from the hello-world.cc

- build project 

$ bazel build //main:hello-world

- review the dependency graph. To visualize the sample project’s dependencies, you can generate a text representation of the dependency graph

$ bazel query --notool_deps --noimplicit_deps "deps(//main:hello-world)"  --output graph

$ xdot <(bazel query --notool_deps --noimplicit_deps "deps(//main:hello-world)" --output graph)

- refine your bazel build 

- multiple build targets, split larger projects into multiple targets and packages. This allows for fast incremental builds. add two cc_binary 

```
cc_library(
    name = "hello-greet",
    srcs = ["hello-greet.cc"],
    hdrs = ["hello-greet.h"],
)

cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
    deps = [
        ":hello-greet",
    ],
)
```

The deps attribute in the hello-world target tells Bazel that the hello-greet library is required to build the hello-world binary

- multiple packages 

//main/BUILD
```
cc_library(
    name = "hello-time",
    srcs = ["hello-time.cc"],
    hdrs = ["hello-time.h"],
    visibility = ["//main:__pkg__"],
)
```

//lib/BUILD 
```
cc_library(
    name = "hello-greet",
    srcs = ["hello-greet.cc"],
    hdrs = ["hello-greet.h"],
)

cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
    deps = [
        ":hello-greet",
        "//lib:hello-time",
    ],
)
```



# First build guide 
https://bazel.build/start
## C++ 
## Java 
## Android 
## iOS 





# Build Concepts 
## Workspaces, packages, targets 
- A workspace is a directory tree on your filesystem that contains the source files for the software you want to build

WORKSPACE.bazel file as an alias of WORKSPACE file.

- Code is organized in repositories.

- Pacakges, The primary unit of code organization in a repository is the package. A package is defined as a directory containing a file named BUILD (or BUILD.bazel).

- Targets, A package is a container of targets, which are defined in the package's BUILD file. Most targets are one of two principal kinds, files and rules.

An invariant of all rules is that the files generated by a rule always belong to the same package as the rule itself; it is not possible to generate files into another package.

- Package groups are sets of packages whose purpose is to limit accessibility of certain rules.



## Labels 
- All targets belong to exactly one package. The name of a target is called its label. Every label uniquely identifies a target.

@myrepo//my/app/main:app_binary

The first part of the label is the repository name, @myrepo// the repository identifier may be abbreviated as //. The labels equal to 

//my/app/main:app_binary

The second part of the label is the un-qualified package name my/app/main the path to the package relative to the repository root.

the label refers to the same package it is used in, the package name (and optionally, the colon) may be omitted. Target in another pacakge should be reference with full name. 

```
app_binary
//equal to 
:app_binary
```

The name of a file target in a subdirectory of the package is the file's path relative to the package root

-  use of //my/app to refer to a package is encouraged in the specification of a package_group or in .bzl files, because it clearly communicates that the package name is absolute and rooted in the top-level directory of the workspace.

- The part of the label after the colon, app_binary is the un-qualified target name. When it matches the last component of the package path

//my/app/main:testdata/input.txt


- Labels starting with @// are references to the main repository, which will still work even from external repositories.

Therefore @//a/b/c is different from //a/b/c 

@//a/b/c is reference back to main repository 
//a/b/c is reference to external repository itself 

- Target names, is the name of the target within the package. 
- Package name is the directory containing the BUILD file relative to the workspace root directory 
- Rules A rule specifies the relationship between inputs and outputs, and the steps to build the outputs. Rules can be of one of many different kinds

BUILD files declare targets by invoking rules.

```
cc_binary(
    name = "my_app",
    srcs = ["my_app.cc"],
    deps = [
        "//absl/base",
        "//absl/strings",
    ],
)
```

Every rule has a set of attributes; the applicable attributes for a given rule, and the significance and semantics of each attribute are a function of the rule's kind. 



## BUILD files 
- BUILD files are evaluated using an imperative language, Starlark. a build rule function, such as cc_library, is executed, it creates a new target in the graph. This target can later be referred using a label.

- Loading an extension Bazel extensions are files ending in .bzl. Use the load statement to import a symbol from an extension.

```
load("//foo/bar:file.bzl", "some_library")
```
The first argument of load is a label identifying a .bzl file. If it's a relative label, it is resolved with respect to the package  containing the current bzl file. 

```
load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule")
```
In a .bzl file, symbols starting with _ are not exported and cannot be loaded from another file.

    + *_binary rules build executable in a given language. build tool's binary output tree at the corresponding name for the rule's label, so //my:program would appear at (for example) $(BINDIR)/my/program.

    + *_test rules are a specialization of a *_binary rule 

    + *_library rules specify separately-compiled modules in the given programming language.
    
- types of depdencies 

scrs dependencies 

deps dependencies 

data dependencies, if a binary/library/test needs some files to run, specify them (or a build rule containing them) in data 

${TEST_SRCDIR}/workspace/path/to/data/file.

glob() to be recursive. Recommended — data = glob(["testdata/**"])

  
    
    

## Dependencies 
- actual and declared dependencies 

A target X is actually dependent on target Y if Y must be present, built, and up-to-date in order for X to be built correctly

- BUILD file writers must explicitly declare all of the actual direct dependencies for every rule to the build system



## Visibility 
- Target visibility controls who may depend on your target

//visibility:public

//visibility:private": Does not grant any additional access;

//foo/bar:__pkg__  Grants access to //foo/bar

//foo/bar:__subpackages__ Grants access //foo/bar and all of its direct and indirect subpackages.

//some_pkg:my_package_group Grants access to all of the packages that are part of the given package_group.

- package group use different syntax compare to target 

the forms "//foo/bar:__pkg__" and "//foo/bar:__subpackages__" are respectively replaced by "//foo/bar" and "//foo/bar/...". 

Likewise, "//visibility:public" and "//visibility:private" are just "public" and "private".

- Use package group instead of specifying in each target 

- Rule target visibility 

The value of the default_visibility argument of the package statement in the target's BUILD file. otherwise default is private 


```
# This target is visible to everyone
cc_binary(
    name = "executable",
    visibility = ["//visibility:public"],
    deps = [":library"],
)

# This target is visible only to targets declared in the same package
cc_library(
    name = "library",
    # No visibility -- defaults to private since no
    # package(default_visibility = ...) was used.
)

cc_library(
    name = "subject",
    visibility = [
        "//noun:__pkg__",
        "//object:__pkg__",
    ],
)

# Our friends are packages //frobber, //fribber and any
# subpackage of //fribber.
package_group(
    name = "friends",
    packages = [
        "//fribber/...",
        "//frobber",
    ],
)
```

- generated file has the same visibility as the rule target that generates it.     

- source file target visibility, explicitly set the visibility of a source file target by calling exports_files. When no visibility argument is passed to exports_files, it makes the visibility public

the flag --incompatible_no_implicit_file_export. If the flag is set, the visibility is private. Else, the legacy behavior applies: The visibility is the same as the BUILD file's default_visibility


```
//frobber/data/BUILD
exports_files(["readme.txt"])

//frobber/bin/BUILD
cc_binary(
  name = "my-program",
  data = ["//frobber/data:readme.txt"],
)
```

- config setting visibility is not enforced by default 

flags to control the behavior
```
--incompatible_enforce_config_setting_visibility enables visibility checking for these targets.
--incompatible_config_setting_private_default_visibility causes config_settings that do not specify a visibility to respect the package's default_visibility
``` 

- package group targets visibility are always public 

- visibility of implicit dependencies 

some rules have implicit, such as cc_library might create dependency to an executable target. 

the target being depended on must be visible to every instance of the rule. 

change this behavior by setting --incompatible_visibility_private_attributes_at_definition. When enabled,

- load visibility 

To set the load visibility of a .bzl file, call the visibility() function from within the file.

disable load visibility enforcement by setting --check_bzl_visibility=false

- declaring load visibility, the default load visibility is always public.

```
# Available to subpackages and to mylib's tests.
visibility(["//mylib/...", "//tests/mylib/..."])

visibility("public")
```
- load visibility practices

    + combined multiple load visibility into one central file 
    
```
# //mylib/internal_defs.bzl

visibility("private")

clients = [
    "//foo",
    "//bar/baz/...",
    ...
]

# //mylib/feature_A.bzl

load(":internal_defs.bzl", "clients")
visibility(clients)

...

# //mylib/feature_B.bzl

load(":internal_defs.bzl", "clients")
visibility(clients)
```

- composing visibilities 

```
# //mylib/macros.bzl

load(":internal_defs.bzl", "our_packages")
load("//some_big_client:defs.bzl", "their_remaining_uses)

# List concatenation. Duplicates are fine.
visibility(our_packages + their_remaining_uses)
```
- protecting individual symbols

```
# //mylib/internal_defs.bzl

# Can't be public, because internal_helper shouldn't be exposed to the world.
visibility("private")

# Can't be underscore-prefixed, because this is
# needed by other .bzl files in mylib.
def internal_helper(...):
    ...

def public_util(...):
    ...


# //mylib/defs.bzl

load(":internal_defs", "internal_helper", _public_util="public_util")
visibility("public")

# Re-export public_util from this file by assigning it to a global variable.

public_util = _public_util
```

- There is a Buildifier lint that provides a warning if users load a file from a directory named internal or private





## Hermeticity 
- a hermetic build system always returns the same output by isolating the build from changes to the host system.

    + Isolation: Hermetic build systems treat tools as source code. They download copies of tools and manage their storage and use inside managed file trees
    
    + Source identity: Hermetic build systems try to ensure the sameness of inputs. Check code hash 
    
- benefits 

speed 

parallel execution '

multiple builds 

reproducibility 



# Command line completion 
- bash 

the Bash completion script is already installed in /etc/bash_completion.d.

    + apt get will automatic install 
    + homebrew will automatic install 
    + from installer 
    
    

# Bazel Glossary 
- action, a command to run during the build 
- action cache, stores a mapping of executed actions 
- action graph  in-memory graph of actions and the artifacts
- action graph query, a query tool that can query over build actions.  
- action key, the cache key of an action 
- analysis phase, The second phase of a build. Processes the target graph specified in BUILD files to produce in memory action graph 
- artifact 
- aspect, create additional actions in their dependencies
- A composition mechanism whereby aspects can be applied to the results of other aspects.
- attribute A parameter to a rule, used to express per-target build information
- BUILD file is the main configuration file that tells Bazel what software outputs to build
- BUILD.bazel file, Takes precedence over a BUILD file
- .bzl file defines rules, macros and constants written in starlark 
- A Starlark-defined piece of configuration. Transitions can set build settings to change a subgraph's configuration
- clean build 
- client-server model 
- command like bazel build 
- command flags 
- configuration 
- configuration trimming, only including the pieces of configuration a target actually needs. For example, if you build Java binary //:j with C++ dependency //:c, it's wasteful to include the value of --javacopt
- configured query, A query tool that queries over configured targets
- configured target, The result of evaluating a target with a configuration. The analysis phase produces this by combining the build's options
- correctness
- dependency
- depset, depsets is time and space efficient, because it’s common to have very large depsets (hundreds of thousands of files). 
- disk cache, a local on disk blob store 
- distdir a read-only directory containing files that bazel would other wise fetch 
- dynamic execution 
- execution phase, the thrid phase of  a build 
- execution root, the workspace's output base 
- A build is hermetic if there are no external influences on its build and test operations, which helps to make sure that results are deterministic and correct
- incremental build 
- label 
- loading phase  build where Bazel parses WORKSPACE, BUILD, and .bzl files to create packages.
- macro 
- mnemonic, Mnemonics can be used as identifiers for spawn strategy selections.
- native rules, Rules that are built into Bazel and implemented in Java.
- output groups,  Rules put their usual outputs in the "default output group" (e.g the .jar file of a java_library, .a and .so for cc_library targets)
- output user root, the directory name is derived from the user's system 
- package 
- package group 
- platform
- provider, A schema describing a unit of information to pass between rule targets along dependency relationships. like compiler options, transitive source or output files, and build metadata. conjunction with depsets to store accumulated transitive data. 
- A schema for defining rule targets in a BUILD file, such as cc_library.
- A target that is an instance of a rule. 
- The runtime dependencies of an executable target. Most commonly, the executable is the executable output of a test rule
- sandboxing 
- stamping, a feature to embed additional information into bazel-built artifacts 
- starlark, the extension language for writing rules and macros 
- startup flags, The set of flags specified between bazel and the command, for example, bazel --host_jvm_debug build.
- target, An object that is defined in a BUILD file and identified by a label. Targets represent the buildable units of a workspace. declare by instantiating a rule. 
- target graph, An in-memory graph of targets and their dependencies. 
- target pattern, A way to specify a group of targets on the command line. Commonly used patterns are :all (all rule targets), :* (all rule + file targets), ...
- A set of tools to build outputs for a language. Typically, a toolchain includes compilers, linkers, interpreters or/and linters. 
- A build target is top-level if it’s requested on the Bazel command line.
- transition A mapping of configuration state from one value to another. Enables targets in the build graph to have different configurations. certain parts of the target graph is forked with distinct configurations for each fork. 
- tree artifact, An artifact that represents a collection of files. Since these files are not themselves artifacts
- visibility, target visibility to control where the target can be referenced. load visibility for controlling a build or .bzl file may load a given .bzl

- workspace, containing a workspace file start, label that start with // are relative to workspace directory 
- workspace file can be empty although it usually contains external repositorty declarations to fetch 



# Language specific rules 
https://bazel.build/reference/be/overview
- c/c++ 

    + rules 
cc_binary
cc_import
cc_library
cc_proto_library
fdo_prefetch_hints
fdo_profile
propeller_optimize
cc_test
cc_toolchain
cc_toolchain_suite

    + cc_binary implicit output targets  
cc_binary(name, deps, srcs, data, additional_linker_inputs, args, compatible_with, copts, defines, deprecation, distribs, env, exec_compatible_with, exec_properties, features, includes, licenses, linkopts, linkshared, linkstatic, local_defines, malloc, nocopts, output_licenses, restricted_to, stamp, tags, target_compatible_with, testonly, toolchains, visibility, win_def_file)

    + cc_import, allows users to import precompiled c/c++ libraries 
                                          
cc_import(name, data, hdrs, alwayslink, compatible_with, deprecation, distribs, features, interface_library, licenses, restricted_to, shared_library, static_library, system_provided, tags, target_compatible_with, testonly, visibility)

    
link static library 
```
cc_import(
  name = "mylib",
  hdrs = ["mylib.h"],
  static_library = "libmylib.a",
  # If alwayslink is turned on,
  # libmylib.a will be forcely linked into any binary that depends on it.
  # alwayslink = 1,
)
```

linking shared library 
```
cc_import(
  name = "mylib",
  hdrs = ["mylib.h"],
  shared_library = "libmylib.so",
)
```   

linking a shared library with interface library 
```
cc_import(
  name = "mylib",
  hdrs = ["mylib.h"],
  # mylib.lib is an import library for mylib.dll which will be passed to linker
  interface_library = "mylib.lib",
  # mylib.dll will be available for runtime
  shared_library = "mylib.dll",
)
```

linking a shared library with system_provided=True 
```
cc_import(
  name = "mylib",
  hdrs = ["mylib.h"],
  # mylib.lib is an import library for mylib.dll which will be passed to linker
  interface_library = "mylib.lib",
  # mylib.dll is provided by system environment, for example it can be found in PATH.
  # This indicates that Bazel is not responsible for making mylib.dll available.
  system_provided = 1,
)
```

linking to static or shared library 
```
cc_import(
  name = "mylib",
  hdrs = ["mylib.h"],
  static_library = "libmylib.a",
  shared_library = "libmylib.so",
)

# first will link to libmylib.a
cc_binary(
  name = "first",
  srcs = ["first.cc"],
  deps = [":mylib"],
  linkstatic = 1, # default value
)

# second will  link to libmylib.so
cc_binary(
  name = "second",
  srcs = ["second.cc"],
  deps = [":mylib"],
  linkstatic = 0,
)
```

on windows 
```
cc_import(
  name = "mylib",
  hdrs = ["mylib.h"],
  static_library = "libmylib.lib", # A normal static library
  interface_library = "mylib.lib", # An import library for mylib.dll
  shared_library = "mylib.dll",
)

# first will link to libmylib.lib
cc_binary(
  name = "first",
  srcs = ["first.cc"],
  deps = [":mylib"],
  linkstatic = 1, # default value
)

# second will link to mylib.dll through mylib.lib
cc_binary(
  name = "second",
  srcs = ["second.cc"],
  deps = [":mylib"],
  linkstatic = 0,
)
```
    + cc_library 
    
cc_library(name, deps, srcs, data, hdrs, alwayslink, compatible_with, copts, defines, deprecation, distribs, exec_compatible_with, exec_properties, features, implementation_deps, include_prefix, includes, licenses, linkopts, linkstamp, linkstatic, local_defines, nocopts, restricted_to, strip_include_prefix, tags, target_compatible_with, testonly, textual_hdrs, toolchains, visibility, win_def_file)

All header files that are used in the build must be declared in the hdrs or srcs of cc_* rules. This is enforced. 

cc_binary and cc_test rules do not have an exported interface, so they also do not have a hdrs attribute. All headers that belong to the binary or test directly should be listed in the srcs
```
cc_binary(
    name = "foo",
    srcs = [
        "foo.cc",
        "foo.h",
    ],
    deps = [":bar"],
)

cc_library(
    name = "bar",
    srcs = [
        "bar.cc",
        "bar-impl.h",
    ],
    hdrs = ["bar.h"],
    deps = [":baz"],
)

cc_library(
    name = "baz",
    srcs = [
        "baz.cc",
        "baz-impl.h",
    ],
    hdrs = ["baz.h"],
)
```

    + cc_proto_library 

cc_proto_library(name, deps, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, restricted_to, tags, target_compatible_with, testonly, visibility)

cc_proto_library generates C++ code from .proto files.

```
cc_library(
    name = "lib",
    deps = [":foo_cc_proto"],
)

cc_proto_library(
    name = "foo_cc_proto",
    deps = [":foo_proto"],
)

proto_library(
    name = "foo_proto",
)
```

    + fdo_prefetch_hints 
    
fdo_prefetch_hints(name, compatible_with, deprecation, distribs, features, licenses, profile, restricted_to, tags, target_compatible_with, testonly, visibility)
 
Represents an FDO prefetch hints profile that is either in the workspace or at a specified absolute path.

```
fdo_prefetch_hints(
    name = "hints",
    profile = "//path/to/hints:profile.afdo",
)

fdo_profile(
  name = "hints_abs",
  absolute_path_profile = "/absolute/path/profile.afdo",
)
```

    + fdo_profile 
    
fdo_profile(name, absolute_path_profile, compatible_with, deprecation, distribs, features, licenses, profile, proto_profile, restricted_to, tags, target_compatible_with, testonly, visibility)

Represents an FDO profile that is either in the workspace or at a specified absolute path.

```
fdo_profile(
    name = "fdo",
    profile = "//path/to/fdo:profile.zip",
)

fdo_profile(
  name = "fdo_abs",
  absolute_path_profile = "/absolute/path/profile.zip",
)
```

    + propeller_optimize 

propeller_optimize(name, compatible_with, deprecation, distribs, features, ld_profile, licenses, restricted_to, tags, target_compatible_with, testonly, visibility)

Represents a Propeller optimization profile in the workspace

```
propeller_optimize(
    name = "layout",
    cc_profile = "//path:cc_profile.txt",
    ld_profile = "//path:ld_profile.txt"
)

propeller_optimize(
    name = "layout_absolute",
    absolute_cc_profile = "/absolute/cc_profile.txt",
    absolute_ld_profile = "/absolute/ld_profile.txt"
)
```

    + cc_test 
    
cc_test(name, deps, srcs, data, additional_linker_inputs, args, compatible_with, copts, defines, deprecation, distribs, env, env_inherit, exec_compatible_with, exec_properties, features, flaky, includes, licenses, linkopts, linkstatic, local, local_defines, malloc, nocopts, restricted_to, shard_count, size, stamp, tags, target_compatible_with, testonly, timeout, toolchains, visibility, win_def_file)

    + cc_toolchain 
    
cc_toolchain(name, all_files, ar_files, as_files, compatible_with, compiler, compiler_files, compiler_files_without_includes, coverage_files, cpu, deprecation, distribs, dwp_files, dynamic_runtime_lib, exec_transition_for_inputs, features, libc_top, licenses, linker_files, module_map, objcopy_files, restricted_to, static_runtime_lib, strip_files, supports_header_parsing, supports_param_files, tags, target_compatible_with, testonly, toolchain_config, toolchain_identifier, visibility)

    + cc_toolchain_suite 

cc_toolchain_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility)

toolchains a collections of C++ toolchains.

```
cc_toolchain_suite(
            name = "toolchain",
            toolchains = {
              "piii|gcc": ":my_cc_toolchain_for_piii_using_gcc",
              "piii": ":my_cc_toolchain_for_piii_using_default_compiler",
            },
          )
```
    

- parameters 

hdrs, List of labels
copts, List of strings; optional
strip_include_prefix, String; optional, The prefix to strip from the paths of the headers of this rule.
textual_hdrs List of labels; optional The list of header files published by this library to be textually included by sources in dependent rules
win_def_fiel The Windows DEF file to be passed to linker.
linkopts Add these flags to the C++ linker command. 
linkstatic cc_binary and cc_test: link the binary in static mode. For cc_library.linkstatic
local_defines List of defines to add to the compile line. Subject to "Make" variable substitution and Bourne shell tokenization
malloc By default, C++ binaries are linked against //tools/cpp:malloc, which is an empty library so the binary ends up using libc malloc
nocopts Remove matching options from the C++ compilation command. Subject to "Make" variable substitution. 
stamp Whether to encode build information into the binary.
win_def_file The Windows DEF file to be passed to linker.
toolchains	Dictionary mapping strings to labels; A map from "<cpu>" or "<cpu>|<compiler>" strings to a cc_toolchain label.

- python 

    + py_binary, an executable Python program consisting of a collection of .py source files (possibly belonging to other py_library rules), a *.runfiles directory tree containing all the code

py_binary(name, deps, srcs, data, args, compatible_with, deprecation, distribs, env, exec_compatible_with, exec_properties, features, imports, legacy_create_init, licenses, main, output_licenses, python_version, restricted_to, srcs_version, stamp, tags, target_compatible_with, testonly, toolchains, visibility)

```
py_binary(
    name = "foo",
    srcs = ["foo.py"],
    data = [":transform"],  # a cc_binary which we invoke at run time
    deps = [
        ":foolib",  # a py_library
    ],
)
```

    + py_library 
    
py_library(name, deps, srcs, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, imports, licenses, restricted_to, srcs_version, tags, target_compatible_with, testonly, visibility)

    + py_test

py_test(name, deps, srcs, data, args, compatible_with, deprecation, distribs, env, env_inherit, exec_compatible_with, exec_properties, features, flaky, imports, legacy_create_init, licenses, local, main, python_version, restricted_to, shard_count, size, srcs_version, stamp, tags, target_compatible_with, testonly, timeout, toolchains, visibility)

```
py_test(
    name = "runtest_test",
    srcs = ["runtest_test.py"],
    deps = [
        "//path/to/a/py/library",
    ],
)

py_test(
    name = "runtest_test",
    srcs = [
        "runtest_main.py",
        "runtest_lib.py",
    ],
    main = "runtest_main.py",
)
```

    + py_runtime,  a Python runtime used to execute Python code. 

py_runtime(name, compatible_with, coverage_tool, deprecation, distribs, features, files, interpreter, interpreter_path, licenses, python_version, restricted_to, stub_shebang, tags, target_compatible_with, testonly, visibility)

```
py_runtime(
    name = "python-2.7.12",
    files = glob(["python-2.7.12/**"]),
    interpreter = "python-2.7.12/bin/python",
)

py_runtime(
    name = "python-3.6.0",
    interpreter_path = "/opt/pyenv/versions/3.6.0/bin/python",
)
```

- rust 
- javascript 



# Commandline reference 
- reference 

https://bazel.build/reference/command-line-reference#startup-options


- option syntax 

bazel [<startup options>] <command> [<args>] -- [<target patterns>]

- option syntax 
```
--<option>=<value>
--<option> <value>
-<short_form> <value>
--no<option>
--<option>=[false|no|0]
--<option>
--<option>=[true|yes|1]
```

- commands 

analyze-profile
aquery, analyzes the given targets and queries the action graph 
build, 	Builds the specified targets.
canonicalize-flags, canolicalize a list of bazel options 
clean, removes output files 
coverage, Generates code coverage report for specified test targets. 
cquery, loads analyzes and queries the specified targets w/configurations 
dump, dump the interal state of the bazel server process 
fetch, fetch external repositories that are prerequisites to the targets 
help 
info, displays runtime info 
license, Prints the license of this software. 
mobile-install, Installs targets to mobile devices. 
modquery, queries the bzlmod external dependency graph 
print_action, prints the command line args for compiling a file 
query, executes a dependency graph query 
run, run the specific target 
shutdown stops bazel server 
sync, sync all repositories specified in the workspace file 
test, builds and run the specified test targets 
version 

- startup options, before the command and are parsed by the client
```
--[no]autodetect_server_javabase 
--[no]batch
--[no]batch_cpu_scheduling
--bazelrc, location of bazelrc 
...
```
- options common to all commands 

```
--experimental_oom_more_eagerly_threshold
--experimental_ui_max_stdouterr_bytes
--repo_env=<a 'name=value' assignment with an optional value part> multiple uses are accumulated, specify environment variables 
--[no]check_bzl_visibility
--[no]enable_bzlmod
--[no]incompatible_always_check_depset_elements
--[no]track_incremental_state
...
--bes_proxy=<a string> default: see description Connect to the Build Event Service through a proxy. only support unix 
...
--build_event_json_file=<a string> default: ""  If non-empty, write a JSON serialisation of the build event protocol to that file.
--build_event_text_file=<a string> default: ""  If non-empty, write a textual representation of the build event
--repository_cache=<a path> default: see description Specifies the cache location of the downloaded values obtained during the fetching of external repositories
...
```
- Aquery options inherit all options from build 

```
--distdir=<a path> multiple uses are accumulated
--output=<a string>
--[no]tool_deps default: "true"
Query: If disabled, dependencies on 'host configuration' or 'execution' targets will not be included in the dependency graph over which the query operates

--override_module=<an equals-separated mapping of module name to path> multiple uses are accumulated

--registry=<a string> multiple uses are accumulated
Specifies the registries to use to locate Bazel module dependencies

--modify_execution_info=<regex=[+-]key,regex=[+-]key,...> default: ""
Add or remove keys from an action's execution info based on action mnemonic.

--fdo_optimize=<a string> default: see description
Use FDO profile information to optimize compilation. Specify the name of a zip file containing a .gcda file tree

```

- options common to all commands, options taht control build execution 

```
--repo_env=<a 'name=value' assignment with an optional value part> multiple uses are accumulated
Specifies additional environment variables to be available only for repository rules.

--[no]enable_bzlmod default: "false"
If true, enables the Bzlmod dependency management system, taking precedence over WORKSPACE

--[no]experimental_analysis_test_call default: "true"
If set to true, analysis_test native call is available.

--nested_set_depth_limit=<an integer> default: "3500"
The maximum depth of the graph internal to a depset

--build_event_json_file=<a string> default: ""
If non-empty, write a JSON serialisation of the build event protocol 

...
--build_event_text_file=<a string> default: ""
If non-empty, write a textual representation of the build event protocol 

--profile=<a path> default: see description
If set, profile Bazel and write data to the specified file

```
- Aquery options 
- Config options 
- Cquery options, Options that appear before the command and are parsed by the client 



# Bazel query reference 
- Action graph query
The action graph query (aquery) operates on the post-analysis Configured Target Graph and exposes information about Actions, Artifacts

- Configuration query 
Traditional Bazel query runs on the post-loading phase target graph and therefore has no concept of configurations and their related concepts.

- Quoting is necessary when writing scripts that construct Bazel query expressions from user-supplied values

```
 //foo:bar+wiz    # WRONG: scanned as //foo:bar + wiz.
 //foo:bar=wiz    # WRONG: scanned as //foo:bar = wiz.
 "//foo:bar+wiz"  # OK.
 "//foo:bar=wiz"  # OK.
```

$ bazel query ' "//foo:bar=wiz" '   # single-quotes for shell, double-quotes for Bazel.

Keywords, when quoted, are treated as ordinary words.

Punctuation, such as parens (), period . and comma ,. Words containing punctuation (other than the exceptions listed above) must be quoted.

- keywords 

except 
in
intersect 
let 
set 
union 


- Bazel query language concepts 

set, The partial order of the targets is not interesting. 
graph, The partial order of targets is significant.

- Cycles in the dependency graph 

- implicit dependencies 

BUILD files, Bazel adds additional implicit dependencies to rules. ex. java rules implicitly depends on JavaBuilder 

- Soundness 

Bazel query language expressions operate over the build dependency graph, which is the graph implicitly defined by all rule declarations in all BUILD files.

- On the preservation of graph order 

- Sky Query is a mode of query that operates over a specified universe scope.

    + example 
    
$ bazel query --universe_scope=//my:target --order_output=no "allrdeps(//my:target)"

compute the test targets in the tests expansion of the targets under some directories that transitively depend on targets whose definition uses a certain .bzl file.

- Syntax and semantics of the grammar
```
expr ::= word
       | let name = expr in expr
       | (expr)
       | expr intersect expr
       | expr ^ expr
       | expr union expr
       | expr + expr
       | expr except expr
       | expr - expr
       | set(word *)
       | word '(' int | word | expr ... ')'
```
expr ::= word
Syntactically, a target pattern is just a word. It's interpreted as an (unordered) set of targets.

bar/baz:all is a target pattern that evaluates to a set containing all the rules

wildcard * matches files as well as rules, it's often more useful than :all for queries.

Variables

expr ::= let name = expr1 in expr2
       | $name
The Bazel query language allows definitions of and references to variables.

let v = foo/... in allpaths($v, //common) intersect $v is equivalent to the allpaths(foo/...,//common) intersect foo/....

Both target patterns and variable references consist of just a single token, a word, creating a syntactic ambiguity.

Algebraic set operations: intersection, union, set difference

expr ::= expr intersect expr
       | expr ^ expr
       | expr union expr
       | expr + expr
       | expr except expr
       | expr - expr

The intersect (^) and union (+) operations are commutative (symmetric); except (-) is asymmetric.       
       
       
Read targets from an external source: set

expr ::= set(word *)

$ bazel query deps(//my:target) --output=label | grep ... | sed ... | awk ... > foo   
$ bazel query "kind(cc_binary, set($(<foo)))"

kind(cc_library, deps(//some_dir/foo:main, 5)) is computed by filtering on the maxrank values using an awk program.

Functions
expr ::= word '(' int | word | expr ... ')'
The query language defines several functions. 

allpaths
attr
buildfiles
rbuildfiles
deps
filter
kind
labels
loadfiles
rdeps
allrdeps
same_pkg_direct_rdeps
siblings
some
somepath
tests
visible

    + deps(x) operator evaluates to the graph formed by the transitive closure of dependencies of its argument set x. For example, the value of deps(//foo) is the dependency graph rooted at the single node foo, including all its dependencies
    
    + rdeps, evaluates to the reverse dependencies of the argument set x within the transitive closure of the universe set u.

expr ::= rdeps(expr, expr)
       | rdeps(expr, expr, depth)
       
    + allrdeps operator behaves just like the rdeps operator, except that the "universe set" is whatever the --universe_scope flag evaluated to, instead of being separately specified.
    
    + siblings(x) operator evalutes to the full set of targets that are in the same package as a target in the argument set.
    
    + some(x, k) operator selects at most k targets arbitrarily from its argument set x, and evaluates to a set containing only those targets. 
    
    + somepath(S, E) and allpaths(S, E) operators compute paths between two sets of targets. Both queries accept two arguments, a set S of starting points and a set E of ending points
    
    + kind(pattern, input) operator applies a filter to a set of targets, and discards those targets that are not of the expected kind
    
    + filter(pattern, input) operator applies a filter to a set of targets, and discards targets whose labels (in absolute form) do not match the pattern
    
     see all bar dependencies of the //foo:foo target, one could evaluate

    ```
    deps(//foo) intersect //bar/...
    ```
    equal to 
    ```
    filter(//bar, deps(//foo))
    ```
       
    + attr(name, pattern, input) operator applies a filter to a set of targets, and discards targets that aren't rules, rule targets that do not have attribute name defined or rule targets where the attribute value does not match the provided regular expression pattern
    
    attr("srcs", "\[\]", deps(//foo))
    will select all rules among //foo dependencies that have an empty srcs
    
    attr("data", ".{3,}", deps(//foo))
    will select all rules among //foo dependencies that specify at least one value in the data attribute (every label is at least 3 characters long due to the // and :).
    
    + visible(predicate, input) operator applies a filter to a set of targets, and discards targets without the required visibility. 

    + labels(attr_name, inputs) operator returns the set of targets specified in the attribute attr_name of type "label" or "list of label" in some rule in set inputs.
    
    + tests(x) operator returns the set of all test rules in set x, expanding any test_suite rules into the set of individual tests that they refer to, and applying filtering by tag
    
    kind(test, foo:*) lists all the *_test and test_suite rules in the foo package. All the results are (by definition) members of the foo package.
    
    + buildfiles(x) operator returns the set of files that define the packages of each target in set x; in other words, for each package, its BUILD file, plus any .bzl files it references via load
    
    + rbuildfiles operator takes a comma-separated list of path fragments and returns the set of BUILD files that transitively depend on these path fragments.
    
    + loadfiles(x) operator returns the set of Starlark files that are needed to load the packages of each target in set x
    

- Output formats, bazel query generates a graph.

```
--output build
--output xml 
...
```

build 
label 
label_kind
minrank 
location 
graph 
graph:node_limit 
xml 

```
bazel query 'kind(http_archive, //external:*)'
```

- proposed specification 

"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"

- role of the build system, test runner will need a manifest of runfiles

    + timeout attribute 
    
timeout	Time Limit (sec.)
short	60
moderate	300
long	900
eternal	3600

    + timeout base on test size 
    
size	Implied timeout label
small	    short
medium	    moderate
large	    long
enormous	eternal

- initial environment block

Variable	Value	Status
HOME	value of $TEST_TMPDIR	
LANG	
LANGUAGE	
LC_ALL	
LC_COLLATE	
LC_CTYPE	
...

- querying with external repositories 

```
# Querying over all members of //external returns the repository.
bazel query 'kind(http_archive, //external:*)'
```

- The following functions are available:

allpaths
attr
buildfiles
rbuildfiles
deps
filter
kind
labels
loadfiles
rdeps
allrdeps
same_pkg_direct_rdeps
siblings
some
somepath
tests
visible

- Output formats
bazel query generates a graph.

- the ordering of results 

which prints results in lexicographical order. However, when somepath(a,b) is used, the results will be printed in deps order instead.

Print the label of each target
```
--output label
```

- Print the source form of targets as they would appear in BUILD

```
--output build
```

- XML

This option causes the resulting targets to be printed in an XML form
```
--output xml
```



# Bazel build encyclopedia of functions 
- Concepts and terminmology 

    + common definitions 
    
    
    Bourne shell tokenization
    Label expansion
    Typical attributes for most rules
    Common attributes for all rules
    Common attributes for tests
    Common attributes for binaries
    Configurable attributes
    Implicit output targets
    
    + make varaibles 
    
    Use
    
    
- functions 

package 
package_group 
exports_files 
glob 
select 
subpackages   
    

- rules 

https://bazel.build/reference/be/overview

    + language specific rules 

Language	Binary rules	    Library rules	            Test rules	                    Other rules
Android	    android_binary      aar_import                  android_instrumentation_test    android_device
                                android_library             android_local_test              android_ndk_repository
                                                                                            android_sdk_repository
                                                

C / C++	    cc_binary           cc_import                   cc_test                         cc_toolchain
                                cc_library                                                  cc_toolchain_suite
                                cc_proto_library
                                fdo_prefetch_hints
                                fdo_profile
                                propeller_optimize

Java	    java_binary         java_import                 java_test                       java_package_configuration
                                java_library                                                java_plugin
                                java_lite_proto_library                                     java_runtime
                                java_proto_library                                          java_toolchain



Objective-C		                j2objc_library                                              available_xcodes
                                objc_import                                                 xcode_config
                                objc_library                                                xcode_version
                                

Protocol                        proto_lang_toolchain
Buffer		                    proto_library

Python	    py_binary           py_library                   py_test                        py_runtime

Shell	    sh_binary           sh_library                   sh_test

- language agnostic native rules 

Family	                    Rules
Extra Actions	            action_listener
                            extra_action
                            
General	                    alias
                            config_setting
                            filegroup
                            genquery
                            genrule
                            test_suite
                            
Platform	                constraint_setting
                            constraint_value
                            platform
                            toolchain
                            toolchain_type
                            
Workspace	                bind
                            local_repository
                            new_local_repository

- Extra Actions rules 

action_listener rule doesn't produce any output itself. Instead, it allows tool developers to insert extra_actions into the build system

extra_action rule doesn't produce any meaningful output when specified as a regular build target.

```
action_listener(
    name = "index_all_languages",
    mnemonics = [
        "Javac",
        "CppCompile",
        "Python",
    ],
    extra_actions = [":indexer"],
)

action_listener(
    name = "index_java",
    mnemonics = ["Javac"],
    extra_actions = [":indexer"],
)

extra_action(
    name = "indexer",
    tools = ["//my/tools:indexer"],
    cmd = "$(location //my/tools:indexer)" +
          "--extra_action_file=$(EXTRA_ACTION_FILE)",
)
```

- General rules 

    + alias,  creates another name a rule can be referred to as.
    Tests are not run if their alias is mentioned on the command line. 
    
    defining environment groups, the aliases to environment rules are not supported.
    
```
filegroup(
    name = "data",
    srcs = ["data.txt"],
)

alias(
    name = "other",
    actual = ":data",
)
```

    + config_setting, Matches an expected configuration state. See select for how to consume this rule and Configurable attributes for an overview
    
config_setting(name, constraint_values, define_values, deprecation, distribs, features, flag_values, licenses, tags, testonly, values, visibility)
    
```
# matches any build that sets --compilation_mode=opt or -c opt
config_setting(
  name = "simple",
  values = {"compilation_mode": "opt"}
)


# The following matches any build that sets user-defined flag --//custom_flags:foo=1
config_setting(
  name = "two_conditions",
  values = {
      "cpu": "arm",
      "define": "FOO=bar"
  }
)

``` 

    + filegroup, Use filegroup to give a convenient name to a collection of targets.can be reference from other rules. Using filegroup is encouraged instead of referencing directories directly.

    
    
filegroup(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, restricted_to, tags, target_compatible_with, testonly, visibility)

```
filegroup(
    name = "mygroup",
    srcs = [
        "a_file.txt",
        "some/subdirectory/another_file.txt",
    ],
)

filegroup(
    name = "exported_testdata",
    srcs = glob([
        "testdata/*.dat",
        "testdata/logs/**/*.log",
        "//my_package:exported_testdata",
    ]),
)
```

    + genquery, runs a query specified in the Blaze query language and dumps the result into a file.

genquery(name, deps, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, expression, features, licenses, opts, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility)

```
genquery(
    name = "kiwi-deps",
    expression = "deps(//kiwi:kiwi_lib)",
    scope = ["//kiwi:kiwi_lib"],
)
```
    
    + genrule, A genrule generates one or more files using a user-defined Bash command.  Any change to the value of PATH will cause Bazel to re-execute the command on the next build.
    
    There are no sources, because the command doesn't take any input. The "binary" run by the command is a perl script in the same package

```
genrule(
    name = "foo",
    srcs = [],
    outs = ["foo.h"],
    cmd = "./$(location create_foo.pl) > \"$@\"",
    tools = ["create_foo.pl"],
)


genrule(
    name = "concat_all_files",
    srcs = [
        "//some:files",  # a filegroup with multiple files in it ==> $(locations)
        "//other:gen",   # a genrule with a single output ==> $(location)
    ],
    outs = ["concatenated.txt"],
    cmd = "cat $(locations //some:files) $(location //other:gen) > $@",
)
```

    + test_suite, A test_suite defines a set of tests that are considered "useful" to humans. This allows projects to define sets of tests, such as "tests you must run before checkin"

test_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, tests, visibility)

$ blaze test //some/test:suite

```
test_suite(
    name = "small_tests",
    tags = ["small"],
)

# current package which are not flaky.
test_suite(
    name = "non_flaky_test",
    tags = ["-flaky"],
)
```

- Platform rules 

    + constraint_setting used to introduce a new constraint type for which a platform may specify a value.
    
predefined setting @platforms//cpu:cpu can be extended with a custom value in order to define a platform targeting an obscure cpu architecture.

constraint_setting(name, default_constraint_value, deprecation, distribs, features, licenses, tags, testonly, visibility)

    + constraint_value 
    
constraint_value(name, constraint_setting, deprecation, distribs, features, licenses, tags, testonly, visibility)

reates a new possible value for the predefined constraint_value
```
constraint_value(
    name = "mips",
    constraint_setting = "@platforms//cpu:cpu",
)
```

    + platform defines a new platform -- a named collection of constraint choices (such as cpu architecture or compiler version) describing an environment in which part of the build may run.  
    
platform(name, constraint_values, deprecation, distribs, exec_properties, features, licenses, parents, remote_execution_properties, tags, testonly, visibility)

```
platform(
    name = "linux_arm",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)
```

Platforms may use the parents attribute to specify another platform that they will inherit constraint values from

Platforms can also inherit the (deprecated) remote_execution_properties attribute from the parent platform

```
platform(
    name = "parent",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)
platform(
    name = "child_a",
    parents = [":parent"],
    constraint_values = [
        "@platforms//cpu:x86_64",
    ],
)
platform(
    name = "child_b",
    parents = [":parent"],
)
```

    + toolchain, This rule declares a specific toolchain's type and constraints so that it can be selected during toolchain resolution
    
toolchain(name, deprecation, distribs, exec_compatible_with, features, licenses, tags, target_compatible_with, target_settings, testonly, toolchain, toolchain_type, visibility)

    
    
    + toolchain_type, defines a new type of toolchain -- a simple target that represents a class of tools that serve the same role for different platforms

toolchain_type(name, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)

```
toolchain_type(
    name = "bar_toolchain_type",
)

bar_binary = rule(
    implementation = _bar_binary_impl,
    attrs = {
        "srcs": attr.label_list(allow_files = True),
        ...
        # No `_compiler` attribute anymore.
    },
    toolchains = ["//bar_tools:toolchain_type"]
)
```

- Workspace rules, Workspace rules are used to pull in external dependencies, typically source code located outside the main repository. 

    + bind, use of bind() is not recommended 
    
    bind(name, actual, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, visibility)
    
    bind it in the WORKSPACE file. For example, suppose there is a java_library target called //third_party/javacc-v2. This can be aliased by adding the following to the WORKSPACE file
    
    select() cannot be used in bind()
    
    To give a target an alias, bind it in the WORKSPACE file
```
bind(
    name = "javacc-latest",
    actual = "//third_party/javacc-v2",
)
```

    Bind can also be used to make targets in external repositories available. a remote repository named @my-ssl imported in the WORKSPACE file and it has a cc_library target //src:openssl-lib
    
```
bind(
    name = "openssl",
    actual = "@my-ssl//src:openssl-lib",
)

# in BUILD file in your workspace can use the imported new bind 
cc_library(
    name = "sign-in",
    srcs = ["sign_in.cc"],
    hdrs = ["sign_in.h"],
    deps = ["//external:openssl"],
)
```

    the header files exposed by //external:openssl can be referred to using their path relative to their repository root
```
#include "sign_in.h"
#include "src/openssl.h"
```

    + local_repository, Allows targets from a local directory to be bound. This means that the current repository can use targets defined in this other directory 
 
local_repository(name, path, repo_mapping) 

```
#  ~/chat-app. It would like to use an SSL library which is defined in a different repository: ~/ssl. The SSL library has a target //src:openssl-lib.

# user can add a dependency on this target by adding the following lines to ~/chat-app/WORKSPACE
local_repository(
    name = "my-ssl",
    path = "/home/user/ssl",
)

# Targets would specify @my-ssl//src:openssl-lib as a dependency

```

    + new_local_repository, allows a local directory to be turned into a bazel repository. This rule creates a Bazel repository by creating a WORKSPACE file and subdirectory containing symlinks to the BUILD file and path given.
    
new_local_repository(name, build_file, build_file_content, path, repo_mapping, workspace_file, workspace_file_content)

```
new_local_repository(
    name = "my-ssl",
    path = "/home/user/ssl",
    build_file = "BUILD.my-ssl",
)
```

use new_local_repository to include single files, not just directories
```
new_local_repository(
    name = "piano",
    path = "/home/username/Downloads/piano.jar",
    build_file = "BUILD.piano",
)

# the following BUILD.piano file:
java_import(
    name = "play-music",
    jars = ["piano.jar"],
    visibility = ["//visibility:public"],
)
```

- functions 

    + package, declares metadata that applies to every subsequent rule in the package 

package(default_deprecation, default_testonly, default_visibility, features)

```
package(default_visibility = ["//foo:target"])
```

    + package_group, a set of packages and associates a label with the set. The label can be referenced in visibility attributes

package_group(name, packages, includes)

```
package_group(
    name = "tropical",
    packages = [
        "//fruits/mango",
        "//fruits/orange",
        "//fruits/papaya/...",
    ],
)

package_group(
    name = "fooapp",
    includes = [
        ":controller",
        ":model",
        ":view",
    ],
)

```    

    + exports_files, specifies a list of files belonging to this package that are exported to other packages.
    
exports_files(["golden.txt"])

    + glob, Glob is a helper function that finds all files that match certain path patterns, and returns a new, mutable, sorted list of their paths.
    
glob(include, exclude=[], exclude_directories=1, allow_empty=True)

```
java_library(
    name = "mylib",
    srcs = glob(
        ["**/*.java"],
        exclude = ["**/testing/**"],
    ),
)
```

    + select the helper function that makes a rule attribute configurable. It can replace the right-hand side of almost any attribute assignment 
    
select(
    {conditionA: valuesA, conditionB: valuesB, ...},
    no_match_error = "custom message"
)

```
sh_binary(
    name = "mytarget",
    srcs = select({
        ":conditionA": ["mytarget_a.sh"],
        ":conditionB": ["mytarget_b.sh"],
        "//conditions:default": ["mytarget_default.sh"]
    })
)
```

This makes the srcs attribute of a sh_binary configurable by replacing its normal label list assignment with a select call that maps configuration conditions to matching values. Each condition is a label reference to a config_setting or constraint_value

    + subpackages, subpackages() is a helper function, similar to glob() that lists subpackages instead of files and directories. lists all the direct subpackages for the package foo/BUILD
    
```
# In foo/BUILD a call to
subs = subpackages(include = ["**"])

# results in subs == ["sub", "bar/baz"]
```   

- rules 

    + workspace, sets the name for this workspace.  can only be used in a WORKSPACE file and must be declared before all other functions in the WORKSPACE file. Each WORKSPACE file should have a workspace function.
    
workspace(name)

if there is a runfile foo/bar in the local repository and the WORKSPACE file contains workspace(name = 'baz'), then the runfile will be available under mytarget.runfiles/baz/foo/bar. If no workspace name is specified, then the runfile will be symlinked to bar.runfiles/foo/bar

- python rules 

    + py_binary, A py_binary is an executable Python program consisting of a collection of .py source files. a *.runfiles directory tree containing all the code and data 
 
```
py_binary(
    name = "foo",
    srcs = ["foo.py"],
    data = [":transform"],  # a cc_binary which we invoke at run time
    deps = [
        ":foolib",  # a py_library
    ],
)
``` 

    + py_library 
    
py_library(name, deps, srcs, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, imports, licenses, restricted_to, srcs_version, tags, target_compatible_with, testonly, visibility)

    + py_test, rule compiles a test. A test is a binary wrapper around some test code.
    
py_test(name, deps, srcs, data, args, compatible_with, deprecation, distribs, env, env_inherit, exec_compatible_with, exec_properties, features, flaky, imports, legacy_create_init, licenses, local, main, python_version, restricted_to, shard_count, size, srcs_version, stamp, tags, target_compatible_with, testonly, timeout, toolchains, visibility)

```
py_test(
    name = "runtest_test",
    srcs = ["runtest_test.py"],
    deps = [
        "//path/to/a/py/library",
    ],
)
``` 

    + py_runtime, a Python runtime used to execute Python code. 
    
py_runtime(name, compatible_with, coverage_tool, deprecation, distribs, features, files, interpreter, interpreter_path, licenses, python_version, restricted_to, stub_shebang, tags, target_compatible_with, testonly, visibility)

```
py_runtime(
    name = "python-2.7.12",
    files = glob(["python-2.7.12/**"]),
    interpreter = "python-2.7.12/bin/python",
)
```

- shell rules 
    + sh_binary, The sh_binary rule is used to declare executable shell scripts.  
    
sh_binary(name, deps, srcs, data, args, compatible_with, deprecation, distribs, env, exec_compatible_with, exec_properties, features, licenses, output_licenses, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility)    







# Build commands and options 
https://bazel.build/docs/user-manual#configurations
- build semanticsaffect the build commands and/or the output file contents.

```
``` 



# User guide 
https://bazel.build/docs

## Overview 

## Release versioning 

## Backward compatibility 

# Basics  
## BUILD style guide 
- formatting example, a standardized tool takes care of most formatting issues. Buildifier is a tool that parses and emits the source code in a standard style

https://github.com/bazelbuild/buildtools
https://github.com/bazelbuild/buildtools/blob/master/buildifier/README.md

```
# Test code implementing the Foo controller.
package(default_testonly = True)

py_test(
    name = "foo_test",
    srcs = glob(["*.py"]),
    data = [
        "//data/production/foo:startfoo",
        "//foo",
        "//third_party/java/jdk:jdk-k8",
    ],
    flaky = True,
    deps = [
        ":check_bar_lib",
        ":foo_data_check",
        ":pick_foo_port",
        "//pyglib",
        "//testing/pybase",
    ],
)
```


- file structure 

package descrition 
all load() function 
the package() function 
calls to rules and macros 

- references to targets in the current package,  Generated files should be prefixed with ":" to indicate that they are not sources. Source files should not be prefixed with :

```
cc_library(
    name = "lib",
    srcs = ["x.cc"],
    hdrs = [":gen_header"],
)

genrule(
    name = "gen_header",
    srcs = [],
    outs = ["x.h"],
    cmd = "echo 'int x();' > $@",
)
```

- Target naming
Target names should be descriptive. If a target contains one source file, the target should generally have a name derived from that source

Avoid using "reserved" target names which have special meaning. This includes all, __pkg__, and __subpackages__, these names have special semantics 

For other rules use snake case 
https://en.wikipedia.org/wiki/Snake_case

For Java *_binary and *_test rules, use "Upper CamelCase"

proto_library targets should have names ending in _proto

- visibility, Avoid setting package default_visibility to //visibility:public.

- dependencies, Dependencies should be restricted to direct dependencies

- Globs, Indicate "no targets" with []. Do not use a glob that matches nothing

- Recursive

Do not use recursive globs to match source files (for example, glob(["**/*.java"])).  because they skip subdirectories containing BUILD files.

It is good practice to author a BUILD file in each directory and define a dependency graph between them.'

- other conventions 

Use uppercase and underscores to declare constants (such as GLOBAL_CONSTANT)

Labels should never be split, even if they are longer than 79 characters. 

The value of the name attribute should be a literal constant string. 

When setting boolean-type attributes, use boolean values, not integer values. 

- python style guide 

No strict line length limit. Long comments and long strings are often split to 79 columns

By default, use double quotation marks for strings. 




## Share variables 
- BUILD files are intended to be simple and declarative. 

```
COPTS = ["-DVERSION=5"]

cc_library(
  name = "foo",
  copts = COPTS,
  srcs = ["foo.cc"],
)

cc_library(
  name = "bar",
  copts = COPTS,
  srcs = ["bar.cc"],
  deps = [":foo"],
)
```

- cross multiple build files 

```
# path/to/variables.bzl, write:


COPTS = ["-DVERSION=5"]

load("//path/to:variables.bzl", "COPTS")

cc_library(
  name = "foo",
  copts = COPTS,
  srcs = ["foo.cc"],
)

cc_library(
  name = "bar",
  copts = COPTS,
  srcs = ["bar.cc"],
  deps = [":foo"],
)
```





## External dependencies 
https://bazel.build/docs/external
- two projects on a system 

/
  home/
    user/
      project1/
        WORKSPACE
        BUILD
        srcs/
          ...
      project2/
        WORKSPACE
        BUILD
        my-libs/
        
Then targets in /home/user/project1/BUILD could depend on @project2//:foo.
        
- supported types of external dependencies 

Dependencies on other Bazel projects
Dependencies on non-Bazel projects
Dependencies on external packages

- use targets from a second Bazel project, you can use local_repository, git_repository or http_archive to symlink it

You would add the following to my_project/WORKSPACE:

```
local_repository(
    name = "coworkers_project",
    path = "/path/to/coworkers-project",
)
```

has a target //foo:bar, your project can refer to it as @coworkers_project//foo:bar

- Rules prefixed with new_, such as new_local_repository, allow you to create targets from projects that do not use Bazel.

```
new_local_repository(
    name = "coworkers_project",
    path = "/path/to/coworkers-project",
    build_file = "coworker.BUILD",
)
```

specifies a BUILD file to overlay on the existing project
```
# coworker.BUILD
cc_library(
    name = "some-lib",
    srcs = glob(["**"]),
    visibility = ["//visibility:public"],
)
```

depend on @coworkers_project//:some-lib from your project's BUILD files.

- Use the ruleset rules_jvm_external to download artifacts from Maven

- fetching dependencies, fetched as needed during bazel build. If you would like to prefetch the dependencies needed for a specific set of targets

se bazel sync. As fetched repositories are stored in the output base

- shadowing dependencies with repo_mapping attribute 

```
# myproject/WORKSPACE 
workspace(name = "myproject")

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "testrunner-v1",
    urls = ["https://github.com/testrunner/v1.zip"],
    sha256 = "..."
)
http_archive(
    name = "testrunner-v2",
    urls = ["https://github.com/testrunner/v2.zip"],
    sha256 = "..."
)
local_repository(
    name = "A",
    path = "../A",
    repo_mapping = {"@testrunner" : "@testrunner-v1"}
)
local_repository(
    name = "B",
    path = "../B",
    repo_mapping = {"@testrunner" : "@testrunner-v2"}
)

# A/WORKSPACE 
workspace(name = "A")

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "testrunner",
    urls = ["https://github.com/testrunner/v1.zip"],
    sha256 = "...",
)

# B/WORKSPACE
workspace(name = "B")

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "testrunner",
    urls = ["https://github.com/testrunner/v2.zip"],
    sha256 = "..."
)
```

Both dependencies A and B depend on testrunner, but they depend on different versions of testrunner

- overriding repositoris from command line use the --override_repository flag.

override @foo to the local directory /path/to/local/foo, pass the --override_repository=foo=/path/to/local/foo

use cases 
    + Debugging issues
    + in an environment where you cannot make network calls

- proxies, bazel will pick up proxy addresses from the HTTPS_PROXY and HTTP_PROXY environment variables and use these to download HTTP/HTTPS files

- On IPv6-only machines, Bazel will be able to download dependencies with no changes

- Transitive dependencies, Bazel only reads dependencies listed in your WORKSPACE file. 

all the dependencies required from your third party project should be listed in your WORKSPACE 

- Caching of external dependencies, Bazel will only re-download external dependencies if their definition changes.

To force a re-download, use bazel sync.

- Layout, External dependencies are all downloaded to a directory under the subdirectory external in the output base

$ ls $(bazel info output_base)/external

bazel clean will not actually delete the external directory. To remove all external artifacts, use bazel clean --expunge.

- offline build,  using the option --nofetch, fetching of further repositories can be disabled during the build.

providing of the needed files is to be done by an entity different from bazel, bazel supports the option --distdir

fetch a file via ctx.download or ctx.download_and_extract and provides a hash sum of the file needed

arbitrary commands in repository rules, without knowing if they call out to the network. Therefore, 

bazel has no option to enforce builds being fully offline. Test it is the only way to make sure. 

- generally be responsible for:

Detecting system settings and writing them to files.
Finding resources elsewhere on the system.
Downloading resources from URLs.
Generating or symlinking BUILD files into the external repository directory.

use repository_ctx.download() and then write a BUILD file that builds it, instead of running ctx.execute(["make"]).

- Prefer http_archive to git_repository and new_git_repository

        
        
        
## Manage dependencies with Bzlmod 
- Bzlmod is the codename of the new external dependency system introduced in Bazel 5.0

In Bazel 5.0, Bzlmod is not turned on by default; the flag --experimental_enable_bzlmod needs to be specified for the following to take effect.

- A module is essentially a Bazel project that can have multiple versions

- A module simply specifies its dependencies using name and version pairs, instead of specific URLs in WORKSPACE. 

- module has a MODULE.bazel file declaring its dependencies

```
module(
    name = "my-module",
    version = "1.0",
)

bazel_dep(name = "rules_cc", version = "0.0.1")
bazel_dep(name = "protobuf", version = "3.19.0")
```

- The MODULE.bazel file is similar to BUILD files as it doesn't support any form of control flow; it additionally forbids load statements. support 

module, to specify metadata 

bazel_dep, to specify direct dependencies 

overrides
    single_version_override
    multiple_version_override
    archive_override
    git_override
    local_path_override

Directives related to module extensions:
    use_extension
    use_repo

- version format 

Semantic Versioning 2.0.0

Abseil LTS 20220623.1

- Version resolution

https://research.swtch.com/vgo-mvs 

- compatibility level, "major version" number in order to detect backwards incompatible versions. This number is called the compatibility level, and is specified by each module version in its module() directive 

- repository names, via different repository names (for example, both @io_bazel_skylib and @bazel_skylib mean Bazel skylib

For Bazel module repos: module_name~version
(Example. @bazel_skylib~1.0.3

For module extension repos: module_name~version~extension_name~repo_name
(Example. @rules_cc~0.0.1~cc_configure~local_config_cc)


Bazel module repos: module_name by default

module extension repos: repository name introduced via use_repo.

- strict deps, prevent accidental and hard-to-debug breakages  

Bazel module repo can see all repos introduced in the MODULE.bazel file via bazel_dep and use_repo.

- Registries
Bzlmod discovers dependencies by requesting their information from Bazel registries

- Index registry is a local directory or a static HTTP server containing information about a list of modules, including their homepage, maintainers, the MODULE.bazel file of each version

    + /bazel_registry.json: A JSON file containing metadata for the registry like:
    
mirrors, specifying the list of mirrors to use for source archives.
module_base_path, specifying the base path for modules with local_repository type in the source.json file.

    + /modules: A directory containing a subdirectory for each module in this registry.

    + /modules/$MODULE: A directory containing a subdirectory for each version of this module
    
    + modules/$MODULE/$VERSION: A directory containing the following files:
    
MODULE.bazel: The MODULE.bazel file of this module version.

source.json: A JSON file containing information on how to fetch the source of this module version.

patches/: An optional directory containing patch files

- Bazel central registry 

Bazel Central Registry (BCR) is an index registry located at bcr.bazel.build. Its contents are backed by the GitHub repo bazelbuild/bazel-central-registry.

The BCR is maintained by the Bazel community; contributors are welcome to submit pull requests. See Bazel Central Registry Policies and Procedures.

- Selecting registries

The repeatable Bazel flag --registry can be used to specify the list of registries to request modules from

put a list of --registry flags in the .bazelrc file of your project.

- Module Extensions

Module extensions allow you to extend the module system by reading input data from modules across the dependency graph

- Extension usage

Extensions are hosted in Bazel modules themselves, so to use an extension in your module, you need to first add a bazel_dep on that module, and then call the use_extension built-in function to bring it into scope

```
bazel_dep(name = "rules_jvm_external", version = "1.0")
maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven")

# specifying some maven.dep and maven.pom tags.
maven.dep(coord="org.junit:junit:3.0")
maven.dep(coord="com.google.guava:guava:1.2")
maven.pom(pom_xml="//:pom.xml")
If the extension generates repos that you want to use in your module, use the use_repo directive to declare them

# generate repos you want to use in your module 
use_repo(
    maven,
    "org_junit_junit",
    guava="com_google_guava_guava",
)
```

- Extension definition

Module extensions are defined similarly to repo rules, using the module_extension function. 

```
# @rules_jvm_external//:extensions.bzl
maven_dep = tag_class(attrs = {"coord": attr.string()})
maven_pom = tag_class(attrs = {"pom_xml": attr.label()})
maven = module_extension(
    implementation=_maven_impl,
    tag_classes={"dep": maven_dep, "pom": maven_pom},
)

# @rules_jvm_external//:extensions.bzl
load("//:repo_rules.bzl", "maven_single_jar")
def _maven_impl(ctx):
  coords = []
  for mod in ctx.modules:
    coords += [dep.coord for dep in mod.tags.dep]
  output = ctx.execute(["coursier", "resolve", coords])  # hypothetical call
  repo_attrs = process_coursier(output)
  [maven_single_jar(**attrs) for attrs in repo_attrs]
```





## Recommanded rules 
## Build with Bazel 



## Commands and options 
- target syntax 

bazel build, bazel run, and bazel test 

- package_path, This option specifies the set of directories that are searched to find the BUILD file for package 

first character is /, the path is absolute.

starts with %workspace%, the path is taken relative to the nearest enclosing bazel director

Anything else is taken relative to the working directory 

- error checking 

check_visibility 

output_filter=regex 

`--output_filter='^//(first/project|second/project):'`	Show the output for the specified packages.

- tool flags, which options Bazel will pass to other tools

```
--copt=cc-option

This option takes an argument which is to be passed to the compiler.

--host_copt=cc-option
This option takes an argument which is to be passed to the compiler for source files that are compiled in the host configuration.


--linkopt=linker-option
This option takes an argument which is to be passed to the compiler when linking.


--strip (always|never|sometimes)
This option determines whether Bazel will strip debugging information from all binaries

--fdo_instrument=profile-output-dir
The --fdo_instrument option enables the generation of FDO (feedback directed optimization) profile output when the built C/C++ binary is executed. the LLVM compiler the argument is also the directory under which the raw LLVM profile data file(s) is dumped. For example: --fdo_instrument=/path/to/rawprof/dir/.

--fdo_optimize=profile-zip
The --fdo_optimize option enables the use of the per-object file profile information to perform FDO (feedback directed optimization) optimizations when compiling. 

...
```

- build semantics 

```
build commands and/or the output file contents.

--compilation_mode (fastbuild|opt|dbg) (-c)
The --compilation_mode option (often shortened to -c, especially -c opt) takes an argument of fastbuild, dbg or opt, and affects various C/C++ code-generation options

-cpu=cpu
This option specifies the target CPU architecture

--action_env=VAR=VALUE
Specifies the set of environment variables available during the execution of all actions.

--host_cpu=cpu
This option specifies the name of the CPU architecture that should be used to build host tools

--per_file_copt=[+-]regex[,[+-]regex]...@option[,option]...
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

--dynamic_mode=mode
Determines whether C++ binaries will be linked dynamically, interacting with the linkstatic attribute on build rules.

--fission (yes|no|[dbg][,opt][,fastbuild])
Enables Fission, which writes C++ debug information to dedicated .dwo files 

--custom_malloc=malloc-library-target
When specified, always use the given malloc implementation, overriding all malloc="target"

--compiler=version
This option specifies the C/C++ compiler version (such as gcc-4.1.0) to be used for the compilation of binaries during the build
```

- execution strategy 

```
--spawn_strategy=strategy
This option controls where and how commands are executed

--jobs=n (-j)
This option, which takes an integer argument, specifies a limit on the number of jobs that should be executed concurrently during the execution

--local_{ram,cpu}_resources resources or resource expression
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. 

...
```

- output selection 

```
--[no]build
This option causes the execution phase of the build to occur

--[no]build_tests_only
If specified, Bazel will build only what is necessary to run the *_test and test_suite rules 

--[no]check_up_to_date
This option causes Bazel not to perform a build, but merely check whether all specified targets are up-to-date. 

--[no]compile_one_dependency
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. 

--save_temps
The --save_temps option causes temporary outputs from the compiler to be saved. These include .s files (assembler code), .i (preprocessed C) and .ii (preprocessed C++) files.

--build_tag_filters=tag[,tag]*
If specified, Bazel will build only targets that have at least one required tag

--test_filter=filter-expression
Specifies a filter that the test runner may use to pick a subset of tests for running
```

- Verbosity control the verbosity of Bazel's output, either to the terminal, or to additional log files.

```
--explain=logfile
This option, which requires a filename argument, causes the dependency checker in bazel build's execution phase to explain, for each build step, either why it is being executed, or that it is up-to-date

--profile=file
This option, which takes a filename argument, causes Bazel to write profiling data into a file.

--sandbox_debug
This option causes Bazel to print extra debugging information when using sandboxing for action execution.

--subcommands (-s)
This option causes Bazel's execution phase to print the full command line for each command prior to executing it

--verbose_failures
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.
```

- Workspace status  "stamp" Bazel-built binaries: to embed additional information into the binaries

```
--workspace_status_command=program
This flag lets you specify a binary that Bazel runs before each build.

...
```

- Platform 
```
--platforms=labels
The labels of the platform rules describing the target platforms for the current command.

--host_platform=label
The label of a platform rule that describes the host system.

--extra_toolchains=labels
The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. 

declared in the WORKSPACE file by register_toolchains().

--toolchain_resolution_debug=regex
Print debug information while finding toolchains if the toolchain type matches the regex.

...
```

- miscellaneous 

```
--symlink_prefix=string
Changes the prefix of the generated convenience symlinks. The default value for the symlink prefix is bazel- 

--platform_suffix=string
Adds a suffix to the configuration short name

...
```

- Running tests, options for command 

$ bazel test

```
--cache_test_results=(yes|no|auto) (-t)
If this option is set to 'auto' (the default) 

--test_verbose_timeout_warnings
This option tells Bazel to explicitly warn the user if a test's timeout is significantly longer than the test's actual execution time

--runs_per_test=[regex@]number
This option specifies the number of times each test should be executed

--test_summary=output_style
Specifies how the test result summary should be displayed

--test_output=output_style
Specifies how test output should be displayed

--[no]verbose_test_summary
By default this option is enabled

--test_arg=arg
Passes command-line options/flags/arguments to each test process.

--test_tmpdir=path
Specifies temporary directory for tests executed locally

--test_env=variable=_value_ OR --test_env=variable
Specifies additional variables that must be injected into the test environment

--run_under=command-prefix
This specifies a prefix that the test runner will insert in front of the test command before running it. 
```

- Test selection A convenience general name filter can forward particular filter 

- Running executable 

The bazel run command is similar to bazel build, except it is used to build and run a single target  

variables are also available to the binary:

BUILD_WORKSPACE_DIRECTORY: the root of the workspace where the build was run.
BUILD_WORKING_DIRECTORY: the current working directory where Bazel was run from

    + Options for bazel run 
    
```
--run_under=command-prefix
This has the same effect as the --run_under option for bazel test

--test_* arguments have an effect when running a test in this manner except --test_arg 

```

- Cleaning build outpus     \

```
a Bazel instance, you can specify the --expunge option to complete remove 

bazel clean --expunge

--expunge_async
```

incorrect incremental build, file a bug report

- Querying dependency graph 

$ bazel query --output location 'kind(genrule, deps(kind(".*_test rule", foo/bar/pebl/...)))'

```
--[no]tool_deps option, enabled by default, causes dependencies in non-target configurations to be included

-[no]implicit_deps option, enabled by default, causes implicit dependencies to be included in the dependency graph over which the query operates.

$ bazel query --output location 'kind(genrule, deps(kind(".*_test rule", foo/bar/pebl/...)))'
```

- Querying the action graph 

- Miscellaneous 

help 

shutdown 

info 

version 

mobile-install 

dump 

memory tracking 

analyze-profile 

canonicalize-flags, command, which takes a list of options for a Bazel command and returns a list of options that has the same effect. 

- Startup and miscellaneous, described in this section affect the startup of the Java virtual machine used by Bazel server process 

```
--batch
Batch mode causes Bazel to not use the standard client/server mode, but instead runs a bazel java process for a single command

--server_javabase=dir
Specifies the Java virtual machine in which Bazel itself runs.

--color (yes|no|auto)
This option determines whether Bazel will use colors to highlight its output on the screen.

--config=name
Selects additional config section from the rc files; for the current command

...
```


- reference 

DWARF Extensions for Separate Debug Information Files https://gcc.gnu.org/wiki/DebugFission





## Write bazelrc files 
- avoid specifying these unchanged options for every build (and other commands), you can specify options in a configuration file, called .bazelrc
- Where are the .bazelrc files. basel looks for optional configuration files in the following locations 

    + The system RC file, unless --nosystem_rc is present.  Path:

On Linux/macOS/Unixes: /etc/bazel.bazelrc
On Windows: %ProgramData%\bazel.bazelrc

system-specified location may contain environment variable references, such as ${VAR_NAME} on Unix or %VAR_NAME% on Windows.

    + a custom Bazel binary, overriding the BAZEL_SYSTEM_BAZELRC_PATH value in //src/main/cpp:option_processor.

    + The workspace RC file, unless --noworkspace_rc is present.

Path: .bazelrc in your workspace directory

    + The home RC file, unless --nohome_rc is present.

On Linux/macOS/Unixes: $HOME/.bazelrc
On Windows: %USERPROFILE%\.bazelrc if exists, or %HOME%/.bazelrc

    + The user-specified RC file, if specified with --bazelrc=file

- .bazelrc syntax 
    
.bazelrc file is a text file with a line-based grammar. Empty lines and lines starting with # (comments) are ignored.

specify a path that is relative to the workspace root, write import %workspace%/path/to/bazelrc.

using import and try-import to add files

Options take the latest values 

- option defaults, Most lines of a bazelrc define default option values
                                                       
startup: startup options, which go before the command  startup_options

common: options that apply to all Bazel commands.

command: Bazel command, such as build or query to which the options apply.

```
syntax similar to that of .cvsrc.) For example, the lines:


build --test_tmpdir=/tmp/foo --verbose_failures
build --test_tmpdir=/tmp/bar
build --test_tmpdir=/tmp/foo --verbose_failures --test_tmpdir=/tmp/bar 

--config
# In addition to setting option defaults adding a :name suffix to the command. These options are ignored by default, but will be included when the option --config=name is present
```

- governing Bazel's behavior
.bazelignore
You can specify directories within the workspace that you want Bazel to ignore, such as related projects





## Call Bazel from scripts 
- The --output_base option controls where the Bazel process should write the outputs of a build t
- Bazel uses a long-running server process as an optimization. 

    1. to call shutdown 
    2. specify --max_idle_secs=5 so that idle servers shutdown
    
- exit code to all commands

0 - Success
2 - Command Line Problem, Bad or Illegal flags or command combination, or Bad Environment Variables. Your command line must be modified.
8 - Build Interrupted but we terminated with an orderly shutdown.
9 - The server lock is held and --noblock_for_lock was passed.
32 - External Environment Failure not on this machine.

33 - Bazel ran out of memory and crashed. You need to modify your command line.

34 - Reserved for Google-internal use.

35 - Reserved for Google-internal use.

36 - Local Environmental Issue, suspected permanent.

37 - Unhandled Exception / Internal Bazel Error.

38 - Reserved for Google-internal use.

41-44 - Reserved for Google-internal use.

45 - Error publishing results to the Build Event Service.

47 - Reserved for Google-internal use.

- return code for bazel build, bazel test 

1 - Build failed.
3 - Build OK, but some tests failed or timed out.
4 - Build successful but no tests were found even though testing was requested.

- bazel run 

1 - Build failed.

returns a non-zero exit code it will be the exit code of the command as well.

- bazel query 

3 - Partial success, but the query encountered 1 or more errors in the input BUILD file
7 - Command failure.

- you should disable reading the .bazelrc file by using the option --bazelrc=/dev/null. If you want to perform a build using the user's preferred settings

- command log file which you can find with the following command:

$ bazel info command_log

change the setting of the --output_base or --output_user_root options.

- parse for many purposes. Two options that may be helpful for your script are --noshow_progress which suppresses progress messages, and --show_result n



 

## Client/Server implementation
- The Bazel system is implemented as a long-lived server process. 
- When you run bazel, you're running the client. The client finds the server based on the output base 
- a Bazel server process appears in the output of ps x or ps -e f as bazel(dirname), where dirname is the basename of the directory
- Bazel server processes may be named just java.) Bazel servers can be stopped using the shutdown command.






## Quick start 
- the Bazel query reference and Bazel cquery reference manuals

https://bazel.build/query/language

cquery configurable query 
https://bazel.build/query/cquery

- run the application by pasting this command:

$ bazel-bin/runner

-  To use a query to view the rules of a package, run the command 

$ bazel query package_folder_name/…

- discover the underlying dependencies of the target by running the command:


$ bazel query --noimplicit_deps "deps(target)"

$ bazel query --noimplicit_deps "deps(:runner)"

- visualize the dependency graph (optional) 

visualize the dependency paths for a specific query. Graphviz

$ bazel query --noimplicit_deps 'deps(:runner)' --output graph > graph.in

$ dot -Tpng < graph.in > graph.png

- called a “reverse dependency”. Using rdeps() can be useful when editing a file in a codebase that you’re unfamiliar

$ bazel query "rdeps(universe_scope, target)"

$ ex) bazel query "rdeps(//... , //src/main/java/com/example/ingredients:cheese)"

- finding targets based on tags 

can tag Bazel targets with different identifiers

$ bazel query 'attr(tags, "pizza", //src/main/java/com/example/customers/...)'

- somepath() and allpaths()

Two functions can help you find dependency paths: somepath() and allpaths(). Given a starting target S and an end point E, find a path between S and E by using somepath(S,E).

$ bazel query "somepath(//src/main/java/com/example/restaurant/..., //src/main/java/com/example/ingredients:cheese)"

- run the package 

$ bazel build //src/main/java/com/example/reviews:review

$ bazel-bin/src/main/java/com/example/reviews/review





## Query guide 
- finding dependencies of a rule, use the deps function 

$ bazel query "deps(//foo)"

- Tracing the dependency chain between two packages with two functions, allpaths and somepath. You may also want to exclude tooling dependencies with --notool_deps

$ bazel query "allpaths(//foo, third_party/...)" --notool_deps --output graph | dot -Tsvg > /tmp/deps.svg

start with a single path:

$ bazel query "somepath(//foo:foo, third_party/zlib:zlibonly)"

by default will get a flatten list, add --output graph with allpaths, you will get graph 

$ bazel query "allpaths(//foo, third_party/...)"

- aside implicit dependencies, rules include implicit dependencies on additional libraries or tools. Using --noimplicit_deps allows you to filter out these deps

- reverse dependencies, the set of targets that depends on some target. For instance, if you're going to change some code, you might want to know what other code you're about to break. You can use rdeps(u, x) to find the reverse dependencies of the targets  

Bazel's Sky Query supports the allrdeps function which allows you to query

- Miscellaneous uses 

packages exist beneath foo?
$ bazel query 'foo/...' --output package

rules are defined in the foo package?
$ bazel query 'kind(rule, foo:*)' --output label_kind

those are C++ tests?
$ bazel query 'kind(cc_.*, tests(//foo:smoke_tests))'

bazel query 'attr(size, small, tests(//foo:smoke_tests))'

bazel query 'filter("pa?t", kind(".*_test rule", //foo/...))'

bazel query path/to/file/bar.java

package depdencies 
$ bazel query 'buildfiles(deps(//foo:foo))' --output package

what genproto rules does bar depend upon 
$ bazel query 'kind(genproto, deps(bar/...))'

$ bazel query 'kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo))'

$ bazel query 'somepath(bar/...,groups2/...:*)'

$ bazel query 'allpaths(//photos/frontend:lib, //third_party/jpeglib)
                intersect
               allpaths(//photos/frontend:lib, //third_party/jpeg)'

$ bazel query 'allpaths(bar/...,X)' --output graph | dot -Tsvg > /tmp/dep.svg

$ bazel query 'deps(//foo-tests)' --output maxrank | tail -1 85 //third_party/zlib:zutil.c




## Query language 
- The action graph query (aquery) operates on the post-analysis Configured Target Graph and exposes information about Actions, Artifacts, and their relationships.

- configurable query, cquery, properly handles configurations but doesn't provide all of the functionality of this original query. 

- examples 

    + show why //foo tree depend on //bar/baz?
    
    $ somepath(foo/..., //bar/baz:all)
    
    + check cpp library dependency 
    
    $ kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo:foo_bin))
    
- query token lexical syntax 

    + keywords 
    
    except

    in

    intersect

    let

    set

    union
    
    + Words, such as "foo/..." or ".*test rule" or "//bar/baz:all". If a character sequence is "quoted" (begins and ends with a single-quote ' or begins and ends with a double-quote "), it is a word.
    
    + Quoting is necessary when writing scripts that construct Bazel query expressions from user-supplied values.
    
```
 //foo:bar+wiz    # WRONG: scanned as //foo:bar + wiz.
 //foo:bar=wiz    # WRONG: scanned as //foo:bar = wiz.
 "//foo:bar+wiz"  # OK.
 "//foo:bar=wiz"  # OK.
```    




## Action graph query
- 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.

- aquery output (without specific details):

```
$ bazel aquery 'deps(//some:label)'
action 'Writing file some_file_name'
  Mnemonic: ...
  Target: ...
  Configuration: ...
  ActionKey: ...
  Inputs: [...]
  Outputs: [...]
```

- syntax for aquery is as follows:

$ bazel aquery "aquery_function(function(//target))"

The query expression (in quotes) consists of the following:

aquery_function(...): functions specific to aquery. More details below.
function(...): the standard functions as traditional query.
//target is the label to the interested target.

    + examples:
```
# Get the action graph generated while building //src/target_a
$ bazel aquery '//src/target_a'

# Get the action graph generated while building all dependencies of //src/target_a
$ bazel aquery 'deps(//src/target_a)'

# Get the action graph generated while building all dependencies of //src/target_a
# whose inputs filenames match the regex ".*cpp".
$ bazel aquery 'inputs(".*cpp", deps(//src/target_a))'
```

- three aquery functions 

```
inputs: filter actions by inputs.
outputs: filter actions by outputs
mnemonic: filter actions by mnemonic
expr ::= inputs(word, expr)

```

$ bazel aquery 'inputs(".*cpp", deps(//src/target_a))'

combine to achive AND operation 
$ bazel aquery 'mnemonic("Cpp.*", (inputs(".*cpp", inputs("foo.*", //src/target_a))))'

- Build options

aquery runs on top of a regular Bazel build and thus inherits the set of options available during a build.

- Aquery options

```
--output=(text|summary|proto|jsonproto|textproto), default=text
```
The default output format (text) is human-readable, use proto, textproto, or jsonproto

- Querying against the state of Skyframe
Skyframe is the evaluation and incrementality model of Bazel. On each instance of Bazel server, Skyframe stores the dependency graph

https://bazel.build/reference/skyframe

    + query on skyframe 
    
```
$ bazel build //target_a
$ bazel build //target_b
# foo.out was generated.

# List all actions on Skyframe's action graph
$ bazel aquery --output=proto --skyframe_state

# List all actions on Skyframe's action graph, whose output matches "foo.out"
$ bazel aquery --output=proto --skyframe_state 'outputs("foo.out")'
```

- comparing aquery outputs 

```
--before, --after: The aquery output files to be compared
```

- It is possible for Aspects to be applied on top of each other. The aquery output of the action generated by these Aspects would then include the Aspect path

- Linking with the JSON profile
While aquery provides information about the actions being run in a build

- Handling shared actions
Sometimes actions are shared between configured targets.



 
## Configurable query 
- cquery is a variant of query that correctly handles select() and build options' effects on the build graph.
- running over the results of Bazel's analysis phase, which integrates these effects. query, by constrast, runs over the results of Bazel's loading phase, before options are evaluated.

- example 

```
sh_library(
    name = "ash",
    deps = select({
        ":excelsior": [":manna-ash"],
        ":americana": [":white-ash"],
        "//conditions:default": [":common-ash"],
    }),
)
sh_library(name = "manna-ash")
sh_library(name = "white-ash")
sh_library(name = "common-ash")
config_setting(
    name = "excelsior",
    values = {"define": "species=excelsior"},
)
config_setting(
    name = "americana",
    values = {"define": "species=americana"},
)
```

```
# Traditional query: query doesn't know which select() branch you will choose,
# so it conservatively lists all of possible choices, including all used config_settings.
$ bazel query "deps(//tree:ash)" --noimplicit_deps
//tree:americana
//tree:ash
//tree:common-ash
//tree:excelsior
//tree:manna-ash
//tree:white-ash

# cquery: cquery lets you set build options at the command line and chooses
# the exact dependencies that implies (and also the config_setting targets).
$ bazel cquery "deps(//tree:ash)" --define species=excelsior --noimplicit_deps
//tree:ash (9f87702)
//tree:manna-ash (9f87702)
//tree:americana (9f87702)
//tree:excelsior (9f87702)
```

- basic syntax 

$ bazel cquery "function(//target)"

function(...) is the function to run on the target. 

//target is the expression fed to the function. 

    + the functions is as same as aquery. functions are available:

allpaths
attr
buildfiles
rbuildfiles
deps
filter
kind
labels
loadfiles
rdeps
allrdeps
same_pkg_direct_rdeps
siblings
some
somepath
tests
visible

- //tree:ash (9f87702)

means //tree:ash was built in a configuration with ID 9f87702

- Target pattern evaluation
//foo has a different meaning for cquery than for query. This is because cquery evaluates configured targets and the build graph may have multiple configured versions of //foo.

For cquery, a target pattern in the query expression evaluates to every configured target with a label that matches that pattern. Output is deterministic

```
# Analyzes //foo in the target configuration, but also analyzes
# //genrule_with_foo_as_tool which depends on a host-configured
# //foo. So there are two configured target instances of //foo in
# the build graph.
$ bazel cquery //foo --universe_scope=//foo,//genrule_with_foo_as_tool
//foo (9f87702)
//foo (HOST)
```

- functions.  supports all but visible, siblings, buildfiles, and tests.

cquery also introduces the following new functions:

    + config, The config operator attempts to find the configured target for the label
    
    $ bazel cquery "config(//bar, host)" --universe_scope=//foo
    
- options, cquery runs over a regular Bazel build and thus inherits the set of options available during a build.

```

--universe_scope (comma-separated list)
Often, the dependencies of configured targets go through transitions

--implicit_deps (boolean, default=True)
Setting this flag to false filters out all results that aren't explicitly set in the BUILD file

--tool_deps (boolean, default=True)
Setting this flag to false filters out all configured targets
```

- output formats, exposing the results as well.

Transitions
```
--transitions=lite
--transitions=full
```

- space-separated list of the base names of all files produced by //foo:

```
  bazel cquery //foo --output=starlark \
    --starlark:expr="' '.join([f.basename for f in target.files.to_list()])"
```

All targets that cquery "builds" must have the same configuration.

Before evaluating queries, cquery triggers a build up to just before the point where build actions would execute. 



# Advanced 
## Configurable build attributes 
- Configurable attributes, commonly known as select(), is a Bazel feature that lets users toggle the values of build rule attributes at the command line.

```
# myapp/BUILD

cc_binary(
    name = "mybinary",
    srcs = ["main.cc"],
    deps = select({
        ":arm_build": [":arm_lib"],
        ":x86_debug_build": [":x86_dev_lib"],
        "//conditions:default": [":generic_lib"],
    }),
)

config_setting(
    name = "arm_build",
    values = {"cpu": "arm"},
)

config_setting(
    name = "x86_debug_build",
    values = {
        "cpu": "x86",
        "compilation_mode": "dbg",
    },
)
```

consume the rules 

$ bazel build //myapp:mybinary --cpu=arm	[":arm_lib"]
$ bazel build //myapp:mybinary -c dbg --cpu=x86	[":x86_dev_lib"]
$ bazel build //myapp:mybinary --cpu=ppc	[":generic_lib"]
$ bazel build //myapp:mybinary -c dbg --cpu=ppc	[":generic_lib"]

- select() serves as a placeholder for a value that will be chosen based on configuration conditions, which are labels referencing config_setting targets.

change the build parameters for all transitive dependencies under a target. For example, genrule's tools changes --cpu to the CPU of the machine running Bazel

```
#myapp/BUILD

config_setting(
    name = "arm_cpu",
    values = {"cpu": "arm"},
)

config_setting(
    name = "x86_cpu",
    values = {"cpu": "x86"},
)

genrule(
    name = "my_genrule",
    srcs = select({
        ":arm_cpu": ["g_arm.src"],
        ":x86_cpu": ["g_x86.src"],
    }),
    tools = select({
        ":arm_cpu": [":tool1"],
        ":x86_cpu": [":tool2"],
    }),
)

cc_binary(
    name = "tool1",
    srcs = select({
        ":arm_cpu": ["armtool.cc"],
        ":x86_cpu": ["x86tool.cc"],
    }),
)
```
 
$ bazel build //myapp:my_genrule --cpu=arm

- configurable attribute is a label reference to a config_setting or constraint_value.

constraint_value provides support for multi-platform behavior.


- built-in flags  config_setting's values attribute:

```
config_setting(
    name = "meaningful_condition_name",
    values = {
        "flag1": "value1",
        "flag2": "value2",
        ...
    },
)
```

flagN is a flag name (without --, so "cpu" instead of "--cpu"). valueN is the expected value for that flag.

valueN is parsed as if it was set on the command line. This means:

```
values = { "compilation_mode": "opt" } matches bazel build -c opt
values = { "force_pic": "true" } matches bazel build --force_pic=1
values = { "force_pic": "0" } matches bazel build --noforce_pic
```

- custom flags project-specific flags with Starlark build settings.

```
config_setting(
    name = "meaningful_condition_name",
    flag_values = {
        "//myflags:flag1": "value1",
        "//myflags:flag2": "value2",
        ...
    },
)

--define is an alternative legacy syntax for custom flags (for example --define foo=bar).
```

- default condition 

built-in condition //conditions:default matches when no other condition matches.

```
# myapp/BUILD

config_setting(
    name = "x86_cpu",
    values = {"cpu": "x86"},
)

cc_library(
    name = "x86_only_lib",
    srcs = select({
        ":x86_cpu": ["lib.cc"],
    }),
)
```
set custom messages with select()'s no_match_error attribute.

- Platforms, specify multiple flags on the command line provides flexibility

```
# myapp/BUILD

sh_binary(
    name = "my_rocks",
    srcs = select({
        ":basalt": ["pyroxene.sh"],
        ":marble": ["calcite.sh"],
        "//conditions:default": ["feldspar.sh"],
    }),
)

config_setting(
    name = "basalt",
    constraint_values = [
        ":black",
        ":igneous",
    ],
)

config_setting(
    name = "marble",
    constraint_values = [
        ":white",
        ":metamorphic",
    ],
)

# constraint_setting acts as an enum type, and constraint_value as an enum value.
constraint_setting(name = "color")
constraint_value(name = "black", constraint_setting = "color")
constraint_value(name = "white", constraint_setting = "color")

constraint_setting(name = "texture")
constraint_value(name = "smooth", constraint_setting = "texture")

constraint_setting(name = "type")
constraint_value(name = "igneous", constraint_setting = "type")
constraint_value(name = "metamorphic", constraint_setting = "type")

platform(
    name = "basalt_platform",
    constraint_values = [
        ":black",
        ":igneous",
    ],
)

platform(
    name = "marble_platform",
    constraint_values = [
        ":white",
        ":smooth",
        ":metamorphic",
    ],
)
```    

$ bazel build //my_app:my_rocks --platforms=//myapp:marble_platform

$ bazel build //my_app:my_rocks --define color=white --define texture=smooth --define type=metamorphic

    + select() directly read constraint_values 
    
```
constraint_setting(name = "type")
constraint_value(name = "igneous", constraint_setting = "type")
constraint_value(name = "metamorphic", constraint_setting = "type")
sh_binary(
    name = "my_rocks",
    srcs = select({
        ":igneous": ["igneous.sh"],
        ":metamorphic" ["metamorphic.sh"],
    }),
)
```

- combining select()s, select cannot appear inside another select 

```
sh_binary(
    name = "my_target",
    srcs = ["always_include.sh"] +
           select({
               ":armeabi_mode": ["armeabi_src.sh"],
               ":x86_mode": ["x86_src.sh"],
           }) +
           select({
               ":opt_mode": ["opt_extras.sh"],
               ":dbg_mode": ["dbg_extras.sh"],
           }),
)
```

- select or chaining 

```
load("@bazel_skylib//lib:selects.bzl", "selects")

sh_binary(
    name = "my_target",
    srcs = ["always_include.sh"],
    deps = selects.with_or({
        (":config1", ":config2", ":config3"): [":standard_lib"],
        ":config4": [":special_lib"],
    }),
)
```

    + config_setting_group, different targets can share :config1_or_2 across different attributes.
    
```
load("@bazel_skylib//lib:selects.bzl", "selects")

config_setting(
    name = "config1",
    values = {"cpu": "arm"},
)
config_setting(
    name = "config2",
    values = {"compilation_mode": "dbg"},
)
selects.config_setting_group(
    name = "config1_or_2",
    match_any = [":config1", ":config2"],
)
sh_binary(
    name = "my_target",
    srcs = ["always_include.sh"],
    deps = select({
        ":config1_or_2": [":standard_lib"],
        "//conditions:default": [":other_lib"],
    }),
)
```

- AND chaining 

```
config_setting(
    name = "config1",
    values = {"cpu": "arm"},
)
config_setting(
    name = "config2",
    values = {"compilation_mode": "dbg"},
)
selects.config_setting_group(
    name = "config1_and_2",
    match_all = [":config1", ":config2"],
)
sh_binary(
    name = "my_target",
    srcs = ["always_include.sh"],
    deps = select({
        ":config1_and_2": [":standard_lib"],
        "//conditions:default": [":other_lib"],
    }),
)
```

- custom error messages 

```
cc_library(
    name = "my_lib",
    deps = select(
        {
            "//tools/cc_target_os:android": [":android_deps"],
            "//tools/cc_target_os:windows": [":windows_deps"],
        },
        no_match_error = "Please build with an Android or Windows toolchain",
    ),
)
```

$ bazel build //myapp:my_lib

- rules compatibility 

```
# myapp/BUILD

some_rule(
    name = "my_target",
    some_attr = select({
        ":foo_mode": [":foo"],
        ":bar_mode": [":bar"],
    }),
)
```

$ bazel build //myapp/my_target --define mode=foo

- Macros can accept select() clauses and pass them through to native rules. But they cannot directly manipulate them.

- bazel query and cquery 

Bazel query operates over Bazel's loading phase. This means it doesn't know what command line flags a target uses since those flags aren't evaluated until later

Bazel cquery operates after Bazel's analysis phase, so it has all this information and can accurately resolve select()s.

```
load("@bazel_skylib//rules:common_settings.bzl", "string_flag")

# myapp/BUILD

string_flag(
    name = "dog_type",
    build_setting_default = "cat"
)

cc_library(
    name = "my_lib",
    deps = select({
        ":long": [":foo_dep"],
        ":short": [":bar_dep"],
    }),
)

config_setting(
    name = "long",
    flag_values = {":dog_type": "dachshund"},
)

config_setting(
    name = "short",
    flag_values = {":dog_type": "pug"},
)
```

$ bazel query 'deps(//myapp:my_lib)'
//myapp:my_lib
//myapp:foo_dep
//myapp:bar_dep

$ bazel cquery 'deps(//myapp:my_lib)' --//myapp:dog_type=pug
//myapp:my_lib
//myapp:bar_dep

- select() does work in rules! doesn't select() work in macros!  macros are evaluated before Bazel reads the build's command line flags. That means there isn't enough information to evaluate select()s.

```
# myapp/defs.bzl

# Rule implementation: when an attribute is read, all select()s have already
# been resolved. So it looks like a plain old attribute just like any other.
def _impl(ctx):
    name = ctx.attr.name
    allcaps = ctx.attr.my_config_string.upper()  # This works fine on all values.
    print("My name is " + name + " with custom message: " + allcaps)

# Rule declaration:
my_custom_bazel_rule = rule(
    implementation = _impl,
    attrs = {"my_config_string": attr.string()},
)

# Macro declaration:
def my_custom_bazel_macro(name, my_config_string):
    allcaps = my_config_string.upper()  # This line won't work with select(s).
    print("My name is " + name + " with custom message: " + allcaps)
    
    
# myapp/BUILD

load("//myapp:defs.bzl", "my_custom_bazel_rule")
load("//myapp:defs.bzl", "my_custom_bazel_macro")

my_custom_bazel_rule(
    name = "happy_rule",
    my_config_string = select({
        "//tools/target_cpu:x86": "first string",
        "//tools/target_cpu:ppc": "second string",
    }),
)

my_custom_bazel_macro(
    name = "happy_macro",
    my_config_string = "fixed string",
)

my_custom_bazel_macro(
    name = "sad_macro",
    my_config_string = select({
        "//tools/target_cpu:x86": "first string",
        "//tools/target_cpu:ppc": "other string",
    }),
)
```

- read select() like a dict 

```
$ cat myapp/defs.bzl
def selecty_genrule(name, select_cmd):
    cmd_suffix = ""
    if type(select_cmd) == "string":
        cmd_suffix = select_cmd + " WITH SUFFIX"
    elif type(select_cmd) == "dict":
        for key in select_cmd.keys():
            select_cmd[key] += " WITH SUFFIX"
        cmd_suffix = select(select_cmd + {"//conditions:default": "default"})

    native.genrule(
        name = name,
        outs = [name + ".out"],
        srcs = [],
        cmd = "echo " + cmd_suffix + "> $@",
    )
```

- select() doesn't work with bind(), Because bind() is a WORKSPACE rule, not a BUILD rule.

Workspace rules do not have a specific configuration, and aren't evaluated in the same way as BUILD rules

    + bind() target point to an alias(), if needed.

```
$ cat WORKSPACE
workspace(name = "myapp")
bind(name = "openssl", actual = "//:ssl")
http_archive(name = "alternative", ...)
http_archive(name = "boringssl", ...)

$ cat BUILD
config_setting(
    name = "alt_ssl",
    define_values = {
        "ssl_library": "alternative",
    },
)

alias(
    name = "ssl",
    actual = select({
        "//:alt_ssl": "@alternative//:ssl",
        "//conditions:default": "@boringssl//:ssl",
    }),
)
```

- use cquery and bazel config to debug:

If //myapp:foo is the top-level target you're building, run:

$ bazel cquery //myapp:foo <desired build flags>

$ $ bazel cquery 'somepath(//bar, //myapp:foo)' <desired build flags>

- doesn't select() work with platforms?

Bazel doesn't support configurable attributes checking whether a given platform is the target platform. workaround 

```
config_setting(
    name = "is_x86_linux",
    constraint_values = [
        "@platforms//cpu:x86",
        "@platforms//os:linux",
    ],
)

cc_library(
    name = "lib",
    srcs = [...],
    linkopts = select({
        ":is_x86_linux": ["--enable_x86_optimizations"],
        "//conditions:default": [],
    }),
)
```



## Integrating with C++ rules 
- how to get CcxToolchainInfo in a custom rule 

```
load("@bazel_tools//tools/cpp:toolchain_utils.bzl", "find_cpp_toolchain", "use_cpp_toolchain")

def _write_cc_toolchain_cpu_impl(ctx):
    cc_toolchain = find_cpp_toolchain(ctx)
    output = ctx.actions.declare_file(ctx.label.name + "_cpu")
    ctx.actions.write(output, cc_toolchain.cpu)
    return [DefaultInfo(files = depset([output]))]

# This rule does nothing, just writes the target_cpu from the cc_toolchain used for this build.
write_cc_toolchain_cpu = rule(
    implementation = _write_cc_toolchain_cpu_impl,
    attrs = {
        "_cc_toolchain": attr.label(default = Label("@bazel_tools//tools/cpp:current_cc_toolchain")),
    },
    toolchains = use_cpp_toolchain(),  # copybara-use-repo-external-label
)
```

- generating commandlines and environment variables using c++ toolchain 

    + features and action_configs - these come from the CcToolchainConfigInfo and encapsulated in CcToolchainInfo
    
    + FeatureConfiguration - returned by cc_common.configure_features
    
    + cc toolchain config variables - returned by cc_common.create_compile_variables or cc_common.create_link_variables.
    
- implementing starlark rules that depend on c++ rules and c++ rules can depend on 

Most C++ rules provide CcInfo (A provider for compilation and linking of C++. ), a provider containing CompilationContext (Immutable store of information needed for C++ compilation that is aggregated across dependencies.) and LinkingContext (Immutable store of information needed for C++ linking that is aggregated across dependencies.).

- reusing logic and actions of c++ rules 




## Implementing toolchain resolution 
- toolchain resolution implementration details 

RegisteredToolchainsFunction and RegisteredExecutionPlatformsFunction find available toolchains and execution platforms

SingleToolchainResolutionFunction resolves a single toolchain type for every execution platform.

    + toolchain and target platform are compatible, by checking the target_compatible_with attribute
    
    + toolchain and execution platform are compatible, by checking the exec_compatible_with attribute
    
    + If multiple toolchains are left, choose the first resigtered 
    
    + ToolchainResolutionFunction calls SingleToolchainResolutionFunction for each requested toolchain type

- Toolchains and Configurations, the dependency from a target to a toolchain uses a special configuration that forces the execution platform to be the same for both



## Code coverage with Bazel 
- This page documents the general process for creating and viewing coverage reports

- creating a coverage report 

A basic repository with test targets
A toolchain with the language-specific code coverage tools installed
A correct "instrumentation" configuration

    + using the --instrumentation_filter flag, which specifies a filter for targets that are tested with the instrumentation enabled
    
- running coverage, produce a coverage report, use bazel coverage --combined_report=lcov [target]. This runs the tests for the target, generating coverage reports in the lcov format for each file.

created under 

$(bazel info output_path)/_coverage/_coverage_report.dat.

- viewing coverage, The coverage report is only output in the non-human-readable lcov format.

$ genhtml --output genhtml "$(bazel info output_path)/_coverage/_coverage_report.dat" 

    + lcov project, https://github.com/linux-test-project/lcov
    
- remote execution  

The report combination action cannot yet run remotely.  

To work around this, use --strategy=CoverageReport=local. --remote_download_minimal and similar flags can also not be used as a consequence of the former.


bazel will currently fail to create coverage information if tests have been cached previously.  --experimental_split_coverage_postprocessing and --experimental_fetch_all_coverage_outputs





## Best practices 
- A project should always be able to run bazel build //... and bazel test //... successfully on its stable branch

- third-party dependencies 

declare them as remote repositories in the WORKSPACE file.

a directory called third_party/ under your workspace directory.

- depending on binaries 

create a BUILD file and build some-library.so from its sources, then depend on that target.

- versioning, diamond dependency issues: if one library depends on guava-19.0 and one depends on guava-20.0, you could end up with a library that tries to depend on two different versions.

- using the .bazelrc file 

configuration file your workspace/.bazelrc (see bazelrc format).

you do not want to check into source control, include the line try-import %workspace%/user.bazelrc

- packages,Every directory that contains buildable files should be a package 
 


## Optimize memory 
- set the maximum heap via the startup flag --host_jvm_args, like --host_jvm_args=-Xmx2g.
- Bazel may throw an OutOfMemoryError (OOM) when it doesn't have enough memory. You can make Bazel use less memory
- minimize the memory that Bazel uses in a build

    +  --discard_analysis_cache will reduce the memory used during execution
    +  --notrack_incremental_state will not store any edges in Bazel's internal dependency graph
    + --nokeep_state_after_build will discard all data after the build
    
    



## Using Bazel on Windows 
- issues are marked with the "team-Windows" label on GitHub

https://github.com/bazelbuild/bazel/issues?q=is%3Aopen+is%3Aissue+label%3Ateam-Windows&utm_source=bazel.build&utm_medium=referral

- Some tools have the Maximum Path Length Limitation on Windows, specify a short output directory for Bazel by the --output_user_root flag.

https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file?utm_source=bazel.build&utm_medium=referral#maximum-path-length-limitation

For file I/O, the "\\?\" prefix to a path string tells the Windows APIs to disable all string parsing and to send the string that follows it straight to the file system. 

Many but not all file I/O APIs support "\\?\"; you should look at the reference topic for each API to be sure. Unicode APIs should be used to make sure the "\\?\" prefix allows you to exceed the MAX_PATH

    + To avoid hitting this issue, you can specify a short output directory for Bazel by the --output_user_root flag.

$ startup --output_user_root=C:/tmp

- enable 8.3 filename support in all volumes, Bazel attempts to create a short name version for long file paths. But to do so the 8.3 filename support

$ fsutil 8dot3name set 0

- enable symlink support, Some features require Bazel to be able to create file symlinks on Windows, either by enabling Developer Mode (on Windows 10 version 1703 or newer), or by running Bazel as an administrator.

```
--windows_enable_symlinks
--enable_runfiles
```

    + add the following lines to your bazelrc file:

```
startup --windows_enable_symlinks
build --enable_runfiles
```

- Running Bazel: MSYS2 shell vs. command prompt vs. PowerShell

    + run bazel from the command prompt (cmd.exe) or powershell instead of bash 
    
    + While Bazel may work for most use cases, some things are broken, like interrupting the build with Ctrl+C from MSYS2). Also, if you choose to run under MSYS2, you need to disable MSYS2's automatic path conversion, otherwise MSYS will convert command line arguments that look like Unix paths (such as //foo:bar) into Windows paths.
    
    https://stackoverflow.com/a/49004265/7778502?utm_source=bazel.build&utm_medium=referral
    
- using bazel without bash (MSYS2). Starting with Bazel 1.0, you can build any rule without Bash unless it

    + genrule, genrules execute bash command 
    
    + sh_binary or sh_test, inheretly need bash 
    
    + starlark rule that uses ctx.actions.run_shell() or ctx.resolve_command()

-  Bazel 1.0, you can test any rule without Bash, except when:

you use --run_under  or --script_path

test rule itself requires Bash (because its executable is a shell script)

- shbinary and sh* rules, and ctx.actions.run_shell() without Bash is not on plan

- setting environment variables into system environment variable to avoid set them again whenever start cmd.exe 

- build on windows 

    + msvc  C++ targets with MSVC, you need:

    The Visual C++ compiler.

    + optional The BAZEL_VC and BAZEL_VC_FULL_VERSION environment variable. This environment variable will control bazel which version of the MSVC to use
       
    ```
    set BAZEL_VC=C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\VC
    set BAZEL_VC_FULL_VERSION=14.16.27023
    
    # For Visual Studio 2015 or older, set BAZEL_VC. (BAZEL_VC_FULL_VERSION is not supported.)
    set BAZEL_VC=C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC
    ```
    + windows sdk, supported with VC 2017 and 2019. The standalone VC 2015 Build Tools doesn't support selecting Windows SDK

    $ set BAZEL_WINSDK_FULL_VERSION=10.0.10240.0

    + Try building a target from one of our sample projects
    
    ```
    $ bazel build //examples/cpp:hello-world
    $ bazel-bin\examples\cpp\hello-world.exe
    ```   
    
    + specify different windows target, specify a different target architecture, set the --cpu build option for your target architecture: * x64 (default): --cpu=x64_windows or no option * x86: --cpu=x64_x86_windows * ARM: --cpu=x64_arm_windows * ARM64: --cpu=arm64_windows
    
    + to build and use Dynamically Linked Libraries (DLL files)
    
    + Command Line Length Limit: To prevent the Windows command line length limit issue, enable the compiler parameter file feature via --features=compiler_param_file.
    
    ```
    does not compile under windows

    cc_library(
        name = "long",
        includes = ["a" * 32768]
        )
        cc_binary(
        name = "long_bin",
        srcs = ["main.cpp"],
        deps = [
            ":long"
        ]
    )
    ```
    
    + build arm 
    
    $ bazel build //examples/cpp:hello-world --cpu=x64_arm_windows
    
- build c++ with clang

    + install llvm's msvc compatible compiler drver (clang-cl.exe)
    
    + install llvm 
    
    + install visual c++ build tools 
    
    + explicitly tell bazel where llvm is installed by BAZEL_LLVM the LLVM installation directory


    $ set BAZEL_LLVM=C:\Program Files\LLVM 
    
    + enable clang toolchain for c++. there are two ways 
    
        * Without --incompatible_enable_cc_toolchain_resolution: You can enable the Clang toolchain by a build flag --compiler=clang-cl.
    
        * with --incompatible_enable_cc_toolchain_resolution: You have to add a platform target to your BUILD file
    
        ```
        platform(
            name = "x64_windows-clang-cl",
            constraint_values = [
                "@platforms//cpu:x86_64",
                "@platforms//os:windows",
                "@bazel_tools//tools/cpp:clang-cl",
            ],
        )
        ```
        
        specify additional build flags 
        
        $... --extra_toolchains=@local_config_cc//:cc-toolchain-x64_windows-clang-cl --extra_execution_platforms=//:x64_windows-clang-cl
        
        register platform and toolchain in WORKSPACE file 
        
        ```
        platform and toolchain in your WORKSPACE file:

        register_execution_platforms(
            ":x64_windows-clang-cl"
        )

        register_toolchains(
            "@local_config_cc//:cc-toolchain-x64_windows-clang-cl",
        )
        ```
        
        The --incompatible_enable_cc_toolchain_resolution flag is planned to be enabled by default in future Bazel release
    
- build java

build Java targets, you need:

    + The Java SE Development Kit
    + On Windows, Bazel builds two output files for java_binary rules:

a .jar file
a .exe file that can set up the environment for the JVM and run the binary

```
$ bazel build //examples/java-native/src/main/java/com/example/myproject:hello-world
$ bazel-bin\examples\java-native\src\main\java\com\example\myproject\hello-world.exe
```

- build python 

    + python interpreter 
    
    + py_binary rules 
    
    a self-extracting zip file 
    
    an executable file that can launch the python interpreter with the self-extracting zip file 
    
    + build python target 
    
```
$ bazel build //examples/py_native:bin
$ bazel-bin\examples\py_native\bin.exe
$ python bazel-bin\examples\py_native\bin.zip
```



# C++ Toolchain configuration 
- invoke the compiler with the right options. bazel needs 

    + Whether the compiler supports thinLTO, modules, dynamic linking, or PIC (position independent code).

    + Paths to the required tools such as gcc, ld, ar, objcopy, and so on.
    
    + The built-in system include directories. Bazel needs these to validate that all headers that were included in the source file in BUILD file 
    
    + default sysroot 
    
    + which flags to use for compilation, linking and archiving 
    
    + which flags to use for supported complication modes (opt, dbg, fastbuild)
    
    + make varialbes specifically required by the compiler 
    
- CcToolchainConfigInfo is a provider that provides the necessary level of granularity for configuring the behavior of Bazel's C++ rules

- point the toolchain_config attribute of the cc_toolchain to your rule. You can create the CcToolchainConfigInfo by calling cc_common.create_cc_toolchain_config_info()

- find Starlark constructors for all structs in @rules_cc//cc:cc_toolchain_config_lib.bzl.

- the cc_toolchain.toolchain_config attribute. The cc_toolchain target passes this information to the C++ target through a CcToolchainProvider.
    
    + a compile or link action, instantiated by a rule such as cc_binary or cc_library,
    
        * The compiler or linker to use
        * Command-line flags for the compiler/linker
        * Configuration flags passed through the --copt/--linkopt options
        * Environment variables
        * Artifacts needed in the sandbox in which the action executes    
    
    specified in the Starlark target that the cc_toolchain

    artifacts to be shipped to the sandbox are declared in the cc_toolchain target

- toolchain selection 

    + User specifies a cc_toolchain_suite target in the BUILD file and points Bazel to the target using --crosstool_top 

    + The cc_toolchain_suite target references multiple toolchains. The values of the --cpu and --compiler flags determine which of those toolchains is selected
    
    if --compiler option is specified, Bazel selects the corresponding entry from the cc_toolchain_suite.toolchains attribute with --cpu | --compiler. 
    
    If the --compiler option is not specified, Bazel selects the corresponding entry from the cc_toolchain_suite.toolchains attribute with just --cpu.
    
    If no flags are specified, Bazel inspects the host system and selects a --cpu value based on its findings.
    
    Once a toolchain has been selected, corresponding feature and action_config objects in the Starlark rule govern the configuration of the build 
    
- C++ rules support multiple unique actions documented in detail in the Bazel source code.
 
- Features 

    + A feature is an entity that requires command-line flags, actions, constraints on the execution environment, or dependency alterations.
    
    + treat_warnings_as_errors, or interact with the C++ rules and include new compile actions and inputs to the compilation, such as header_modules or thin_lto
    
    + CcToolchainConfigInfo contains a list of features, where each feature consists of one or more flag groups. a list of flags that apply to specific Bazel actions.

    + A feature is specified by name, which allows full decoupling of the Starlark rule configuration from Bazel releases
    
    + a feature is enabled by 
    
    is set to true 
    
    bazel or rule owner explicitly enable it 
    
    user enables it throught the --feature bazel option or features rule attribute 
    
- feature relationships 

constraint                              description 

requires = [                            The feature is supported only if the specified required features are enabled.
   feature_set (features = [
       'feature-name-1',
       'feature-name-2'
   ]),
]

implies = ['feature']                   This feature implies the specified feature(s).

provides = ['feature']                  this feature is one of several mutually exclusive alternate features.

with_features = [                       feature can specify multiple flag sets with multiple. When with_features is specified
  with_feature_set(                     all the features specified in not_features set are disabled
    features = ['feature-1'],
    not_features = ['feature-2'],
  ),
]

- Actions provide the flexibility to modify the circumstances under which an action executes without assuming how the action will be run. 

Features reference actions to signal which Bazel actions they affect since actions can modify the Bazel action graph

"assembler actions" and "compiler actions" in the table below are CppCompileAction, while the link actions are CppLinkAction.

    + assembler actions 
    
preprocess-assemble 

assemble 

    + compiler actions 
    
cc-flags-make-variable 
c-compile 
c++-compile 
c++-header-parsing     Run the compiler's parser on a header file to ensure that the header is self-contained

    + link actions 
    
c++-link-dynamic-library
c++-link-nodeps-dynamic-library
c++-link-executable

    + AR actions 
    
c++-link-static-library

    + LTO action 
    
    lto-backend     ThinLTO action compiling bitcodes into native objects 
    lto-index       ThinLTO action generating global index 
    
- using action_config 

The action_config is a Starlark struct that describes a Bazel action by specifying the tool (binary) to invoke during the action and sets of flags defined by features

action_name 
tools 
flag_sets 
env_sets, environment constraints 

the goal is to avoid unnecessary action_config+feature pairs. 

- using tool constructor 

tool_path, path to the tool in question  relative to current location 
with_features, a list of features sets out of which at least one must be satisfied 

an action_config until a tool with a with_feature set matching the feature configuration is found 
 
- example usages 

decompressing that archive to produce the application bundle and .plist files consumable by Xcode.

```
Bazel action:


load("@rules_cc//cc:defs.bzl", "ACTION_NAMES")

action_configs = [
    action_config (
        config_name = ACTION_NAMES.cpp_link_executable,
        action_name = ACTION_NAMES.cpp_link_executable,
        tools = [
            tool(
                with_features = [
                    with_feature(features=["generate-debug-symbols"]),
                ],
                tool_path = "toolchain/mac/ld-with-dsym-packaging",
            ),
            tool (tool_path = "toolchain/mac/ld"),
        ],
    ),
]

features = [
    feature(
        name = "generate-debug-symbols",
        flag_sets = [
            flag_set (
                actions = [
                    ACTION_NAMES.c_compile,
                    ACTION_NAMES.cpp_compile
                ],
                flag_groups = [
                    flag_group(
                        flags = ["-g"],
                    ),
                ],
            )
        ],
        implies = ["unbundle-debuginfo"],
   ),
]
```

    + same feature can be implemented entirely differently for Linux, which uses fission, or for Windows, which produces .pdb

```
load("@rules_cc//cc:defs.bzl", "ACTION_NAMES")

action_configs = [
    action_config (
        name = ACTION_NAMES.cpp_compile,
        tools = [
            tool(
                tool_path = "toolchain/bin/gcc",
            ),
        ],
    ),
]

features = [
    feature (
        name = "generate-debug-symbols",
        requires = [with_feature_set(features = ["dbg"])],
        flag_sets = [
            flag_set(
                actions = [ACTION_NAMES.cpp_compile],
                flag_groups = [
                    flag_group(
                        flags = ["-gsplit-dwarf"],
                    ),
                ],
            ),
            flag_set(
                actions = [ACTION_NAMES.cpp_link_executable],
                flag_groups = [
                    flag_group(
                        flags = ["-Wl", "--gdb-index"],
                    ),
                ],
            ),
      ],
    ),
]
```    

- flag groups 

CcToolchainConfigInfo allows you to bundle flags into groups that serve a specific purpose. You can specify a flag within using pre-defined variables within the flag value, which the compiler expands when adding the flag to the build command

```
flag_group (
    flags = ["%{output_execpath}"],
)
```

Flag groups are expanded to the build command
```
flag_group (
    iterate_over = "include_paths",
    flags = ["-I%{include_paths}"],
)

# expands to -I<path> for each path element in the include_paths list.
flag_group (
    iterate_over = "include_paths",
    flags = ["-iprefix=%{include_paths}", "-isystem=%{include_paths}"],
)

# Variables can correspond to structures accessible using dot-notation. For example:
flag_group (
    flags = ["-l%{libraries_to_link.name}"],
)

# must specify the full path through the fields. For example:
flag_group (
    iterate_over = "libraries_to_link",
    flag_groups = [
        flag_group (
            iterate_over = "libraries_to_link.shared_libraries",
            flags = ["-l%{libraries_to_link.shared_libraries.name}"],
        ),
    ],
)
```

- conditional expansion, Flag groups support conditional expansion based on the presence of a particular variable or its field using the expand_if_available, expand_if_not_available, expand_if_true, expand_if_false, or expand_if_equal

```
flag_group (
    iterate_over = "libraries_to_link",
    flag_groups = [
        flag_group (
            iterate_over = "libraries_to_link.shared_libraries",
            flag_groups = [
                flag_group (
                    expand_if_available = "libraries_to_link.shared_libraries.is_whole_archive",
                    flags = ["--whole_archive"],
                ),
                flag_group (
                    flags = ["-l%{libraries_to_link.shared_libraries.name}"],
                ),
                flag_group (
                    expand_if_available = "libraries_to_link.shared_libraries.is_whole_archive",
                    flags = ["--no_whole_archive"],
                ),
            ],
        ),
    ],
)
```

The --whole_archive and --no_whole_archive options are added to the build command only when a currently iterated library has an is_whole_archive field.

- CcToolchainConfigInfo reference, CcToolchainConfigInfo build variables

- Well-known features  

Variable	                        Action	                        Description
source_file	                        compile	                        Source file to compile.
input_file	                        strip	                        Artifact to strip.
output_file	                        compile	                        Compilation output.
output_assembly_file	            compile	                        Emitted assembly file. Applies only when the compile action emits assembly text, typically when using the --save_temps flag. The contents are the same as for output_file.
output_preprocess_file	            compile	                        Preprocessed output. Applies only to compile actions that only preprocess the source files, typically when using the --save_temps flag. The contents are the same as for output_file.
includes	                        compile	Sequence of files the compiler must unconditionally include in the compiled source.
include_paths	                    compile	Sequence directories in which the compiler searches for headers included using #include<foo.h> and #include "foo.h".
quote_include_paths	                compile	Sequence of -iquote includes - directories in which the compiler searches for headers included using #include "foo.h".
system_include_paths	            compile	Sequence of -isystem includes - directories in which the compiler searches for headers included using #include <foo.h>.
dependency_file	                    compile	The .d dependency file generated by the compiler.
preprocessor_defines	            compile	Sequence of defines, such as --DDEBUG.
pic	                                compile	Compiles the output as position-independent code.
gcov_gcno_file	                    compile	The gcov coverage file.
per_object_debug_info_file	        compile	The per-object debug info (.dwp) file.
stripotps	                        strip	Sequence of stripopts.
legacy_compile_flags	            compile	Sequence of flags from legacy CROSSTOOL fields such as compiler_flag, optional_compiler_flag, cxx_flag, and optional_cxx_flag.
user_compile_flags	                compile	Sequence of flags from either the copt rule attribute or the --copt, --cxxopt, and --conlyopt flags.
unfiltered_compile_flags	        compile	Sequence of flags from the unfiltered_cxx_flag legacy CROSSTOOL field or the unfiltered_compile_flags feature. These are not filtered by the nocopts rule attribute.
sysroot		                                                        The sysroot.
runtime_library_search_directories	link	Entries in the linker runtime search path (usually set with the -rpath flag).
library_search_directories	        link	Entries in the linker search path (usually set with the -L flag).
libraries_to_link	                link	Flags providing files to link as inputs in the linker invocation.
def_file_path	                    link	Location of def file used on Windows with MSVC.
linker_param_file	                link	Location of linker param file created by bazel to overcome command line length limit.
output_execpath	                    link	Execpath of the output of the linker.
generate_interface_library	        link	"yes" or "no" depending on whether interface library should be generated.
interface_library_builder_path	    link	Path to the interface library builder tool.
interface_library_input_path	    link	Input for the interface library ifso builder tool.
interface_library_output_path	    link	Path where to generate interface library using the ifso builder tool.
legacy_link_flags	                link	Linker flags coming from the legacy CROSSTOOL fields.
user_link_flags	                    link	Linker flags coming from the --linkopt or linkopts attribute.
linkstamp_paths	                    link	A build variable giving linkstamp paths.
force_pic	                        link	Presence of this variable indicates that PIC/PIE code should be generated (Bazel option `--force_pic` was passed).
strip_debug_symbols	                link	Presence of this variable indicates that the debug symbols should be stripped.
is_cc_test	                        link	Truthy when current action is a cc_test linking action, false otherwise.
is_using_fission	compile,        link	Presence of this variable indicates that fission (per-object debug info) is activated. Debug info will be in .dwo files instead of .o files and the compiler and linker need to know this.
fdo_instrument_path	compile,        link	Path to the directory that stores FDO instrumentation profile.
fdo_profile_path	                compile	Path to FDO profile.
fdo_prefetch_hints_path	            compile	Path to the cache prefetch profile.
csfdo_instrument_path	            compile, link	Path to the directory that stores conte


Feature	                                        Documentation
opt | dbg | fastbuild	                        Enabled by default based on compilation mode.
static_linking_mode | dynamic_linking_mode	    Enabled by default based on linking mode.
per_object_debug_info	                        Enabled if the supports_fission feature is specified and enabled and the current compilation mode is specified in the --fission flag.
supports_start_end_lib	                        If enabled (and the option --start_end_lib is set), Bazel will not link against static libraries but instead use the --start-lib/--end-lib linker options to link against objects directly. This speeds up the build since Bazel doesn't have to build static libraries.
supports_interface_shared_libraries	            If enabled (and the option --interface_shared_objects is set), Bazel will link targets that have linkstatic set to False (cc_tests by default) against interface shared libraries. This makes incremental relinking faster.
supports_dynamic_linker	                        If enabled, C++ rules will know the toolchain can produce shared libraries.
static_link_cpp_runtimes	                    If enabled, Bazel will link the C++ runtime statically in static linking mode and dynamically in dynamic linking mode. Artifacts specified in the cc_toolchain.static_runtime_lib or cc_toolchain.dynamic_runtime_lib attribute (depending on the linking mode) will be added to the linking actions.
supports_pic	                                If enabled, toolchain will know to use PIC objects for dynamic libraries. The `pic` variable is present whenever PIC compilation is needed. If not enabled by default, and `--force_pic` is passed, Bazel will request `supports_pic` and validate that the feature is enabled. If the feature is missing, or couldn't be enabled, `--force_pic` cannot be used.
static_linking_mode | dynamic_linking_mode	    Enabled by default based on linking mode.
no_legacy_features	                            Prevents Bazel from adding legacy features to the C++ configuration when present. See the complete list of features below.

- legacy features patching logic, Bazel applies the following changes to the toolchain's features for backwards compatibility

Moves legacy_compile_flags feature to the top of the toolchain
Moves default_compile_flags feature to the top of the toolchain
Adds dependency_file (if not present) feature to the top of the toolchain
Adds pic (if not present) feature to the top of the toolchain
Adds per_object_debug_info (if not present) feature to the top of the toolchain
Adds preprocessor_defines (if not present) feature to the top of the toolchain
Adds includes (if not present) feature to the top of the toolchain
Adds include_paths (if not present) feature to the top of the toolchain
Adds fdo_instrument (if not present) feature to the top of the toolchain
Adds fdo_optimize (if not present) feature to the top of the toolchain
Adds cs_fdo_instrument (if not present) feature to the top of the toolchain
Adds cs_fdo_optimize (if not present) feature to the top of the toolchain
Adds fdo_prefetch_hints (if not present) feature to the top of the toolchain
Adds autofdo (if not present) feature to the top of the toolchain
Adds build_interface_libraries (if not present) feature to the top of the toolchain
Adds dynamic_library_linker_tool (if not present) feature to the top of the toolchain
Adds shared_flag (if not present) feature to the top of the toolchain
Adds linkstamps (if not present) feature to the top of the toolchain
Adds output_execpath_flags (if not present) feature to the top of the toolchain
Adds runtime_library_search_directories (if not present) feature to the top of the toolchain
Adds library_search_directories (if not present) feature to the top of the toolchain
Adds archiver_flags (if not present) feature to the top of the toolchain
Adds libraries_to_link (if not present) feature to the top of the toolchain
Adds force_pic_flags (if not present) feature to the top of the toolchain
Adds user_link_flags (if not present) feature to the top of the toolchain
Adds legacy_link_flags (if not present) feature to the top of the toolchain
Adds static_libgcc (if not present) feature to the top of the toolchain
Adds fission_support (if not present) feature to the top of the toolchain
Adds strip_debug_symbols (if not present) feature to the top of the toolchain
Adds coverage (if not present) feature to the top of the toolchain
Adds llvm_coverage_map_format (if not present) feature to the top of the toolchain
Adds gcc_coverage_map_format (if not present) feature to the top of the toolchain
Adds fully_static_link (if not present) feature to the bottom of the toolchain
Adds user_compile_flags (if not present) feature to the bottom of the toolchain
Adds sysroot (if not present) feature to the bottom of the toolchain
Adds unfiltered_compile_flags (if not present) feature to the bottom of the toolchain
Adds linker_param_file (if not present) feature to the bottom of the toolchain
Adds compiler_input_flags (if not present) feature to the bottom of the toolchain
Adds compiler_output_flags (if not present) feature to the bottom of the toolchain










# Remote distribution 
## Remote Execution Overview 
- Remote execution of a Bazel build allows you to distribute build and test actions across multiple machines

fast build 

a consistent execution environment 

reuse of build outputs 

- Bazel uses an open-source gRPC protocol to allow for remote execution and remote caching.



## RBE rules
- Configuring bazel ci to test rules for remote execution 

- setting up the bazel ci for testing 

.bazelci/presubmit.yml file 

rbe_ubuntu1604 config 

bazel-toolchains github repository to your workspace 

```
load("@bazel_toolchains//rules:rbe_repo.bzl", "rbe_autoconfig")
rbe_autoconfig(name = "buildkite_config")
```

- using a custom container in the rbe_unbuntu1604 ci config 

http://gcr.io/cloud-marketplace/google/rbe-ubuntu16-04

pull the container registry 

$ gcloud docker -- pull gcr.io/cloud-marketplace/google/rbe-ubuntu16-04@sha256:sha256-checksum

 
## RBE CI 
## Dynamic execution 
## Remoting caching 
## Docker sandbox 
## Non-hermetic WORKSPACE rules 
## Remote cache hits 
## Local cache hits 
## Output directory layout 
## Overview 
## Multiplex workers 
## Creating workers 
## Overview 
## BEP examples 
## BEP glossary 






# Tutorials 
## C++ use cases 
- include multiple files in a single target with glob.

cc_library(
    name = "build-all-the-files",
    srcs = glob(["*.cc"]),
    hdrs = glob(["*.h"]),
)

- using transitive includes, If a file includes a header, then any rule with that file as a source (that is, having that file in the srcs, hdrs, or textual_hdrs attribute) should depend on the included header's library rule.  

cc_library(
    name = "sandwich",
    srcs = ["sandwich.cc"],
    hdrs = ["sandwich.h"],
    deps = [":bread"],
)

cc_library(
    name = "bread",
    srcs = ["bread.cc"],
    hdrs = ["bread.h"],
    deps = [":flour"],
)

cc_library(
    name = "flour",
    srcs = ["flour.cc"],
    hdrs = ["flour.h"],
)

- adding include paths 

cc_library(
    name = "some_lib",
    srcs = ["some_lib.cc"],
    hdrs = ["include/some_lib.h"],
    copts = ["-Ilegacy/some_lib/include"],
)

...

- adding include path, 
cc_library(
    name = "some_lib",
    srcs = ["some_lib.cc"],
    hdrs = ["include/some_lib.h"],
    copts = ["-Ilegacy/some_lib/include"],
)


- include external libraries 

```
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "gtest",
    url = "https://github.com/google/googletest/archive/release-1.10.0.zip",
    sha256 = "94c634d499558a76fa649edb13721dce6e98fb1e7018dfaeba3cd7a083945e91",
    build_file = "@//:gtest.BUILD",
)
```

    + make http_archive strip this prefix by adding the strip_prefix attribute:


load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "gtest",
    url = "https://github.com/google/googletest/archive/release-1.10.0.zip",
    sha256 = "94c634d499558a76fa649edb13721dce6e98fb1e7018dfaeba3cd7a083945e91",
    build_file = "@//:gtest.BUILD",
    strip_prefix = "googletest-release-1.10.0",
)

    + gtest.BUILD would look like this:

```
cc_library(
    name = "main",
    srcs = glob(
        ["src/*.cc"],
        exclude = ["src/gtest-all.cc"]
    ),
    hdrs = glob([
        "include/**/*.h",
        "src/*.h"
    ]),
    copts = ["-Iexternal/gtest/include"],
    linkopts = ["-pthread"],
    visibility = ["//visibility:public"],
)
```

- running c++ tests 

./test/hello-test.cc,
```
#include "gtest/gtest.h"
#include "main/hello-greet.h"

TEST(HelloTest, GetGreet) {
  EXPECT_EQ(get_greet("Bazel"), "Hello Bazel");
}
```

```
cc_test(
    name = "hello-test",
    srcs = ["hello-test.cc"],
    copts = ["-Iexternal/gtest/include"],
    deps = [
        "@gtest//:main",
        "//main:hello-greet",
    ],
)
```

make hello-greet visible to hello-test, you must add "//test:__pkg__", to the visibility attribute in ./main/BUILD.

- Adding dependencies on precompiled libraries 

```
cc_library(
    name = "mylib",
    srcs = ["mylib.so"],
    hdrs = ["mylib.h"],
)
```




## Bazel Tutorial: Configuring C++ toolchains 
- set up build environment 

The tutorial uses clang version 9.0.1, which you can install on your system.

install bazel 

add BUILD file 
```
cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
)
```

create .bazelrc 
```
# Use our custom-configured c++ toolchain.

build:clang_config --crosstool_top=//toolchain:clang_suite

# Use --cpu as a differentiator.

build:clang_config --cpu=k8

# Use the default Bazel C++ toolchain to build the tools used during the
# build.

build:clang_config --host_crosstool_top=@bazel_tools//tools/cpp:toolchain
```

build your target with bazel build --config=clang_config //main:hello-world, Bazel uses your custom toolchain from the cc_toolchain_suite //toolchain:clang_suite. The suite may list different toolchains for different CPUs

crosstool_top, 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 --compiler

host_crosstool_top, Bazel uses the value of --crosstool_top to compile code in the host configuration, such as tools run during the build. The main purpose of this flag is to enable cross-compilation.

the pre-existing default C++ toolchain is specified for the host platform. 

- configuring the c++ toolchain 

In the workspace directory, create the toolchain directory for the package and add a BUILD file 
```
package(default_visibility = ["//visibility:public"])

filegroup(name = "clang_suite")

# point --crosstool_top to a rule that does provide ToolchainInfo - that is the cc_toolchain_suite rule.
cc_toolchain_suite(
    name = "clang_suite",
    toolchains = {
        "k8": ":k8_toolchain",
    },
)

# The toolchains attribute automatically maps the --cpu (and also --compiler when specified) values to cc_toolchain

# declaration of a cc_toolchain_config rule:


cc_toolchain_config(name = "k8_toolchain_config")

# define cc_toolchain targets for every value in the cc_toolchain_suite.

cc_toolchain(
    name = "k8_toolchain",
    toolchain_identifier = "k8-toolchain",
    toolchain_config = ":k8_toolchain_config",
    all_files = ":empty",
    compiler_files = ":empty",
    dwp_files = ":empty",
    linker_files = ":empty",
    objcopy_files = ":empty",
    strip_files = ":empty",
    supports_param_files = 0,
)
```

define cc_toolchain targets for every value in the cc_toolchain_suite.toolchains attribute.

making a toolchain/cc_toolchain_config.bzl file with the following content. To use the cc_toolchain_config rule, add a load statement to toolchains/BUILD:

```
load(":cc_toolchain_config.bzl", "cc_toolchain_config")

def _impl(ctx):
    return cc_common.create_cc_toolchain_config_info(
        ctx = ctx,
        toolchain_identifier = "k8-toolchain",
        host_system_name = "local",
        target_system_name = "local",
        target_cpu = "k8",
        target_libc = "unknown",
        compiler = "clang",
        abi_version = "unknown",
        abi_libc_version = "unknown",
    )

cc_toolchain_config = rule(
    implementation = _impl,
    attrs = {},
    provides = [CcToolchainConfigInfo],
)
```

Bazel what tools to use. For that, you need the tool_path() constructor from @bazel_tools//tools/cpp:cc_toolchain_config_lib.bzl:

```
# toolchain/cc_toolchain_config.bzl:
# NEW
load("@bazel_tools//tools/cpp:cc_toolchain_config_lib.bzl", "tool_path")

def _impl(ctx):
    tool_paths = [ # NEW
        tool_path(
            name = "gcc",
            path = "/usr/bin/clang",
        ),
        tool_path(
            name = "ld",
            path = "/usr/bin/ld",
        ),
        tool_path(
            name = "ar",
            path = "/usr/bin/ar",
        ),
        tool_path(
            name = "cpp",
            path = "/bin/false",
        ),
        tool_path(
            name = "gcov",
            path = "/bin/false",
        ),
        tool_path(
            name = "nm",
            path = "/bin/false",
        ),
        tool_path(
            name = "objdump",
            path = "/bin/false",
        ),
        tool_path(
            name = "strip",
            path = "/bin/false",
        ),
    ]
    return cc_common.create_cc_toolchain_config_info(
        ctx = ctx,
        toolchain_identifier = "local",
        host_system_name = "local",
        target_system_name = "local",
        target_cpu = "k8",
        target_libc = "unknown",
        compiler = "clang",
        abi_version = "unknown",
        abi_libc_version = "unknown",
        tool_paths = tool_paths, # NEW
    )
```

Make sure that /usr/bin/clang and /usr/bin/ld are the correct paths for your system.

- Bazel needs to know where to search for included headers. 

using the includes attribute of cc_binary, but here this is solved at the toolchain level with the cxx_builtin_include_directories parameter of cc_common.create_cc_toolchain_config_info

linker is missing the C++ standard library and it can't find its symbols. There are many ways to solve this, such as using the linkopts attribute of cc_binary. Here it is solved by making sure that any target using the toolchain

```
  # NEW
  load("@bazel_tools//tools/build_defs/cc:action_names.bzl", "ACTION_NAMES")
  # NEW
  load(
      "@bazel_tools//tools/cpp:cc_toolchain_config_lib.bzl",
      "feature",
      "flag_group",
      "flag_set",
      "tool_path",
  )

  all_link_actions = [ # NEW
      ACTION_NAMES.cpp_link_executable,
      ACTION_NAMES.cpp_link_dynamic_library,
      ACTION_NAMES.cpp_link_nodeps_dynamic_library,
  ]

  def _impl(ctx):
      tool_paths = [
          tool_path(
              name = "gcc",
              path = "/usr/bin/clang",
          ),
          tool_path(
              name = "ld",
              path = "/usr/bin/ld",
          ),
          tool_path(
              name = "ar",
              path = "/bin/false",
          ),
          tool_path(
              name = "cpp",
              path = "/bin/false",
          ),
          tool_path(
              name = "gcov",
              path = "/bin/false",
          ),
          tool_path(
              name = "nm",
              path = "/bin/false",
          ),
          tool_path(
              name = "objdump",
              path = "/bin/false",
          ),
          tool_path(
              name = "strip",
              path = "/bin/false",
          ),
      ]

      features = [ # NEW
          feature(
              name = "default_linker_flags",
              enabled = True,
              flag_sets = [
                  flag_set(
                      actions = all_link_actions,
                      flag_groups = ([
                          flag_group(
                              flags = [
                                  "-lstdc++",
                              ],
                          ),
                      ]),
                  ),
              ],
          ),
      ]

      return cc_common.create_cc_toolchain_config_info(
          ctx = ctx,
          features = features, # NEW
          cxx_builtin_include_directories = [
              "/usr/lib/llvm-9/lib/clang/9.0.1/include",
              "/usr/include",
          ],
          toolchain_identifier = "local",
          host_system_name = "local",
          target_system_name = "local",
          target_cpu = "k8",
          target_libc = "unknown",
          compiler = "clang",
          abi_version = "unknown",
          abi_libc_version = "unknown",
          tool_paths = tool_paths,
      )

  cc_toolchain_config = rule(
      implementation = _impl,
      attrs = {},
      provides = [CcToolchainConfigInfo],
  )
```

build the project with 
$ bazel build --config=clang_config //main:hello-world

- reviews 

You need to specify a --crosstool_top flag in the command line which should point to a cc_toolchain_suite - You can create a shortcut for a particular configuration using the .bazelrc file - The cc_toolchain_suite may list cc_toolchains for different CPUs and compilers. You can use command line flags like --cpu to differentiate

Your tools could come from a different workspace and you would have to make their files available to the cc_toolchain with target dependencies on attributes, such as compiler_files. The tool_paths would need to be changed as well.












## C++ dependency graphs 
- generate a text representation of the dependency graph by running this command at the workspace root

$ bazel query --notool_deps --noimplicit_deps "deps(//main:hello-world)" --output graph

with graphviz and run command 

$ xdot <(bazel query --notool_deps --noimplicit_deps "deps(//main:hello-world)" --output graph)





## C++ labels, use labels to reference targets 
- Bazel uses labels to reference targets - for example, //main:hello-world or //lib:hello-time

$ //path/to/package:target-name

    + the target is a rule target, then path/to/package is the path from the workspace root (the directory containing the WORKSPACE file) to the directory containing the BUILD file
                    
    target-name is what you named the target in the BUILD file (the name attribute)                
                    
    + target is a file target, then path/to/package is the path to the root of the package (the directory containing the package's BUILD file).
    
    target-name is the name of the target file including its full path relative to the root of the package 

    + targets at the repository root, the package path is empty, just use //:target-name. 
    
    When referencing targets within the same BUILD file, you can even skip the // workspace root identifier use :target-name.
                    
         
         
# Migrate 
## Overview 
## Maven 
## XCode 



# Extending bazel 
# Concepts 
## Overview 
- bazel extensions are files ending in .bzl file use a load statement to import a symbol from an extension 

- starlark language 

- share variables between two BUILD files by use the value COPTS

//variable.bzl 
```
COPTS = ["-DVERSION=5"]
```

```
load("//path/to:variables.bzl", "COPTS")
cc_library(
  name = "foo",
  copts = COPTS,
  srcs = ["foo.cc"],
)

cc_library(
  name = "bar",
  copts = COPTS,
  srcs = ["bar.cc"],
  deps = [":foo"],
)
```

- macros and rules 

A macro is a function that instantiates rules. It is useful when a BUILD file is getting too repetitive or too complex

A rule is more powerful than a macro. It can access Bazel internals

- evaluation model 

loading phase > analysis phase > execution phase 

evaluate the .bzl files and BUILD files. A file is read at most once per build and the result of the evaluation is cached and reused





## Rules 
- A rule defines a series of actions that Bazel performs on inputs to produce a set of outputsare referenced in providers returned by 

the rule's implementation function.

- rule creation In a .bzl file, use the rule function to define a new rule, and store the result in a global variable.

```
example_library = rule(
    implementation = _example_library_impl,
    attrs = {
        "deps": attr.label_list(),
        ...
    },
)
```

call to rule also must specify if the rule creates an executable output (with executable=True), or specifically a test executable (with test=True)

test rule mast end with _test 

- target instantiation 

    + rule can be loaded and called in BUILD files:


load('//some/pkg:rules.bzl', 'example_library')

example_library(
    name = "example_target",
    deps = [":another_target"],
    ...
)

- attributes, An attribute is a rule argument. Attributes can provide specific values to a target's implementation 
- dependency attributes, Rules that process source code usually define the following attributes to handle various types of dependencies

srcs, specify source files 
deps, specify code dpendencies for a target 
data, specify files to be made available at runtime 

```
example_library = rule(
    implementation = _example_library_impl,
    attrs = {
        "srcs": attr.label_list(allow_files = [".example"]),
        "hdrs": attr.label_list(allow_files = [".header"]),
        "deps": attr.label_list(providers = [ExampleInfo]),
        "data": attr.label_list(allow_files = True),
        ...
    },
)

example_library(
    name = "my_target",
    deps = [":other_target"],
)

example_library(
    name = "other_target",
    ...
)
```

- private attribute and implicit dependencies 

attribute private by giving it a name that begins with an underscore (_). Private attributes must have default values. private attribute is used for implicit dependencies 

```
example_library = rule(
    implementation = _example_library_impl,
    attrs = {
        ...
        "_compiler": attr.label(
            default = Label("//tools:example_compiler"),
            allow_single_file = True,
            executable = True,
            cfg = "exec",
        ),
    },
)
```

- Implicit dependencies are generally used for tools that reside in the same repository as the rule implementation. If the tool comes from the execution platform or a different repository instead, the rule should obtain that tool from a toolchain.

- output attributes 

Output attributes, such as attr.output and attr.output_list, declare an output file that the target generates

define output file targets

output file targets depend on the instantiated rule target

Output attributes are the preferred way of creating predeclared outputs

- implementation function 

Rule implementation functions are usually private (named with a leading underscore). take exactly one parameter: a rule context, conventionally named ctx. They return a list of providers.

- targets, analysis time as Target objects. These objects contain the providers generated when the target's implementation function was executed.

ctx.attr has fields corresponding to the names of each dependency attribute, containing Target

label_list attributes, this is a list of Targets. For label attributes, this is a single Target or None.

a target's implementation function: 
```
return [ExampleInfo(headers = depset(...))]
```

a collect headers from a rule 
```
def _example_library_impl(ctx):
    ...
    transitive_headers = [hdr[ExampleInfo].headers for hdr in ctx.attr.hdrs]
```    

get target's implementation function for the legacy style 
```
return struct(example_info = struct(headers = depset(...)))
```

- Files are represented by File objects. Since Bazel does not perform file I/O during the analysis phase, these objects cannot be used to directly read or write file content.

ctx.files contains a list of the default outputs 


```
def _example_library_impl(ctx):
    ...
    headers = depset(ctx.files.hdrs, transitive=transitive_headers)
    srcs = ctx.files.srcs
    ...
```

ctx.executable behaves the same as ctx.file, but only contains fields for dependency attributes whose specs set executable=True.

- declaring outputs, outputs can be created using using ctx.actions.declare_file and ctx.actions.declare_directory. outputs are based on the target's name, ctx.label.name:

```
def _example_library_impl(ctx):
  ...
  output_file = ctx.actions.declare_file(ctx.label.name + ".output")
  ...
```

- actions, generate a set of outputs from a set of inputs, for example "run gcc on hello.c and get hello.o". 
 
    + create actions are defined in ctx.actions:

    ctx.actions.run, to run an executable.
    ctx.actions.run_shell, to run a shell command.
    ctx.actions.write, to write a string to a file.
    ctx.actions.expand_template, to generate a file from a template.
    ctx.actions.args can be used to efficiently accumulate the arguments for actions

    ```
    def _example_library_impl(ctx):
        ...

        transitive_headers = [dep[ExampleInfo].headers for dep in ctx.attr.deps]
        headers = depset(ctx.files.hdrs, transitive=transitive_headers)
        srcs = ctx.files.srcs
        inputs = depset(srcs, transitive=[headers])
        output_file = ctx.actions.declare_file(ctx.label.name + ".output")

        args = ctx.actions.args()
        args.add_joined("-h", headers, join_with=",")
        args.add_joined("-s", srcs, join_with=",")
        args.add("-o", output_file)

        ctx.actions.run(
            mnemonic = "ExampleCompile",
            executable = ctx.executable._compiler,
            arguments = [args],
            inputs = inputs,
            outputs = [output_file],
        )
        ...
    ```

- if your action runs the unzip command, you must specify which files you expect to be inflated (before running unzip). Actions which create a variable number of files internally can wrap those in a single file

Actions must list all of their inputs.     
    
Actions must create all of their outputs. output will be cached and reused    
    
Actions are comparable to pure functions: They should depend only on the provided inputs, and avoid accessing computer information, username, clock, network, or I/O devices

- Providers are pieces of information that a rule exposes to other rules that depend on it.

can include output files, libraries, parameters to pass on a tool's command line, or anything else accumulating into a depset 

a rule's implementation function can only read providers from the instantiated target's immediate dependencies, rules need to forward any information from a target's dependencies that needs to be known by a target's consumers

- default outputs, A target's default outputs are the outputs that are requested by default when the target is requested for build at the command line. 

Default outputs are specified by the files parameter of DefaultInfo

```
def _example_library_impl(ctx):
    ...
    return [
        DefaultInfo(files = depset([output_file]), ...),
        ...
    ]
```

DefaultInfo.files defaults to all predeclared outputs https://bazel.build/extending/rules#output_attributes

- Runfiles are a set of files used by a target at runtime (as opposed to build time). During the execution phase, Bazel creates a directory tree containing symlinks pointing to the runfiles

ctx.runfiles output of executable rules is implicitly added to the runfiles.

```
def _example_library_impl(ctx):
    ...
    runfiles = ctx.runfiles(files = ctx.files.data)
    transitive_runfiles = []
    for runfiles_attr in (
        ctx.attr.srcs,
        ctx.attr.hdrs,
        ctx.attr.deps,
        ctx.attr.data,
    ):
        for target in runfiles_attr:
            transitive_runfiles.append(target[DefaultInfo].default_runfiles)
    runfiles = runfiles.merge_all(transitive_runfiles)
    return [
        DefaultInfo(..., runfiles = runfiles),
        ...
    ]
```

- Custom providers with provider function 


```
ExampleInfo = provider(
    "Info needed to compile/link Example code.",
    fields={
        "headers": "depset of header Files from transitive dependencies.",
        "files_to_link": "depset of Files from compilation.",
    })
    
    
# rule impl then can return provider instance 
def _example_library_impl(ctx):
  ...
  return [
      ...
      ExampleInfo(
          headers = headers,
          files_to_link = depset(
              [output_file],
              transitive = [
                  dep[ExampleInfo].files_to_link for dep in ctx.attr.deps
              ],
          ),
      )
  ]
```

    + custom initialization 
provider symbol is called, instead of directly returning a new instance, it will forward the arguments along to the init callback.

raw constructor, by contrast, will bypass the init callback.

```
# //pkg:exampleinfo.bzl

_core_headers = [...]  # private constant representing standard library files

# It's possible to define an init accepting positional arguments, but
# keyword-only arguments are preferred.
def _exampleinfo_init(*, files_to_link, headers = None, allow_empty_files_to_link = False):
    if not files_to_link and not allow_empty_files_to_link:
        fail("files_to_link may not be empty")
    all_headers = depset(_core_headers, transitive = headers)
    return {'files_to_link': files_to_link, 'headers': all_headers}

ExampleInfo, _new_exampleinfo = provider(
    ...
    init = _exampleinfo_init)

export ExampleInfo


# use the provider 
ExampleInfo(
    files_to_link=my_files_to_link,  # may not be empty
    headers = my_headers,  # will automatically include the core headers
)

# the raw constructor can be used to define alternative public factory. 
# raw constructor is bound to a variable whose name begins with an underscore (_new_exampleinfo above), so that user code cannot load it 
def make_barebones_exampleinfo(headers):
    """Returns an ExampleInfo with no files_to_link and only the specified headers."""
    return _new_exampleinfo(files_to_link = depset(), headers = all_headers)
```

    + force the user to use the factory method 
    
```
 force them to use a factory function instead:


def _exampleinfo_init_banned(*args, **kwargs):
    fail("Do not call ExampleInfo(). Use make_exampleinfo() instead.")

ExampleInfo, _new_exampleinfo = provider(
    ...
    init = _exampleinfo_init_banned)

def make_exampleinfo(...):
    ...
    return _new_exampleinfo(...)
```

- executable rules and test rules 

Executable and test rules are created by setting the respective executable or test argument to True

```
example_binary = rule(
   implementation = _example_binary_impl,
   executable = True,
   ...
)

# Test rules must have names that end in _test.
example_test = rule(
   implementation = _example_binary_impl,
   test = True,
   ...
)
```

That executable is added to the default outputs of the rule and implicitly added to the runfiles:

```
def _example_binary_impl(ctx):
    executable = ctx.actions.declare_file(ctx.label.name)
    ...
    return [
        DefaultInfo(executable = executable, ...),
        ...
    ]
```

Since _compiler is a private attribute, it follows that ctx.attr._compiler will always point to //tools:example_compiler
```
example_library = rule(
    implementation = _example_library_impl,
    attrs = {
        ...
        "_compiler": attr.label(
            default = Label("//tools:example_compiler"),
            allow_single_file = True,
            executable = True,
            cfg = "exec",
        ),
    },
)
```

- Executable rules and test rules have additional attributes implicitly defined, in addition to those added for all rules.

- runfiles location,  target is run with bazel run (or test), the root of the runfiles directory is adjacent to the executable. runfiles directory corresponds to File.short_path.

runfiles_root = launcher_path.path + ".runfiles"
workspace_name = ctx.workspace_name
runfile_path = runfile_file.short_path
execution_root_relative_path = "%s/%s/%s" % (runfiles_root, workspace_name, runfile_path)

- advanced topics 

    + requesting output files,  output groups, which are collections of output files that may be requested together. These can be requested with --output_groups. for example a rule has a debug_files output_group 
    
$ bazel build //pkg:mytarget --output_groups=debug_files    

Output groups can be specified with the OutputGroupInfo provider

```
def _example_library_impl(ctx):
    ...
    debug_file = ctx.actions.declare_file(name + ".pdb")
    ...
    return [
        DefaultInfo(files = depset([output_file]), ...),
        OutputGroupInfo(
            debug_files = depset([debug_file]),
            all_files = depset([output_file, debug_file]),
        ),
        ...
    ]
```

OutputGroupInfo can be returned by both an aspect and the rule target to which that aspect is applied

- configurations, build a C++ binary for a different architecture.  

a dependency is a tool that's needed to help build the target, the corresponding attribute should specify a transition to an exec configuration.

a dependency attribute has the flag executable=True, cfg must be set explicitly. 

use cfg=my_transition to use user-defined transitions, which allow rule authors a great deal of flexibility in changing configurations

    + "host" is terminal, "exec" isn't: Once a dependency is in the "host" configuration, no more transitions are allowed. 

    + "host" is monolithic, "exec" isn't: There is only one "host" configuration, but there can be a different "exec"

    + "host" assumes you run tools on the same machine as Bazel

Both the "exec" and "host" configurations apply the same option changes, (for example, set --compilation_mode from --host_compilation_mode, set --cpu from --host_cpu, etc).

- configuration fragments, rules may access 

```
def _impl(ctx):
    # Using ctx.fragments.cpp leads to an error since it was not declared.
    x = ctx.fragments.java
    ...

my_rule = rule(
    implementation = _impl,
    fragments = ["java"],      # Required fragments of the target configuration
    host_fragments = ["java"], # Required fragments of the host configuration
    ...
)
``` 

ctx.fragments only provides configuration fragments for the target configuration

- runfiles symlinks, root_symlinks or symlinks arguments. The root_symlinks is a dictionary mapping paths to files

```
    ...
    runfiles = ctx.runfiles(
        root_symlinks = {"some/path/here.foo": ctx.file.some_data_file2}
        symlinks = {"some/path/here.bar": ctx.file.some_data_file3}
    )
    # Creates something like:
    # sometarget.runfiles/
    #     some/
    #         path/
    #             here.foo -> some_data_file2
    #     <workspace_name>/
    #         some/
    #             path/
    #                 here.bar -> some_data_file3
```

- code coverage, When the coverage command is run, the build may need to add coverage instrumentation for certain targets
- turn on compile-time instrumentation if the dependencies' sources should be instrumented

InstrumentedFilesInfo is not returned, a default one is created with each non-tool dependency attribute that doesn't set cfg to "host" or "exec"

```
# Are this rule's sources or any of the sources for its direct dependencies
# in deps instrumented?
if (ctx.configuration.coverage_enabled and
    (ctx.coverage_instrumented() or
     any([ctx.coverage_instrumented(dep) for dep in ctx.attr.deps]))):
    # Do something to turn on coverage for this compile action
    
def _example_library_impl(ctx):
    ...
    return [
        ...
        coverage_common.instrumented_files_info(
            ctx,
            dependency_attributes = ["deps", "data"],
            # Omitted if coverage is not supported for this rule:
            source_attributes = ["srcs", "hdrs"],
        )
        ...
    ]
```

- Validation actions can also help to improve build performance by moving parts of actions that are not required for building artifacts into separate actions

- Validations Output Group is an output group designed to hold the otherwise unused outputs of validation actions, so that they don't need to be artificially added to the inputs of other actions.

    + validation actions are not run in three cases:

When the target is depended upon as a tool
When the target is depended upon as an implicit dependency (for example, an attribute that starts with "_")
When the target is built in the host or exec configuration.

```
def _rule_with_validation_impl(ctx):

  ctx.actions.write(ctx.outputs.main, "main output\n")

  ctx.actions.write(ctx.outputs.implicit, "implicit output\n")

  validation_output = ctx.actions.declare_file(ctx.attr.name + ".validation")
  ctx.actions.run(
      outputs = [validation_output],
      executable = ctx.executable._validation_tool,
      arguments = [validation_output.path])

  return [
    DefaultInfo(files = depset([ctx.outputs.main])),
    OutputGroupInfo(_validation = depset([validation_output])),
  ]


rule_with_validation = rule(
  implementation = _rule_with_validation_impl,
  outputs = {
    "main": "%{name}.main",
    "implicit": "%{name}.implicit",
  },
  attrs = {
    "_validation_tool": attr.label(
        default = Label("//validation_actions:validation_tool"),
        executable = True,
        cfg = "exec"),
  }
)
```




## Macros 
- A macro is a function called from the BUILD file that can instantiate rules. Macros are mainly used for encapsulation and code reuse 

By the end of the loading phase, macros don't exist anymore

- usage

    + genrule in a BUILD file generates a file using //:generator with a some_arg argument hardcoded in the command:
```
def file_generator(name, arg, visibility=None):
    native.genrule(
        name = name,
        outs = [name + ".txt"],
        cmd = "$(location //:generator) %s > $@" % arg,
        tools = ["//:generator"],
        visibility = visibility,
    )
```
  
    + use macros to chain rules together 
```    
def chained_genrules(name, visibility=None):
        native.genrule(
        name = name + "-one",
        outs = [name + ".one"],
        cmd = "$(location :tool-one) $@",
        tools = [":tool-one"],
        visibility = ["//visibility:private"],
    )

    native.genrule(
        name = name + "-two",
        srcs = [name + ".one"],
        outs = [name + ".two"],
        cmd = "$(location :tool-two) $< $@",
        tools = [":tool-two"],
        visibility = visibility,
    )
```

- expanding macros, use the query command with --output=build to see the expanded form:

```
$ bazel query --output=build :file
# /absolute/path/test/ext.bzl:42:3
genrule(
    name = "file",
    tools = ["//:generator"],
    outs = ["//test:file.txt"],
    cmd = "$(location //:generator) some_arg > $@",
)
```

- instantiating native rules, Native rules (rules that don't need a load() statement) can be instantiated from the native module

```
def my_macro(name, visibility=None):
  native.cc_library(
    name = name,
    srcs = ["main.cc"],
    visibility = visibility,
  )
```

native can only be used in .bzl files, and not in WORKSPACE or BUILD files.

- label resolution in macros 

macros are evaluated in the loading phase, label strings such as "//foo:bar" that occur in a macro are interpreted relative to the BUILD

```
# @my_ruleset//rules:defs.bzl
def my_cc_wrapper(name, deps = [], **kwargs):
  native.cc_library(
    name = name,
    deps = deps + select({
      # Due to the use of Label, this label is resolved within @my_ruleset,
      # regardless of its site of use.
      Label("//config:needs_foo"): [
        # Due to the use of Label, this label will resolve to the correct target
        # even if the canonical name of @dep_of_my_ruleset should be different
        # in the main workspace, such as due to repo mappings.
        Label("@dep_of_my_ruleset//tools:foo"),
      ],
      "//conditions:default": [],
    }),
    **kwargs,
  )
```

- Debugging

$ bazel query --output=build //my/path:all will show you how the BUILD file looks after evaluation. 

    + You may filter the output based on generator_function
    
$ bazel query --output=build 'attr(generator_function, my_macro, //my/path:all)'

    + To find out where exactly the rule foo is generated in a BUILD file
    
    Insert this line near the top of the BUILD file: cc_library(name = "foo"). Run Bazel. You will get an exception when the rule foo is created
    
    due to a name conflict show you the full stack trace.                       
    
    + You can also use print for debugging. It displays the message as a DEBUG log line

- errors,  throw an error, use the fail function. Explain clearly to the user what went wrong and how to fix their BUILD file. 

```
def my_macro(name, deps, visibility=None):
  if len(deps) < 2:
    fail("Expected at least two values in deps")
  # ...
```   




## Depsets 
- Depsets are a specialized data structure for efficiently collecting data across a target’s transitive dependencie

    + a directed acyclic graph (DAG) that typically looks similar to the target graph.

```
s = depset(["a", "b", "c"])
t = depset(["d", "e"], transitive = [s])

print(s)    # depset(["a", "b", "c"])
print(t)    # depset(["d", "e", "a", "b", "c"])
```

- compare 
```
s = depset(["a", "b", "c"])
t = depset(["c", "b", "a"])
print(sorted(s.to_list()) == sorted(t.to_list()))  # True
```

- depsets should be used whenever you are accumulating information through your transitive dependencies. This helps ensure that your build scales well as your target graph grows deeper

```
FooFiles = provider(fields = ["transitive_sources"])

def get_transitive_srcs(srcs, deps):
  """Obtain the source files for a target and its transitive dependencies.

  Args:
    srcs: a list of source files
    deps: a list of targets that are direct dependencies
  Returns:
    a collection of the transitive sources
  """
  return depset(
        srcs,
        transitive = [dep[FooFiles].transitive_sources for dep in deps])

```




## Aspects 
- Aspects allow augmenting build dependency graphs with additional information and actions.

IDEs that integrate Bazel can use aspects to collect information about the project.

Code generation tools can leverage aspects to execute on their inputs in target-agnostic manner.

```
def _print_aspect_impl(target, ctx):
    # Make sure the rule has a srcs attribute.
    if hasattr(ctx.rule.attr, 'srcs'):
        # Iterate through the files that make up the sources and
        # print their paths.
        for src in ctx.rule.attr.srcs:
            for f in src.files.to_list():
                print(f.path)
    return []

print_aspect = aspect(
    implementation = _print_aspect_impl,
    attr_aspects = ['deps'],
)
```

- Aspects are similar to rules in that they have an implementation function that generates actions and returns providers. However, their power comes from the way the dependency graph is built for them

- common argument for attr_aspects is ['*'] which would propagate the aspect to all attributes of a rule.

- Invoking the aspect using the command line

The simplest way to apply an aspect is from the command line using the --aspects argument

$ bazel build //MyExample:example --aspects print.bzl%print_aspect

The --aspects flag takes one argument, which is a specification of the aspect in the format <extension file label>%<aspect top-level name>.

- advanced example

```
# invoke an aspect from a rule.

# file_count.bzl file:


FileCountInfo = provider(
    fields = {
        'count' : 'number of files'
    }
)

def _file_count_aspect_impl(target, ctx):
    count = 0
    # Make sure the rule has a srcs attribute.
    if hasattr(ctx.rule.attr, 'srcs'):
        # Iterate through the sources counting files
        for src in ctx.rule.attr.srcs:
            for f in src.files.to_list():
                if ctx.attr.extension == '*' or ctx.attr.extension == f.extension:
                    count = count + 1
    # Get the counts from our dependencies.
    for dep in ctx.rule.attr.deps:
        count = count + dep[FileCountInfo].count
    return [FileCountInfo(count = count)]

file_count_aspect = aspect(
    implementation = _file_count_aspect_impl,
    attr_aspects = ['deps'],
    attrs = {
        'extension' : attr.string(values = ['*', 'h', 'cc']),
    }
)

def _file_count_rule_impl(ctx):
    for dep in ctx.attr.deps:
        print(dep[FileCountInfo].count)

file_count_rule = rule(
    implementation = _file_count_rule_impl,
    attrs = {
        'deps' : attr.label_list(aspects = [file_count_aspect]),
        'extension' : attr.string(default = '*'),
    },
)


# BUILD.bazel file:


load('//:file_count.bzl', 'file_count_rule')

cc_library(
    name = 'lib',
    srcs = [
        'lib.h',
        'lib.cc',
    ],
)

cc_binary(
    name = 'app',
    srcs = [
        'app.h',
        'app.cc',
        'main.cc',
    ],
    deps = ['lib'],
)

file_count_rule(
    name = 'file_count',
    deps = ['app'],
    extension = 'h',
)
```

Aspects with parameters cannot be used via the command line because there is no syntax to define the parameters.

When the file_count target is built, our aspect will be evaluated for itself, and all of the targets accessible recursively via deps.




## Repository rules 
- In a .bzl file, use the repository_rule function to create a new repository rule and store it in a global variable.

- A custom repository rule can be used just like a native repository rule. It has a mandatory name attribute

be referred as @<name>//package:target where <name> is the value of the name attribute.

- An attribute is a rule argument

```
local_repository = repository_rule(
    implementation=_impl,
    local=True,
    attrs={"path": attr.string(mandatory=True)})
```

- implementation function 

Every repository rule requires an implementation function. It contains the actual logic of the rule and is executed strictly in the Loading Phase

```
def _impl(repository_ctx):
  repository_ctx.symlink(repository_ctx.attr.path, "")

local_repository = repository_rule(
    implementation=_impl,
    ...)
```

- change in a dependency in the dependency graph (including the WORKSPACE file itself) will cause an execution of the implementation function.

.bzl files needed to define the repository rule.

Declaration of the repository rule in the WORKSPACE file.

Content of any file used and referred to by a label (for example, //mypkg:label.txt not mypkg/label.txt).

- forcing refectch of external repositories 

$ bazel sync 




## Configurations 
- Bazel's API for customizing how your project builds. define build settings 

define custom flags for your project, obsoleting the need for --define

write transitions to configure deps in different configurations than their parents (such as --compilation_mode=opt or --cpu=arm)

bake better defaults into rules (such as automatically build //my:android_app with a specified SDK)

- user defined build settings 

A build setting is a single piece of configuration information. looks like  {cpu: ppc, copt: "-DFoo"}. Each entry is a build setting.

- The build_setting rule() parameter

Build settings are rules like any other rule and are differentiated using the Starlark rule() function's build_setting attribute.

-  build setting rules have implementation functions. The basic Starlark-type value of the build settings can be accessed via the ctx.build_setting_value method. 
 
```
# example/buildsettings/build_settings.bzl
TemperatureProvider = provider(fields = ['type'])

temperatures = ["HOT", "LUKEWARM", "ICED"]

def _impl(ctx):
    raw_temperature = ctx.build_setting_value
    if raw_temperature not in temperatures:
        fail(str(ctx.label) + " build setting allowed to take values {"
             + ", ".join(temperatures) + "} but was set to unallowed value "
             + raw_temperature)
    return TemperatureProvider(type = raw_temperature)

temperature = rule(
    implementation = _impl,
    build_setting = config.string(flag = True)
)
```

- defining multi-set string flags 

String settings have an additional allow_multiple parameter which allows the flag to be set multiple times

```
# example/buildsettings/build_settings.bzl
allow_multiple_flag = rule(
    implementation = _impl,
    build_setting = config.string(flag = True, allow_multiple = True)
)

# example/buildsettings/BUILD
load("//example/buildsettings:build_settings.bzl", "allow_multiple_flag")
allow_multiple_flag(
    name = "roasts",
    build_setting_default = "medium"
)
```

$ bazel build //my/target --//example:roasts=blonde --//example:roasts=medium,dark

- instantiating build settings 

Rules defined with the build_setting parameter have an implicit mandatory build_setting_default attribute

```
# example/buildsettings/build_settings.bzl
FlavorProvider = provider(fields = ['type'])

def _impl(ctx):
    return FlavorProvider(type = ctx.build_setting_value)

flavor = rule(
    implementation = _impl,
    build_setting = config.string(flag = True)
)


# example/buildsettings/BUILD
load("//example/buildsettings:build_settings.bzl", "flavor")
flavor(
    name = "favorite_flavor",
    build_setting_default = "APPLE"
)
```

- predefined settings 

```
# example/BUILD
load("@bazel_skylib//rules:common_settings.bzl", "string_flag")
string_flag(
    name = "myflag",
    values = ["a", "b", "c"],
    build_setting_default = "a",
)
```       

- target read configuration with build settings 

```
# example/rules.bzl
load("//example/buildsettings:build_settings.bzl", "FlavorProvider")
def _rule_impl(ctx):
    if ctx.attr.flavor[FlavorProvider].type == "ORANGE":
        ...

drink_rule = rule(
    implementation = _rule_impl,
    attrs = {
        "flavor": attr.label()
    }
)

# example/BUILD
load("//example:rules.bzl", "drink_rule")
load("//example/buildsettings:build_settings.bzl", "flavor")
flavor(
    name = "favorite_flavor",
    build_setting_default = "APPLE"
)
drink_rule(
    name = "my_drink",
    flavor = ":favorite_flavor",
)

```

- use sets of common implicit attributes. For example:

```
# kotlin/rules.bzl
_KOTLIN_CONFIG = {
    "_compiler": attr.label(default = "//kotlin/config:compiler-flag"),
    "_mode": attr.label(default = "//kotlin/config:mode-flag"),
    ...
}

...

kotlin_library = rule(
    implementation = _rule_impl,
    attrs = dicts.add({
        "library-attr": attr.string()
    }, _KOTLIN_CONFIG)
)

kotlin_binary = rule(
    implementation = _binary_impl,
    attrs = dicts.add({
        "binary-attr": attr.label()
    }, _KOTLIN_CONFIG)
```

- build setting's name is its full target path using name=value syntax:

$ bazel build //my/target --//example:string_flag=some-value # allowed
$ bazel build //my/target --//example:string_flag some-value # not allowed

- boolean syntax is supported:

$ bazel build //my/target --//example:boolean_flag
$ bazel build //my/target --no//example:boolean_flag

- using build setting alias, multiple times results in the most recent one taking precedence.  

Set an alias by adding --flag_alias=ALIAS_NAME=TARGET_PATH to your .bazelrc .

```
# .bazelrc
build --flag_alias=coffee=//experimental/user/starlark_configurations/basic_build_setting:coffee-temp
```

- label typed build settings. bazel has two built-in rules: label_flag and label_setting. These rules forward the providers of the actual target to which the build setting is set. they can't customely defined.
  

```
# example/rules.bzl
MyProvider = provider(fields = ["my_field"])

def _dep_impl(ctx):
    return MyProvider(my_field = "yeehaw")

dep_rule = rule(
    implementation = _dep_impl
)

def _parent_impl(ctx):
    if ctx.attr.my_field_provider[MyProvider].my_field == "cowabunga":
        ...

parent_rule = rule(
    implementation = _parent_impl,
    attrs = { "my_field_provider": attr.label() }
)

# example/BUILD
load("//example:rules.bzl", "dep_rule", "parent_rule")

dep_rule(name = "dep")

parent_rule(name = "parent", my_field_provider = ":my_field_provider")

label_flag(
    name = "my_field_provider",
    build_setting_default = ":dep"
)
```

- Users can configure attributes on build settings by using select(). Build setting targets can be passed to the flag_values attribute of config_setting.

- user defined transitions 

A configuration transition maps the transformation from one configured target to another within the build graph.

```
"_allowlist_function_transition": attr.label(
      default = "@bazel_tools//tools/allowlists/function_transition_allowlist"
  )
```

- defining, Transitions define configuration changes between rules. For example, a request like "compile my dependency for a different CPU than its parent" is handled by a transition.

a transition is a function from an input configuration to one or more output configurations.

```
# a defining transition() function and an implementation function.
# example/transitions/transitions.bzl
def _impl(settings, attr):
    _ignore = (settings, attr)
    return {"//example:favorite_flavor" : "MINT"}

hot_chocolate_transition = transition(
    implementation = _impl,
    inputs = [],
    outputs = ["//example:favorite_flavor"]
)

```
settings and attr. settings is a dictionary {String:Object} of all settings declared in the inputs parameter to transition().
attr is a dictionary of attributes and values of the rule to which the transition is attached.

- Outgoing edge transition can map a single input configuration to two or more output configurations. 

```
# returning a list of dictionaries in the transition implementation function.

# example/transitions/transitions.bzl
def _impl(settings, attr):
    _ignore = (settings, attr)
    return [
        {"//example:favorite_flavor" : "LATTE"},
        {"//example:favorite_flavor" : "MOCHA"},
    ]

coffee_transition = transition(
    implementation = _impl,
    inputs = [],
    outputs = ["//example:favorite_flavor"]
)

# set custom keys that the rule implementation function can use to read individual dependencies:
# example/transitions/transitions.bzl
def _impl(settings, attr):
    _ignore = (settings, attr)
    return {
        "Apple deps": {"//command_line_option:cpu": "ppc"},
        "Linux deps": {"//command_line_option:cpu": "x86"},
    }

multi_arch_transition = transition(
    implementation = _impl,
    inputs = [],
    outputs = ["//command_line_option:cpu"]
)
```

- attaching transitions, Transitions can be attached in two places: incoming edges and outgoing edges. Effectively this means rules can transition their own configuration

    + Incoming edge transitions are activated by attaching a transition object (created by transition()) to rule()'s cfg parameter:
    
```
# example/rules.bzl
load("example/transitions:transitions.bzl", "hot_chocolate_transition")
drink_rule = rule(
    implementation = _impl,
    cfg = hot_chocolate_transition,
    ...
```
    
    + no way to attach to native rules 
    
    + Outgoing edge transitions are activated by attaching a transition object (created by transition()) to an attribute's cfg parameter:
    
```
# example/rules.bzl
load("example/transitions:transitions.bzl", "coffee_transition")
drink_rule = rule(
    implementation = _impl,
    attrs = { "dep": attr.label(cfg = coffee_transition)}
    ...
```

- Bazel doesn't support transitioning on --define with "//command_line_option:define". Instead, use a custom build setting

- transitions on allow multiple build settings 

```
# example/buildsettings/build_settings.bzl
string_flag = rule(
    implementation = _impl,
    build_setting = config.string(flag = True, allow_multiple = True)
)

# example/BUILD
load("//example/buildsettings:build_settings.bzl", "string_flag")
string_flag(name = "roasts", build_setting_default = "medium")

# example/transitions/rules.bzl
def _transition_impl(settings, attr):
    # Using a value of just "dark" here will throw an error
    return {"//example:roasts" : ["dark"]},

coffee_transition = transition(
    implementation = _transition_impl,
    inputs = [],
    outputs = ["//example:roasts"]
)
```

- no-op transitions If a transition returns {}, [], or None, this is shorthand for keeping all settings at their original values.

```
# example/transitions/transitions.bzl
def _impl(settings, attr):
    _ignore = (attr)
    if settings["//example:already_chosen"] is True:
      return {}
    return {
      "//example:favorite_flavor": "dark chocolate",
      "//example:include_marshmallows": "yes",
      "//example:desired_temperature": "38C",
    }

hot_chocolate_transition = transition(
    implementation = _impl,
    inputs = ["//example:already_chosen"],
    outputs = [
        "//example:favorite_flavor",
        "//example:include_marshmallows",
        "//example:desired_temperature",
    ]
)
```

- accessing attributes with transitions 

When attaching a transition to an outgoing edge (regardless of whether the transition is a 1:1 or 1:2+ transition), ctx.attr is forced to be a list if it isn't already. 

```
# example/transitions/rules.bzl
def _transition_impl(settings, attr):
    return {"//example:favorite_flavor" : "LATTE"},

coffee_transition = transition(
    implementation = _transition_impl,
    inputs = [],
    outputs = ["//example:favorite_flavor"]
)

def _rule_impl(ctx):
    # Note: List access even though "dep" is not declared as list
    transitioned_dep = ctx.attr.dep[0]

    # Note: Access doesn't change, other_deps was already a list
    for other dep in ctx.attr.other_deps:
      # ...


coffee_rule = rule(
    implementation = _rule_impl,
    attrs = {
        "dep": attr.label(cfg = coffee_transition)
        "other_deps": attr.label_list(cfg = coffee_transition)
    })
    
# ctx.split_attr can be used to read individual deps for each key:


# example/transitions/rules.bzl
def _impl(settings, attr):
    _ignore = (settings, attr)
    return {
        "Apple deps": {"//command_line_option:cpu": "ppc"},
        "Linux deps": {"//command_line_option:cpu": "x86"},
    }

multi_arch_transition = transition(
    implementation = _impl,
    inputs = [],
    outputs = ["//command_line_option:cpu"]
)

def _rule_impl(ctx):
    apple_dep = ctx.split_attr.dep["Apple deps"]
    linux_dep = ctx.split_attr.dep["Linux deps"]
    # ctx.attr has a list of all deps for all keys. Order is not guaranteed.
    all_deps = ctx.attr.dep

multi_arch_rule = rule(
    implementation = _rule_impl,
    attrs = {
        "dep": attr.label(cfg = multi_arch_transition)
    })
```





# Writing rules 
## Creating a rule 
## Creating a macro 
## Creating custom verbs 
## Starlark language 
## Starlark style guide 
## Challenges 
## Writing rules for Windwos 
## Example rules 

# Distributing rules 
## Testing rules 
## Lint 
## Optimizing performance 
## Deploy rules 
## Document rules with Stardoc 




# Design docs 
## Platforms 
- Modeling the environment as a platform helps Bazel to automatically select the appropriate toolchains for build actions. 

- Be used combination with config_setting rule to write configurable attributes 

- Bazel recognizes three roles that a platform may serve 

host, the platform on which bazel run 
execution, a platform on which build tools execute build actions 
target, a platform on which a final output resides and executes 

- support build scenarios regardiong platforms 

single-platform builds (default) 

cross-compliation builds, host and execution platforms are the same but the target platform is different 

multi-platform builds, host execution and target platforms are all different 

platforms is defined by using the constraint_setting and constraint_value rules within BUILD files

```
constraint_setting(name = "glibc_version")

constraint_value(
    name = "glibc_2_25",
    constraint_setting = ":glibc_version",
)

constraint_value(
    name = "glibc_2_26",
    constraint_setting = ":glibc_version",
)
```

They maybe defined across different packages in the workspace 

The platform rule introduces a new platform with certain choices of constraint values. 

The constraint_value is unique for each platform

```
platform(
    name = "linux_x86",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:x86_64",
        ":glibc_2_25",
    ],
)
```
Bazel auto detect host platform : @local_config_platform//:host. 

- specify a platform for a build 

```
--host_platform - defaults to @bazel_tools//platforms:host_platform
--platforms - defaults to @bazel_tools//platforms:target_platform
```

- skipping incompatible tagets 

target_compatible_with attribute to tell Bazel what target platform constraints your code has.

:win_driver_lib is only compatible for building with 64-bit Windows
```
cc_library(
    name = "win_driver_lib",
    srcs = ["win_driver_lib.cc"],
    target_compatible_with = [
        "@platforms//cpu:x86_64",
        "@platforms//os:windows",
    ],
)
```

- more expressive constraints

Use select() in combination with @platforms//:incompatible to express more complicated restrictions. 

```
cc_library(
    name = "unixish_lib",
    srcs = ["unixish_lib.cc"],
    target_compatible_with = select({
        "@platforms//os:osx": [],
        "@platforms//os:linux": [],
        "//conditions:default": ["@platforms//:incompatible"],
    }),
)

# describes a library that is compatible with everything except for ARM.
cc_library(
    name = "non_arm_lib",
    srcs = ["non_arm_lib.cc"],
    target_compatible_with = select({
        "@platforms//cpu:arm": ["@platforms//:incompatible"],
        "//conditions:default": [],
    ],
)
```

- detecting incompatible targets using bazel cquery. use the IncompatiblePlatformProvider in bazel cquery's Starlark output format








## Execution groups 



## Toolchains 
https://bazel.build/extending/toolchains
- Bazel selects an appropriate toolchain based on platform constraints.

- motivation 
```
bar_binary = rule(
    implementation = _bar_binary_impl,
    attrs = {
        "srcs": attr.label_list(allow_files = True),
        ...
        "_compiler": attr.label(
            default = "//bar_tools:barc_linux",  # the compiler running on linux
            providers = [BarcInfo],
        ),
    },
)

BarcInfo = provider(
    doc = "Information about how to invoke the barc compiler.",
    # In the real world, compiler_path and system_lib might hold File objects,
    # but for simplicity they are strings for this example. arch_flags is a list
    # of strings.
    fields = ["compiler_path", "system_lib", "arch_flags"],
)

# compiler's label is hardcoded into bar_binary, yet different targets may need different compilers depending on what platform
def _bar_binary_impl(ctx):
    ...
    info = ctx.attr._compiler[BarcInfo]
    command = "%s -l %s %s" % (
        info.compiler_path,
        info.system_lib,
        " ".join(info.arch_flags),
    )
    ...
```

    + one option to improve to shift the compile info to user 
    
```
bar_binary(
    name = "myprog_on_linux",
    srcs = ["mysrc.bar"],
    compiler = "//bar_tools:barc_linux",
)

bar_binary(
    name = "myprog_on_windows",
    srcs = ["mysrc.bar"],
    compiler = "//bar_tools:barc_windows",
)
```

    + improve, select to choose the compiler based on the platform:
    
```
config_setting(
    name = "on_linux",
    constraint_values = [
        "@platforms//os:linux",
    ],
)

config_setting(
    name = "on_windows",
    constraint_values = [
        "@platforms//os:windows",
    ],
)

bar_binary(
    name = "myprog",
    srcs = ["mysrc.bar"],
    compiler = select({
        ":on_linux": "//bar_tools:barc_linux",
        ":on_windows": "//bar_tools:barc_windows",
    }),
)
```

    + The toolchain framework solves this problem by adding an extra level of indirection. you declare that your rule has an abstract dependency on some member of a family of targets (a toolchain type), and Bazel automatically resolves this to a particular target (a toolchain) based on the applicable platform constraints. 
    
    This will hide to the rule author and target author 
    
```
# By convention, toolchain_type targets are named "toolchain_type" and
# distinguished by their package path. So the full path for this would be
# //bar_tools:toolchain_type.
toolchain_type(name = "toolchain_type")

bar_binary = rule(
    implementation = _bar_binary_impl,
    attrs = {
        "srcs": attr.label_list(allow_files = True),
        ...
        # No `_compiler` attribute anymore.
    },
    toolchains = ["//bar_tools:toolchain_type"],
)

# accesses this dependency under ctx.toolchains instead of ctx.attr
def _bar_binary_impl(ctx):
    ...
    info = ctx.toolchains["//bar_tools:toolchain_type"].barcinfo
    # The rest is unchanged.
    command = "%s -l %s %s" % (
        info.compiler_path,
        info.system_lib,
        " ".join(info.arch_flags),
    )
    ..
```

ctx.toolchains["//bar_tools:toolchain_type"] returns the ToolchainInfo provider of whatever target Bazel resolved the toolchain dependency to

- mandatory and optional toolchains 

```
bar_binary = rule(
    ...
    toolchains = [
        config_common.toolchain_type("//bar_tools:toolchain_type", mandatory = False),
    ],
)

toolchains = ["//bar_tools:toolchain_type"]

toolchains = [config_common.toolchain_type("//bar_tools:toolchain_type")]

toolchains = [config_common.toolchain_type("//bar_tools:toolchain_type", mandatory = True)]

toolchains = [config_common.toolchain_type("//bar_tools:toolchain_type", mandatory = False)]
```

- Writing aspects that use toolchains 

```
bar_aspect = aspect(
    implementation = _bar_aspect_impl,
    attrs = {},
    toolchains = ['//bar_tools:toolchain_type'],
)

def _bar_aspect_impl(target, ctx):
  toolchain = ctx.toolchains['//bar_tools:toolchain_type']
  # Use the toolchain provider like in a rule.
  return []
```

- Defining toolchains,  convention this rule's name is suffixed with "_toolchain".

```
def _bar_toolchain_impl(ctx):
    toolchain_info = platform_common.ToolchainInfo(
        barcinfo = BarcInfo(
            compiler_path = ctx.attr.compiler_path,
            system_lib = ctx.attr.system_lib,
            arch_flags = ctx.attr.arch_flags,
        ),
    )
    return [toolchain_info]

bar_toolchain = rule(
    implementation = _bar_toolchain_impl,
    attrs = {
        "compiler_path": attr.string(),
        "system_lib": attr.string(),
        "arch_flags": attr.string_list(),
    },
)

// define targets for specific barc compilers.
bar_toolchain(
    name = "barc_linux",
    arch_flags = [
        "--arch=Linux",
        "--debug_everything",
    ],
    compiler_path = "/path/to/barc/on/linux",
    system_lib = "/usr/lib/libbarc.so",
)

bar_toolchain(
    name = "barc_windows",
    arch_flags = [
        "--arch=Windows",
        # Different flags, no debug support on windows.
    ],
    compiler_path = "C:\\path\\on\\windows\\barc.exe",
    system_lib = "C:\\path\\on\\windows\\barclib.dll",
)

// create toolchain definitions for the two bar_toolchain targets
toolchain(
    name = "barc_linux_toolchain",
    exec_compatible_with = [
        "@platforms//os:linux",
        "@platforms//cpu:x86_64",
    ],
    target_compatible_with = [
        "@platforms//os:linux",
        "@platforms//cpu:x86_64",
    ],
    toolchain = ":barc_linux",
    toolchain_type = ":toolchain_type",
)

toolchain(
    name = "barc_windows_toolchain",
    exec_compatible_with = [
        "@platforms//os:windows",
        "@platforms//cpu:x86_64",
    ],
    target_compatible_with = [
        "@platforms//os:windows",
        "@platforms//cpu:x86_64",
    ],
    toolchain = ":barc_windows",
    toolchain_type = ":toolchain_type",
)
```

- a complex version of bar_toolchain 

```
def _bar_toolchain_impl(ctx):
    # The implementation is mostly the same as above, so skipping.
    pass

bar_toolchain = rule(
    implementation = _bar_toolchain_impl,
    attrs = {
        "compiler": attr.label(
            executable = True,
            mandatory = True,
            cfg = "exec",
        ),
        "system_lib": attr.label(
            mandatory = True,
            cfg = "target",
        ),
        "arch_flags": attr.string_list(),
    },
)
```

- The toolchain transition keeps the configuration the same, except that it forces the execution platform to be the same for the toolchain as for the parent

- Registering and building with toolchains. WORKSPACE file using register_toolchains(), or by passing the toolchains' labels on the command line using the --extra_toolchains

```
register_toolchains(
    "//bar_tools:barc_linux_toolchain",
    "//bar_tools:barc_windows_toolchain",
    # Target patterns are also permitted, so you could have also written:
    # "//bar_tools:all",
)

# toolchain will be selected based on the target and execution platforms.

# my_pkg/BUILD

platform(
    name = "my_target_platform",
    constraint_values = [
        "@platforms//os:linux",
    ],
)

bar_binary(
    name = "my_bar_binary",
    ...
)
```
$ bazel build //my_pkg:my_bar_binary --platforms=//my_pkg:my_target_platform

Bazel will see that //my_pkg:my_bar_binary is being built with a platform that has @platforms//os:linux and therefore resolve the //bar_tools:toolchain_type reference to //bar_tools:barc_linux_toolchain. This will end up building //bar_tools:barc_linux but not //bar_tools:barc_windows.

up-level references (..) and current-directory references (./) are forbidden.

- toolchain resolution 

    1. gathered from the WORKSPACE file via register_execution_platforms and register_toolchains. 

    2. specified on the command line via --extra_execution_platforms and --extra_toolchains. 

    3. The host platform is an available execution platform.

    4. If the rule uses execution groups, each execution group performs toolchain resolution separately for both platform and toolchains 
    
- debugging toolchains 

use the --toolchain_resolution_debug=regex flag. During toolchain resolution, the flag provides verbose output for toolchain types or target names that match the regex variable. You can use .* to output all information. 

example to see which cquery dependencies are from toolchain resolution

$ bazel cquery 'deps(//cc:my_cc_lib, 1)'
$ bazel cquery 'deps(//cc:my_cc_lib, 1)' --transitions=lite | grep "toolchain dependency" [toolchain dependency]#@local_config_cc//:cc-compiler-k8#HostTransition -> b6df211





# APIs 
https://bazel.build/rules/lib/starlark-overview#global-constants
## Build file API 
- global functions 

all
analysis_test_transition
any
archive_override
aspect
bazel_dep
bind
bool
configuration_field
depset
dict
dir
enumerate
exec_group
fail
float
getattr
git_override
hasattr
hash
int
len
list
local_path_override
max
min
module
module_extension
multiple_version_override
print
provider
range
register_execution_platforms(*platform_labels)
    + Register an already-defined platform so that Bazel can use it as an execution platform during toolchain resolution.
    
register_toolchains(*platform_labels)
    + Specifies already-defined execution platforms to be registered when this module is selected. Should be absolute target patterns (ie. beginning with either @ or //)
    
register_toolchains(*(toolchain_labels)

    + Specifies already-defined toolchains to be registered when this module is selected.
    
    
repository_rule(implementation, attrs, local, environ, configure, remotable, doc)
repr
reversed
rule
select
single_version_override
sorted
str
tag_class
tuple
type
use_extension
use_repo
visibility
workspace
zip

- global constatns 

apple_common
apple_toolchain
attr
bazel_py
cc_common
cmd_helper
config_common
coverage_common
java_common
platform_common, for Starlark to interact with the platform APIs.
    + members 
    ConstraintSettingInfo,  constructor/key for the ConstraintSettingInfo provider.
    
    ConstraintValueInfo
    PlatformInfo
    TemplateVariableInfo
    ToolchainInfo  
    
    
proto_common
testing

- configuration fragments 

apple
coverage
cpp
go
j2objc
java
objc
platform
proto
py
swift

- providers 

AnalysisTestResultInfo
AppleDebugOutputs
AppleDynamicFramework
AppleExecutableBinary
BaselineProfileProvider
CcInfo
    + A provider for compilation and linking of C++. This is also a marking provider telling C++ rules that they can depend on the rule with this provider. 
    
    + members 
    CcInfo
    compilation_context
    linking_context
    to_json
    to_proto
    
CcStarlarkApiProvider
CcToolchainConfigInfo
CcToolchainInfo
    + Information about the C++ compiler being used.
    + members 
    
    all_files
    ar_executable
    built_in_include_directories
    compiler
    compiler_executable
    cpu
    dynamic_runtime_lib
    gcov_executable
    ld_executable
    libc
    needs_pic_for_dynamic_libraries
    nm_executable
    objcopy_executable
    objdump_executable
    preprocessor_executable
    static_runtime_lib
    strip_executable
    sysroot
    target_gnu_system_name
    to_json
    to_proto
    
CompilationContext
ConstraintCollection
ConstraintSettingInfo
ConstraintValueInfo
DebugPackageInfo
DefaultInfo
    + A provider that gives general information about a target's direct and transitive files. Every rule type has this provider
    + members 
    
    DefaultInfo
    data_runfiles
    default_runfiles
    files
    files_to_run
    to_json
    to_proto
    
ExecutionInfo
    + Use this provider to specify special environment requirements needed to run tests.
    + members 
    
    ExecutionInfo
    exec_group
    requirements
    to_json
    to_proto
    
FeatureFlagInfo
file_provider
FilesToRunProvider
GeneratedExtensionRegistryProvider
IncompatiblePlatformProvider
InstrumentedFilesInfo
java_compilation_info
java_output_jars
JavaInfo
JavaPluginData
JavaPluginInfo
JavaRuntimeInfo
JavaToolchainInfo
ObjcProvider
OutputGroupInfo
PlatformInfo
ProguardSpecProvider
ProtoInfo
ProtoRegistryProvider
PyInfo
PyRuntimeInfo
RunEnvironmentInfo
TemplateVariableInfo
ToolchainInfo
    + Provider returned by toolchain rules to share data with rules which depend on toolchains. Read about toolchains for more information.
    
    + members 
    to_json
    to_proto
    
ToolchainTypeInfo
XcodeProperties
XcodeVersionConfig

- built-in types 
Action
actions
apple_bitcode_mode
apple_platform
apple_platform_type
Args
Aspect
Attribute
bazel_module
bazel_module_tags
BuildSetting
CcCompilationOutputs
CcLinkingOutputs
config
configuration
ctx
    + members 
    actions
    aspect_ids
    attr
    bin_dir
    build_file_path
    build_setting_value
    configuration
    coverage_instrumented
    created_actions
    default_provider
    disabled_features
    exec_groups
    executable
    expand_location
    expand_make_variables
    features
    file
    files
    fragments
    genfiles_dir
    host_configuration
    host_fragments
    info_file
    label
    new_file
    outputs
    resolve_command
    resolve_tools
    rule
    runfiles
    split_attr
    target_platform_has_constraint
    toolchains
    var
    version_file
    workspace_name
    
depset
DirectoryExpander
DottedVersion
exec_result
ExecGroupCollection
ExecGroupContext
ExecTransitionFactory
FeatureConfiguration
File
fragments
java_annotation_processing
java_output
Label
LateBoundDefault
LibraryToLink
License
LinkerInput
LinkingContext
module_ctx
module_extension
native
native_rule_transition
path
ProtoModule
Provider
repository_ctx

    + The context of the repository rule containing helper functions and information about attributes. get an repository_ctx object as an argument to the implementation function. members
    
    attr
    delete
    download, repository_ctx.download(url, output='', sha256='', executable=False, allow_fail=False, canonical_id='', auth={}, *, integrity='') Downloads a file to the output path for the provided url and returns a struct containing success
    download_and_extract
    execute
    extract
    file
    name
    os
    patchm, repository_ctx.patch(patch_file, strip=0)
    path
    read
    report_progress
    symlink, repository_ctx.symlink(target, link_name)
    template
    which
    workspace_root
    
    

repository_os
repository_rule
root
rule
rule_attributes
runfiles
struct
SymlinkEntry
tag_class
Target
TemplateDict
toolchain_type
ToolchainContext
transition

- core starlark data types 

bool
builtin_function_or_method
dict
float
function
int
json
list
range
string
tuple

- git repository rules can be loaded from @bazel_tools//tools/build_defs/repo:git.bzl. clone an external repository

git_repository(name, branch, build_file, build_file_content, commit, init_submodules, patch_args,
               patch_cmds, patch_cmds_win, patch_tool, patches, recursive_init_submodules, remote,
               shallow_since, strip_prefix, tag, verbose, workspace_file, workspace_file_content)              
 


new_git_repository(name, branch, build_file, build_file_content, commit, init_submodules,
                   patch_args, patch_cmds, patch_cmds_win, patch_tool, patches,
                   recursive_init_submodules, remote, shallow_since, strip_prefix, tag, verbose,
                   workspace_file, workspace_file_content)

- http repository rules 

    + Downloads a Bazel repository as a compressed archive file, decompresses it, and makes its targets available for binding.
    
http_archive(name, add_prefix, auth_patterns, build_file, build_file_content, canonical_id,
             integrity, netrc, patch_args, patch_cmds, patch_cmds_win, patch_tool, patches,
             remote_patch_strip, remote_patches, sha256, strip_prefix, type, url, urls,
             workspace_file, workspace_file_content)

add to WORKSPACE file 
```
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
  name = "my_ssl",
  url = "http://example.com/openssl.zip",
  sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  build_file = "@//:openssl.BUILD",
)
```   

    + Downloads a file from a URL and makes it available to be used as a file group.
    
http_file(name, auth_patterns, canonical_id, downloaded_file_path, executable, integrity, netrc,
          sha256, url, urls)
          
```
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")

http_file(
  name = "my_deb",
  url = "http://example.com/package.deb",
  sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
)
```

    + http_jar, Downloaded files must have a .jar extension
    
http_jar(name, auth_patterns, canonical_id, downloaded_file_name, integrity, netrc, sha256, url,
         urls)
         
```
  load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_jar")

  http_jar(
      name = "my_ssl",
      url = "http://example.com/openssl-0.2.jar",
      sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  )
```

- utils repository rules 
    
    + maybe(repo_rule, name, kwargs)
    
Utility function for only adding a repository if it's not already present.

    + parse_netrc(contents, filename)
Utility function to parse at least a basic .netrc file.

    + patch(ctx, patches, patch_cmds, patch_cmds_win, patch_tool, patch_args, auth)
    
Implementation of patching an already extracted repository.

    + read_user_netrc(ctx)
    
Read user's default netrc file.

    + update_attrs
    
update_attrs(orig, keys, override)
    
Utility function for altering and adding the specified attributes to a particular repository rule invocation.

    + use_netrc 
    
use_netrc(netrc, urls, patterns)
    
Compute an auth dict from a parsed netrc file and a list of URLs.

    + workspace_and_buildfile
    
workspace_and_buildfile(ctx)

Utility function for writing WORKSPACE and, if requested, a BUILD file.









# Bazel examples 
https://github.com/bazelbuild/examples/tree/main/rules


# Bazel buildtools 
https://github.com/bazelbuild/buildtools

- buildifier for formatting BUILD 
- buildozer for doing command-line operations 
- unused_deps for finding unneeded dependencies