2019年6月 – gitweixin

Fuchsia 6月 29,2019

Fuchsia源代码

Fuchsia uses the jiri tool to manage git repositories https://fuchsia.googlesource.com/jiri. This tool manages a set of repositories specified by a manifest.

See Source code layout for an overview of how the code is organized.

For how to build, see Fuchsia’s Getting Started doc.

Creating a new checkout

The bootstrap procedure requires that you have Go 1.6 or newer and Git installed and on your PATH.

This script will bootstrap a development environment for by first creating directories fuchsia.

curl -s "https://fuchsia.googlesource.com/fuchsia/+/master/scripts/bootstrap?format=TEXT" | base64 --decode | bash

This script will set up your development environment to track the HEAD of the fuchsia repository. If you wish to track a different repository at HEAD, you can use the fx set-petal command.

Setting up environment variables

Upon success, the bootstrap script should print a message recommending that you add the .jiri_root/bindirectory to your PATH. This will add jiri to your PATH, which is recommended and is assumed by other parts of the Fuchsia toolchain.

Another tool in .jiri_root/bin is fx, which helps configuring, building, running and debugging Fuchsia. See fx help for all available commands.

You can also source scripts/fx-env.sh, but sourcing fx-env.sh is not required. It defines a few environment variables that are commonly used in the documentation, such as $FUCHSIA_DIR, and provides useful shell functions, for instance fd to change directories effectively. See comments in scripts/fx-env.sh for more details.

Working without altering your PATH

If you don’t like having to mangle your environment variables, and you want jiri to “just work” depending on your current working directory, just copy jiri into your PATH. However, you must have write access (without sudo) to the directory into which you copy jiri. If you don’t, then jiri will not be able to keep itself up-to-date.

cp .jiri_root/bin/jiri ~/bin

To use the fx tool, you can either symlink it into your ~/bin directory:

ln -s `pwd`/scripts/fx ~/bin

or just run the tool directly as scripts/fx. Make sure you have jiri in your PATH.

Who works on the code

In the root of every repository and in many other directories are OWNERS files. These list email addresses of individuals who are familiar with and can provide code review for the contents of the containing directory. See owners.md for more discussion.

How to handle third-party code

See the guidelines on writing the metadata for third-party code in README.fuchsia files.

Troubleshooting

Authentication errors

If you see an error when you check out the code warning you about Invalid authentication credentials, you likely have a cookie in your $HOME/.gitcookies file that applies to repositories that jiri tries to check out anonymously (likely in the domain .googlesource.com). You can follow the onscreen directions to get passwords for the specific repositories, or you can delete the offending cookie from your .gitcookies file.

作者 east

Fuchsia 6月 29,2019

Fusia开发指南

本文档是与开发Fuchsia和在Fuchsia上运行的软件相关的所有Fuchsia文档的顶级入口点。

开发工作流程

本节介绍用于构建，运行，测试和调试Fuchsia以及在Fuchsia上运行的程序的工作流程和工具。

Getting started – 从这里开始. 本文档介绍如何获取源，构建和运行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片状政策

This document codifies the best practice for interacting with test flakes on Fuchsia.

Background: What is a flaky test?

A flaky test is a test that sometimes passes and sometimes fails, when run using the exact same revision of the code.

Flaky tests are bad because they: – Risk letting real bugs slip past our commit queue (CQ) infrastructure. – Devalue otherwise useful tests. – Increase the failure rate of CQ, increasing latency for modifying code.

This document is specific to test flakes, not infrastructure flakes.

Requirements: Goals for flaky tests

Flakes should be removed from the critical path of CQ as quickly as possible.
Since flakes present themselves as a failing test, flakes should not be ignored once taken off of CQ. They represent a real problem that should be fixed.
Tests may flake at any time, and as a consequence, the observer of these bugs may not necessarily be the person best equipped to fix it. The process for reporting bugs must be fast, easy, and decoupled from diagnosis and patching.

Policy

The process for identifying and fixing flake is intentionally decoupled from between two parties:

Observer: An individual who has witnessed flake on bots.

Resolver: An individual who has the ability to remove flake from the bots.

This separation satisfies requirement (3): if someone contributes to Fuchsia, it is their responsibility to act as an observer for the entire codebase, and their responsibility to act as a resolver for code they touch.

We recommend the following four-step process for dealing with flakes: 1) Observer: Identify the flake. 2) Observer: File a bug under the FLK project. 3) Resolver: Disable the offending test immediately. 4) Resolver: Fix the offending test offline, re-enable the test.

Observer: Identify

Flake can appear in many locations: CQ dry-runs, an actual CQ run, or in the roller into global integration. In any of these cases, flake can be identified as a test that sometimes passes and sometimes fails, with the same revision of the codebase. When a test is identified this way, a log should be captured, providing context and revealing which subtest failed.

Observer: Bug

(Googlers-Only) File a bug under go/test-flake: Link to the failing bot, and include the name of the failing test.

Resolver: Disable

A resolver should prioritize, above all else, disabling the test from the commit queue. This can be achieved in a number of recommended ways:

If the flake has been prompted by a recent patch: Submitting a revert of a patch which triggers this flake.
Submitting a patch to disable the test explicitly.

