ResiLien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Revise our contributing/development documentation 

Our documentation for how to contribute was in quite a state of disrepair,
with some documents still describing things as they were before moving
providers into separate repositories, others making assumptions about
Go development that are no longer true in modules mode, and so forth.

This is an attempt at a reset to a good state that should work with the
codebase as it currently stands, and should hopefully serve as a basis
for iterative improvement from here.

These new instructions lean primarily on standard Go toolchain usage and
instruct using the Makefile only for some Terraform-specific situations
that the Go toolchain does not automatically handle. The idea here is that
this direct usage of primary commands in the Go toolchain is less likely
to be broken by changes in future Go releases, and should be immediately
familiar to anyone who has experience with Go development.
This commit is contained in:
Martin Atkins 2019-10-11 17:28:54 -07:00
parent 96af863065
commit f96edbb113
4 changed files with 263 additions and 351 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

424
.github/CONTRIBUTING.md vendored
View File

@ -1,265 +1,281 @@
# Contributing to Terraform # Contributing to Terraform
**First:** if you're unsure or afraid of _anything_, just ask ---
or submit the issue or pull request anyways. You won't be yelled at for
giving your best effort. The worst that can happen is that you'll be
politely asked to change something. We appreciate any sort of contributions,
and don't want a wall of rules to get in the way of that.
However, for those individuals who want a bit more guidance on the This repository contains only Terraform core, which includes the command line
best way to contribute to the project, read on. This document will cover interface and the main graph engine. Providers are implemented as plugins that
what we're looking for. By addressing all the points we're looking for, each have their own repository in
it raises the chances we can quickly merge or address your contributions. [the `terraform-providers` organization](https://github.com/terraform-providers)
on GitHub. Instructions for developing each provider are in the associated
README file. For more information, see
[the provider development overview](https://www.terraform.io/docs/plugins/provider.html).
Specifically, we have provided checklists below for each type of issue and pull ---
request that can happen on the project. These checklists represent everything
we need to be able to review and respond quickly.
## HashiCorp, Official, and Community Providers Terraform is an open source project and we appreciate contributions of various
kinds, including bug reports and fixes, enhancement proposals, documentation
updates, and user experience feedback.
We separate providers out into what we call "HashiCorp Providers", "Partner Providers" and "Community Providers". To record a bug report, enhancement proposal, or give any other product
feedback, please [open a GitHub issue](https://github.com/hashicorp/terraform/issues/new/choose)
using the most appropriate issue template. Please do fill in all of the
information the issue templates request, because we've seen from experience that
this will maximize the chance that we'll be able to act on your feedback.
HashiCorp providers are providers that we dedicate full time engineers to Please not that we _don't_ use GitHub issues for usage questions. If you have
improving, supporting the latest features, and fixing bugs. These are providers a question about how to use Terraform in general or how to solve a specific
we understand deeply and are confident we have the resources to manage problem with Terraform, please start a topic in
ourselves. [the Terraform community forum](https://discuss.hashicorp.com/c/terraform-core),
where both Terraform team members and community members participate in
discussions.
Partner providers are providers where we depend on our partners to **All communication on GitHub, the community forum, and other HashiCorp-provided
contribute fixes and enhancements to improve. HashiCorp will run automated communication channels is subject to
tests and ensure these providers continue to work, but will not dedicate full [the HashiCorp community guidelines](https://www.hashicorp.com/community-guidelines).**
time engineers to add new features to these providers. These providers are
available in official Terraform releases, but the functionality is primarily
contributed.
All HashiCorp and Partner providers can be found in the (terraform-providers github organization)[https://github.com/terraform-providers]. ## Terraform CLI/Core Development Environment
Any provider issues should be opened in the provider's repository.
Our testing standards are the same for both HashiCorp and Official providers, This repository contains the source code for Terraform CLI, which is the main
and HashiCorp runs full acceptance test suites for every provider nightly to component of Terraform that contains the core Terraform engine.
ensure Terraform remains stable.
Community Providers are providers that are neither maintained nor tested by The HashiCorp-maintained Terraform providers are also open source but are not
HashiCorp. We can make no promises that these providers will work with any given in this repository; instead, they are each in their own repository in
version of Terraform. These providers are not automatically installed by [the `terraform-providers` organization](https://github.com/terraform-providers)
`terraform init` and instead require manual installation. on GitHub.
We make the distinction between these types of providers to help This repository also does not include the source code for some other parts of
highlight the vast amounts of community effort that goes in to making Terraform the Terraform product including Terraform Cloud, Terraform Enterprise, and the
great, and to help contributors better understand the role HashiCorp employees Terraform Registry. Those components are not open source, though if you have
play in the various areas of the code base. feedback about them (including bug reports) please do feel free to
[open a GitHub issue on this repository](https://github.com/hashicorp/terraform/issues/new/choose).
## Issues ---
### Issue Reporting Checklists If you wish to work on the Terraform CLI source code, you'll first need to
install the [Go](https://golang.org/) compiler and the version control system
[Git](https://git-scm.com/).
We welcome feature requests and bug reports. Below you'll find checklists with At this time the Terraform development environment is targeting only Linux and
guidelines for well-formed issues of each type. Mac OS X systems. While Terraform itself is compatible with Windows,
unfortunately the unit test suite currently contains Unix-specific assumptions
around maximum path lengths, path separators, etc.
#### Bug Reports Refer to the file [`.go-version`](.go-version) to see which version of Go
Terraform is currently built with. Other versions will often work, but if you
run into any build or testing problems please try with the specific Go version
indicated. You can optionally simplify the installation of multiple specific
versions of Go on your system by installing
[`goenv`](https://github.com/syndbg/goenv), which reads `.go-version` and
automatically selects the correct Go version.
- [ ] __Test against latest release__: Make sure you test against the latest Use Git to clone this repository into a location of your choice. Terraform is
released version. It is possible we already fixed the bug you're experiencing. using [Go Modules](https://blog.golang.org/using-go-modules), and so you
should _not_ clone it inside your `GOPATH`.
- [ ] __Search for possible duplicate reports__: It's helpful to keep bug Switch into the root directory of the cloned repository and build Terraform
reports consolidated to one thread, so do a quick search on existing bug using the Go toolchain in the standard way:
reports to check if anybody else has reported the same thing. You can scope
searches by the label "bug" to help narrow things down.
- [ ] __Include steps to reproduce__: Provide steps to reproduce the issue, ```
along with your `.tf` files, with secrets removed, so we can try to cd terraform
reproduce it. Without this, it makes it much harder to fix the issue. go install .
```
- [ ] __For panics, include `crash.log`__: If you experienced a panic, please The first time you run the `go install` command, the Go toolchain will download
create a [gist](https://gist.github.com) of the *entire* generated crash log any library dependencies that you don't already have in your Go modules cache.
for us to look at. Double check no sensitive items were in the log. Subsequent builds will be faster because these dependencies will already be
available on your local disk.
#### Feature Requests Once the compilation process succeeds, you can find a `terraform` executable in
the Go executable directory. If you haven't overridden it with the `GOBIN`
environment variable, the executable directory is the `bin` directory inside
the directory returned by the following command:
- [ ] __Search for possible duplicate requests__: It's helpful to keep requests ```
consolidated to one thread, so do a quick search on existing requests to go env GOPATH
check if anybody else has reported the same thing. You can scope searches by ```
the label "enhancement" to help narrow things down.
- [ ] __Include a use case description__: In addition to describing the If you are planning to make changes to the Terraform source code, you should
behavior of the feature you'd like to see added, it's helpful to also lay run the unit test suite before you start to make sure everything is initially
out the reason why the feature would be important and how it would benefit passing:
Terraform users.
#### Questions ```
go test ./...
```
Please do not use GitHub to ask questions! Instead: As you make your changes, you can re-run the above command to ensure that the
tests are _still_ passing. If you are working only on a specific Go package,
you can speed up your testing cycle by testing only that single package, or
packages under a particular package prefix:
* __Search for answers in Terraform documentation__ ```
go test ./command/...
go test ./addrs
```
* __Ask in the Community Forum__: Use [the community forum](https://discuss.hashicorp.com/c/terraform-core) for questions not answered by the documentation. ## Acceptance Tests: Testing interactions with external services
* __Request an update to the documentation__: If you find that the Terraform's unit test suite is self-contained, using mocks and local files
documentation is confusing or incorrect, open an issue (or a pull request) and to help ensure that it can run offline and is unlikely to be broken by changes
let us know. to outside systems.
### Issue Lifecycle However, several Terraform components interact with external services, such
as the automatic provider installation mechanism, the Terraform Registry,
Terraform Cloud, etc.
1. The issue is reported. There are some optional tests in the Terraform CLI codebase that _do_ interact
with external services, which we collectively refer to as "acceptance tests".
You can enable these by setting the environment variable `TF_ACC=1` when
running the tests. We recommend focusing only on the specific package you
are working on when enabling acceptance tests, both because it can help the
test run to complete faster and because you are less likely to encounter
failures due to drift in systems unrelated to your current goal:
2. The issue is verified and categorized by a Terraform collaborator. ```
Categorization is done via GitHub labels. We generally use a two-label TF_ACC=1 go test ./internal/initwd
system of (1) issue/PR type, and (2) section of the codebase. Type is ```
usually "bug", "enhancement", "documentation", or "question", and section
can be any of the providers or provisioners or "core".
3. Unless it is critical, the issue is left for a period of time (sometimes Because the acceptance tests depend on services outside of the Terraform
many weeks), giving outside contributors a chance to address the issue. codebase, and because the acceptance tests are usually used only when making
changes to the systems they cover, it is common and expected that drift in
those external systems will cause test failures. Because of this, prior to
working on a system covered by acceptance tests it's important to run the
existing tests for that system in an _unchanged_ work tree first and respond
to any test failures that preexist, to avoid misinterpreting such failures as
bugs in your new changes.
4. The issue is addressed in a pull request or commit. The issue will be ## Generated Code
referenced in the commit message so that the code that fixes it is clearly
linked.
5. The issue is closed. Sometimes, valid issues will be closed to keep Some files in the Terraform CLI codebase are generated. In most cases, we
the issue tracker clean. The issue is still indexed and available for update these using `go generate`, which is the standard way to encapsulate
future viewers, or can be re-opened if necessary. code generation steps in a Go codebase.
## Pull Requests However, code generation often relies on external tools which must be correctly
installed before running `go generate`. Terraform's `Makefile` includes
a target to install the tools needed for `go generate`:
Thank you for contributing! Here you'll find information on what to include in ```
your Pull Request to ensure it is accepted quickly. make tools
```
* Pull requests that don't follow the guidelines will be annotated with what After the tools are installed successfully, you can run code generation for
they're missing. A community or core team member may be able to swing around all packages:
and help finish up the work, but these PRs will generally hang out much
longer until they can be completed and merged.
### Pull Request Lifecycle ```
go generate ./...
```
1. You are welcome to submit your pull request for commentary or review before Use `git diff` afterwards to inspect the changes and ensure that they are what
it is fully completed. Please prefix the title of your pull request with you expected.
"[WIP]" to indicate this. It's also a good idea to include specific
questions or items you'd like feedback on.
2. Once you believe your pull request is ready to be merged, you can remove any Terraform includes generated Go stub code for the Terraform provider plugin
"[WIP]" prefix from the title and a core team member will review. Follow protocol, which is defined using Protocol Buffers. Because the Protocol Buffers
[the checklists below](#checklists-for-contribution) to help ensure that tools are not written in Go and thus cannot be automatically installed using
your contribution will be merged quickly. `go get`, we follow a different process for generating these, which requires
that you've already installed a suitable version of `protoc`:
3. One of Terraform's core team members will look over your contribution and ```
either provide comments letting you know if there is anything left to do. We make protobuf
do our best to provide feedback in a timely manner, but it may take some ```
time for us to respond.
4. Once all outstanding comments and checklist items have been addressed, your ## External Dependencies
contribution will be merged! Merged PRs will be included in the next
Terraform release. The core team takes care of updating the CHANGELOG as
they merge.
5. In rare cases, we might decide that a PR should be closed. We'll make sure Terraform uses Go Modules for dependency management, but currently uses
to provide clear reasoning when this happens. "vendoring" to include copies of all of the external library dependencies
in the Terraform repository to allow builds to complete even if third-party
dependency sources are unavailable.
### Checklists for Contribution Our dependency licensing policy for Terraform excludes proprietary licenses
and "copyleft"-style licenses. We accept the common Mozilla Public License v2,
MIT License, and BSD licenses. We will consider other open source licenses
in similar spirit to those three, but if you plan to include such a dependency
in a contribution we'd recommend opening a GitHub issue first to discuss what
you intend to implement and what dependencies it will require so that the
Terraform team can review the relevant licenses to for whether they meet our
licensing needs.
There are several different kinds of contribution, each of which has its own If you need to add a new dependency to Terraform or update the selected version
standards for a speedy review. The following sections describe guidelines for for an existing one, use `go get` from the root of the Terraform repository
each type of contribution. as follows:
#### Documentation Update ```
go get github.com/hashicorp/hcl/v2@2.0.0
```
Because [Terraform's website][website] is in the same repo as the code, it's This command will download the requested version (2.0.0 in the above example)
easy for anybody to help us improve our docs. and record that version selection in the `go.mod` file. It will also record
checksums for the module in the `go.sum`.
- [ ] __Reasoning for docs update__: Including a quick explanation for why the To complete the dependency change, clean up any redundancy in the module
update needed is helpful for reviewers. metadata files and resynchronize the `vendor` directory with the new package
- [ ] __Relevant Terraform version__: Is this update worth deploying to the selections by running the following commands:
site immediately, or is it referencing an upcoming version of Terraform and
should get pushed out with the next release?
#### New Provider ```
go mod tidy
go mod vendor
```
Implementing a new provider gives Terraform the ability to manage resources in To ensure that the vendoring has worked correctly, be sure to run the unit
a whole new API. It's a larger undertaking, but brings major new functionality test suite at least once in _vendoring_ mode, where Go will use the vendored
into Terraform. dependencies to build the test programs:
Terraform Providers are external plugins, not in the Terraform codebase. Please ```
see the [Provider Development Program](https://www.terraform.io/guides/terraform-provider-development-program.html) documentation if you are interested in go test -mod=vendor ./...
submitting a new provider. ```
#### Core Bugfix/Enhancement Because dependency changes affect a shared, top-level file, they are more likely
than some other change types to become conflicted with other proposed changes
during the code review process. For that reason, and to make dependency changes
more visible in the change history, we prefer to record dependency changes as
separate commits that include only the results of the above commands and the
minimal set of changes to Terraform's own code for compatibility with the
new version:
We are always happy when any developer is interested in diving into Terraform's ```
core to help out! Here's what we look for in smaller Core PRs. git add go.mod go.sum vendor
git commit -m "vendor: go get github.com/hashicorp/hcl/v2@2.0.0"
```
- [ ] __Unit tests__: Terraform's core is covered by hundreds of unit tests at You can then make use of the new or updated dependency in new code added in
several different layers of abstraction. Generally the best place to start subsequent commits.
is with a "Context Test". These are higher level test that interact
end-to-end with most of Terraform's core. They are divided into test files
for each major action (plan, apply, etc.). Getting a failing test is a great
way to prove out a bug report or a new enhancement. With a context test in
place, you can work on implementation and lower level unit tests. Lower
level tests are largely context dependent, but the Context Tests are almost
always part of core work.
- [ ] __Documentation updates__: If the core change involves anything that
needs to be reflected in our documentation, you can make those changes in
the same PR. The [Terraform website][website] source is in this repo and
includes instructions for getting a local copy of the site up and running if
you'd like to preview your changes.
- [ ] __Well-formed Code__: Do your best to follow existing conventions you
see in the codebase, and ensure your code is formatted with `go fmt`. (The
Travis CI build will fail if `go fmt` has not been run on incoming code.)
The PR reviewers can help out on this front, and may provide comments with
suggestions on how to improve the code.
#### Core Feature ## Proposing a Change
If you're interested in taking on a larger core feature, it's a good idea to If you'd like to contribute a code change to Terraform, we'd love to review
get feedback early and often on the effort. a GitHub pull request.
- [ ] __Early validation of idea and implementation plan__: Terraform's core In order to be respectful of the time of community contributors, we prefer to
is complicated enough that there are often several ways to implement discuss potential changes in GitHub issues prior to implementation. That will
something, each of which has different implications and tradeoffs. Working allow us to give design feedback up front and set expectations about the scope
through a plan of attack with the team before you dive into implementation of the change, and, for larger changes, how best to approach the work such that
will help ensure that you're working in the right direction. Opening a GitHub the Terraform team can review it and merge it along with other concurrent work.
issue, or commenting on an existing issue, is a great way to get these
conversations started.
- [ ] __Unit tests__: Terraform's core is covered by hundreds of unit tests at
several different layers of abstraction. Generally the best place to start
is with a "Context Test". These are higher level test that interact
end-to-end with most of Terraform's core. They are divided into test files
for each major action (plan, apply, etc.). Getting a failing test is a great
way to prove out a bug report or a new enhancement. With a context test in
place, you can work on implementation and lower level unit tests. Lower
level tests are largely context dependent, but the Context Tests are almost
always part of core work.
- [ ] __Documentation updates__: If the core change involves anything that
needs to be reflected in our documentation, you can make those changes in
the same PR. The [Terraform website][website] source is in this repo and
includes instructions for getting a local copy of the site up and running if
you'd like to preview your changes.
- [ ] __Well-formed Code__: Do your best to follow existing conventions you
see in the codebase, and ensure your code is formatted with `go fmt`. (The
Travis CI build will fail if `go fmt` has not been run on incoming code.)
The PR reviewers can help out on this front, and may provide comments with
suggestions on how to improve the code.
### Writing Acceptance Tests If the bug you wish to fix or enhancement you wish to implement isn't already
covered by a GitHub issue that contains feedback from the Terraform team,
please do start a discussion (either in
[a new GitHub issue](https://github.com/hashicorp/terraform/issues/new/choose)
or an existing one, as appropriate) before you invest significant development
time. If you mention your intent to implement the change described in your
issue, the Terraform team can prioritize including implementation-related
feedback in the subsequent discussion.
#### Acceptance Tests Often Cost Money to Run At this time, we do not have a formal process for reviewing outside proposals
that significantly change Terraform's workflow, its primary usage patterns,
and its language. While we do hope to put such a thing in place in the future,
we wish to be up front with potential contributors that unfortunately we are
unlikely to be able to give prompt feedback for large proposals that could
entail a significant design phase, though we are still interested to hear about
your use-cases so that we can consider ways to meet them as part of other
larger projects.
Because acceptance tests create real resources, they often cost money to run. Most changes will involve updates to the test suite, and changes to Terraform's
Because the resources only exist for a short period of time, the total amount documentation. The Terraform team can advise on different testing strategies
of money required is usually a relatively small. Nevertheless, we don't want for specific scenarios, and may ask you to revise the specific phrasing of
financial limitations to be a barrier to contribution, so if you are unable to your proposed documentation prose to match better with the standard "voice" of
pay to run acceptance tests for your contribution, simply mention this in your Terraform's documentation.
pull request. We will happily accept "best effort" implementations of
acceptance tests and run them for you on our side. This might mean that your PR
takes a bit longer to merge, but it most definitely is not a blocker for
contributions.
#### Running an Acceptance Test This repository is primarily maintained by a small team at HashiCorp along with
their other responsibilities, so unfortunately we cannot always respond
Acceptance tests can be run using the `testacc` target in the Terraform promptly to pull requests, particularly if they do not relate to an existing
`Makefile`. The individual tests to run can be controlled using a regular GitHub issue where the Terraform team has already participated. We _are_
expression. Prior to running the tests provider configuration details such as grateful for all contributions however, and will give feedback on pull requests
access keys must be made available as environment variables. as soon as we're able.
[website]: https://github.com/hashicorp/terraform/tree/master/website
[acctests]: https://github.com/hashicorp/terraform#acceptance-tests
[community forum]: https://discuss.hashicorp.com/c/terraform-core
[ml]: https://groups.google.com/group/terraform-tool

5
.github/SUPPORT.md vendored
View File

@ -1,5 +1,4 @@
# Support # Support
Terraform is a mature project with a growing community. There are active, dedicated people willing to help you through various mediums. If you have questions about Terraform usage, please feel free to create a topic
on [the official community forum](https://discuss.hashicorp.com/c/terraform-core).
Take a look at those mediums listed at https://www.terraform.io/community.html

58
BUILDING.md
View File

@ -1,43 +1,65 @@
# Building Terraform # Building Terraform
This document contains details about the process for building binaries for This document contains details about the process for building release-style
Terraform. binaries for Terraform.
(If you are intending instead to make changes to Terraform and build binaries
only for your local testing, see
[the contributing guide](.github/CONTRIBUTING.md).)
## Versioning ## Versioning
As a pre-1.0 project, we use the MINOR and PATCH versions as follows: Until Terraform v1.0, Terraform's versioning scheme is as follows:
* a `MINOR` version increment indicates a release that may contain backwards * Full version strings start with a zero in the initial position.
incompatible changes * The second position increments for _major_ releases, which may contain
* a `PATCH` version increment indicates a release that may contain bugfixes as backwards incompatible changes.
well as additive (backwards compatible) features and enhancements * The third and final position increments for _minor_ releases, which
we aim to keep backwards compatible with prior releases for the same major
version.
Although the Terraform team takes care to preserve compatibility between
major releases as much as possible, major release upgrades will often require
specific upgrade actions for a subset of users as we refine the product
design in preparation for making more specific backward-compatibility promises
in a later Terraform 1.0 release.
## Process ## Process
If only need to build binaries for the platform you're running (Windows, Linux, Terraform release binaries are built via cross-compilation on a Linux
Mac OS X etc..), you can follow the instructions in the README for [Developing system, using [gox](https://github.com/mitchellh/gox).
Terraform][1].
The guide below outlines the steps HashiCorp takes to build the official release The steps below are a subset of the steps HashiCorp uses to prepare the
binaries for Terraform. This process will generate a set of binaries for each supported official distribution packages available from
platform, using the [gox](https://github.com/mitchellh/gox) tool. [the download page](https://www.terraform.io/downloads.html). This
process will generate an executable for each of the supported target platforms.
HashiCorp prepares release binaries on Linux amd64 systems. This build process
may need to be adjusted for other host platforms.
```sh ```sh
# clone the repository if needed # clone the repository if needed
git clone https://github.com/hashicorp/terraform.git git clone https://github.com/hashicorp/terraform.git
cd terraform cd terraform
# Verify unit tests pass # Verify that the unit tests are passing
make test make test
# Build the release # Run preparation steps and then build the executable for each target platform
# in the subdirectory "pkg".
# This generates binaries for each platform and places them in the pkg folder # This generates binaries for each platform and places them in the pkg folder
make bin make bin
``` ```
After running these commands, you should have binaries for all supported Official releases are subsequently then packaged, hashed, and signed before
platforms in the `pkg` folder. uploading to [the HashiCorp releases service](https://releases.hashicorp.com/terraform/).
Those final packaging steps are not fully reproducible using the contents
of this repository due to the use of HashiCorp's private signing key. However,
you can place the generated executables in `.zip` archives to produce a
similar result without the checksums and digital signature.
## Release Bundles for use in Terraform Enterprise
[1]: https://github.com/hashicorp/terraform#developing-terraform If you wish to build distribution archives that blend official Terraform
release executables with a mixture of official and third-party provider builds,
see [the `terraform-bundle` tool](tools/terraform-bundle).

127
README.md
View File

@ -34,134 +34,9 @@ All documentation is available on the [Terraform website](http://www.terraform.i
Developing Terraform Developing Terraform
-------------------- --------------------
If you wish to work on Terraform itself or any of its built-in providers, you'll first need [Go](http://www.golang.org) installed on your machine (version 1.11+ is *required*).
This repository contains only Terraform core, which includes the command line interface and the main graph engine. Providers are implemented as plugins that each have their own repository in [the `terraform-providers` organization](https://github.com/terraform-providers) on GitHub. Instructions for developing each provider are in the associated README file. For more information, see [the provider development overview](https://www.terraform.io/docs/plugins/provider.html). This repository contains only Terraform core, which includes the command line interface and the main graph engine. Providers are implemented as plugins that each have their own repository in [the `terraform-providers` organization](https://github.com/terraform-providers) on GitHub. Instructions for developing each provider are in the associated README file. For more information, see [the provider development overview](https://www.terraform.io/docs/plugins/provider.html).
For local development of Terraform core, first make sure Go is properly installed and that a To learn more about compiling Terraform and contributing suggested changes, please refer to [the contributing guide](.github/CONTRIBUTING.md).
[GOPATH](http://golang.org/doc/code.html#GOPATH) has been set. You will also need to add `$GOPATH/bin` to your `$PATH`.
Next, using [Git](https://git-scm.com/), clone this repository into `$GOPATH/src/github.com/hashicorp/terraform`.
You'll need to run `make tools` to install some required tools, then `make`. This will compile the code and then run the tests. If this exits with exit status 0, then everything is working!
You only need to run `make tools` once (or when the tools change).
```sh
$ cd "$GOPATH/src/github.com/hashicorp/terraform"
$ make tools
$ make
```
To compile a development version of Terraform and the built-in plugins, run `make dev`. This will build everything using [gox](https://github.com/mitchellh/gox) and put Terraform binaries in the `bin` and `$GOPATH/bin` folders:
```sh
$ make dev
...
$ bin/terraform
...
```
If you're developing a specific package, you can run tests for just that package by specifying the `TEST` variable. For example below, only `terraform` package tests will be run.
```sh
$ make test TEST=./terraform
...
```
If you're working on a specific provider which has not been separated into an individual repository and only wish to rebuild that provider, you can use the `plugin-dev` target. For example, to build only the Test provider:
```sh
$ make plugin-dev PLUGIN=provider-test
```
### Dependencies
Terraform uses Go Modules for dependency management, but for the moment is
continuing to use Go 1.6-style vendoring for compatibility with tools that
have not yet been updated for full Go Modules support.
If you're developing Terraform, there are a few tasks you might need to perform.
#### Adding a dependency
If you're adding a dependency, you'll need to vendor it in the same Pull Request as the code that depends on it. You should do this in a separate commit from your code, as makes PR review easier and Git history simpler to read in the future.
To add a dependency:
Assuming your work is on a branch called `my-feature-branch`, the steps look like this:
1. Add an `import` statement to a suitable package in the Terraform code.
2. Run `go mod vendor` to download the latest version of the module containing
the imported package into the `vendor/` directory, and update the `go.mod`
and `go.sum` files.
3. Review the changes in git and commit them.
#### Updating a dependency
To update a dependency:
1. Run `go get -u module-path@version-number`, such as `go get -u github.com/hashicorp/hcl@2.0.0`
2. Run `go mod vendor` to update the vendored copy in the `vendor/` directory.
3. Review the changes in git and commit them.
### Acceptance Tests
Terraform has a comprehensive [acceptance
test](http://en.wikipedia.org/wiki/Acceptance_testing) suite covering the
built-in providers.
### Cross Compilation and Building for Distribution
If you wish to cross-compile Terraform for another architecture, you can set the `XC_OS` and `XC_ARCH` environment variables to values representing the target operating system and architecture before calling `make`. The output is placed in the `pkg` subdirectory tree both expanded in a directory representing the OS/architecture combination and as a ZIP archive.
For example, to compile 64-bit Linux binaries on Mac OS X, you can run:
```sh
$ XC_OS=linux XC_ARCH=amd64 make bin
...
$ file pkg/linux_amd64/terraform
terraform: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked, not stripped
```
`XC_OS` and `XC_ARCH` can be space separated lists representing different combinations of operating system and architecture. For example, to compile for both Linux and Mac OS X, targeting both 32- and 64-bit architectures, you can run:
```sh
$ XC_OS="linux darwin" XC_ARCH="386 amd64" make bin
...
$ tree ./pkg/ -P "terraform|*.zip"
./pkg/
├── darwin_386
│   └── terraform
├── darwin_386.zip
├── darwin_amd64
│   └── terraform
├── darwin_amd64.zip
├── linux_386
│   └── terraform
├── linux_386.zip
├── linux_amd64
│   └── terraform
└── linux_amd64.zip
4 directories, 8 files
```
_Note: Cross-compilation uses [gox](https://github.com/mitchellh/gox), which requires toolchains to be built with versions of Go prior to 1.5. In order to successfully cross-compile with older versions of Go, you will need to run `gox -build-toolchain` before running the commands detailed above._
#### Docker
When using docker you don't need to have any of the Go development tools installed and you can clone terraform to any location on disk (doesn't have to be in your $GOPATH). This is useful for users who want to build `master` or a specific branch for testing without setting up a proper Go environment.
For example, run the following command to install the required tools and build terraform in a linux-based container for macOS.
```sh
docker run --rm -v $(pwd):/go/src/github.com/hashicorp/terraform -w /go/src/github.com/hashicorp/terraform -e XC_OS=darwin -e XC_ARCH=amd64 golang:latest bash -c "apt-get update && apt-get install -y zip && make tools bin"
```
## License ## License
[Mozilla Public License v2.0](https://github.com/hashicorp/terraform/blob/master/LICENSE) [Mozilla Public License v2.0](https://github.com/hashicorp/terraform/blob/master/LICENSE)