fuchsia学习-getting_started.md

fuchsia是google开发的一款全新操作系统，是一种微内核操作系统。

pink+purple = fuchsia，粉色+紫色= 紫红色，什么东西？有另外一种解释：灯笼海棠。长什么样子？如下：

• 开始fuchsia之前，需要准备好环境，

debian系统需要安装如下：sudo apt-get install build-essential curl git python unzip

获取源码，可根据说明文档获取：development/source_code/README.md

构建fuchsia，参考文档：development/workflows/build_and_pave_quickstart.md

• 构建

如果你已经添加了.jiri_root/bin到path，fx命令就已经可以直接使用了。也可以直接通过scripts/fx使用fx命令。构建 命令如下：

fx set core.x64 --with //bundles:kitchen_sink （选择构建配置，并默认产物在当前out/x64目录下）

fx build  （开始构建，增量构建，提示：fx -i build，可以实时监测文件是否被修改，自动触发构建）

 fuchsia可以通过网络很快地下载软件包，文档development/build/boards_and_products.md讲述了构建时set选择的参数意义。或者你也可以使用底层构建系统，参考文档development/build/README.md。

• 定制构建环境

默认，你得到的时一个x64的debug构建环境。不过你可以更改这个配置。如下：

fx set workstation.x64     # x64 debug build
fx set core.arm64          # arm64 debug build
fx set core.x64 --release  # x64 release build

• 使用ccache和goma加速构建

ccache通过缓存之前构建出来的产物来加速构建。如果环境变量CCACHE_DIR有效，并且对应的文件夹存在，ccache默认使能。

goma是google者专有，通过分发到多台机器编译来加速构建。如果你安装过goma在~/goma，这个也会被默认使用的。当然ccache也可以使用它。

可以通过设置fx的flags来更改fx的构建行为：

--ccache     # force use of ccache even if goma is available
--no-ccache  # disable use of ccache
--no-goma    # disable use of goma

• 启动fuchsia

1、安装并从硬件启动， 要使Fuchsia在硬件上运行，需要使用paver（铺路机，参考文档development/workflows/paving.md）。快速查看基本构建和铺路机的工作流程，参考文档development/workflows/build_and_pave_quickstart.md。

2、从qemu启动，如果你没有可以支持的硬件，也可以在模拟器qemu下运行fuchsia，参考文档/zircon/docs/qemu.md。fuchsia包含了预构建的二进制qemu文件，在目录buildtolls/qemu。

命令fx run会在qemu模拟器里运行zircon，使用本地构建好的硬盘镜像。fx run -h显示一些帮助信息，如下是其中一部分内容：

There are various flags for `fx run` to control QEMU's configuration:
* `-m` sets QEMU's memory size in MB.
* `-g` enables graphics (see below).
* `-N` enables networking (see below).
* `-k` enables KVM acceleration on Linux.

qemu使用提示：`ctrl+a x` 推出qemu，`ctrl+a ?`或者`ctrl+a h` 打印支持的命令。

• 使能图形

qemu对图形的支持是很有限的，因为缺Vulkan的支持。只有zircon的UI能打出来吧。通过命令可以增加图形：fx run -g。

• 使能网络

首先需要配置qemu支持网络，Enabling-Networking-under-QEMU，具体可参考文档/zircon/docs/qemu.md。会提供一个虚拟的接口给qemu使用。配置好了之后，可以通过命令增加网络功能：fx run -N -u scripts/start-dhcp-server.sh。“-u”参数运行了一个脚本，设置本地dhcp服务器，并且NAT配置ipv4和路由信息。

• 勘察fuchsia

在另一个独立的shell环境，启动开发更新服务器，如果它没有准备好。命令：fx serve -v。

通过网络启动fuchsia，可以在qemu模拟器通过参数‘-N’完成，也可以在一个已经铺好路的硬件环境完成。当fuchsia启动后，shell会输出带$符号的命令行，那就可以运行程序了。

• 关机或重启，可以通过命令：dm shutdown
• 更改一些源

 fuchisa系统里的大部分东西都被保存在包里。典型的开发过程中，涉及重新构建、上传fuchsia包到开发设备中，或者qemu虚拟设备中。

对二进制rolldice的源文件‘garnet/bin/rolldice/src/main.rs’做一些修改。重新构建并上传rolldice包到一个运行中的fuchsia设备可以使用命令：fx build-push rolldice。上传成功后，在该设备上运行rolldice命令。

• 选择一个标签（表格）

fuchsia启动时通过图形呈现多种标签形态。当前选中的标签在屏幕顶部被高亮黄色显示。可以通过组合键Alt-Tab切换标签。标签0是控制台，显示启动和组件日志信息；标签1~3是shell环境；标签4~更高，是你运行的组件。为了可以选择标签，你需要进入控制台模式（"console mode"），下个部分会有详细讲解。

• 运行图形组件

