Fuchsia 6月 29,2019

文档评论

Comments in your code are very important for maintainability and helping other people understand your code. Documentation comments are especially effective at describing the purpose of protocols, structures, methods, data types, and other elements of program code.

Documentation comments should be applied consistently to all public APIs since they are a valuable asset for SDK consumers.

Tips for writing effective documentation comments:

Write in plain U.S. English.
Write complete sentences and paragraphs.
Write clear and brief comments, no more than a few sentences.
Follow the approved style guide for your programming language.
Avoid creating running words that are not compound words. For example “notready” is two words run together. Use an appropriate separator, for example “not ready”, “notReady”, “not_ready”, or “not-ready”).
Always add value. Don’t restate what is already indicated by the type signature.
Describe units of measure and integrity constraints of variables.
Link to conceptual documentation for more complete descriptions of how APIs fit together as a whole.
Follow the approved style guide for your programming language. See the Development Readme for style guidelines related to specific programming languages.

What documentation style guidelines should I follow?

It is important to try to follow documentation style guidelines to ensure that the documentation, even comments, can flow together. See Documentation Style Guide.

Also, see the Development Readme for style guidelines related to specific programming languages.

作者 east

Fuchsia 6月 29,2019

文档标准

A document about what to document and how to document it for people who create things that need documentation.

Why document?

Fuchsia is a new operating system. Effective documentation allows new people to join and grow the project by having all necessary documentation be clear and concise.

Who is the audience?

The documentation described here is intended to address a technical audience, i.e. those who expect to implement or exercise APIs or understand the internal dynamics of the operating system. These standards are not intended for end-user product documentation.

What should I document?

Document protocols, introduce essential concepts, explain how everything fits together.

Conventions: e.g. this document about documentation, code style
System Design: e.g. network stack, compositor, kernel, assumptions
APIs: e.g. FIDL protocols, library functions, syscalls
Protocols: e.g. schemas, encodings, wire formats, configuration files
Tools: e.g. bootserver, netcp, fx
Workflows: e.g. environment set up, test methodologies, where to find various parts, how to get work done

Where should I put documents? What goes where?

Documentation that is only for developers working on creating or maintaining a specific part of the code should be kept in the same directory as the source code.

Documentation that should be generally available to developers must be available in one of two locations:

Zircon specific documentation should be created in /zircon/docs.
Fuchsia documentation that is not specific to Zircon specific should be created in /docs. In the /docs/directory, you should create your documentation or images in one of these sub-directories:
- best-practices General best practice guidelines on how to develop with Fuchsia source. If you create best practice documentation about about using a specific feature of Fuchsia, you should create the documentation in the same directory as the other documentation for that specific feature.
- development Instructions, tutorials, and procedural documentation for developers that are working on Fuchsia. This directory includes documentation on how to get started, build, run, and test Fuchsia and software running on devices operating Fuchsia. You should organize the content that you create by specific activities, such as testing, getting started, or by workflow topic.
- the-book Concept and developer guides about the features of Fuchsia. You should organize the content that you create by specific features.
- images Images that are used in the documentation. You should place images in this common directory and avoid placing images in the same directory as documentation.

What documentation should I create?

Most documentation can be divided into four categories:

Reference – Information-oriented documentation
Conceptual – Understanding-oriented documentation
Procedural
- How to – Goal-oriented documentation
- Codelab – Learning-oriented documentation

See Documentation Types for more information.

However, comments in your code are very important for maintainability and helping other people understand your code. See the Code Comment Guidelines for style guidelines related to comments for your code.

What documentation style guidelines should I follow?

It is important to try to follow documentation style guidelines to ensure that the documentation created by a large number of contributors can flow together. See Documentation Style Guide.

How can I expose my documentation?

Documentation is only useful when users can find it. Adding links to or from existing documentation greatly improves the chances that someone can find your documentation.

Tips for leaving breadcrumbs:

Top-down linkage: Add links from more general documents to more specific documents to help readers learn more about specific topics. The Fuchsia book is a good starting point for top-down linkage.
Bottom-up linkage: Add links from more specific documents to more general documents to help readers understand the full context context of the topics being discussed. Adding links from module, class, or protocol documentation comments to conceptual documentation overviews can be particularly effective.
Sideways linkage: Add links to documents on subjects that help readers better understand the content of your document.

作者 east

Fuchsia 6月 29,2019

文档类型

Documentation is an important part of any product or feature because it lets users know how to properly use a feature that has been implemented. These guidelines are meant to be a quick and easy reference for types of documentation. For information on documentation style guidelines, see Documentation Style Guide.

Conceptual, procedural, or reference documentation

Most documentation can be divided into these categories:

Reference – Documentation that provides a source of information about parts of a system such as API parameters.
Conceptual – Documentation that helps you understand a concept such as mods in Fuchsia.
Procedural
- How-to – Documentation that provides steps on how to accomplish a goal such as create a user.
- Codelab – Documentation that provides steps of a learning path (this tends to be a much bigger procedure than a how-to) such as create a component.

You should write a reference document if you need to provide information about parts of a system including, but not limited to APIs and CLIs. Reference documentation should allow the user to understand how to use a specific feature quickly and easily.

