gazelle

README

Gazelle Java extension

This provides an experimental Gazelle extension to generate build files for Java projects.

Usage

In the WORKSPACE file set up the rules_jvm correctly:

load("@contrib_rules_jvm//:repositories.bzl", "contrib_rules_jvm_deps", "contrib_rules_jvm_gazelle_deps")

contrib_rules_jvm_deps()

contrib_rules_jvm_gazelle_deps()

load("@contrib_rules_jvm//:setup.bzl", "contrib_rules_jvm_setup")

contrib_rules_jvm_setup()

load("@contrib_rules_jvm//:gazelle_setup.bzl", "contib_rules_jvm_gazelle_setup")

contib_rules_jvm_gazelle_setup()

In the top level BUILD.bazel file, setup Gazelle to use gazelle-languages binary:

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

# gazelle:prefix github.com/your/project
gazelle(
    name = "gazelle",
    gazelle = ":gazelle_bin",
)

gazelle_binary(
    name = "gazelle_bin",
    languages = DEFAULT_LANGUAGES + [
        "@contrib_rules_jvm//java/gazelle",
    ],
)

Make sure you have everything setup properly by building the gazelle binary: bazel build //:gazelle_bin

When you update your Maven dependencies, you must rebuild the package index:

# Pin Maven deps
bazel run @unpinned_maven//:pin

# Download Maven deps so the Maven resolver can do its work
bazel fetch @maven//...

# Update the Maven mapping
bazel run @contrib_rules_jvm//java/gazelle/cmd/parsejars -- --repo-root "$PWD"
# this generates a maven_manifest.json file that should be versioned along the maven_install.json file

# Run Gazelle with the java extension
bazel run //:gazelle

Configuration options

This Gazelle extension supports some configuration options, which are enabled by adding comments to your root BUILD.bazel file. For example, to set java_maven_install_file, you would add the following to your root BUILD.bazel file:

# gazelle:java_maven_install_file project/main_maven_install.json

See javaconfig/config.go for a list of configuration options and their documentation.

Troubleshooting

If one forgets to run bazel fetch @maven//..., the code will complain and tell you to run this command.

If one forgets to "Update the Maven mapping", they use out of date data for the rules resolution, and the hash check will fail. An error is printed and the resolution does not happen.

Contibutors documentation

The following are the targets of interest:

• //java/gazelle implements a Gazelle extension
• //java/gazelle/private/javaparser/cmd/javaparser-wrapper wraps the java parser with an activity tracker (to stop the parser) and an adapter to prevent self imports.
• //java/src/com/github/bazel_contrib/contrib_rules_jvm/javaparser/generators:Main is the java parser side process

The maven integration relies on:

• //java/gazelle/cmd/parsejars CLI to create the packages database (see usage in tools/update-dependencies.sh)
• github.com/bazel-contrib/rules_jvm/java/gazelle/private/maven#NewResolverFromManifest loads the packages DB and resolve Maven dependencies

Documentation

Index

• func NewLanguage() language.Language
• type Configurer
  • func NewConfigurer(lang *javaLang) *Configurer
  • func (jc *Configurer) CheckFlags(fs *flag.FlagSet, c *config.Config) error
  • func (jc *Configurer) Configure(c *config.Config, rel string, f *rule.File)
  • func (jc *Configurer) KnownDirectives() []string
  • func (jc Configurer) RegisterFlags(fs *flag.FlagSet, cmd string, c *config.Config)
• type Resolver
  • func NewResolver(lang *javaLang) *Resolver
  • func (Resolver) Embeds(r *rule.Rule, from label.Label) []label.Label
  • func (jr Resolver) Imports(c *config.Config, r *rule.Rule, f *rule.File) []resolve.ImportSpec
  • func (Resolver) Name() string
  • func (jr Resolver) Resolve(c *config.Config, ix *resolve.RuleIndex, rc *repo.RemoteCache, r *rule.Rule, ...)

Functions

func NewLanguage

func NewLanguage() language.Language

Types

type Configurer

type Configurer struct {
	// contains filtered or unexported fields
}

Configurer satisfies the config.Configurer interface. It's the language-specific configuration extension.

See config.Configurer for more information.

func NewConfigurer

func NewConfigurer(lang *javaLang) *Configurer

func (*Configurer) CheckFlags

func (jc *Configurer) CheckFlags(fs *flag.FlagSet, c *config.Config) error

func (*Configurer) Configure

func (jc *Configurer) Configure(c *config.Config, rel string, f *rule.File)

func (*Configurer) KnownDirectives

func (jc *Configurer) KnownDirectives() []string

func (Configurer) RegisterFlags

func (jc Configurer) RegisterFlags(fs *flag.FlagSet, cmd string, c *config.Config)

type Resolver

type Resolver struct {
	// contains filtered or unexported fields
}

Resolver satisfies the resolve.Resolver interface. It's the language-specific resolver extension.

See resolve.Resolver for more information.

func NewResolver

func NewResolver(lang *javaLang) *Resolver

func (Resolver) Embeds

func (Resolver) Embeds(r *rule.Rule, from label.Label) []label.Label

func (Resolver) Imports

func (jr Resolver) Imports(c *config.Config, r *rule.Rule, f *rule.File) []resolve.ImportSpec

func (Resolver) Name

func (Resolver) Name() string

func (Resolver) Resolve

func (jr Resolver) Resolve(c *config.Config, ix *resolve.RuleIndex, rc *repo.RemoteCache, r *rule.Rule, imports interface{}, from label.Label)