You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
1. For Mac users, you can install all of the Homebrew and Go packages together.
15
+
16
+
```bash
17
+
make install-tools-mac
18
+
```
19
+
20
+
Obviously, this won't work on Linux, so ensure that the following packages are installed from your system's package manager.
21
+
22
+
* Go 1.21+ (primary language)
23
+
* Node.js 18+ (linting tools)
24
+
* Python 3.11+ (linting tools)
25
+
*`jq` (shell scripting tools)
26
+
*`pre-commit` (linting tools)
27
+
28
+
1. Running `make`in the root of the repo, by itself, will display a list of tasks and what they do. The ones highlighted in yellow are the ones that are most frequently used, or combine running multiple sub-tasks with one convenient command.
29
+
30
+
```bash
31
+
make
32
+
```
33
+
34
+
1. After the core dependencies are installed, install the Git hooks. These will validate code on commit and reject anything that does not meet this project's best practices.
35
+
36
+
```bash
37
+
make install-hooks
38
+
```
39
+
40
+
1. This project uses [Conventional Commits](https://www.conventionalcommits.org). If you are unfamiliar with this pattern of writing your commit messages, please read the spec. This project supports the following keywords:
| `build` | Changes that affect the build system or external dependencies. |
45
+
| `ci` | Changes to our CI configuration files and scripts. |
46
+
| `deps` | Updating dependencies. |
47
+
| `docs` | Documentation only changes. |
48
+
| `feat` | A new feature. |
49
+
| `fix` | A bug fix. |
50
+
| `lint` | Linter or static analysis-related changes. |
51
+
| `perf` | A code change that improves performance. |
52
+
| `refactor` | A code change that neither fixes a bug nor adds a feature. |
53
+
| `style` | Changes that do not affect the meaning of the code (whitespace, formatting, etc.). |
54
+
| `test` | Adding missing tests or correcting existing tests, benchmarks, fuzzing, etc. |
55
+
3
56
## Build provider from source
4
57
5
-
> **IMPORTANT:** You probably want **"Install provider (as a user)"** instead.
58
+
> [!IMPORTANT]
59
+
> You probably want **"Install provider (as a user)"** instead.
6
60
7
61
This will build the provider for the current OS and CPU architecture, and install it into your Go binary path.
8
62
@@ -18,21 +72,13 @@ This will build the provider for the current OS and CPU architecture, and instal
18
72
19
73
By default, Terraform expects to download providers over the internet. Instead, we're going to download our own from GitHub Enterprise, and we need to tell Terraform how to find it.
20
74
21
-
We're going to assume you already have [Homebrew](https://mac.install.guide/homebrew/index.html) and the [Xcode CLI tools](https://mac.install.guide/commandlinetools/1.html) installed.
22
-
23
-
1. Install [Go](https://go.dev). For Mac users, it's as simple as…
24
-
25
-
```bash
26
-
brew install go
27
-
```
28
-
29
75
1. Find where your installed Go binaries live.
30
76
31
77
```bash
32
78
./find-go-bin.sh
33
79
```
34
80
35
-
1. Update your `~/.terraformrc` file with these contents:
81
+
1. Update your `~/.terraformrc` file with these contents, replacing `<GO_BIN_PATH>` with the result from `./find-go-bin.sh`.
36
82
37
83
```hcl
38
84
provider_installation {
@@ -44,13 +90,6 @@ We're going to assume you already have [Homebrew](https://mac.install.guide/home
44
90
}
45
91
```
46
92
47
-
1. Replace `<GO_BIN_PATH>` with the path to your Go binaries, above.
48
-
49
-
```bash
50
-
# After running `make build`...
51
-
dirname $(which terraform-provider-corefunc)
52
-
```
53
-
54
93
## Ensure the provider is installed correctly
55
94
56
95
```bash
@@ -76,95 +115,174 @@ You can apply this plan to save these new output values to the Terraform state,
76
115
77
116
## Testing and fuzzing
78
117
79
-
The `nproc` binary is commonly available on most Linux distributions. To install in Alpine Linux or macOS, you should install the `coreutils` package from `apk` (Alpine Linux) or `brew` (macOS).
118
+
The `nproc` binary is commonly available on most Linux distributions. If it's not installed, go back to the top of this document and follow instructions.
80
119
81
120
### Unit tests (and code coverage)
82
121
83
122
This will run Unit and Fuzz tests. This tests the low-level Go code, but not the Terraform integration wrapped around it.
84
123
85
124
```bash
86
-
go test -count=1 -parallel=$(nproc) -timeout 30s -coverpkg=./... -coverprofile=_coverage.txt -v ./...
This will run all tests: Unit, Acceptance, and Fuzz. Acceptance tests run the code through Terraform and test the Terraform communication pathway.
98
137
99
138
```bash
100
-
TF_ACC=1 go test -count=1 -parallel=$(nproc) -timeout 30s -coverpkg=./... -coverprofile=_coverage.txt -v ./...
139
+
make acc
101
140
```
102
141
103
142
You can view the code coverage report with:
104
143
105
144
```bash
106
-
go tool cover -html=_coverage.txt
145
+
make view-cov
107
146
```
108
147
109
148
### Fuzzer
110
149
111
150
This will run the fuzzer for 10 minutes. [Learn more about fuzzing](https://go.dev/doc/tutorial/fuzz).
112
151
113
152
```bash
114
-
go test -fuzz=Fuzz -fuzztime 10m -v ./corefunc/.
153
+
make fuzz
115
154
```
116
155
117
-
### Benchmarks
156
+
### Running individual tests
118
157
119
-
Benchmarks test the performance/scalability of a package. Different versions of the benchmarks execute different code paths inside the functions.
158
+
We don't have `make` tasks for individual tests, however, if you run one of the testing `make` tasks, the first line of the output will show you the command being run. For example:
120
159
121
160
```bash
161
+
# Line breaks added for readability.
122
162
go test \
123
-
-bench=. \
124
-
-benchtime=10s \
125
-
-benchmem \
126
-
-cpuprofile=_cpu.out \
127
-
-memprofile=_mem.out \
128
-
-trace=_trace.out \
129
-
./corefunc \
130
-
| tee _bench.txt
163
+
-count=1 \
164
+
-parallel=$(nproc) \
165
+
-timeout 30s \
166
+
-coverpkg=./... \
167
+
-coverprofile=__coverage.out \
168
+
-v ./...
131
169
```
132
170
133
-
Then:
171
+
You can add `-run` followed by a Go regexp pattern to match the names of the tests you want to run.
134
172
135
173
```bash
136
-
go tool pprof -http :8080 _cpu.out
174
+
# Line breaks added for readability.
175
+
go test \
176
+
-run "TruncateLabel" \
177
+
-count=1 \
178
+
-parallel=$(nproc) \
179
+
-timeout 30s \
180
+
-coverpkg=./corefunc/... \
181
+
-coverprofile=__coverage.out \
182
+
-v ./corefunc/...
137
183
```
138
184
185
+
## Benchmarks
186
+
187
+
Benchmarks test the performance of a package.
188
+
189
+
### Quick benchmarks
190
+
191
+
You can run a _quick_ benchmark (relatively speaking) that gets some data we can measure. It benchmarks the results of:
192
+
193
+
* Each test
194
+
* …with each testcase
195
+
* …serially as well as in parallel
196
+
139
197
```bash
140
-
go tool pprof -http :8081 _mem.out
198
+
make quickbench
141
199
```
142
200
201
+
### Benchmark analysis
202
+
203
+
If you want to compare benchmarks between code changes, you'll need to run a _more complete_ benchmark which will provide enough data for analysis. It benchmarks the results of:
204
+
205
+
* Each test
206
+
* …with each test case
207
+
* …serially as well as in parallel
208
+
* …multiple times over
209
+
143
210
```bash
144
-
go tool trace _trace.out
211
+
make bench
145
212
```
146
213
214
+
Benchmark files are timestamped, so you can compare benchmark results across runs. See [benchstat documentation](https://pkg.go.dev/golang.org/x/perf/cmd/benchstat) to understand how to most effectively slice the results.
215
+
216
+
> [!NOTE]
217
+
> If you put old before new, values in the right-most column represent the size of the decrease (negative values are better). If you reverse them and push new before old, values in the right-most column represent the size of the increase (positive values are better).
I had to go into each file with VS Code, select the benchmarking lines, and sort _ascending_, then sort _numerically_ to get the lines in an order that makes sense.
249
+
250
+
The way that these are written, `TruncateLabel` is the test. `balanced{number}` is the test-case. And the `-10` is the number of CPU cores I have on my machine.
251
+
252
+
For the middle part (`balanced{number}`), the number represents the number of characters I truncated the label to. I know from the implementation that different truncation lengths can trigger different code paths, and that anything under `6` results in a near-immediate return with no calculation necessary. We also know that the longer lengths similarly have less truncation logic to perform.
253
+
254
+
But the middle tests from ~10–80 are most likely to execute _all_ of the code in the function, which makes it the most intersting.
255
+
256
+
### Exploring profiler data
257
+
258
+
Then, you can view the CPU profiler results…
153
259
154
260
```bash
155
-
rm -f _*.out _*.txt *.test
261
+
make view-cpupprof
156
262
```
157
263
158
-
## Scanning for vulnerabilities
264
+
…view the memory profiler results…
159
265
160
266
```bash
161
-
go install golang.org/x/vuln/cmd/govulncheck@latest
162
-
govulncheck -test ./...
267
+
make view-mempprof
163
268
```
164
269
270
+
…or view the trace results.
271
+
165
272
```bash
166
-
go install github.com/google/osv-scanner/cmd/osv-scanner@v1
167
-
osv-scanner -r .
273
+
make view-trace
274
+
```
275
+
276
+
When you're done, clean-up.
277
+
278
+
```bash
279
+
make clean-bench
280
+
```
281
+
282
+
## Scanning for vulnerabilities
283
+
284
+
```bash
285
+
make vuln
168
286
```
169
287
170
288
## Previewing documentation
@@ -174,26 +292,23 @@ osv-scanner -r .
174
292
Generate the Terraform Registry-facing documentation.
175
293
176
294
```bash
177
-
go generate -v ./...
295
+
make docs-provider
178
296
```
179
297
180
-
### CLI Go Documentation
298
+
### Go CLI Documentation
181
299
182
300
You can get the package documentation on the CLI using the `go doc` command.
183
301
184
302
```bash
185
-
go doc -C corefunc/ -all
303
+
make docs-cli
186
304
```
187
305
188
-
### Local HTTP Go Documentation Server
306
+
### Go Documentation Server
189
307
190
308
```bash
191
-
go install golang.org/x/tools/cmd/godoc@latest
192
-
godoc -index -links
309
+
make docs-serve
193
310
```
194
311
195
-
Then open <http://localhost:6060/pkg/github.com/northwood-labs/terraform-provider-corefunc/corefunc/>in your web browser.
196
-
197
312
## Running the debugger
198
313
199
314
> **IMPORTANT:** At present, we only provide support for debugging in VSCode. Debugging through other tools may work, but they are untested.
0 commit comments