qemu不支持Vulkan因此不能运行图像组件。大部分fuchsia中的图像组件使用Scenic进行排版（Scenic，具体参考目录/garnet/bin/ui/）。你可以运行在/system/apps目录里的组件，使用命令：launch spinning_square_view。Scenic的示例应用程序的源码可以在目录/garnet/examples/ui找到。

当你运行使用Scenic的应用程序，使用硬件加速图像。或者如果你构建topaz层，它会启动进入fuchsia的用户图形界面，system UI。fuchsia会进入图像模式，graphics mode，它不会显示任何shell命令行。为了使用shell命令行，你需要进入console mode，通过按Alt-Escape键。console mode可以切换标签，前面已经讲过了。再次按下Alt-Escape键又会恢复到图像界面。如果你想在图像界面中使用shell命令行，可以通过选择"Ask Anything" 盒子并输入moterm，运行term，term源码位于topaz/+/master/app/term。

• 运行测试

编译过的测试二进制文件存放在/pkgfs/packages/，通过URL的方式访问提取。你可以尝试运行一个测试程序，输入如下命令：run fuchsia-pkg://fuchsia.com/ledger_tests#meta/ledger_unittests.cmx。如果想离开正在运行的fuchsia，并重新编译重新运行测试程序。在一个使用的终端通过网络运行fuchsia，那么在另一个终端，输入命令：fx run-test []。关于此，你可能需要细读文档，development/workflows/testing_faq.md。

• 贡献修改

见文档CONTRIBUTING.md。

• 更多的帮助文档

fuchsia文档，README.md。

工作于zircon，拷贝文件，网络启动，日志查看等。参考/zircon/docs/getting_started.md。

文档标准，参考best-practices/documentation_standards.md。

系统引导组件信息，参考/garnet/bin/sysmgr/。

工作流程和常用问答，参考development/workflows/workflow_tips_and_faq.md。

 

原英文文档：

# Fuchsia

Pink + Purple == Fuchsia (a new Operating System)

Welcome to Fuchsia! This document has everything you need to get started with
Fuchsia.

*** note
NOTE: The Fuchsia source includes
[Zircon](/zircon/README.md),
the core platform that underpins Fuchsia.
The Fuchsia build process will build Zircon as a side-effect;
to work on Zircon only, read and follow Zircon's
[Getting Started](/zircon/docs/getting_started.md)
doc.
***

[TOC]

## Prerequisites

### Prepare your build environment (once per build environment)

#### Debian

```
sudo apt-get install build-essential curl git python unzip
```

#### macOS

1.  Install Command Line Tools:

    ```
    xcode-select --install
    ```

