sam build

Builds a serverless application and prepares it for subsequent steps in your workflow, like locally testing the application or deploying it to the AWS Cloud. If you provide a RESOURCE_LOGICAL_ID, then AWS SAM builds only that resource. To build a resource of a nested application or stack, you can provide the application or stack logical ID along with the resource logical ID using the format StackLogicalId/ResourceLogicalId.

The sam build command processes your AWS SAM template file, application code, and any applicable language-specific files and dependencies. The command also copies build artifacts in the format and location expected for subsequent steps in your workflow. You specify dependencies in a manifest file that you include in your application, such as requirements.txt for Python functions, or package.json for Node.js functions.

The format of your application's build artifacts depends on its package type. You specify your AWS Lambda function's package type with the PackageType property. The options are:

For more information about Lambda package types, see Lambda deployment packages in the AWS Lambda Developer Guide.

If a resource includes a Metadata resource attribute with a BuildMethod entry, sam build builds that resource according to the value of the BuildMethod entry. Valid values for BuildMethod are 1) One of the identifiers for a Lambda runtime, or 2) The makefile identifier.

To build layers and custom runtimes, you can also use the Metadata resource attribute with a BuildMethod entry. For information about building layers, see Building layers. For information about building custom runtimes, see Building custom runtimes.

For serverless function resources that have the Image package type, use the Metadata resource attribute to configure Docker image settings that are required to build a container image. For more information about building container images, see Building a container image.

For a complete example that uses this command, including locally testing and deploying to the AWS Cloud, see Tutorial: Deploying a Hello World application. The sam build command is part of Step 2: Build your application.

Usage:

sam build [OPTIONS] [RESOURCE_LOGICAL_ID]

Examples:

To use these commands, update your SAM template to specify the path
to your function's source code in the resource's Code or CodeUri property.

To build on your workstation, run this command in the directory containing your
SAM template. Built artifacts are written to the .aws-sam/build directory.
$ sam build
 
To build inside a Lambda-like Docker container
$ sam build --use-container

To build with environment variables passed to the build container from the command line
$ sam build --use-container --container-env-var Function1.GITHUB_TOKEN=<token1> --container-env-var GLOBAL_ENV_VAR=<global-token>

To build with environment variables passed to the build container from a file
$ sam build --use-container --container-env-var-file <env-file.json>

Build a Node.js 12 application using a container image pulled from DockerHub
$ sam build --use-container --build-image amazon/aws-sam-cli-build-image-nodejs12.x

Build a function resource using the Python 3.8 container image pulled from DockerHub
$ sam build --use-container --build-image Function1=amazon/aws-sam-cli-build-image-python3.8 
  
To build and run your functions locally
$ sam build && sam local invoke
  
To build and package for deployment
$ sam build && sam package --s3-bucket <bucketname>

To build the 'MyFunction' resource
$ sam build MyFunction

To build the 'MyFunction' resource of the 'MyNestedStack' nested stack
$ sam build MyNestedStack/MyFunction

Arguments:

Options:

Examples

Building a resource using a Lambda runtime identifier

Here's an example AWS SAM template showing how to build a resource using a Lambda runtime identifier:

Resources:
  MyLayer:
    Type: AWS::Serverless::LayerVersion
    Properties:
      ContentUri: my_layer
      CompatibleRuntimes:
        - python3.6
    Metadata:
      BuildMethod: python3.6

With this template, the following command will build the MyLayer resource against the Python 3.6 runtime environment:

sam build MyLayer

Building a resource using the makefile identifier

Here's an example AWS SAM showing how to build a resource using the makefile identifier:

Resources:
  MyLayer:
    Type: AWS::Serverless::LayerVersion
    Properties:
      ContentUri: my_layer
      CompatibleRuntimes:
        - python3.8
    Metadata:
      BuildMethod: makefile

This is an example of an associated makefile. The file must be named Makefile, and include a build target with the commands you want to run:

build-MyLayer:
    mkdir -p "$(ARTIFACTS_DIR)/python"
    cp *.py "$(ARTIFACTS_DIR)/python"
    python -m pip install -r requirements.txt -t "$(ARTIFACTS_DIR)/python"

With this template and makefile, the following command will execute the commands for the build-MyLayer target:

sam build MyLayer

Passing environment variables to a build container

Here's an example showing how to pass environment variables to a build container using a file.

First, create a file named env.json with the following contents:

{
  "MyFunction1": {
    "GITHUB_TOKEN": "TOKEN1"
  },
  "MyFunction2": {
    "GITHUB_TOKEN": "TOKEN2"
  }
}

Then, run the following command:

sam build --use-container --container-env-var-file env.json

For more information about container environment variable files, see Container environment variable file.