README.md
1# Go App Engine packages
2
3[](https://travis-ci.org/golang/appengine)
4
5This repository supports the Go runtime on App Engine,
6including both classic App Engine and Managed VMs.
7It provides APIs for interacting with App Engine services.
8Its canonical import path is `google.golang.org/appengine`.
9
10See https://cloud.google.com/appengine/docs/go/
11for more information.
12
13File issue reports and feature requests on the [Google App Engine issue
14tracker](https://code.google.com/p/googleappengine/issues/entry?template=Go%20defect).
15
16## Directory structure
17The top level directory of this repository is the `appengine` package. It
18contains the
19basic APIs (e.g. `appengine.NewContext`) that apply across APIs. Specific API
20packages are in subdirectories (e.g. `datastore`).
21
22There is an `internal` subdirectory that contains service protocol buffers,
23plus packages required for connectivity to make API calls. App Engine apps
24should not directly import any package under `internal`.
25
26## Updating a Go App Engine app
27
28This section describes how to update a traditional Go App Engine app to use
29these packages.
30
31### 1. Update YAML files (Managed VMs only)
32
33The `app.yaml` file (and YAML files for modules) should have these new lines added:
34```
35vm: true
36```
37See https://cloud.google.com/appengine/docs/go/modules/#Go_Instance_scaling_and_class for details.
38
39### 2. Update import paths
40
41The import paths for App Engine packages are now fully qualified, based at `google.golang.org/appengine`.
42You will need to update your code to use import paths starting with that; for instance,
43code importing `appengine/datastore` will now need to import `google.golang.org/appengine/datastore`.
44You can do that manually, or by running this command to recursively update all Go source files in the current directory:
45(may require GNU sed)
46```
47sed -i '/"appengine/{s,"appengine,"google.golang.org/appengine,;s,appengine_,appengine/,}' \
48 $(find . -name '*.go')
49```
50
51### 3. Update code using deprecated, removed or modified APIs
52
53Most App Engine services are available with exactly the same API.
54A few APIs were cleaned up, and some are not available yet.
55This list summarises the differences:
56
57* `appengine.Context` has been replaced with the `Context` type from `golang.org/x/net/context`.
58* Logging methods that were on `appengine.Context` are now functions in `google.golang.org/appengine/log`.
59* `appengine.Timeout` has been removed. Use `context.WithTimeout` instead.
60* `appengine.Datacenter` now takes a `context.Context` argument.
61* `datastore.PropertyLoadSaver` has been simplified to use slices in place of channels.
62* `delay.Call` now returns an error.
63* `search.FieldLoadSaver` now handles document metadata.
64* `urlfetch.Transport` no longer has a Deadline field; set a deadline on the
65 `context.Context` instead.
66* `aetest` no longer declares its own Context type, and uses the standard one instead.
67* `taskqueue.QueueStats` no longer takes a maxTasks argument. That argument has been
68 deprecated and unused for a long time.
69* `appengine.BackendHostname` and `appengine.BackendInstance` were for the deprecated backends feature.
70 Use `appengine.ModuleHostname`and `appengine.ModuleName` instead.
71* Most of `appengine/file` and parts of `appengine/blobstore` are deprecated.
72 Use [Google Cloud Storage](https://godoc.org/google.golang.org/cloud/storage) instead.
73* `appengine/socket` is not required on Managed VMs. Use the standard `net` package instead.
74
){kind=link}