BUILD.bazel

load("@bazel_gazelle//:def.bzl", "gazelle")

# The following directives inform gazelle how to auto-generate BUILD.bazel
# files throughout the repo. By including them here, we can run gazelle using
# `bazel run //:gazelle` instead of invoking gazelle directly.
#
# NB: Be sure to re-generate BUILD.bazel files if any of the directives below
# are changed.

# Define the gazelle prefix and what the autogenerated BUILD files should be
# named as.
#
# gazelle:prefix github.com/cockroachdb/cockroach
# gazelle:build_file_name BUILD.bazel

# We disable protobuf generation for our dependencies.
#
# gazelle:proto disable_global

# Gazelle needs the following resolve hints.
#
# TODO(irfansharif): I'm not sure why this is. Is it because it's a proto only
# package?
#
# gazelle:resolve go github.com/grpc-ecosystem/grpc-gateway/internal //vendor/github.com/grpc-ecosystem/grpc-gateway/internal

# See pkg/sql/opt/optgen/cmd/langgen/BUILD.bazel for more details.
#
# gazelle:resolve go github.com/cockroachdb/cockroach/pkg/sql/opt/optgen/lang //pkg/sql/opt/optgen/lang

# We exclude a few things from gazelle consideration:
# - The protobuf C dependency, it's are already bazel-ified, lest we overwrite
#   those build files
# - The artifacts directory
# - All checked-in autogenerated files (they'll get autogenerated on the fly
#   through bazel)
# - A testdata "repo" that looks like a go package, but isn't
#   (testdata/src/example.com)
# - A few auto-generated sql parser files
#
# gazelle:exclude c-deps/protobuf
# gazelle:exclude artifacts
# gazelle:exclude **/zcgo_flags.go
# gazelle:exclude **/zcgo_flags_*.go
# gazelle:exclude **/*.og.go
# gazelle:exclude **/*.eg.go
# gazelle:exclude pkg/sql/parser/sql.go
# gazelle:exclude pkg/sql/parser/helpmap_test.go
# gazelle:exclude pkg/sql/parser/help_messages.go
# gazelle:exclude pkg/sql/lex/keywords.go
# gazelle:exclude pkg/sql/lex/tokens.go
# gazelle:exclude pkg/sql/lexbase/reserved_keywords.go
# gazelle:exclude pkg/sql/opt/rule_name_string.go
# gazelle:exclude pkg/cmd/prereqs/testdata

# Generally useful references:
#
#   https://docs.bazel.build/versions/master/user-manual.html
#   https://docs.bazel.build/versions/master/guide.html

# TODO(irfansharif): Today we let bazel take over the vendor directory and
# define each vendored dependency as a bazel target. We should be able to have
# bazel ignore all of vendor/ and create those dependencies on the fly.
# Deleting the vendor directory and running `bazel run //:gazelle` shows what
# that would look like (though that doesn't quite work yet).

# TODO(irfansharif): Document a few usage patterns for bazel and how to
# understand all the autogen stuff. Probably as a tech note. Here are a few
# short hands I've used so far:
#
#   bazel test //pkg/kv/kvserver/concurrency/...
#   bazel test //pkg/kv/kvserver:all --test_cache_results=no --test_output=all
#   bazel test --features race //pkg/kv/kvserver/concurrency/... --test_output=all \
#     --test_arg='-test.v' --test_arg='-show-logs' --test_filter='TestBTreeClone.*' \
#     --run_under='stress -maxtime=120s' --cache_test_results=no
#   bazel build //pkg/sql/opt
#   bazel build //pkg/sql/opt:all
#   bazel build //pkg/sql/colexec:gen-exec
#   bazel build //pkg/cmd/cockroach-short
#   bazel build //:libjemalloc
#   bazel query //pkg/sql/colexec:all
#   bazel run //:gazelle
#   bazel run //pkg/cmd/cockroach-short -- demo
#   bazel run //pkg/sql/opt/optgen/cmd/langgen -- -h
#   bazel run //:gazelle -- update-repos -from_file=go.mod -to_macro=DEPS.bzl%go_deps
#
# The //<stuff> names can also be fully qualified using @cockroach, and that
# appears in certain parts of the codebase/elsewhere. Specifically it'll look
# like:
#
#   bazel build @cockroach//pkg/cmd/cockroach-short
#
# TODO(irfansharif): We should define shorthands for all of the above. See
# https://docs.bazel.build/versions/master/skylark/tutorial-custom-verbs.html

# TODO(irfansharif): The way we currently generate code through bazel, that
# code is only available within the bazel sandbox. Bazel ignores all
# the pre-generated code that is already checked into the codebase (through
# `make generate`/etc.) through the exclude directives above. It's generating
# everything on the fly.
#
# As we move towards bazel, we'll want to introduce a mechanism that implants
# the generated code within the sandbox placing them "back into" the
# appropriate packages. This is to ensure we don't break existing IDEs and code
# editors which rely on files existing in the same package itself (as opposed
# to the sandbox). This way we could continue checking in auto-generated code.
# We should provide a bazel alternative for `make generate` that does this very
# same thing. See [1], this is a long standing issue for folks using using Go,
# bazel, and autogenerated code.
#
# [1]: https://github.com/bazelbuild/rules_go/issues/512.

# TODO(irfansharif): We'll need to pin toolchains somewhere to make sure
# everything below works as expected.

gazelle(
    name = "gazelle",
    prefix = "github.com/cockroachdb/cockroach",
)