Need help with amazonka?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

brendanhay
501 Stars 193 Forks Other 7.3K Commits 62 Opened issues

Description

A comprehensive Amazon Web Services SDK for Haskell.

Services available

!
?

Need anything else?

Contributors list

Amazonka

MPL2 Hackage Build Gen Docs

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.

License

Amazonka is licensed 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.

Directory Layout

This repository is organised into the following directory structure:

  • lib/amazonka
    : The main library containing setup, authentication, and send logic. This will be your primary dependency.
  • lib/service/amazonka-*
    : A library per supported Amazon Web Service, you'll need to add a dependency on each selected service library.
  • lib/amazonka-core
    : The
    amazonka-core
    library upon which each of the services depends.
  • lib/amazonka-test
    : Common test functionality.
  • examples
    : Basic examples for using the service libraries.
  • configs
    : Service configuration, templates, and assets used by the code generator.
  • docs
    : The website documentation and related build code.
  • gen
    : The code and configuration generators.
  • nix
    : Nix configuration code for toolchain packages.
  • scripts
    : Scripts to manage the project, such as the release lifecycle.
  • tools
    : Custom bazel rules.
  • third_party
    : Third party packages and patches.

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.

Getting Started

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!

1. Clone this repository

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

2. Setup Nix

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:

sh 

Once Nix is setup, you can enable the cache to avoid building dependencies:

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

3. Enter a Nix Shell

The build tools are installed and activated upon entering a Nix shell, which is achieved by running the following command in the root of the repository:

nix-shell

You can also enter a shell and explicitly specify the GHC version:

nix-shell --argstr ghcVersion 884

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.

Building the Project

The following commands assume you're already in a nix-shell outlined in the previous step.

Cabal

If you're familiar with Cabal, you can build

amazonka-*
packages via:
cabal build amazonka amazonka-s3

Or the entire project (which will take a very long time!):

cabal build all

Bazel

Alternatively, if you plan on contributing to the project or want to perform code generation, you will need to familiarise yourself with Bazel. You can build packages by specifying one or more targets using Bazel's label syntax:

bazel build //lib/amazonka //lib/services/amazonka-s3

Or build all Haskell libraries in the project using the

...
wildcard:
bazel build //lib/...

To view what targets are available in the workspace:

bazel query //...

By default, the

bazel
command will use the same GHC version as the Nix shell's
ghcVersion
argument. You can choose a different GHC version using
nix-shell --argstr ghcVersion 884
- which is just a synonym for
bazel build --//tools/ghc:version=884
.

Building the Documentation

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:bundle

Alternatively, you can serve the documentation site locally on

http://localhost:1313
by running:
bazel run //docs:serve

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

To update the botocore service definitions used by the generator, you can run:

./scripts/update-botocore

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/.json:libraryName
(Haskell package name) and
configs/annexes/.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.

Code Formatting

Please use

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

Third Party Packages

When naming an additional library which provides supplemental functionality to

amazonka
, if you want to use the
amazonka-*
namespace, then please consider prefixing your package names with
amazonka-contrib-*
. For example, amazonka-contrib-rds-utils.

This minimises potential future collisions with auto-generated package names and new AWS service and product releases.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.