extend.md

<!-- Generated with Stardoc: http://skydoc.bazel.build -->

Extending Gazelle
=================

Gazelle started out as a build file generator for Go projects, but it can be
extended to support other languages and custom sets of rules.

To extend Gazelle, you must do three things:

* Write a [go_library] with a function named `NewLanguage` that provides an
  implementation of the [Language] interface. This interface provides hooks for
  generating rules, parsing configuration directives, and resolving imports
  to Bazel labels. By convention, the library's package name should match
  the language (for example, `proto` or `bzl`).
* Write a [gazelle_binary](#gazelle_binary) rule. Include your library in the `languages`
  list.
* Write a [gazelle] rule that points to your `gazelle_binary`. When you run
  `bazel run //:gazelle`, your binary will be built and executed instead of
  the default binary.

Tests
-----

To write tests for your gazelle extension, you can use [gazelle_generation_test](#gazelle_generation_test),
which will run a gazelle binary of your choosing on a set of test workspaces.


Supported languages
-------------------

Moved to [/README.rst](/README.rst#supported-languages)

Example
-------

Gazelle itself is built using the model described above, so it may serve as
an example.

[//language/proto:go_default_library] and [//language/go:go_default_library]
both implement the [Language]
interface. There is also [//internal/gazellebinarytest:go_default_library],
a stub implementation used for testing.

`//cmd/gazelle` is a `gazelle_binary` rule that includes both of these
libraries through the `DEFAULT_LANGUAGES` list (you may want to use
`DEFAULT_LANGUAGES` in your own rule).

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

gazelle_binary(
    name = "gazelle",
    languages = [
        "@rules_python//gazelle",  # Use gazelle from rules_python.
        "@bazel_gazelle//language/go",  # Built-in rule from gazelle for Golang.
        "@bazel_gazelle//language/proto",  # Built-in rule from gazelle for Protos.
         # Any languages that depend on Gazelle's proto plugin must come after it.
        "@external_repository//language/gazelle",  # External languages can be added here.
    ],
    visibility = ["//visibility:public"],
)
```

This binary can be invoked using a `gazelle` rule like this:

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

# gazelle:prefix example.com/project
gazelle(
    name = "gazelle",
    gazelle = "//:my_gazelle_binary",
)
```

You can run this with `bazel run //:gazelle`.

Interacting with protos
-----------------------

The proto extension ([//language/proto:go_default_library]) gathers metadata
from .proto files and generates `proto_library` rules based on that metadata.
Extensions that generate language-specific proto rules (e.g.,
`go_proto_library`) may use this metadata.

For API reference, see the [proto godoc].

To get proto configuration information, call [proto.GetProtoConfig]. This is
mainly useful for discovering the current proto mode.

To get information about `proto_library` rules, examine the `OtherGen`
list of rules passed to `language.GenerateRules`. This is a list of rules
generated by other language extensions, and it will include `proto_library`
rules in each directory, if there were any. For each of these rules, you can
call `r.PrivateAttr(proto.PackageKey)` to get a [proto.Package] record. This
includes the proto package name, as well as source names, imports, and options.

[Language]: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language#Language
[//internal/gazellebinarytest:go_default_library]: https://github.com/bazelbuild/bazel-gazelle/tree/master/internal/gazellebinarytest
[//language/go:go_default_library]: https://github.com/bazelbuild/bazel-gazelle/tree/master/language/go
[//language/proto:go_default_library]: https://github.com/bazelbuild/bazel-gazelle/tree/master/language/proto
[gazelle]: https://github.com/bazelbuild/bazel-gazelle#bazel-rule
[go_binary]: https://github.com/bazelbuild/rules_go/blob/master/go/core.rst#go-binary
[go_library]: https://github.com/bazelbuild/rules_go/blob/master/go/core.rst#go-library
[proto godoc]: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language/proto
[proto.GetProtoConfig]: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language/proto#GetProtoConfig
[proto.Package]: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language/proto#Package

<a id="gazelle_binary"></a>

## gazelle_binary

<pre>
gazelle_binary(<a href="#gazelle_binary-name">name</a>, <a href="#gazelle_binary-languages">languages</a>)
</pre>

The `gazelle_binary` rule builds a Go binary that incorporates a list of
language extensions. This requires generating a small amount of code that
must be compiled into Gazelle's main package, so the normal [go_binary]
rule is not used.

When the binary runs, each language extension is run sequentially. This affects
the order that rules appear in generated build files. Metadata may be produced
by an earlier extension and consumed by a later extension. For example, the
proto extension stores metadata in hidden attributes of generated
`proto_library` rules. The Go extension uses this metadata to generate
`go_proto_library` rules.

**ATTRIBUTES**


| Name  | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="gazelle_binary-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
| <a id="gazelle_binary-languages"></a>languages |  A list of language extensions the Gazelle binary will use.<br><br>Each extension must be a [go_library] or something compatible. Each extension must export a function named `NewLanguage` with no parameters that returns a value assignable to [Language].   | <a href="https://bazel.build/concepts/labels">List of labels</a> | required |  |


<a id="gazelle_generation_test"></a>

## gazelle_generation_test

<pre>
gazelle_generation_test(<a href="#gazelle_generation_test-name">name</a>, <a href="#gazelle_generation_test-gazelle_binary">gazelle_binary</a>, <a href="#gazelle_generation_test-test_data">test_data</a>, <a href="#gazelle_generation_test-build_in_suffix">build_in_suffix</a>, <a href="#gazelle_generation_test-build_out_suffix">build_out_suffix</a>,
                        <a href="#gazelle_generation_test-gazelle_timeout_seconds">gazelle_timeout_seconds</a>, <a href="#gazelle_generation_test-size">size</a>, <a href="#gazelle_generation_test-kwargs">kwargs</a>)
</pre>

gazelle_generation_test is a macro for testing gazelle against workspaces.

The generation test expects a file structure like the following:

```
|-- <testDataPath>
    |-- some_test
        |-- WORKSPACE
        |-- README.md --> README describing what the test does.
        |-- arguments.txt --> newline delimited list of arguments to pass in (ignored if empty).
        |-- expectedStdout.txt --> Expected stdout for this test.
        |-- expectedStderr.txt --> Expected stderr for this test.
        |-- expectedExitCode.txt --> Expected exit code for this test.
        |-- app
            |-- sourceFile.foo
            |-- BUILD.in --> BUILD file prior to running gazelle.
            |-- BUILD.out --> BUILD file expected after running gazelle.
```

To update the expected files, run `UPDATE_SNAPSHOTS=true bazel run //path/to:the_test_target`.


**PARAMETERS**


| Name  | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="gazelle_generation_test-name"></a>name |  The name of the test.   |  none |
| <a id="gazelle_generation_test-gazelle_binary"></a>gazelle_binary |  The name of the gazelle binary target. For example, //path/to:my_gazelle.   |  none |
| <a id="gazelle_generation_test-test_data"></a>test_data |  A list of target of the test data files you will pass to the test. This can be a https://bazel.build/reference/be/general#filegroup.   |  none |
| <a id="gazelle_generation_test-build_in_suffix"></a>build_in_suffix |  The suffix for the input BUILD.bazel files. Defaults to .in. By default, will use files named BUILD.in as the BUILD files before running gazelle.   |  `".in"` |
| <a id="gazelle_generation_test-build_out_suffix"></a>build_out_suffix |  The suffix for the expected BUILD.bazel files after running gazelle. Defaults to .out. By default, will use files named check the results of the gazelle run against files named BUILD.out.   |  `".out"` |
| <a id="gazelle_generation_test-gazelle_timeout_seconds"></a>gazelle_timeout_seconds |  Number of seconds to allow the gazelle process to run before killing.   |  `2` |
| <a id="gazelle_generation_test-size"></a>size |  Specifies a test target's "heaviness": how much time/resources it needs to run.   |  `None` |
| <a id="gazelle_generation_test-kwargs"></a>kwargs |  Attributes that are passed directly to the test declaration.   |  none |