blob: 5341d759cf4d6903f1aaec5a0549586c96c30524 [file] [log] [blame] [view] [edit]
# Component URLs
A [component URL][glossary.component-url] is a URL that identifies a component.
This section describes the syntax used for displaying URLs to users.
## URL Format
A component URL can, in principle, have any [scheme][rfc-uri-scheme]. Some
common schemes you may encounter are:
- [fuchsia-pkg](#fuchsia-pkg)
- [fuchsia-boot](#fuchsia-boot)
- [http(s)](#http)
### fuchsia-pkg {#fuchsia-pkg}
A `fuchsia-pkg` component URL is a [package URL][doc-package-url] that locates a
component distributed in a [Fuchsia package][doc-package].
It has the same format as [package URL][doc-package-url], with a
[resource path][doc-package-url-resource-path] relative to the package root that
locates a [component manifest][doc-manifests]. This path is usually of the form
`meta/<manifest_name>.cm`.
```none {:.devsite-disable-click-to-copy}
fuchsia-pkg://<repo-hostname>[/<pkg-name>[/<pkg-variant>][?hash=<pkg-hash>][#<path-to-manifest>]]
```
Example:
```none {:.devsite-disable-click-to-copy}
fuchsia-pkg://fuchsia.com/stash#meta/stash_secure.cm
```
### fuchsia-boot {#fuchsia-boot}
A `fuchsia-boot` component URL locates a component in the system boot image.
This scheme is used to identify components that must be resolved during early
boot before a [`fuchsia-pkg`](#fuchsia-pkg) [resolver][doc-resolvers] is
available. It has the following format:
```none {:.devsite-disable-click-to-copy}
fuchsia-boot:///<path-to-manifest-in-bootfs>
```
Example:
```none {:.devsite-disable-click-to-copy}
fuchsia-boot:///#meta/driver_manager.cm
```
### http(s) {#http}
An `http(s)` component URL identifies a web page as a component. Such a
component could be executed as a web page in a web [runner][doc-runners], for
example.
Example:
```none {:.devsite-disable-click-to-copy}
https://en.wikipedia.org/wiki/Hippos
```
## Relative URLs {#relative}
The Component Framework supports a subset of relative URLs (Relative URLs are
defined in [URL RFC 3986][url-rfc-3986]). Specifically, Component Framework
supports relative path URLs (plus a *URL fragment* with the path to the
component manifest) to subpackaged components, and fragment-only URLs.
The path to the component manifest is the only content allowed in a relative
component URL fragment (`#meta/<component>.cm`). If the fragment contains any
other content, or if a relative component includes URL query parameters
(`?key=value`), the component will not resolve.
### Relative path URLs to subpackaged components
A relative path URL is resolved at runtime based on a known "context". For
components resolving a child component by relative URL, the context is a
resolver-supplied value associated with the parent component. The URL `path` is
interpreted as the name of one of the declared
[subpackage][glossary.subpackage]s of the parent component's package.
Relative subpackage path URLs start with a
[relative package URL][doc-relative-package-url] and have the following format:
```none {:.devsite-disable-click-to-copy}
<subpackage-path>#<path-to-manifest>
```
Example:
```none {:.devsite-disable-click-to-copy}
child#meta/default.cm
```
For more information on subpackages and subpackaged components, see
the documentation on [Fuchsia Subpackages][doc-subpackages].
### Relative fragment-only URLs {#relative-fragment-only}
A relative fragment-only URL is resolved at runtime based on the URL of the
parent component's [package][doc-package]. Fragment-only URLs have the following
format:
```none {:.devsite-disable-click-to-copy}
#<path-to-manifest>
```
Example:
```none {:.devsite-disable-click-to-copy}
#meta/child.cm
```
For a `fuchsia-pkg` parent component with the following URL:
```none {:.devsite-disable-click-to-copy}
fuchsia-pkg://fuchsia.com/package#meta/component.cm
```
The relative URL resolves to:
```none {:.devsite-disable-click-to-copy}
fuchsia-pkg://fuchsia.com/package#meta/child.cm
```
[glossary.component-url]: /docs/glossary/README.md#component-url
[glossary.subpackage]: /docs/glossary/README.md#subpackage
[doc-manifests]: /docs/concepts/components/v2/component_manifests.md
[doc-package]: /docs/concepts/packages/package.md
[doc-package-url]: /docs/concepts/packages/package_url.md
[doc-package-url-resource-path]: /docs/concepts/packages/package_url.md#resource-paths
[doc-relative-package-url]: /docs/concepts/packages/package.md#relative-package-urls
[doc-resolvers]: /docs/concepts/components/v2/capabilities/resolver.md
[doc-runners]: /docs/concepts/components/v2/capabilities/runner.md
[doc-subpackages]: /docs/concepts/components/v2/subpackaging.md
[rfc-uri-scheme]: https://tools.ietf.org/html/rfc3986#section-3.1
[url-rfc-3986]: https://datatracker.ietf.org/doc/html/rfc3986#section-4.2