|
1 | 1 | This is an example linter that can be compiled into a plugin for `golangci-lint`. |
2 | 2 |
|
3 | | -To use this: |
4 | | - |
5 | 3 | ### Create the Plugin From This Linter |
6 | 4 |
|
7 | | -1. Download the source code \* |
| 5 | +1. Download the source code |
8 | 6 | 2. From the root project directory, run `go build -buildmode=plugin plugin/example.go`. |
9 | | -3. Copy the generated `example.so` file into your project or to some other known location of your choosing. \** |
10 | | - |
| 7 | +3. Copy the generated `example.so` file into your project or to some other known location of your choosing. [^1] |
11 | 8 |
|
12 | 9 | ### Create a Copy of `golangci-lint` that Can Run with Plugins |
13 | 10 |
|
14 | | -In order to use plugins, you'll need a golangci-lint executable that can run them. Plugin dependencies defined in the |
15 | | -`go.mod` file MUST have a matching version (or hash) as the same dependency in th `golangci-lint` binary if the |
16 | | -dependency is used in both. Because of the high probability of this both using the same dependency, it is recommended |
17 | | -to use a locally built binary. To do so: |
| 11 | +In order to use plugins, you'll need a golangci-lint executable that can run them. |
| 12 | + |
| 13 | +Plugin dependencies defined in the `go.mod` file MUST have a matching version (or hash) as the same dependency in th `golangci-lint` binary if the dependency is used in both. |
| 14 | + |
| 15 | +Because of the high probability of this both using the same dependency, it is recommended to use a locally built binary. |
| 16 | + |
| 17 | +To do so: |
18 | 18 |
|
19 | 19 | 1. Download [golangci-lint](https://github.com/golangci/golangci-lint) source code |
20 | | -2. From the projects root directory, run `make` |
| 20 | +2. From the projects root directory, run `make build` |
21 | 21 | 3. Copy the `golangci-lint` executable that was created to your path, project, or other location |
22 | 22 |
|
23 | 23 | ### Configure Your Project for Linting |
24 | 24 |
|
25 | | -If you already have a linter plugin available, you can follow these steps to define its usage in a projects |
26 | | -`.golangci.yml` file. If you're looking for instructions on how to configure your own custom linter, they can be found |
27 | | -further down. |
| 25 | +If you already have a linter plugin available, you can follow these steps to define its usage in a projects `.golangci.yml` file. |
28 | 26 |
|
29 | | -1. If the project you want to lint does not have one already, copy the [.golangci.yml](https://github.com/golangci/golangci-lint/blob/master/.golangci.yml) |
30 | | - to the root directory. |
31 | | -2. Adjust the yaml to appropriate `linters-settings:custom` entries as so: |
32 | | -``` |
33 | | -linters-settings: |
34 | | - custom: |
35 | | - example: |
36 | | - path: /example.so |
37 | | - description: The description of the linter |
38 | | - original-url: github.com/golangci/example-linter |
39 | | -``` |
| 27 | +If you're looking for instructions on how to configure your own custom linter, they can be found further down. |
| 28 | + |
| 29 | +1. If the project you want to lint does not have one already, copy the [.golangci.yml](https://github.com/golangci/golangci-lint/blob/master/.golangci.yml) to the root directory. |
| 30 | +2. Adjust the YAML to appropriate `linters-settings.custom` entries as so: |
| 31 | + ```yml |
| 32 | + linters-settings: |
| 33 | + custom: |
| 34 | + example: |
| 35 | + path: /example.so |
| 36 | + description: The description of the linter |
| 37 | + original-url: github.com/golangci/example-linter |
| 38 | + ``` |
40 | 39 |
|
41 | | -That is all the configuration that is required to run a custom linter in your project. Custom linters are enabled by default, |
42 | | -but abide by the same rules as other linters. If the disable all option is specified either on command line or in |
43 | | -`.golang.yml` files `linters:disable-all: true`, custom linters will be disabled; they can be re-enabled by adding them |
44 | | -to the `linters:enable` list, or providing the enabled option on the command line, `golangci-lint run -Eexample`. |
| 40 | +That is all the configuration that is required to run a custom linter in your project. |
| 41 | +
|
| 42 | +Custom linters are enabled by default, but abide by the same rules as other linters. |
| 43 | +
|
| 44 | +If the disable all option is specified either on command line or in `.golang.yml` files `linters.disable-all: true`, custom linters will be disabled; |
| 45 | +they can be re-enabled by adding them to the `linters:enable` list, |
| 46 | +or providing the enabled option on the command line, `golangci-lint run -Eexample`. |
45 | 47 |
|
46 | 48 | ### To Create Your Own Custom Linter |
47 | 49 |
|
48 | 50 | Your linter must implement one or more `golang.org/x/tools/go/analysis.Analyzer` structs. |
49 | | -Your project should also use `go.mod`. All versions of libraries that overlap `golangci-lint` (including replaced |
50 | | -libraries) MUST be set to the same version as `golangci-lint`. You can see the versions by running `go version -m golangci-lint`. |
51 | 51 |
|
52 | | -You'll also need to create a go file like `plugin/example.go`. This MUST be in the package `main`, and define a |
53 | | -variable of name `AnalyzerPlugin`. The `AnalyzerPlugin` instance MUST implement the following interface: |
54 | | -``` |
| 52 | +Your project should also use `go.mod`. |
| 53 | + |
| 54 | +All versions of libraries that overlap `golangci-lint` (including replaced libraries) MUST be set to the same version as `golangci-lint`. |
| 55 | +You can see the versions by running `go version -m golangci-lint`. |
| 56 | + |
| 57 | +You'll also need to create a go file like `plugin/example.go`. |
| 58 | + |
| 59 | +This MUST be in the package `main`, and define a variable of name `AnalyzerPlugin`. |
| 60 | +The `AnalyzerPlugin` instance MUST implement the following interface: |
| 61 | + |
| 62 | +```go |
55 | 63 | type AnalyzerPlugin interface { |
56 | 64 | GetAnalyzers() []*analysis.Analyzer |
57 | 65 | } |
58 | 66 | ``` |
59 | | -The type of `AnalyzerPlugin` is not important, but is by convention `type analyzerPlugin struct {}`. See |
60 | | -[plugin/example.go](https://github.com/golangci/example-plugin-linter/plugin/example.go) for more info. |
61 | 67 |
|
62 | | -To build the plugin, from the root project directory, run `go build -buildmode=plugin plugin/example.go`. This will create a plugin `*.so` |
63 | | -file that can be copied into your project or another well known location for usage in golangci-lint. |
| 68 | +The type of `AnalyzerPlugin` is not important, but is by convention `type analyzerPlugin struct {}`. |
| 69 | +See [plugin/example.go](https://github.com/golangci/example-plugin-linter/plugin/example.go) for more info. |
| 70 | + |
| 71 | +To build the plugin, from the root project directory, run `go build -buildmode=plugin plugin/example.go`. |
64 | 72 |
|
65 | | -\* Sorry, I haven't found a way to enable `go get` functionality for plugins yet. If you know how, let me know! |
| 73 | +This will create a plugin `*.so` file that can be copied into your project or another well known location for usage in golangci-lint. |
66 | 74 |
|
67 | | -\** Alternately, you can use the `-o /path/to/location/example.so` output flag to have it put it there for you. |
| 75 | +[^1]: Alternately, you can use the `-o /path/to/location/example.so` output flag to have it put it there for you. |
0 commit comments