From f1a8516c805a46de1d66f5abf17375529aa1e952 Mon Sep 17 00:00:00 2001
From: Nick Cook <nickcook@google.com>
Date: Mon, 13 May 2019 23:19:16 +0000
Subject: [PATCH] [docs] Document how to run the examples in //examples.
Add information about running the examples using fx commands.
PiperOrigin-RevId: 246914905
Change-Id: I6489354d5941671f6f04682e548d32d0bee28fef
---
docs/run-examples.md | 222 +++++++++++++++++++++++++++++++++++++++++++
1 file changed, 222 insertions(+)
create mode 100644 docs/run-examples.md
diff --git a/docs/run-examples.md b/docs/run-examples.md
new file mode 100644
index 00000000000..8853c7459a8
--- /dev/null
+++ b/docs/run-examples.md
@@ -0,0 +1,222 @@
+
+# Run the examples
+
+While exploring the source code, you may have noticed the `examples` directory.
+This guide will show you how to build Fuchsia to include these examples and then
+run them on the device.
+
+## Explore the GN file
+
+Go ahead and open the `BUILD.gn` file in the `examples` directory.
+
+If you aren't familiar with GN, take a look at the
+[introductory presentation](https://docs.google.com/presentation/d/15Zwb53JcncHfEwHpnG_PoIbbzQ3GQi_cpujYwbpcbZo/view#slide=id.g119d702868_0_12)
+or [docs](https://gn.googlesource.com/gn/+/master/docs/). In short, GN is a meta
+build system. Its output files serve as inputs to
+[Ninja](https://ninja-build.org/), the actual build system.
+
+In this file, you can see that the examples are designated as a named group.
+This group names three targets as dependencies:
+
+```gn
+group("examples") {
+ testonly = true
+ deps = [
+ "cowsay",
+ "fortune",
+ "hello_world",
+ ]
+}
+```
+
+You can find a directory for each of these dependencies. Each directory has its
+own `BUILD.gn` file that defines a package for the specific example.
+
+Note: You can look at the `build/package.gni` file to learn more about how
+Fuchsia packages are defined by GN.
+
+Let's take a look at each example.
+
+### Cowsay
+
+This sample takes a word and repeats it back from an ASCII-art cow.
+
+To access a shell on the device, use the `fx shell` command:
+
+```
+fx shell
+```
+
+Now run the binary directly:
+
+```
+cowsay hi
+```
+
+```uglyprint
+ _____
+| hi |
+ -----
+ \ ^__^
+ \ (oo)\_____
+ (__)\ )\/\
+ ||----w |
+ || ||
+```
+
+You may notice that you can run this program without any changes to the build
+you already served to the device. Why? This example is pulled in as part of the
+command line utilities in `garnet/packages/prod/BUILD.gn`. But this isn't
+typically how you run a Fuchsia package; you will see that soon.
+
+### Fortune
+
+This sample prints a pithy observation. Let's try to run it using the extended
+format for `fx shell` that accepts command arguments:
+
+```
+fx shell fortune # won't work, no package in build
+```
+
+This won't work since this package wasn't pulled into the last build. You can
+confirm it isn't in the build by listing the contents of the `bin` directory:
+
+```
+fx shell ls bin
+```
+
+`cowsay` is there, but not `fortune`. Don't worry, you will add it soon.
+
+### Hello world
+
+This sample outputs `Hello, world!` and is written in both C++ and Rust. You may
+notice something different about this sample: each language-dependent directory
+also contains a `meta` subdirectory with `.cmx` files.
+
+This type of file is known as a
+[component manifest](glossary.md#component-manifest) and describes how to run
+the application on Fuchsia as a [component](glossary.md#component). This is
+the proper way to create a Fuchsia package.
+
+You run a Fuchsia component by referencing its
+[Fuchsia package URI](glossary.md#fuchsia_pkg-uri).
+
+## Set the build to include examples
+
+You can include the examples in the build, but you need to determine where they
+will be included:
+
+* Base: Packages that are included in paving images produced by the build.
+ They are included in over-the-air updates and are always updated as a
+ single unit.
+
+* Cache: Packages that are included in paving images, but are not included in
+ over-the-air system updates. These packages can be updated at any time that
+ updates are available.
+
+* Universe: Packages that are additional optional packages that can be
+ fetched and run on-demand, but are not pre-baked into any paving images.
+
+(For more information, see [fx workflows](development/workflows/fx.md).)
+
+To include this package in Universe so it can be fetched on-demand, use the
+`--with` flag when setting the product and board:
+
+```
+fx set ... --with //examples
+fx build
+```
+
+You now have a build that includes the examples. Now you need to serve this new
+build to the device. You probably already have `fx serve` running, but if not,
+go ahead and start it:
+
+```
+fx serve
+```
+
+## Try the examples
+
+Open a shell on the device to try the examples:
+
+```
+fx shell
+```
+
+### Cowsay
+
+This should work the same as before. It is still pulled into the base image.
+
+### Fortune
+
+Try to run the fortune example again:
+
+```
+fortune
+```
+
+It should now return a pithy quote.
+
+### Hello world
+
+You can't run this sample as the other two (try to run `hello_world_cpp` or
+`hello_world_rust`). To run a Fuchsia component, you need to run it's Fuchsia
+package URI. Lucily, there are some built-in conveniences to help you find this.
+You can use the `run` command:
+
+```
+run fuchsia-pkg://fuchsia.com/hello_world_cpp#meta/hello_world_cpp.cmx
+```
+
+And it should output the following:
+
+```uglyprint
+Hello, World!
+```
+
+Important: You must have `fx serve` running in order to serve components from
+your repository to the device. If it is not running, you may get an error from
+the device (for example,
+`fuchsia-pkg://fuchsia.com/hello_world_cpp#meta/hello_world_cpp.cmx: not
+found`).
+
+The `run` command can expand a string to a URI if the string only matches one
+component in your product configuration:
+
+```
+run hello_world_cpp
+```
+
+If there are multiple matches, the command will list them for you to choose
+from:
+
+```
+run hello
+```
+
+```uglyprint
+fuchsia-pkg://fuchsia.com/hello_world_cpp#meta/hello_world_cpp.cmx
+fuchsia-pkg://fuchsia.com/hello_world_rust#meta/hello_world_rust.cmx
+Error: "hello" matched multiple components.
+```
+
+You can explore what components are in your product configuration using the
+`locate` command.
+
+* Find your favorite component.
+
+ ```
+ locate hello_world_cpp
+ ```
+
+* Find all runnable components in your universe.
+
+ ```
+ locate --list cmx
+ ```
+
+* Find multiple test components.
+
+ ```
+ locate --list test
+ ```
--
GitLab