Amazonka

An Amazon Web Services SDK for Haskell with support for most public services. Parts of the code contained in this repository are auto-generated and automatically kept up to date with Amazon's latest service APIs.

• You can find the latest Haddock documentation for each respective library on the Amazonka website.
• A release changelog can be found in amazonka/CHANGELOG.md.
• For problems, comments, or feedback please create an issue here on GitHub.

• License
• Supported Platforms and GHC Versions
• Contributing
  • Getting Started
  • Running the Generator
  • Code Formatting
  • Directory Layout
  • Third Party Package Naming

Licence

Amazonka is released under the Mozilla Public License Version 2.0.

The AWS service descriptions are licensed under Apache 2.0. Source files derived from the service descriptions contain an additional licensing clause in their header.

Supported Platforms and GHC Versions

GHC versions 8.8.4 and 8.10.7 are officially supported and tested on NixOS, Ubuntu, and macOS. GHC 8.6.5 may also work, but is not tested by our continuous integration pipeline.

Contributing

This repository is built using a combination of Nix and your choice of Bazel or Cabal. If you're just using Amazonka as a git dependency in your Cabal or Stack project, you can skip these steps. But if you plan on contributing to the codebase - welcome, read on!

Getting Started

1. Clone this repository

git clone [email protected]:brendanhay/amazonka.git
cd amazonka

2. Setup the Development Toolchain

Building the code in this repository requires various development dependencies (e.g. Nix, Bazel, GHC.)

The Nix package manager is used to obtain and build the other dependencies in a hermetic environment. You can install Nix by following the official installation instructions.

3. Activate Build Caching

Finally, Nix and Bazel ideally need to use Amazonka's shared build caches to ensure we don't unnecessarily rebuild artefacts that have already been built on continuous integration.

You can install and configure Cachix via:

nix-env -iA cachix -f https://cachix.org/api/v1/install
cachix use amazonka

The Bazel remote cache is automatically configured in the provided .bazelrc.

4. Enter a Development Shell

The build toolchain is activated by entering a Nix shell, which will arrange your search PATH to point to the necessary tooling.

You can enter a nix-shell manually by running the following command in the root of the repository:

nix-shell

Optionally, If you have Direnv and lorri installed you can use the provided .envrc instead, which will also add the scripts directory to your PATH. You can extend this by adding your own uncommitted .envrc.local file. See the Direnv Wiki for various recipes.

After installing Direnv, you'll need to run the following command once:

direnv allow

5. Building

The following commands assume you're already in a nix-shell.

If you're already familiar with (and prefer) Cabal, you can build the amazonka-* packages via:

cabal build amazonka

Alternatively, if you are a contributor or plan on performing code generation you will need to familiarise yourself with Bazel. You can build the entire workspace using a wildcard label:

bazel build //...

To view what targets are available in the workspace:

bazel query //...

See Bazel labels for more information.

Running the Code Generator

The gen Bazel package contains code generators for synthesising Haskell data types, packages, and configuration from the botocore service definitions.

scripts/generate will run the code generator for all services configured in config/services, for example:

./scripts/generate

Or, you can selectively run the generator on one or more services:

./scripts/generate ec2 s3 iam

scripts/generate-configs will run the config generator to produce placeholder config/serivces configurations for the version of botocore pinned in the WORKSPACE.

To generate any missing service configurations:

./scripts/generate-configs

Service configurations generated in this way are intended as examples only and the resulting configs/services/<name>.json:libraryName (Haskell package name) and configs/annexes/<name>.json:serviceAbbreviation (Haskell package namespace) should be manually verified and curated as necessary.

For pull requests which affect generated output please do not include the regenerated amazonka-* packages, only commit updates to the build rules, documentation, generator, and related configuration. This ensures the Continuous Integration process is the single source of truth for the generated code and reduces noise in pull requests, keeping them reviewable and focused on actual generator code/logic changes.

Building the Documentation Site

The docs Bazel package contains the Haddock target and Hugo static site definition and markdown content. To build the site locally, run:

bazel build //docs:site

Alternatively, you can serve the documentation site locally on http://localhost:1313 by running:

bazel build //docs:serve

Code Formatting

Please use ./scripts/format frequently - it's OK, I hate 2 spaces too, we're in this together.

Directory Layout

This repository is organised into the following directory structure:

• amazonka: Actual operational logic, you'll need to import this to send requests etc.
• amazonka-*: Data types for each of the individual Amazon Web Service libraries.
• amazonka-*/test: Tests and fixtures for each respective library.
• examples: The amazonka-examples library containing basic examples.
• test: The amazonka-test library containing common test functionality.
• docs: The documentation website and related build code.
• gen: The code and config generation binaries.
• config: Service configuration, templates, and assets used by the code generator.
• scripts: Convenient scripts to manage the release lifecycle of the service libraries.
• nix: Nix configuration code for the toolchain packages.
• tools: Custom bazel rules.
• third_party: Third party bazel packages and patches.

Third Party Package Naming

It is often desirable to provide supplemental functionality to amazonka as an additional library, for example providing S3 encryption via a package such as amazonka-s3-encryption.

Authors of these packages should carefully consider package naming and preferably do not prefix the package with amazonka-* to avoid potential future collisions with generated package names.