These mechanisms are recommended: They remove the faulty test, and prevent the commit queue becoming unreliable. The first option (reverting code) is preferred, but it is not as easy as the second option (disabling test), which reduces test coverage. Importantly, neither of these options prevent diagnosis and fixing of the flake, but they allow it to be processed offline.

There is a third alternative to disable tests, but it is explicitly not recommended:

Finding a fix for the flake and resolving it directly.

This alternative is not recommended, because it combines the steps of “disable the test” with “fixing the test offline”. Although this is the most straight-line path for removing flake, it has a serious cost: it causes the CQ to be unreliable for all other contributors, which allows additional flakes to compound in the codebase.

Resolver: Fix Offline

At this point, the resolver can take the bug filed by the observer, locally re-enable the test, and work on reproducing the failure. This will enable them to find the root cause, and fix the issue. Once the issue has been fixed, the bug can be closed, and the test can be re-enabled. If any reverted patches need to re-land, they can re-land safely.

Improvements and Tooling

Ongoing efforts to improve tooling surrounding flake are currently in progress.

These include:

Automatically filing flake bugs, removing the “Observer” role from the path to identify flakes.
Automatically assigning flake bugs, based information present in OWNERs files.
Tracking flake rates over time, to determine “liveness” of flake bugs filed.
“FYI” bots, which can still continue executing known-flaky tests.
“Deflaking” infrastructure, to re-run tests in high volume before they are committed.

When these improvments are available, this document will update to include the adjusted policy.

作者 east

Fuchsia 6月 29,2019

所有文档的一般风格指南

It is important to create documentation that follows similar guidelines. This allows documentation to be clear and concise while allowing users to easily find necessary information. For information about the complete documentation standards, see Documentation Standards.

These are general style guidelines that can help create clearer documentation:

Write in plain U.S. English. You should write in plain U.S. English and try to avoid over complicated words when you describe something.
Avoid using pronouns such as “I” or “we”. These can be quite ambiguous when someone reads the documentation. It is better to say “You should do….” instead of “We recommend that you do….”. It is ok to use “you” as this allows the documentation to speak to a user.
If you plan on using acronyms, you should define them the first time you write about them. For example, looks good to me (LGTM). Don’t assume that everyone will understand all acronyms. You do not need to define acronyms that might be considered industry standards such as TCP/IP.
In most cases, avoid future tense. Words such as “will” are very ambiguous. For example “you will see” can lead to questions such as “when will I see this?”. In 1 minute or in 20 minutes? In most cases, assume that when someone reads the documentation you are sitting next to them and reading the instructions to them.
Use active voice. You should always try to write in the active voice since passive voice can make sentences very ambiguous and hard to understand. There are very few cases where you should use the passive voice for technical documentation.
- Active voice – the subject performs the action denoted by the verb.
- “The operating system runs a process.” This sentence answers the question on what is happening and who/what is performing the action.
- Passive voice – the subject is no longer active, but is, instead, being acted upon by the verb – or passive.
- “A process is being run.” This sentence is unclear about who or what is running the process. You might consider “a process is run by the operating system”, but the object of the action is still made into the subject of the sentence which indicates passive voice. Passive voice tends to be wordier than active voice, which can make your sentence unclear. In most cases, if you use “by” this indicates that your sentence might be still be in passive voice. A correct way of writing this example is “The operating systems runs the process.”
Do not list future plans for a product/feature. “In the future, the product will have no bugs.” This leads to the question as to when this would happen, but most importantly this is not something that anyone can guarantee will actually happen.
Do not talk about how certain features work behind the covers unless it is absolutely necessary. Always ask yourself, “Is this text necessary to understand this concept or to get through these instructions?” This also leads to shorter (less maintenance) and more concise (happier readers) documentation.
Avoid using uncommon words, highly technical words, or jargon that users might not understand. Also, avoid using idioms such as “that’s the way the cookie crumbles”, while it might make sense to you, it could not translate well into another language. Keep in mind that a lot of users are non-native English speakers.
Use compound words correctly. Use the compound words that give the correct meaning. For example, “set up” (verb) and “setup” (noun) have different meanings.
Avoid using words such as “best” or “great” since these are all relative terms. How can you prove that “this operating system is the best?”
Avoid referencing proprietary information. This can refer to any potential terminology or product names that may be trademarked or any internal information (API keys, machine names, etc…)
Avoid starting a sentence with “this” since it is unclear what “this” references.
- For example: “The operating system is fast and efficient. This is what makes it well designed.” Does “this” refer to fast, efficient, or operating system? Consider using: “The operating system is well designed because it is fast and efficient”.
Keep sentences fairly short and concrete. Using punctuation allows your reader to follow instructions or concepts. If by the time you read the last word of your sentence, you can’t remember how the sentence started, it is probably too long. Also, short sentences are much easier to translate correctly.
Know your audience. It is good practice to know your audience before you write documentation. Your audience can be, for example, developers, end-users, integrators, and they can have varying degrees of expertise and knowledge about a specific topic. Knowing your audience allows you to understand what information your audience should be familiar with. When a document is meant for a more advanced audience, it is best practice to state it up front and let the user know prerequisites before reading your document.
Use markdown. You must create documentation in markdown (.md) and keep the markdown file wrapped to a 80 character column size.

作者 east

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

月度归档6月 2019