You should write a conceptual document if you plan on explaining a concept about a product. Conceptual documents explain a specific concept, but for the most part they do not include actual examples. They provide essential facts, background, and diagrams to help your readers build a foundational understanding of a product or topic. You should not explain industry standards that your audience should be familiar with, for example, TCP/IP. You might explain how this concept ties in with your feature, but you should not explain the basics behind that industry standard concept.

You should write a procedural document if you plan on explaining to a user how to use a specific feature and are able to guide a user through simple numbered steps. Procedural documents tend to reinforce the concepts that were explained in a conceptual document by giving one or more examples that might be useful for users.

Procedural documents are divided into two categories:

How-to – Consider writing a how to when you want to help the user accomplish a very specific goal.
Codelab – Consider writing a codelab when you want to help the user learn about a bigger goal that might involve working with multiple parts of a product or feature. The codelab should not go over 60 minutes and should provide the user with a specific result.

How can you decide what type of document is appropriate for your use case? Consider these examples:

What is a car? This is a conceptual document.
How does an internal combustion engine work? This is a conceptual document that would be geared towards more advanced users.
How to use the alarm manager in Android. That is a procedural document. The main set of procedures can be a codelab since a hand-held example is ideal to understand the function of the alarm manager.
How to operate the radio. This is a procedural document. This can be a how to guide since the use of a radio tends to be quite intuitive and in most cases wouldn’t require a hand-held example.
How does a transistor work? This is a conceptual document that would be geared towards a more advanced user.
Functions of the car radio. This is a reference document.
How a new technology improved the car radio. This is a conceptual document.

Note: A feature may require more than one type of document. You may decide that your feature requires just reference documentation or that you need reference, conceptual, and how to documentation.