1.  In addition to Command Line Tools, you also need to
    install a recent version of [Xcode](https://developer.apple.com/xcode/).

## Get the Source

Follow [the instructions to get the Fuchsia source](development/source_code/README.md)
and then return to this document.

## Build Fuchsia

Note: A quick overview of the basic build-and-pave workflow can be found [here](development/workflows/build_and_pave_quickstart.md).

### Build

If you added `.jiri_root/bin` to your path as part of getting the source code,
the `fx` command should already be in your path. If not, the command is also
available as `scripts/fx`.

```
fx set core.x64 --with //bundles:kitchen_sink
fx build
```

The first command selects the build configuration you wish to build and
generates the build system itself in an output directory (e.g., `out/x64`).
Fuchsia can ephemerally download [packages](development/build/boards_and_products.md) over the network;
here we use the `--available` flag to make the necessary packages covered in this guide
available for download.

The second command actually executes the build, transforming the source code in
build products. If you modify the source tree, you can do an incremental build
by re-running the `fx build` command alone. `fx -i build` starts a watcher
and automatically builds whenever a file is changed.

Alternatively, you can use the [underlying build system directly](development/build/README.md).

#### [optional] Customize Build Environment

By default you will get a x64 debug build. You can skip this section unless
you want something else.

Run `fx set` to see a list of build options. Some examples:

```
fx set workstation.x64     # x64 debug build
fx set core.arm64          # arm64 debug build
fx set core.x64 --release  # x64 release build
```

#### [optional] Accelerate builds with `ccache` and `goma`

`ccache` accelerates builds by caching artifacts from previous builds. `ccache`
is enabled automatically if the `CCACHE_DIR` environment variable is set and
refers to a directory that exists.

[Googlers only: `goma` accelerates builds by distributing compilation across
many machines.  If you have `goma` installed in `~/goma`, it is used by default.
It is also used by default in preference to `ccache`.]

To override the default behaviors, pass flags to `fx set`:

```
--ccache     # force use of ccache even if goma is available
--no-ccache  # disable use of ccache
--no-goma    # disable use of goma
```

## Boot Fuchsia

### Installing and booting from hardware

To get Fuchsia running on hardware requires using the paver, which these
[instructions](development/workflows/paving.md) will help you get up and running
with.

Note: A quick overview of the basic build-and-pave workflow can be found
[here](development/workflows/build_and_pave_quickstart.md).

### Boot from QEMU

If you don't have the supported hardware, you can run Fuchsia under emulation
using [QEMU](/zircon/docs/qemu.md).
Fuchsia includes prebuilt binaries for QEMU under `buildtools/qemu`.

The `fx run` command will launch Zircon within QEMU, using the locally built
disk image:

```
fx run
```

There are various flags for `fx run` to control QEMU's configuration:
* `-m` sets QEMU's memory size in MB.
* `-g` enables graphics (see below).
* `-N` enables networking (see below).
* `-k` enables KVM acceleration on Linux.

Use `fx run -h` to see all available options.

#### QEMU tips

* `ctrl+a x` will exit QEMU in text mode.
* `ctrl+a ?` or `ctrl+a h` prints all supported commands.

#### Enabling Graphics

Note: Graphics under QEMU are extremely limited due to a lack of Vulkan
support. Only the Zircon UI renders.

To enable graphics under QEMU, add the `-g` flag to `fx run`:

```
fx run -g
```

#### Enabling Network

First, [configure](/zircon/docs/qemu.md#Enabling-Networking-under-QEMU) a
virtual interface for QEMU's use.

Once this is done you can add the `-N` and `-u` flags to `fx run`:

```
fx run -N -u scripts/start-dhcp-server.sh
```

The `-u` flag runs a script that sets up a local DHCP server and NAT to
configure the IPv4 interface and routing.

## Explore Fuchsia

In a separate shell, start the development update server, if it isn't already
running:

```
fx serve -v
```

Boot Fuchsia with networking. This can be done either in QEMU via the `-N` flag,
or on a paved hardware, both described above.
When Fuchsia has booted and displays the "$" shell prompt, you can run programs!

For example, to receive deep wisdom, run:

```
fortune
```

To shutdown or reboot Fuchsia, use the `dm` command:

```
dm help
dm shutdown
```

### Change some source

Almost everything that exists on a Fuchsia system is stored in a Fuchsia
package. A typical development
[workflow](development/workflows/package_update.md) involves re-building and
pushing Fuchsia packages to a development device or QEMU virtual device.

Make a change to the rolldice binary in `garnet/bin/rolldice/src/main.rs`.

Re-build and push the rolldice package to a running Fuchsia device with:

```
fx build-push rolldice
```

From a shell prompt on the Fuchsia device, run the updated rolldice component
with:

```
rolldice
```

### Select a tab

Fuchsia shows multiple tabs after booting [with graphics
enabled](#enabling-graphics). The currently selected tab is highlighted in
yellow at the top of the screen. You can switch to the next tab using Alt-Tab on
the keyboard.

- Tab zero is the console and displays the boot and component log.
- Tabs 1, 2 and 3 contain shells.
- Tabs 4 and higher contain components you've launched.

Note: to select tabs, you may need to enter "console mode". See the next section for details.

### Launch a graphical component

QEMU does not support Vulkan and therefore cannot run our graphics stack.

Most graphical components in Fuchsia use the [Scenic](/garnet/bin/ui/) system
compositor. You can launch such components, commonly found in `/system/apps`,
like this:

```
launch spinning_square_view
```

Source code for Scenic example apps is [here](/garnet/examples/ui).

When you launch something that uses Scenic, uses hardware-accelerated graphics, or if you build
the [default](https://fuchsia.googlesource.com/topaz/+/master/packages) package (which will
boot into the Fuchsia System UI), Fuchsia will enter "graphics mode", which will not display any
of the text shells. In order to use the text shell, you will need to enter "console mode" by
pressing Alt-Escape. In console mode, Alt-Tab will have the behavior described in the previous
section, and pressing Alt-Escape again will take you back to the graphical shell.

If you would like to use a text shell inside a terminal emulator from within the graphical shell
you can launch the [term](https://fuchsia.googlesource.com/topaz/+/master/app/term) by selecting the
"Ask Anything" box and typing `moterm`.

## Running tests

Compiled test binaries are installed in `/pkgfs/packages/`, and are referenced by a URI.
You can run a test by invoking it in the terminal. E.g.

```
run fuchsia-pkg://fuchsia.com/ledger_tests#meta/ledger_unittests.cmx
```

If you want to leave Fuchsia running and recompile and re-run a test, run
Fuchsia with networking enabled in one terminal, then in another terminal, run:

```
fx run-test  []
```

You may wish to peruse the [testing FAQ](development/workflows/testing_faq.md).

## Contribute changes

* See [CONTRIBUTING.md](/CONTRIBUTING.md).

## Additional helpful documents

* [Fuchsia documentation](README.md) hub
* Working with Zircon - [copying files, network booting, log viewing, and
more](/zircon/docs/getting_started.md#Copying-files-to-and-from-Zircon)
* [Documentation Standards](best-practices/documentation_standards.md) - best practices
  for documentation
* [Information on the system bootstrap component](/garnet/bin/sysmgr/).
* [Workflow tips and FAQ](development/workflows/workflow_tips_and_faq.md) that help increase
  productivity.