# The Go Runtime

## Overview

Your Cloud Run function runs in an environment consisting of an operating
system version plus add-on packages, language support, and
the Functions Framework library that supports and invokes your function.
This environment is identified by the language version, and is known as the
runtime.

For information about runtimes in general, and to learn which Ubuntu version
each Go runtime uses, see the
[Cloud Run functions execution environment](https://docs.cloud.google.com/functions/1stgendocs/concepts/execution-environment.md.txt#go).

## Select your runtime

Cloud Run functions supports several versions of Go, listed on the
[Runtime support](https://docs.cloud.google.com/functions/1stgendocs/runtime-support.md.txt#go) page. You can
select the preferred Go runtime for your function during deployment.

If you're using the Google Cloud CLI, specify the runtime
by using the `--runtime` parameter with the Go runtime of your choice.
For example:

```bash
gcloud functions deploy FUNCTION_NAME --no-gen2 --runtime go121 FLAGS...
```

`FLAGS...` refers to arguments passed during the first
deployment of your function. For more information regarding required and
optional arguments, see
[Deploy a Cloud Run function](https://docs.cloud.google.com/functions/1stgendocs/deploy.md.txt#basics).

## Function preparation

You can write a function on your local machine and upload it.
To prepare your local machine for Go development,
see [Setting Up a Go Development Environment](https://docs.cloud.google.com/go/docs/setup.md.txt).

To get started quickly with Go on Cloud Run functions, see the
[Quickstart](https://docs.cloud.google.com/functions/1stgendocs/create-deploy-gcloud-1st-gen).

## Source code structure

For Cloud Run functions to find your function's definition, your
source code must follow a specific structure. See
[Writing Cloud Run functions](https://docs.cloud.google.com/functions/1stgendocs/writing.md.txt#structuring_source_code)
for more information.

## Specifying dependencies

Cloud Run functions in Go must provide all of their dependencies either with
Go modules and a `go.mod` file, or with a `vendor` directory. For more information,
see [Specifying dependencies in Go](https://docs.cloud.google.com/functions/1stgendocs/writing/specifying-dependencies-go.md.txt).

## Environment variables

Your Go runtime automatically sets certain environment variables for your function
to use as needed. For details, see
[Using Environment Variables](https://docs.cloud.google.com/functions/1stgendocs/configuring/env-var.md.txt#newer_runtimes).

## `Context` type

[Go's `context` package](https://golang.org/pkg/context/) defines the `Context`
type, which carries deadlines, cancellation signals, and other request-scoped
values across API boundaries and between processes.

The following Cloud Run functions code shows an example of context access by a
Pub/Sub client:

```go

// Package helloworld provides a set of Cloud Functions samples.
package helloworld

import (
	"context"
	"fmt"
	"log"

	"github.com/GoogleCloudPlatform/functions-framework-go/functions"
	"github.com/cloudevents/sdk-go/v2/event"
)

func init() {
	functions.CloudEvent("HelloPubSub", helloPubSub)
}

// MessagePublishedData contains the full Pub/Sub message
// See the documentation for more details:
// https://cloud.google.com/eventarc/docs/cloudevents#pubsub
type MessagePublishedData struct {
	Message PubSubMessage
}

// PubSubMessage is the payload of a Pub/Sub event.
// See the documentation for more details:
// https://cloud.google.com/pubsub/docs/reference/rest/v1/PubsubMessage
type PubSubMessage struct {
	Data []byte `json:"data"`
}

// helloPubSub consumes a CloudEvent message and extracts the Pub/Sub message.
func helloPubSub(ctx context.Context, e event.Event) error {
	var msg MessagePublishedData
	if err := e.DataAs(&msg); err != nil {
		return fmt.Errorf("event.DataAs: %w", err)
	}

	name := string(msg.Message.Data) // Automatically decoded from base64.
	if name == "" {
		name = "World"
	}
	log.Printf("Hello, %s!", name)
	return nil
}
```