Reference documentation {#reference-documentation}

Reference documentation should provide information about parts of a system including, but not limited to APIs and CLIs. The style of reference documentation should be the same for all reference documentation of that type. For example, API documentation should define all of the API’s parameters, indicate if a parameter is required or optional, and show examples of the use of the API. These examples should be very generic and simple. If you feel like you need a more elaborate example, consider creating a procedural document to reinforce your reference documentation.

For the style guide for API documentation, see API style guide.

Conceptual documentation {#conceptual-documentation}

Conceptual documentation should try to be brief and for the most part should not go above 1 page. If you need to write more than one page to describe a concept, consider breaking that concept into sub-concepts by using headings. By keeping your document brief you achieve the following:

You do not overwhelm your reader with a wall of text.
Avoid losing the reader while they read your document.

The first paragraph should try to be a brief summary of your document, this should allow the user to quickly read through it, determine what the document covers, and if this is relevant to what they want to learn. If your document has multiple headings, you should include a bulleted list with the high-level headings after this first paragraph.

You should use graphics, images, or diagrams to reinforce certain concepts. The text that comes before and after the graphic should explain what the graphic shows. Images should be saved in a feature specific ‘images/’ directory or a common ‘images/’ directory. You should also save the source file of your images in a ‘images/src/’ directory.

Good conceptual documentation usually includes:

Description rather than instruction
Background concepts
Diagrams or other visual aids (preferably in .png format)
Links to how-to and/or reference docs

After writing your document, it is good practice to proofread the document, put yourself in the user’s shoes (no longer being the expert that developed the feature), and try to answer these questions:

Does the information in the document explain the concept completely?
Is there information that is not needed for this concept? If so, remove it.
Is there unnecessary detail about how things might work in the background?
If I am the user, is there additional I would have liked to know?

Then, add your feedback into your document.

Procedural documentation {#procedural-documentation}

Procedural documents are divided into two categories:

How-to – Consider writing a how to when you want to help the user accomplish a very specific goal.
Codelab – Consider writing a codelab when you want to help the user learn about a bigger goal that might involve working with multiple parts of a product or feature.

Procedural documentation should try to be brief and each task within your documentation should try to avoid going above 10 steps (codelabs can be much longer, but should not exceed 45-60 minutes for a user to complete). You should divide long procedures into multiple sub-tasks to try to keep tasks manageable for a user. For example, if you wanted to write a procedural document for taking care of a dog, you might have a table of content that looks like this:

How to take care of a dog:

Feeding a dog
Washing a dog
Trimming a dog’s nails
Brushing a dog
Playing with a dog

Difference between a codelab and a how to

At a very high-level, a codelab is essentially a large how to, composed of various smaller how tos. Codelabs are great when you want to give the user a hand-held experience of working through a task, especially if this task is considered a little more complicated and might involve working with various areas of a product. On the other hand, a how to should describe the steps on how to work through a minor task that should only involve a single area of a product.

Consider the following when you think that you might need to create a codelab:

How many codelabs are planned for this general feature? Keep in mind that you do not want a whole documentation set to just be codelabs, use them in moderation.
Codelabs should be self-contained, avoid creating links to other codelabs, other how-tos or other information that might have a user leave the actual codelab. It is ok to provide links to conceptual documents that can enhance a user’s knowledge for a given topic.
Would this procedural documentation benefit from having a very specific example through a codelab?
Do you want to expose an exciting feature from the product through the codelab? This helps you highlight a neat feature that a user might not know about without doing a codelab.

General procedural documentation guidelines

Each task or subtask should have a paragraph that lets a user know what the task is about and what a user should be able to do after performing the steps.
Use screenshots or graphics to assist a user in navigating a user interface (UI).
A procedural document should not have to explain any concepts to a user, but should reference conceptual documents in case a user does not know about a certain concept. For example, a procedure with a reference to a conceptual document might look like this:Configure the server with the appropriate configuration. For more information about server configurations, see “server configuration”.
Avoid giving the users multiple paths to select when working through procedures. When you avoid giving the user choices, your documentation should lead all users to the same end result (for example, starting the server).
If a procedural document is meant for beginner users, avoid adding procedures that you might consider better suited for advanced users. If your document is intended for advanced users, state it up front and give them a list of prerequisites before they go through your how to or codelab.

作者 east

Fuchsia 6月 29,2019

Fuchsia贡献变化

Fuchsia manages commits through Gerrit at https://fuchsia-review.googlesource.com. Not all projects accept patches; please see the CONTRIBUTING.md document in individual projects for details.

Submitting changes

To submit a patch to Fuchsia, you may first need to generate a cookie to authenticate you to Gerrit. To generate a cookie, log into Gerrit and click the “Generate Password” link at the top of https://fuchsia.googlesource.com. Then, copy the generated text and execute it in a terminal.

Once authenticated, follow these steps to submit a patch to a repo in Fuchsia:

# create a new branchgit checkout -b branch_name# write some awesome stuff, commit to branch_name# edit some_file ...git add some_file# if specified in the repo, follow the commit message formatgit commit ...# upload the patch to Gerrit# `jiri help upload` lists flags for various features, e.g. adding reviewersjiri upload # Adds default topic - ${USER}-branch_name# orjiri upload -topic="custom_topic"# orgit push origin HEAD:refs/for/master# at any time, if you'd like to make changes to your patch, use --amendgit commit --amend# once the change is landed, clean up the branchgit branch -d branch_name

See the Gerrit documentation for more detail: https://gerrit-documentation.storage.googleapis.com/Documentation/2.12.3/intro-user.html#upload-change

Commit message tags

If submitting a change to Zircon, Garnet, Peridot or Topaz, include [tags] in the commit subject flagging which module, library, app, etc, is affected by the change. The style here is somewhat informal. Look at these example changes to get a feel for how these are used.

https://fuchsia-review.googlesource.com/c/zircon/+/112976
https://fuchsia-review.googlesource.com/c/garnet/+/110795
https://fuchsia-review.googlesource.com/c/peridot/+/113955
https://fuchsia-review.googlesource.com/c/topaz/+/114013

Gerrit will flag your change with Needs Label: Commit-Message-has-tags if these are missing.

Example:

# Ready to submit[parent][component] Update component in Topaz.Test: Added test X# Needs Label: Commit-Message-has-tagsUpdate component in Topaz.Test: Added test X

Testing

Developers are responsible for high-quality automated testing of their code. Reviewers are responsible for pushing back on changes that do not include sufficient tests.

If a change requires non-obvious manual testing for validation, those testing steps should be described in a line in the change description beginning with “Test:”. If the instructions are more elaborate, they can be added to a linked bug.

In some cases, we are not able to test certain behavior changes because we lack some particular piece of infrastructure. In that case, we should have an issue in the tracker about creating that infrastructure and the test label should mention the bug number in addition to describing how the change was manually tested:

Test: Manually tested that [...]. Automated testing needs US-XXXX

If the change does not intend to change behavior, the CL description should indicate as such.

[Non-Googlers only] Sign the Google CLA

In order to land your change, you need to sign the Google CLA.

[Googlers only] Issue actions

Commit messages may reference issue IDs in Fuchsia’s issue tracker; such references will become links in the Gerrit UI. Issue actions may also be specified, for example to automatically close an issue when a commit is landed:

BUG-123 #done

done is the most common issue action, though any workflow action can be indicated in this way.

Issue actions take place when the relevant commit becomes visible in a Gerrit branch, with the exception that commits under refs/changes/ are ignored. Usually, this means the action will happen when the commit is merged to master, but note that it will also happen if a change is uploaded to a private branch.Note: Fuchsia’s issue tracker is not open to external contributors at this time.

Cross-repo changes

Changes in two or more separate repos will be automatically tracked for you by Gerrit if you use the same topic.

Using jiri upload

Create branch with same name on all repos and upload the changes

# make and commit the first changecd examples/fortunegit checkout -b add_feature_foo* edit foo_related_files ... *git add foo_related_files ...git commit ...# make and commit the second change in another repositorycd fuchsia/buildgit checkout -b add_feature_foo* edit more_foo_related_files ... *git add more_foo_related_files ...git commit ...# Upload all changes with the same branch name across reposjiri upload -multipart # Adds default topic - ${USER}-branch_name# orjiri upload -multipart -topic="custom_topic"# after the changes are reviewed, approved and submitted, clean up the local branchcd examples/fortunegit branch -d add_feature_foocd fuchsia/buildgit branch -d add_feature_foo

Using Gerrit commands

# make and commit the first change, upload it with topic 'add_feature_foo'cd examples/fortunegit checkout -b add_feature_foo* edit foo_related_files ... *git add foo_related_files ...git commit ...git push origin HEAD:refs/for/master%topic=add_feature_foo# make and commit the second change in another repositorycd fuchsia/buildgit checkout -b add_feature_foo* edit more_foo_related_files ... *git add more_foo_related_files ...git commit ...git push origin HEAD:refs/for/master%topic=add_feature_foo# after the changes are reviewed, approved and submitted, clean up the local branchcd examples/fortunegit branch -d add_feature_foocd fuchsia/buildgit branch -d add_feature_foo

Multipart changes are tracked in Gerrit via topics, will be tested together, and can be landed in Gerrit at the same time with Submit Whole Topic. Topics can be edited via the web UI.

Changes that span repositories

See Changes that span repositories.

Resolving merge conflicts

# rebase from origin/master, revealing the merge conflictgit rebase origin/master# resolve the conflicts and complete the rebase* edit files_with_conflicts ... *git add files_with_resolved_conflicts ...git rebase --continuejiri upload# continue as usualgit commit --amendjiri upload

作者 east

Fuchsia 6月 29,2019

运行示例

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 or docs. In short, GN is a meta build system. Its output files serve as inputs to Ninja, 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:

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

 _____
| 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 and describes how to run the application on Fuchsia as a component. This is the proper way to create a Fuchsia package.

You run a Fuchsia component by referencing its Fuchsia package URL.

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.)

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 //examplesfx 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 URL. Luckily, 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:

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 URL 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

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

作者 east

Fuchsia 6月 29,2019

Fuchsia 不是 Linux

A modular, capability-based operating system

This document is a collection of articles describing the Fuchsia operating system, organized around particular subsystems. Sections will be populated over time.

Zircon Kernel

Zircon is the microkernel underlying the rest of Fuchsia. Zircon also provides core drivers and Fuchsia’s libc implementation.

Zircon Core

Framework

Core Libraries
Application model
- Interface definition language (FIDL)
- Services
- Environments
Boot sequence
Device, user, and story runners
Components
Namespaces
Sandboxing
Story
Module
Agent

Storage

Block devices
File systems
Directory hierarchy
Ledger
Document store
Application cache

Networking

Ethernet
Wireless
Bluetooth
Telephony
Sockets
HTTP

Graphics

Components

Component framework

Media

Audio
Video
DRM

Intelligence

Context
Agent Framework
Suggestions

User interface

Device, user, and story shells
Stories and modules

Backwards compatibility

POSIX lite (what subset of POSIX we support and why)
Web runtime

Update and recovery

Verified boot
Updater

更多知识参考

作者 east

Fuchsia 6月 29,2019

开发

his document is a top-level entry point to all of Fuchsia documentation related to developing Fuchsia and software running on Fuchsia.

Developer workflow

This sections describes the workflows and tools for building, running, testing and debugging Fuchsia and programs running on Fuchsia.

Getting started – start here. This document covers getting the source, building and running Fuchsia.
Source code
fx workflows
Multiple device setup
Pushing a package
Changes that span layers
Debugging
LibFuzzer-based fuzzing
Build system
Workflow tips and FAQ
Testing FAQ

Languages

README – Language usage in Fuchsia
C/C++
Dart
FIDL
Go
Rust
Python
Flutter modules – how to write a graphical module using Flutter
New language – how to bring a new language to Fuchsia

API

README – Developing APIs for Fuchsia
Council – Definition of the API council
System – Rubric for designing the Zircon System Interface
FIDL API – Rubric for designing FIDL protocols
FIDL style – FIDL style rubric
C – Rubric for designing C library interfaces
Tools – Rubrics for designing developer tools
Devices – Rubric for designing device interfaces

ABI

System – Describes scope of the binary-stable Fuchsia System Interface

SDK

SDK – information about developing the Fuchsia SDK

Hardware

This section covers Fuchsia development hardware targets.

Testing

Conventions

This section covers Fuchsia-wide conventions and best practices.

Documentation standards
Endian Issues and recommendations

Tracing

Miscellaneous

作者 east

Fuchsia 6月 29,2019

Fuchsia

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

Welcome to Fuchsia! This document has everything you need to get started with Fuchsia.Note: The Fuchsia source includes Zircon, 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 doc.

Prerequisites

Prepare your build environment (once per build environment)

Debian

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

macOS

Install Command Line Tools:xcode-select --install
In addition to Command Line Tools, you also need to install a recent version of Xcode.

Get the Source

Follow the instructions to get the Fuchsia source and then return to this document.

Build Fuchsia

Note: A quick overview of the basic build-and-pave workflow can be found here.

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_sinkfx 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 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.

[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 buildfx set core.arm64          # arm64 debug buildfx 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 gomainstalled 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 will help you get up and running with.Note: A quick overview of the basic build-and-pave workflow can be found here.

Boot from QEMU

If you don’t have the supported hardware, you can run Fuchsia under emulation using QEMU. 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. * -genables 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 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 helpdm shutdown

Change some source

Almost everything that exists on a Fuchsia system is stored in a Fuchsia package. A typical development workflowinvolves 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. 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 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.

When you launch something that uses Scenic, uses hardware-accelerated graphics, or if you build the defaultpackage (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 termby 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 <test name> [<test args>]

You may wish to peruse the testing FAQ.

Contribute changes

See CONTRIBUTING.md.

Additional helpful documents

Fuchsia documentation hub
Working with Zircon – copying files, network booting, log viewing, and more
Documentation Standards – best practices for documentation
Information on the system bootstrap component.
Workflow tips and FAQ that help increase productivity.

作者 east

Fuchsia 6月 29,2019

词汇表

概观

本文档的目的是为Fuchsia中使用的一系列技术术语提供简短定义。

添加新定义

定义应提供术语的高级描述，并且在大多数情况下不应超过两个或三个句子。
当需要使用另一个非平凡的技术术语作为描述的一部分时，请考虑为该术语添加定义并从原始定义链接到该术语。
定义应该由更详细的文档和相关主题的链接列表补充。

Terms

Agent

An agent is a role a component can play to execute in the background in the context of a session. An agent’s life cycle is not tied to any story, is a singleton per session, and provides services to other components. An agent can be invoked by other components or by the system in response to triggers like push notifications. An agent can provide services to components, send and receive messages, and make proposals to give suggestions to the user.

AppMgr

The Application Manager (AppMgr) is responsible for launching components and managing the namespaces in which those components run. It is the first process started in the fuchsia job by the DevMgr.

Banjo

Banjo is a language for defining protocols that are used to communicate between drivers. It is different from FIDL in that it specifies an ABI for drivers to use to call into each other, rather than an IPC protocol.

Base shell

The platform-guaranteed set of software functionality which provides a basic user-facing interface for boot, first-use, authentication, escape from and selection of session shells, and device recovery.

bootfs

The bootfs RAM disk contains the files needed early in the boot process when no other filesystems are available. It is part of the ZBI, and is decompressed and served by bootsvc. After the early boot process is complete, the bootfs is mounted at /boot.

Documentation

bootsvc

bootsvc is the second process started in Fuchsia. It provides a filesystem service for the bootfs and a loader service that loads programs from the same bootfs. After starting these services, it loads the third program, which defaults to devmgr.

Documentation

Bus Driver

A driver for a device that has multiple children. For example, hardware interfaces like PCI specify a topology in which a single controller is used to interface with multiple devices connected to it. In that situation, the driver for the controller would be a bus driver.

Cache directory

Similar to a data directory, except that the contents of a cache directory may be cleared by the system at any time, such as when the device is under storage pressure. Canonically mapped to /cache in the component instance’s namespace.

Testing isolated cache storage.

Capability

A capability is a value which combines an object reference and a set of rights. When a program has a capability it is conferred the privilege to perform certain actions using that capability. A handle is a common example for a capability.

Capability routing

A way for one component to give capabilities to another instance over the component instance tree. Component manifests define how routing takes place, with syntax for service capabilities, directory capabilities, and storage capabilities.

Capability routing is a components v2 concept.

expose

A component instance may use the expose manifest keyword to indicate that it is making a capability available to its parent to route. Parents may offer a capability exposed by any of their children to their other children or to their parent, but they cannot use it themselves in order to avoid dependency cycles.

offer

A component instance may use the offer manifest keyword to route a capability that was exposed to it to one of its children (other than the child that exposed it).

use

A component instance may use the use manifest keyword to consume a capability that was offered to it by its parent.

Channel

A channel is an IPC primitive provided by Zircon. It is a bidirectional, datagram-like transport that can transfer small messages including Handles. FIDL protocols typically use channels as their underlying transport.

Channel Overview

Component

A component is a unit of executable software on Fuchsia. Components support capability routing, software composition, isolation boundaries, continuity between executions, and introspection.

Component collection

A node in the component instance tree whose children are dynamically instantiated rather than statically defined in acomponent manifest.

Component collection is a components v2 concept.

Component declaration

A component declaration is a FIDL table (fuchsia.sys2.ComponentDecl) that includes information about a component’s runtime configuration, capabilities it exposes, offers, and uses, and facets.

Component declaration is a components v2 concept.

Component Framework

An application framework for declaring and managing components, consisting of build tools, APIs, conventions, and system services.

Components v1, Components v2

Component instance

One of possibly many instances of a particular component at runtime. A component instance has its own environment and lifecycle independent of other instances.

Component instance tree

A tree structure that represents the runtime state of parent-child relationships between component instances. If instance A launches instance B then in the tree A will be the parent of B. The component instance tree is used in static capability routing such that parents can offer capabilities to their children to use, and children can exposecapabilities for their parents to expose to their parents or offer to other children.

Component instance tree is a components v2 concept.

Component Manager

A system service which lets component instances manage their children and routes capabilities between them, thus implementing the component instance tree. Component Manager is the system service that implements thecomponents v2 runtime.

Component Manifest

In Components v1, a component manifest is a JSON file with a .cmx extension that contains information about a component’s runtime configuration, services and directories it receives in its namespace, and facets.

In Components v2, a component manifest is a file with a .cm extension, that encodes a component declaration.

Component manifests v2

Component Manifest Facet

Additional metadata that is carried in a component manifest. This is an extension point to the component framework.

Components v1

A shorthand for the Component Architecture as first implemented on Fuchsia. Includes a runtime as implemented by appmgr and sysmgr, protocols and types as defined in fuchsia.sys, build-time tools such as cmc, and SDK libraries such as libsys and libsvc.

Components v2

Components v2

A shorthand for the Component Architecture in its modern implementation. Includes a runtime as implemented bycomponent_manager, protocols and types as defined in fuchsia.sys2, and build-time tools such as cmc.

Components v1

Concurrent Device Driver

A concurrent device driver is a hardware driver that supports multiple concurrent operations. This may be, for example, through a hardware command queue or multiple device channels. From the perspective of the core driver, the device has multiple pending operations, each of which completes or fails independently. If the driven device can internally parallelize an operation, but can only have one operation outstanding at a time, it may be better implemented with a sequential device driver.

Core Driver

A core driver is a driver that implements the application-facing RPC interface for a class of drivers (e.g. block drivers, ethernet drivers). It is hardware-agnostic. It communicates with a hardware driver through banjo to service its requests.

Data directory

A private directory within which a component instance may store data local to the device, canonically mapped to /data in the component instance’s namespace.

DevHost

A Device Host (DevHost) is a process containing one or more device drivers. They are created by the Device Manager, as needed, to provide isolation between drivers for stability and security.

DevMgr

The Device Manager (DevMgr) is responsible for enumerating, loading, and managing the life cycle of device drivers, as well as low level system tasks (providing filesystem servers for the boot filesystem, launching AppMgr, and so on).

DDK

The Driver Development Kit is the documentation, APIs, and ABIs necessary to build Zircon Device Drivers. Device drivers are implemented as ELF shared libraries loaded by Zircon’s Device Manager.

Directory capability

A capability that permits access to a filesystem directory by adding it to the namespace of the component instancethat uses it. If multiple component instances are offered the same directory capability then they will have access to the same underlying filesystem directory.

Directory capability is a components v2 concept.

Capability routing

Driver

A driver is a dynamic shared library which DevMgr can load into a DevHost and that enables, and controls one or more devices.

Environment

A container for a set of components, which provides a way to manage their lifecycle and provision services for them. All components in an environment receive access to (a subset of) the environment’s services.

Escher

Graphics library for compositing user interface content. Its design is inspired by modern real-time and physically based rendering techniques though we anticipate most of the content it renders to have non-realistic or stylized qualities suitable for user interfaces.

FAR

The Fuchsia Archive Format is a container for files to be used by Zircon and Fuchsia.

FAR Spec

FBL

FBL is the Fuchsia Base Library, which is shared between kernel and userspace.

Zircon C++

fdio

fdio is the Zircon IO Library. It provides the implementation of posix-style open(), close(), read(), write(), select(), poll(), etc, against the RemoteIO RPC protocol. These APIs are return- not-supported stubs in libc, and linking against libfdio overrides these stubs with functional implementations.

Source

FIDL

The Fuchsia Interface Definition Language (FIDL) is a language for defining protocols that are typically used over channels. FIDL is programming language agnostic and has bindings for many popular languages, including C, C++, Dart, Go, and Rust. This approach lets system components written in a variety of languages interact seamlessly.

Flutter

Flutter is a functional-reactive user interface framework optimized for Fuchsia and is used by many system components. Flutter also runs on a variety of other platforms, including Android and iOS. Fuchsia itself does not require you to use any particular language or user interface framework.

Fuchsia API Surface

The Fuchsia API Surface is the combination of the Fuchsia System Interface and the client libraries included in the Fuchsia SDK.

Fuchsia Package

A Fuchsia Package is a unit of software distribution. It is a collection of files, such as manifests, metadata, zero or more executables (e.g. Components), and assets. Individual Fuchsia Packages can be identified using fuchsia-pkg URLs.

fuchsia-pkg URL

The fuchsia-pkg URL scheme is a means for referring to a repository, a package, or a package resource. The syntax is fuchsia-pkg://<repo-hostname>[/<pkg-name>][#<path>]]. E.g., for the componentecho_client_dart.cmx published under the package echo_dart‘s meta directory, from the fuchsia.comrepository, its URL is fuchsia-pkg://fuchsia.com/echo_dart#meta/echo_client_dart.cmx.

Fuchsia SDK

The Fuchsia SDK is a collection of libraries and tools that the Fuchsia project provides to Fuchsia developers. Among other things, the Fuchsia SDK contains a definition of the Fuchsia System Interface as well as a number of client libraries.

Fuchsia System Interface

The Fuchsia System Interface is the binary interface that the Fuchsia operating system presents to software it runs. For example, the entry points into the vDSO as well as all the FIDL protocols are part of the Fuchsia System Interface.

Fuchsia Volume Manager

Fuchsia Volume Manager (FVM) is a partition manager providing dynamically allocated groups of blocks known as slices into a virtual block address space. The FVM partitions provide a block interface enabling filesystems to interact with it in a manner largely consistent with a regular block device.

Filesystems

GN

GN is a meta-build system which generates build files so that Fuchsia can be built with Ninja. GN is fast and comes with solid tools to manage and explore dependencies. GN files, named BUILD.gn, are located all over the repository.

Handle

A Handle is how a userspace process refers to a kernel object. They can be passed to other processes over Channels.

Reference

Hardware Driver

A hardware driver is a driver that controls a device. It receives requests from its core driver and translates them into hardware-specific operations. Hardware drivers strive to be as thin as possible. They do not support RPC interfaces, ideally have no local worker threads (though that is not a strict requirement), and some will have interrupt handling threads. They may be further classified into sequential device drivers and concurrent device drivers.

Hub

The hub is a portal for introspection. It enables tools to access detailed structural information about realms and component instances at runtime, such as their names, job and process ids, and published services.

Jiri

Jiri is a tool for multi-repo development. It is used to checkout the Fuchsia codebase. It supports various subcommands which makes it easy for developers to manage their local checkouts.

Job

A Job is a kernel object that groups a set of related processes, their child processes and their jobs (if any). Every process in the system belongs to a job and all jobs form a single rooted tree.

Job Overview

Kernel Object

A kernel object is a kernel data structure which is used to regulate access to system resources such as memory, i/o, processor time and access to other processes. Userspace can only reference kernel objects via Handles.

Reference

KOID

A Kernel Object Identifier.

Kernel Object

Ledger

Ledger is a distributed storage system for Fuchsia. Applications use Ledger either directly or through state synchronization primitives exposed by the Modular framework that are based on Ledger under-the-hood.

LK

Little Kernel (LK) is the embedded kernel that formed the core of the Zircon Kernel. LK is more microcontroller-centric and lacks support for MMUs, userspace, system calls — features that Zircon added.

LK on Github

Module

A module is a role a component can play to participate in a story. Every component can be be used as a module, but typically a module is asked to show UI. Additionally, a module can have a module metadata file which describes the Module’s data compatibility and semantic role.

Module metadata format

Musl

Fuchsia’s standard C library (libc) is based on Musl Libc.

Namespace

A namespace is the composite hierarchy of files, directories, sockets, services, and other named objects which are offered to components by their environment.

Fuchsia Namespace Spec

Netstack

An implementation of TCP, UDP, IP, and related networking protocols for Fuchsia.

Ninja

Ninja is the build system executing Fuchsia builds. It is a small build system with a strong emphasis on speed. Unlike other systems, Ninja files are not supposed to be manually written but should be generated by other systems, such as GN in Fuchsia.

Outgoing directory

A file system directory where a component may expose capabilities for others to use.

Package

Package is an overloaded term. Package may refer to a Fuchsia Package or a GN build package.

Paver

A tool in Zircon that installs partition images to internal storage of a device.

Guide for installing Fuchsia with paver.

Platform Source Tree

The Platform Source Tree is the open source code hosted on fuchsia.googlesource.com, which comprises the source code for Fuchsia. A given Fuchsia system can include additional software from outside the Platform Source Tree by adding the appropriate Fuchsia Package.

Realm

In components v1, realm is synonymous to environment.

In components v2, a realm is a subtree of component instances in the component instance tree. It acts as a container for component instances and capabilities in the subtree.

Scenic

The system compositor. Includes views, input, compositor, and GPU services.

Sequential Device Driver

A sequential device driver is a hardware driver that will only service a single request at a time. The core driversynchronizes and serializes all requests.

Service

A service is an implementation of a FIDL interface. Components can offer their creator a set of services, which the creator can either use directly or offer to other components.

Services can also be obtained by interface name from a Namespace, which lets the component that created the namespace pick the implementation of the interface. Long-running services, such as Scenic, are typically obtained through a Namespace, which lets many clients connect to a common implementation.

Service capability

A capability that permits communicating with a service over a channel using a specified FIDL protocol. The server end of the channel is held by the component instance that provides the capability. The client end of the channel is given to the component instance that uses the capability.

Capability routing

Service capability is a components v2 concept.

Session

An interactive session with one or more users. Has a session shell, which manages the UI for the session, and zero or more stories. A device might have multiple sessions, for example if users can interact with the device remotely or if the device has multiple terminals.

Session Shell

The replaceable set of software functionality that works in conjunction with devices to create an environment in which people can interact with mods, agents and suggestions.

Storage capability

A storage capability is a capability that allocates per-component isolated storage for a designated purpose within a filesystem directory. Multiple component instances may be given the same storage capability, but underlying directories that are isolated from each other will be allocated for each individual use. This is different from directory capabilities, where a specific filesystem directory is routed to a specific component instance.

Isolation is achieved because Fuchsia does not support dotdot.

There are three types of storage capabilities:

data: a directory is added to the namespace of the component instance that uses the capability. Acts as a data directory.
cache: same as data, but acts as a cache directory.
meta: a directory is allocated to be used by component manager, where it will store metadata to enable features like persistent component collections.

Storage capability is a components v2 concept.

Capability routing

Story

A user-facing logical container encapsulating human activity, satisfied by one or more related modules. Stories allow users to organize activities in ways they find natural, without developers having to imagine all those ways ahead of time.

Story Shell

The system responsible for the visual presentation of a story. Includes the presenter component, plus structure and state information read from each story.

userboot

userboot is the first process started by the Zircon kernel. It is loaded from the kernel image in the same way as the vDSO, instead of being loaded from a filesystem. Its primary purpose is to load the second process, bootsvc, from the bootfs.

Documentation

Virtual Dynamic Shared Object

The Virtual Dynamic Shared Object (vDSO) is a Virtual Shared Library — it is provided by the Zircon kernel and does not appear in the filesystem or a package. It provides the Zircon System Call API/ABI to userspace processes in the form of an ELF library that’s “always there.” In the Fuchsia SDK and Zircon DDK it exists as libzircon.so for the purpose of having something to pass to the linker representing the vDSO.

Virtual Memory Address Range

A Virtual Memory Address Range (VMAR) is a Zircon kernel object that controls where and how Virtual Memory Objects may be mapped into the address space of a process.

VMAR Overview

Virtual Memory Object

A Virtual Memory Object (VMO) is a Zircon kernel object that represents a collection of pages (or the potential for pages) which may be read, written, mapped into the address space of a process, or shared with another process by passing a Handle over a Channel.

VMO Overview

Zircon Boot Image

A Zircon Boot Image (ZBI) contains everything needed during the boot process before any drivers are working. This includes the kernel image and a RAM disk for the boot filesystem.

ZBI header file

Zedboot

Zedboot is a recovery image that is used to install and boot a full Fuchsia system. Zedboot is actually an instance of the Zircon kernel with a minimal set of drivers and services running used to bootstrap a complete Fuchsia system on a target device. Upon startup, Zedboot listens on the network for instructions from a bootserver which may instruct Zedboot to install a new OS. Upon completing the installation Zedboot will reboot into the newly installed system.

Zircon

Zircon is the microkernel and lowest level userspace components (driver runtime environment, core drivers, libc, etc) at the core of Fuchsia. In a traditional monolithic kernel, many of the userspace components of Zircon would be part of the kernel itself.

ZX

ZX is an abbreviation of “Zircon” used in Zircon C APIs/ABIs (zx_channel_create(), zx_handle_t, ZX_EVENT_SIGNALED, etc) and libraries (libzx in particular).

ZXDB

The native low-level system debugger.

Reference

作者 east

Fuchsia 6月 29,2019

Fuchsia 行为准则

Google和Fuchsia团队致力于保护和培养多元化，热情的社区。以下是我们的社区行为准则，适用于我们的回购和组织，邮件列表，博客内容，IRC频道和任何其他由Fuchsia支持的通信组，以及在这些空间环境中发起的任何私人通信。简而言之，社区讨论应该是

尊重和善良;
关于Fuchsia;
关于功能和代码，而不是涉及的个人。
要有尊重和建设性。
尊重每一个人。建立彼此的想法。我们每个人都有权享受我们的经验和参与，而不必担心骚扰，歧视或屈尊俯就，无论是公然的还是微妙的。请记住，Fuchsia是一个地理位置分散的团队，您可能无法与他们的主要语言的人沟通。在处理困难问题时，我们都会感到沮丧，但我们不能让这种挫败感变成人身攻击。

如果您看到或听到某些声音，请说出来。
当您认为自己或他人不受尊重时，您有权礼貌地参与。让你感到不舒服的人可能不知道他们在做什么 – 鼓励他们礼貌地引起他们的注意。

如果您感到不舒服，或者认为您的问题未得到适当考虑，您可以发送电子邮件至fuchsia-community-managers@google.com，请求社区经理参与。与社区经理共享的所有问题都将保密，但您也可以在此处提交匿名报告。请注意，如果没有办法与您联系，匿名报告可能难以采取行动。您还可以创建一个一次性帐户进行报告。如果认为有必要进行公众回应，受害者和记者的身份将保密，除非这些人以其他方式指示我们。

虽然所有报告都将得到认真对待，但Fuchsia社区管理人员可能不会对他们认为不违反本行为准则的投诉采取行动。

我们不会容忍任何形式的骚扰，包括但不限于：
骚扰评论
恐吓
鼓励一个人进行自我伤害。
线程，频道，列表等的持续中断或脱轨
冒犯或暴力评论，笑话或其他
不恰当的性内容
不受欢迎的性关注或其他积极的关注
请求停止后继续进行一对一通信
分发或威胁分发人们的个人识别信息，AKA“doxing”
未遵守此政策的后果
不遵守此政策的后果可能包括由Fuchsia社区经理自行决定：

请求道歉;
私人或公共警告或谴责;
暂时禁止邮件列表，博客，Fuchsia存储库或组织，或其他由Fuchsia支持的通信组，包括失去提交者身份;
永久禁止任何上述内容，或来自所有当前和未来的Fuchsia支持或Google支持的社区，包括失去提交者身份。
与会者警告说，任何骚扰行为都应立即停止;如果不这样做，将导致后果升级。可以通过fuchsia-community-appeals@google.com对Fuchsia社区经理的决定提出上诉。

致谢
本行为准则改编自Chromium行为准则，基于极客女权主义行为准则，Django行为准则和极客女权主义维基“有效行为准则”指南。

作者 east