docs/development/build/packages.md

### Packages

**Build packages** are defined in JSON files which can be found at:

* Garnet Layer Packages: [`//garnet/packages/`][garnet-packages-source].
* Peridot Layer Packages: [`//peridot/packages/`][peridot-packages-source].
* Topaz Layer Packages: [`//topaz/packages/`][topaz-packages-source].

Build packages are a Fuchsia-specific feature built on top of GN to help
customize Fuchsia builds.

A build package file contains references to other build packages it expands
on (`imports`) and the Fuchsia packages it adds to the build (`packages`):
```json
{
    "imports": [
        "garnet/packages/prod/network",
    ],
    "packages": [
        "//garnet/examples/http/wget"
    ]
}
```

Build packages define an aggregation of one or more build labels, either by
importing other packages, or by referencing build labels. GN [parses the JSON
package definitions][preprocess-build-packages-py] early on in the build
(often referenced from [product definitions][products], and those definitions
determine what else GN has to do.

**Fuchsia packages**, not to be confused with build packages, are artifacts
of the Fuchsia build system, generated by the GN targets listed in `packages`.
A Fuchsia package includes a manifest of its contents, and zero or more
executables and their assets.

For example, the above build packages file adds a Fuchsia package called
"wget" to the build. This package contains the binaries built
from the build target of the same name in `//garnet/examples/http/wget/BUILD.gn`:

```py
package("wget") {
  deps = [
    # The path to the dependency that creates the wget binary.
    ":bin"
  ],
  binaries = [{
    name = "wget"
  }]
}
```

The `binaries` field in the package definition specifies that this package
includes a single binary named `wget`. The `binaries` field does not create
the binary--that's the job of the package's dependencies list, specified in
`deps`:

```py
# Executable defines a c++ binary, the label of the executable target will
# be the same as the name of the produced binary file.
executable("bin") {
  output_name = "wget"

  sources = [
    "wget.cc",
  ]

  deps = [
    # This executable also has its own dependencies.
    "//garnet/public/lib/app/cpp",
    "//sdk/lib/fidl/cpp",
  ]
}
```

The `binaries` field in a `package` target lets GN know to deploy the
binary within Fuchsia when you boot your Fuchsia OS image, allowing you
to run your binary from inside the Fuchsia shell:

```bash
$ wget google.com
--2018-06-13 17:04:44--  http://google.com/
$
```




[garnet-packages-source]: /garnet/packages/
[peridot-packages-source]: /peridot/packages/
[topaz-packages-source]: https://fuchsia.googlesource.com/topaz/+/master/packages/
[preprocess-build-packages-py]: /build/gn/prepreprocess_build_packages.py
[products]: products.md