-
Notifications
You must be signed in to change notification settings - Fork 2.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update README to clarify getting SDK with go modules (#2280)
Updates the SDK's README.md to clarify the instructions for getting the SDK. This also avoids the potential issues getting the SDK with Go modules and retrieving a non-working version of SDK dependencies. Related to golang/go#28396
- Loading branch information
Showing
1 changed file
with
69 additions
and
20 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -4,32 +4,56 @@ | |
|
|
||
| aws-sdk-go is the official AWS SDK for the Go programming language. | ||
|
|
||
| Checkout our [release notes](https://github.com/aws/aws-sdk-go/releases) for information about the latest bug fixes, updates, and features added to the SDK. | ||
| Checkout our [release notes](https://github.com/aws/aws-sdk-go/releases) for | ||
| information about the latest bug fixes, updates, and features added to the SDK. | ||
|
|
||
| We [announced](https://aws.amazon.com/blogs/developer/aws-sdk-for-go-2-0-developer-preview/) the Developer Preview for the [v2 AWS SDK for Go](https://github.com/aws/aws-sdk-go-v2). The v2 SDK is available at https://github.com/aws/aws-sdk-go-v2, and `go get github.com/aws/aws-sdk-go-v2` via `go get`. Check out the v2 SDK's [changes and updates](https://github.com/aws/aws-sdk-go-v2/blob/master/CHANGELOG.md), and let us know what you think. We want your feedback. | ||
| We [announced](https://aws.amazon.com/blogs/developer/aws-sdk-for-go-2-0-developer-preview/) the Developer Preview for the [v2 AWS SDK for Go](https://github.com/aws/aws-sdk-go-v2). The v2 SDK source is available at https://github.com/aws/aws-sdk-go-v2, and add it to your project with `go get github.com/aws/aws-sdk-go-v2`. Check out the v2 SDK's [changes and updates](https://github.com/aws/aws-sdk-go-v2/blob/master/CHANGELOG.md), and let us know what you think. We want your feedback. | ||
|
|
||
| ## Installing | ||
|
|
||
| If you are using Go 1.5 with the `GO15VENDOREXPERIMENT=1` vendoring flag, or 1.6 and higher you can use the following command to retrieve the SDK. The SDK's non-testing dependencies will be included and are vendored in the `vendor` folder. | ||
| Use `go get` to retrieve the SDK to add it to your `GOPATH` workspace, or | ||
| project's Go module dependencies. | ||
|
|
||
| go get -u github.com/aws/aws-sdk-go | ||
| go get github.com/aws/aws-sdk-go | ||
|
|
||
| Otherwise if your Go environment does not have vendoring support enabled, or you do not want to include the vendored SDK's dependencies you can use the following command to retrieve the SDK and its non-testing dependencies using `go get`. | ||
| To update the SDK use `go get -u` to retrieve the latest version of the SDK. | ||
|
|
||
| go get -u github.com/aws/aws-sdk-go/aws/... | ||
| go get -u github.com/aws/aws-sdk-go/service/... | ||
| go get -u github.com/aws/aws-sdk-go | ||
|
|
||
| If you're looking to retrieve just the SDK without any dependencies use the following command. | ||
| ### Dependencies | ||
|
|
||
| go get -d github.com/aws/aws-sdk-go/ | ||
| The SDK includes a `vendor` folder containing the runtime dependencies of the | ||
| SDK. The metadata of the SDK's dependencies can be found in the Go module file | ||
| `go.mod` or Dep file `Gopkg.toml`. | ||
|
|
||
| These two processes will still include the `vendor` folder and it should be deleted if its not going to be used by your environment. | ||
| ### Go Modules | ||
|
|
||
| If you are using Go modules, your `go get` will default to the latest tagged | ||
| release version of the SDK. To get a specific release version of the SDK use | ||
| `@<tag>` in your `go get` command. | ||
|
|
||
| go get github.com/aws/[email protected] | ||
|
|
||
| To get the latest SDK repository change use `@latest`. | ||
|
|
||
| go get github.com/aws/aws-sdk-go@latest | ||
|
|
||
| ### Go 1.5 | ||
|
|
||
| If you are using Go 1.5 without vendoring enabled, (`GO15VENDOREXPERIMENT=1`), | ||
| you will need to use `...` when retrieving the SDK to get its dependencies. | ||
|
|
||
| go get github.com/aws/aws-sdk-go/... | ||
|
|
||
| This will still include the `vendor` folder. The `vendor` folder can be deleted | ||
| if not used by your environment. | ||
|
|
||
| rm -rf $GOPATH/src/github.com/aws/aws-sdk-go/vendor | ||
|
|
||
| ## Getting Help | ||
|
|
||
| Please use these community resources for getting help. We use the GitHub issues for tracking bugs and feature requests. | ||
| Please use these community resources for getting help. We use the GitHub issues | ||
| for tracking bugs and feature requests. | ||
|
|
||
| * Ask a question on [StackOverflow](http://stackoverflow.com/) and tag it with the [`aws-sdk-go`](http://stackoverflow.com/questions/tagged/aws-sdk-go) tag. | ||
| * Come join the AWS SDK for Go community chat on [gitter](https://gitter.im/aws/aws-sdk-go). | ||
|
|
@@ -38,19 +62,44 @@ Please use these community resources for getting help. We use the GitHub issues | |
|
|
||
| ## Opening Issues | ||
|
|
||
| If you encounter a bug with the AWS SDK for Go we would like to hear about it. Search the [existing issues](https://github.com/aws/aws-sdk-go/issues) and see if others are also experiencing the issue before opening a new issue. Please include the version of AWS SDK for Go, Go language, and OS you’re using. Please also include repro case when appropriate. | ||
| If you encounter a bug with the AWS SDK for Go we would like to hear about it. | ||
| Search the [existing issues](https://github.com/aws/aws-sdk-go/issues) and see | ||
| if others are also experiencing the issue before opening a new issue. Please | ||
| include the version of AWS SDK for Go, Go language, and OS you’re using. Please | ||
| also include reproduction case when appropriate. | ||
|
|
||
| The GitHub issues are intended for bug reports and feature requests. For help and questions with using AWS SDK for GO please make use of the resources listed in the [Getting Help](https://github.com/aws/aws-sdk-go#getting-help) section. Keeping the list of open issues lean will help us respond in a timely manner. | ||
| The GitHub issues are intended for bug reports and feature requests. For help | ||
| and questions with using AWS SDK for GO please make use of the resources listed | ||
| in the [Getting Help](https://github.com/aws/aws-sdk-go#getting-help) section. | ||
| Keeping the list of open issues lean will help us respond in a timely manner. | ||
|
|
||
| ## Reference Documentation | ||
|
|
||
| [`Getting Started Guide`](https://aws.amazon.com/sdk-for-go/) - This document is a general introduction how to configure and make requests with the SDK. If this is your first time using the SDK, this documentation and the API documentation will help you get started. This document focuses on the syntax and behavior of the SDK. The [Service Developer Guide](https://aws.amazon.com/documentation/) will help you get started using specific AWS services. | ||
|
|
||
| [`SDK API Reference Documentation`](https://docs.aws.amazon.com/sdk-for-go/api/) - Use this document to look up all API operation input and output parameters for AWS services supported by the SDK. The API reference also includes documentation of the SDK, and examples how to using the SDK, service client API operations, and API operation require parameters. | ||
|
|
||
| [`Service Developer Guide`](https://aws.amazon.com/documentation/) - Use this documentation to learn how to interface with an AWS service. These are great guides both, if you're getting started with a service, or looking for more information on a service. You should not need this document for coding, though in some cases, services may supply helpful samples that you might want to look out for. | ||
|
|
||
| [`SDK Examples`](https://github.com/aws/aws-sdk-go/tree/master/example) - Included in the SDK's repo are a several hand crafted examples using the SDK features and AWS services. | ||
| [`Getting Started Guide`](https://aws.amazon.com/sdk-for-go/) - This document | ||
| is a general introduction on how to configure and make requests with the SDK. | ||
| If this is your first time using the SDK, this documentation and the API | ||
| documentation will help you get started. This document focuses on the syntax | ||
| and behavior of the SDK. The [Service Developer | ||
| Guide](https://aws.amazon.com/documentation/) will help you get started using | ||
| specific AWS services. | ||
|
|
||
| [`SDK API Reference | ||
| Documentation`](https://docs.aws.amazon.com/sdk-for-go/api/) - Use this | ||
| document to look up all API operation input and output parameters for AWS | ||
| services supported by the SDK. The API reference also includes documentation of | ||
| the SDK, and examples how to using the SDK, service client API operations, and | ||
| API operation require parameters. | ||
|
|
||
| [`Service Developer Guide`](https://aws.amazon.com/documentation/) - Use this | ||
| documentation to learn how to interface with AWS services. These are great | ||
| guides both, if you're getting started with a service, or looking for more | ||
| information on a service. You should not need this document for coding, though | ||
| in some cases, services may supply helpful samples that you might want to look | ||
| out for. | ||
|
|
||
| [`SDK Examples`](https://github.com/aws/aws-sdk-go/tree/master/example) - | ||
| Included in the SDK's repo are several hand crafted examples using the SDK | ||
| features and AWS services. | ||
|
|
||
| ## Overview of SDK's Packages | ||
|
|
||
|
|
||