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