/HEAD/docs/ 中.
+ 在 `/docs/` 目录下，您应当在以下子目录之一内创建文档：
+
+ * get-started:
+
+ 有关下载、设置、开始 Fuchsia 开发的具体指南应当放进 `/get-started`。这类内容应当包含观点明确的、简短的教程，以帮助新用户入门 Fuchsia，并在 Fuchsia.dev 中链接至附加文档。
+ * development:
+
+ `/development/` 目录（在网站上显示为“指南”（Guides））中包含了针对Fuchsia开发者的说明和教程。该目录包含关于如何构建、运行和测试 Fuchsia 的文档。
+ * concepts:
+
+ `/concepts` 目录包含针对 Fuchsia 具体特性及其工作原理的深入解释，包括操作系统概述、框架、架构和软件包（package）。
+ * reference:
+
+ `/reference/` 目录包含自动生成的关于 Fuchsia 工具和 API 的参考文档，包括 FIDL 和内核的参考文档。
+ * contribute:
+
+ `/contribute/` 目录包含代码和文档的贡献进度以及最佳做法，包含文档准则和风格指南、代码策略以及管理体系。
+ * `images`
+
+ `/images/` 目录包含在文档中使用的图像。您应当将图像放在这一公共目录中。
+
+
+## 文档类型
+
+
+大多数文档可以分为以下几类：
+
+
+- [程序性的](documentation-types.md#procedural-documentation)
+ - 入门 - 初始设置的文档
+ - 指南 - 任务导向的文档
+
+
+- [概念性的](documentation-types.md#conceptual-documentation) - 多侧重于教授 Fuchsia、Fuchsia 架构和 Fuchsia 组件的基础性文档
+
+
+- [参考文档](documentation-types.md#reference-documentation) - 侧重于详细说明 Fuchsia API 和 工具的语法和参数的文档。这类文档通常自动生成。
+
+
+要获取更多信息，请参阅[文档类型](documentation-types.md)。
+
+
+## 文档和代码风格指南
+
+
+为确保由大量贡献者创建的文档都保持一致性，遵循文档风格指南很重要。要获取具体文档指导，请参阅[文档风格指南](documentation-style-guide.md)；要获取代码样例指导，请参阅[代码样例风格指南](code-sample-style-guide.md)。
+
+
+
+## 搜索的最佳做法
+
+文档只有在用户能查到的时候才算有用。下面是一些关于可查性和搜索的最佳做法：
+
+ - 将您的文档添加至目录：在 fuchsia.dev 的左侧导航中添加文档链接。要获取更多信息，请参阅[网站导航和目录文件](documentation-navigation-toc.md)
+
+- 交叉链接文档：添加指向文档主题的链接，以帮助读者更好地理解文档的内容。 例如，[Fuchsia 模拟器] (/development/build/emulator.md) 的概念文档链接到有关 Fuchsia 模拟器的相关指南和入门文档。
+
+- 使用一致的术语：如果您在撰写有关 Fuchsia 中特定概念的文章，请确认您使用的是一致的术语。 使用[术语表](/glossary/README.md)来验证用语。
+
+
+## 文档的文件格式和文件名
+
+
+Fuchsia 的所有文档均使用 Markdown（`.md`）撰写，Fuchsia.dev 使用 [Hoedown Markdown Parser](https://github.com/hoedown/hoedown) 作为 Markdown 文档语法分析器。
+
+
+该网站的导航是由 `_toc.yaml` 文件配置的，该文件包含在每个文档目录中。请使用[网站导航和目录文件](documentation-navigation-toc.md)中的指导来更新这些文件。
+
+
+文件和目录名应当为小写，并使用短横线（hyphen）而非下划线（underscore）来分隔单词。在文件或目录名中请仅使用标准 ASCII 字母数字字符。如果文件名包含带有下划线的命令，那么您可以包含下划线。
+
+
+## 语言风格总体指导
+
+
+- **使用通俗易懂的美国英语撰写。** 使用清晰、直白的美国英语撰写，以使内容易于理解。请使用简单的词汇，保持简洁，并使用（常见）缩写，如 _it's_ 或 _don't_。
+
+- **心怀敬意。** 请遵循[尊重性规范](/contribute/respectful_code.md)中规定的方针。
+
+- **使用第二人称（“you”）撰写。** Fuchsia文档是写给用户（“you”）的。例如，“您（you）可以通过以下步骤安装 Fuchsia……”。不要使用第三人称称呼读者（“Fuchsia 用户可以通过……安装 Fuchsia”）或使用“we”（“我们（we）可以通过……安装 Fuchsia”）。
+
+- **使用现在时态撰写。** 请在记录系统时始终立足眼下（it is），而非未来（it will be）。类似“will”之类的词语非常含糊。例如“您将看到”这种说法将引起如“我何时将会看到？”之类的问题。1分钟，还是20分钟呢？另外，若非必要，请不要提及未来的产品特性。提及可能取消的未来计划将导致维护上的困难。
+
+- **保持语句简短具体。** 使用标点符号可以便于您的读者跟进说明、理解概念。而且，短句更易于翻译。
+
+- **了解您的受众群体。** 在撰写文档之前，请确定好您的受众群体。了解受众群体使您能够明确他们应当熟悉的概念。当撰写面向更高级受众群体的文档时，请在文档前声明，让用户了解这一前提后，再进行阅读。
+
+- **使用主动语态。** 请尽量使用主动语态写作，因为被动语态会使句子模棱两可且难以理解。 下面是一个例子：
+ - 主动语态：“操作系统运行一个进程。”（The operating system runs a process.）在这种情况下，主语执行动词表示的动作。
+ - 被动语态：“一个进程正在被运行。”（A process is being run.）主语不再是“主动的”（_active_），而是被动词作用——它是“被动的”（_passive_）。
+ 大多数情况下，如果您使用了“by”，那么您的句子可能仍然是被动语态。
+
+
+- **若使用首字母缩写词，请您在第一次书写时进行定义。** 例如，looks good to me（LGTM，我觉得看起来很好）。不要认为每个人都理解所有的首字母缩写词。您不需要定义工业标准首字母缩写词，如 TCP/IP。
+
+
+- **定义技术术语，回避行话。** Fuchsia 文档应当易于各个层次的开发者理解。请避免使用不常用或高度技术性词语而使得文章过于复杂。如果您使用了 Fuchsia 特定的术语，请在[术语表](/glossary/README.md)中对其进行定义。请回避自造词。
+
+
+- **回避口头表达或地区习语。** 请记住，许多 Fuchsia 用户并非英语母语者。请避免使用难于翻译的习语，例如“that's the way the cookie crumbles.”（生米已成熟饭/覆水难收）虽然对您而言能够理解，但是很难准确地翻译到其他语言中。
+
+
+- **避免引用专有信息。** 这里指的是任何可能是已注册商标的任何潜在词语或您公司的任何内部信息（API 密钥、机器名等）。
+
+
+- **使用性别中立代词。** 请不要使用 _he_，_him_，_his_，_she_ 或 _her_，也不要使用 _he/she_ 或 _(s)he_ 等其他类似的符号表达方式。取而代之，请使用单数的 _they_。
+
+
+- **使用一致的术语。** 确保术语在代码、用户界面和文档中是一致的。尽可能使用常见术语，并使用[术语表](/glossary/README.md)来验证用语。
diff --git a/contribute/docs/documentation-style-guide.md b/contribute/docs/documentation-style-guide.md
index 4c182bb5..5b750e55 100644
--- a/contribute/docs/documentation-style-guide.md
+++ b/contribute/docs/documentation-style-guide.md
@@ -1,13 +1,23 @@
+
+# 文档风格指南
+
+本文档给出了针对 Fuchsia.dev 写作风格的指南。这些方针基于[Google 开发者风格指南][google-dev-doc-style-guide]中的通用指导。
+
+注意：本指南重点介绍了为 Fuchsia 编写文档的一些最佳做法。其中的某些主题在以下文档的资源中可能会得到更为广泛的探讨：
+
+* 要获取关于通用文档标准的信息，包括文件类型、位置和整体语言风格，请参阅 [Fuchsia 文档标准][doc-standard]。
+* 要获取关于措辞、风格和结构的具体指导，请参阅 [Fuchsia 文档风格指南][style-guide]。
+* 要获取完整的 Markdown 参考指南，请参阅 [Markdown 参考指南][markdown-guide]。
+
+## 文字和链接
+
+### 遵循 80 字符限制
+
+在 Fuchsia 项目中，代码的行最大长度为 100 字符，而文档的行最大长度为 80 字符。该规则一个值得注意的例外情况是网址（即链接），写在一行中，不换行。
+
+代码常使用缩进（页面左侧的空格），而英文散文（文档）多形成文字段落。这种差异导致了不同的宽度规格。
+
+### 标记外部链接
+
+请使用 `{:.external}` 标记任何不属于 `fuchsia.dev`、
+`fuchsia.googlesource.com` 或 `fuchsia-review.googlesource.com` 的链接：
+
+```none
+这是一个[外部](http://example.com){:.external}链接。
```
+
+注意外部链接标志：这是一个[外部][external-link-example]{:.external}链接。
+
+### 使用参考风格的链接
+
+一般来说，Fuchsia 建议在 Markdown 文件中使用参考风格（reference-style）的链接。 参考风格链接使用与链接相关联的参考标识符，接下来每当您在文档中使用该链接时，即可引用该标识符。这使得文档中的链接易于更新。
+
+推荐：请在您需要链接的位置创建标识符。
+
+
+本例中，链接标识符称为 `fuchsia-home`：
+
+```none
+欢迎来到 [Fuchsia 首页][fuchsia-home]。
```
+
+
+接着在文档底部对其定义：
+
[fuchsia-home]: https://fuchsia.dev/``` 后添加 `posix-terminal` 能让读者更容易复制代码块中的内容。
+
```posix-terminal
@@ -149,66 +283,127 @@ fx ota
```
+
+该代码块在渲染时，命令前会出现 `$`：
```posix-terminal
fx ota
```
+
+不推荐：请勿在命令里硬编码 `$` 字符。
```sh
$ fx ota
```
+
+### 使用 none 以禁用复制功能
+
+推荐：对于不需要读者复制内容的代码或输出样例，请在 ``` 后添加 `none {:.devsite-disable-click-to-copy}`。
+
+
+```none {:.devsite-disable-click-to-copy}
+$ my_command
+不必复制和粘贴该代码块。
+```
+
+该代码块在渲染时，右上角没有复制标志：
+
+ ```none {:.devsite-disable-click-to-copy}
+$ my_command
+不必复制和粘贴该代码块。
```
+
+不推荐：为只需查看的内容启用复制功能。如果您在 ``` 之后不指定任何内容，那么复制功能默认是启用的。
+
+
+```
+$ my_command
+不必复制和粘贴该代码块。
+```
+
+该代码块渲染为如下形式：
+
+```
+$ my_command
+不必复制和粘贴该代码块。
```
+
+### 引用源代码时使用路径，不要使用网址
+
+推荐：任何引用源代码的链接应当仅使用路径引用。否则您将收到静态错误检查（static error check）。
+
++更新[状态标头][sh] +[sh]: /zircon/system/ulib/inspect/include/lib/inspect/cpp/vmo/state.h@@ -220,4 +415,4 @@ Update the [state header][sh] [google-dev-doc-style-guide]: https://developers.google.com/style [markdown-reference-links]: /contribute/docs/markdown.md [external-link-example]: http://example.com -[fuchsia-dev]: https://fuchsia.dev \ No newline at end of file +[fuchsia-dev]: https://fuchsia.dev diff --git a/contribute/governance/rfcs/0001_rfc_process.md b/contribute/governance/rfcs/0001_rfc_process.md index fc97df8f..728cc74b 100644 --- a/contribute/governance/rfcs/0001_rfc_process.md +++ b/contribute/governance/rfcs/0001_rfc_process.md @@ -27,7 +27,7 @@ establishing a consistent and transparent path for making project-wide, technical decisions, all the stakeholders can be confident about the technical direction of the project. --> -现在，Fuchsia 项目在项目级别的技术决定上并没有一个正式的工作流程。以我们目前的规模来说，这样的非正式性导致了不同的人在项目方向和如何组合系统上有着不同的看法。 通过建立这样一个一致且透明的项目标准， 所有的利益相关者都能够在项目的技术方向充满信息。 +现在，Fuchsia 项目在项目级别的技术决定上并没有一个正式的工作流程。以我们目前的规模来说，这样的非正式性导致了不同的人在项目方向和如何组合系统上有着不同的看法。 通过建立这样一个一致且透明的项目标准， 所有的利益相关者都能够在项目的技术方向充满信心。 @@ -72,7 +72,7 @@ The following kinds of changes must use the RFC process: changing the set of supported languages impacts everyone who needs to debug and understand the system, even if not everyone uses the new language. --> - * **制订项目政策。** 项目政策对系统有着广泛的影响，常常影响着项目贡献者。比如，修改支持的（编程）语言集，会影响需要调试和理解系统的人员，即使并不是所有的人都使用新语言。 + * **制定项目政策。** 项目政策对系统有着广泛的影响，常常影响着项目贡献者。比如，修改支持的（编程）语言集，会影响需要调试和理解系统的人员，即使并不是所有的人都使用新语言。 -### 步骤二：起草 {#draft} +#### 第二步：起草 {#draft} -在这个阶段不必担心您的 RFC 的序号。反之，请使用 `NNNN` 做为占位符。比如，一个文件的名字应该是 `NNNN_my_idea.md` 这种形式。RFC 文档会在合并之前不久获得一个序号。 +在这个阶段不必担心您的 RFC 的序号。反之，请使用 `NNNN` 作为占位符。比如，一个文件的名字应该是 `NNNN_my_idea.md` 这种形式。RFC 文档会在合并之前不久获得一个序号。 -> **建议。** 您可以在准备好接收反馈之前，先把包含 RFC 的 CL 标记为“进行中”。 +> **建议：** 您可以在准备好接收反馈之前，先把包含 RFC 的 CL 标记为“进行中”。 -利益相关者将代码审查标志设为 -1 或者 -2 并不一定会阻止项目接收该 RFC。要获取关于 RFC 接受决定流程的更多细节，请参阅下面的[“决定如何做出”章节](#how-decisions-are-made) 。 +利益相关者将代码审查标志设为 -1 或者 -2 并不一定会阻止项目接受该 RFC。要获取关于 RFC 接受决定流程的更多细节，请参阅下面的[“决定如何做出”章节](#how-decisions-are-made) 。 - -## Summary - -In the past, `zx_task_kill` allowed usermode to kill individual threads. However, -killing individual threads encourages bad practices and has a high chance of leaving -the process in a bad state. For this reason, the ability to kill individual threads -should be removed. - -## Motivation and problem statement - -There is no reasonable use for usermode to kill individual threads. Exposing such facility -encourages bad practices. - -On Fuchsia, like other systems, killing a thread is done asynchronously; for running threads there -is no practical way to determine the exact place where it is safe to terminate a thread. For a -blocked (waiting) thread, the safer and often simple solution is to add logic so upon wakeup the -thread exits by itself. - -Dangers killing a thread - -* Locks can be left acquired, including global locks like ones controlling the heap. -* Memory can be leaked. At the very least the thread stack, but often many other pieces. -* Runtime left in an inconsistent state. This is at least true for the C and Go runtime. -* Killing a thread in its way to a syscall leaves the process in an unknown state. Kernel is - fine but the process does not have a way to know what happened and what did not happen. -* Defeats RAII wrappers and automatic cleanup. In fact, it defeats most guarantees from the high - level languages Fuchsia uses. - -## Design - -The following syscall will fail with `ZX_ERR_NOT_SUPPORTED` when passed a handle to a thread: - -``` -zx_status_t zx_task_kill(zx_handle_t handle); -``` - -Processes and jobs will still be killable as normal. - -## Implementation - -Luckily, thread killing is not used very much in Fuchsia. The only use cases are in test code -that checks that a thread hits a specific exception. This code is going to be updated so that -the excepting thread exits itself after the exception is handled. For code where the exception -is unrecoverable, the excepting thread's instruction pointer can be set directly to -zx_thread_exit or the runtime's thread exit function before the thread resumes. These tests -may still leak what the excepting thread had stored on the heap, but the runtime is in -a better state, and the leaks will be collected when the test's process exits. - -## Performance - -N/A - -## Security considerations - -N/A - -## Privacy considerations - -N/A - -## Testing - -The zircon core-tests will be updated to ensure that the zx_task_kill syscall behaves as intended. -Some amount of static analysis can be done to find call sites of zx_task_kill that are passed -threads. - -The full Fuchsia Large Scale Change (LSC) process will be followed to ensure this change is -properly tested. - -## Documentation - -The documentation for [zx_task_kill](/reference/syscalls/task_kill.md) will be updated to -reflect that threads are not killable. - -## Drawbacks, Alternatives, and Unknowns - -The alternative to this proposal is the current status quo, which is to allow threads to be -killed. Threads have been killable for the entire history of Fuchsia, but there has not been -any acceptable use cases where programs have relied on this behavior. For this reason, -we believe that thread killing can be safely removed. - -## Prior art and references - -* [Windows Vista tries to remove -TerminateThread](https://devblogs.microsoft.com/oldnewthing/20150814-00/?p=91811) +{% set rfcid = "RFC-0007" %} +{% include "docs/contribute/governance/rfcs/_common/_rfc_header.md" %} +# {{ rfc.name }}: {{ rfc.title }} + + + +## 概述 + + +过去，`zx_task_kill` 允许在用户态杀死单个线程。但是，杀死单个线程会为不良做法提供支持，并且很有可能使进程处于不良状态。出于这个原因，应该删除杀死单个线程的能力。 + + +## 动机与问题陈述 + + +对于用户态而言，杀死单个线程的做法没有合理用途。暴露此类能力会为不良做法提供支持。 + + +在 Fuchsia 上，和其他系统一样，杀死一个线程是异步完成的；对于正在运行的线程，没有实用的方法来确定可安全终止线程的确切位置。对于阻塞（等待）状态的线程，通常更安全且简单的解决方案是添加逻辑，以便在唤醒后线程自行退出。 + + +杀死线程的危险 + + +* 锁可以被保持获取，包括像控制堆这样的全局锁。 +* 内存可能会泄漏。至少线程堆栈可能泄漏，但通常还有许多其他部分的内存会泄漏。 +* 运行时处于不一致的状态。至少对于 C 和 Go 运行时来说是这样。 +* 以系统调用的方式杀死一个线程会使进程处于未知状态。这对内核没有影响，但该进程无法知道发生了什么以及没有发生什么。 +* 破坏 RAII 包装器和自动清理。事实上，它破坏了 Fuchsia 使用的高级语言的大多数保证机制。 + + +## 设计 + + +当将句柄被传递给线程时，以下系统调用将失败并返回`ZX_ERR_NOT_SUPPORTED`： + +``` +zx_status_t zx_task_kill(zx_handle_t handle); +``` + + +进程和作业仍然可以正常地被杀死。 + + +## 实现 + + +幸运的是，Fuchsia 中并没有太多使用到杀死线程。唯一的用例是在检查线程是否遇到特定异常的测试代码中。此代码将被更新，以便异常线程在异常被处理后自行退出。对于异常无法恢复的代码，可以在线程恢复前，将异常线程的指令指针直接设置为 zx_thread_exit 或运行时的线程退出函数。这些测试可能仍然会泄漏异常线程存储在堆上的内容，但运行时会处于一个更好的状态，并且会在测试的进程退出时收集泄漏的内容。 + + +## 性能 + +N/A + + +## 安全性考虑 + +N/A + + +## 隐私问题 + +N/A + + +## 测试 + + +Zircon 核心测试将被更新，以确保 zx_task_kill 系统调用按预期运行。可以进行一些静态分析来找到传递线程的 zx_task_kill 的调用点。 + + +将遵循完整的 Fuchsia 大型变更（Large Scale Change，LSC）流程，以确保这一变化被正确测试。 + + +## 文档 + + +[zx_task_kill](/reference/syscalls/task_kill.md) 的文档将被更新以反映线程不可杀死。 + + +## 缺点、替代方案和未知因素 + + +该提议的替代方案是当前的现状，即允许线程被杀死。在 Fuchsia 的整个历史中，线程都是可以被杀死的，但是没有任何可接受的用例表明程序依赖于这种行为。出于这个原因，我们相信可以安全地删除线程杀死功能。 + + +## 现有技术和参考文献 + + +* [Windows Vista 尝试移除 TerminateThread 方法](https://devblogs.microsoft.com/oldnewthing/20150814-00/?p=91811) diff --git a/development/hardware/README.md b/development/hardware/README.md index c8f52c71..b4f9ddac 100644 --- a/development/hardware/README.md +++ b/development/hardware/README.md @@ -1,34 +1,73 @@ + +# 在设备上安装 Fuchsia + +Fuchsia 平台能够安装在以下硬件设备上： + +- [Chromebook][install-fuchsia-on-chromebook] +- [Intel NUC 迷你电脑][install-fuchsia-on-nuc] +- [Khadas VIM3 开发板][install-fuchsia-on-vim3] + +## 架构支持 + +Fuchsia 支持两种指令集（Instruction Set Architecture，ISA）： + +* `arm64`——Fuchsia 在受支持的微处理器上，对 `arm64`（也称为 AArch64）的支持没有限制。 + +* `x86-64`——Fuchsia 在受支持的微处理器上，对 `x86-64`（也称为 IA32e 或 AMD64）的支持有一定限制。 + +## CPU 支持 + +Fuchsia 对于 CPU 的支持： + +* Intel——对于 Intel CPU，只有 Broadwell 及更高版本是受到主动支持的，并且会添加新的功能。另外，我们将接受补丁，以保持 Nehalem 及更高版本正常引导。 + +* AMD——AMD CPU 是**不**受主动支持的（具体地，我们对其没有进行主动测试），但是我们将接受补丁，以确保其正确引导。 + +## 目录 + +- [在 Chromebook 上安装 Fuchsia][install-fuchsia-on-chromebook] +- [在 NUC 迷你电脑上安装 Fuchsia][install-fuchsia-on-nuc] +- [在 NUC 迷你电脑上使用 Zedboot（旧版）安装 Fuchsia][install-fuchsia-on-nuc-legacy] +- [在 Khadas VIM3 开发板上安装 Fuchsia][install-fuchsia-on-vim3] +- 创建 Fuchsia 可引导镜像： + - [从 USB 闪存驱动器安装 Fuchsia][prepare-usb] + - [使用 Fuchsia 安装程序（旧版）][use-the-installer-legacy] +- 设置实验性硬件： + - [在 Acer Switch Alpha 12 上安装 Fuchsia][install-fuchsia-on-acer12] + - [在 Toulouse 上安装 Fuchsia][install-fuchsia-on-toulouse] diff --git a/development/hardware/acer12.md b/development/hardware/acer12.md index 15043e12..a5e18252 100644 --- a/development/hardware/acer12.md +++ b/development/hardware/acer12.md @@ -1,27 +1,81 @@ + +# 宏碁 Switch Alpha 12 + +警告：这些说明是用于配置本机器并在其上启动一个实验性、开发中的操作系统。 + +## 打开机器电源 + +您必须按住电源按钮（左侧，音量摇杆上方）几秒钟，然后松开，从而启动。电源按钮本身上的微小蓝灯亮起时（是的，当您按住电源按钮时很难看到这个灯），或者当显示屏背光亮起时，您可以放心地松开。如果您按得太久，它可能会再次关闭电源。 + +## 关闭机器电源 + +如果您启动到了 Windows 10，或者某些东西挂起或崩溃了并且您需要关闭电源，请按住电源按钮直到显示屏关闭。请确保总共按住大约 10 秒钟。 + +## 进入 BIOS + +在机器关闭的情况下，按住音量加键，然后保持不松手并按住电源键。当显示屏背光亮起时松开电源键。另一种方法是，在打开机器电源时按住外接键盘上的 F2 键。 + +## 启用 Zircon 引导 + +1. 启动机器并进入 BIOS（基本输入输出系统） + +2. 从左侧的选项卡中选择“Security（安全）” + +3. 点击“Supervisor Password Is（管理员密码是）”下的“[clean]”灰色条 + +4. 输入管理员密码，并再次输入，然后按OK + +5. 从左侧的选项卡中选择“Boot（启动）” + +6. 点击“Secure Boot（安全启动）”下的“[Enabled]”灰色条（如果没有灰色条，则表示您尚未设置管理员密码，请返回并立即设置） + +7. 从菜单中选择“Disabled（已禁用）” + +8. 可以在每项右侧使用向上/向下箭头调整“Boot priority order（启动优先级顺序）”列表 + +9. 排列该列表成如下： - USB HDD - USB FDD - USB CDROM @@ -29,36 +83,108 @@ With the machine off, Press and hold Volume Up, then continue to hold while pres - Network Boot-IPV4 - Network Boot-IPV6 - Windows Boot Manager + +10. 选择左侧的“Main（主菜单）”选项卡，分别按“[SetTime]”和“[SetDate]”按钮设置时间和日期。这是想要正常使用网络所必需的操作。 + +11. （可选）返回“Security（安全）”选项卡并将管理员密码设置为空。否则每次使用 BIOS 时都需要输入密码。修改安全启动设置时需要密码，在没有密码时会持续显示“disabled（已禁用）”。 + +12. 从左侧的选项卡中选择“Exit（退出）” + +13. 选择“Exit Saving Changes（退出并保存更改）” + +14. 继续[使用 USB 闪存驱动器进行设置](usb_setup.md) + +## 如果您最终进入 Windows 10 设置怎么办？ + +如果您没有进入 BIOS 并且没有安装其他操作系统，您最终会出现蓝色背景的“Hi there”屏幕，要求您选择国家、语言等。 + +1. 请按住电源约 10 秒（屏幕将在 2-3 秒后关闭）。 + +2. 然后按上所述引导进入 BIOS。 + +## 如果您卡在 Windows 10 恢复中怎么办？ + +有可能最终出现这样的情况：机器真的想帮助您恢复失败的启动并进入 Windows 10，将您丢进了一个恢复屏幕——蓝色背景，屏幕左上方显示“Recovery（恢复模式）”，还有一段文字说 “It looks like Windows didn’t load correctly（Windows 似乎未正确加载）”。 + +1. 选择“See advanced repair options（查看高级修复选项）” + +2. 选择“Troubleshoot（疑难解答）”（螺丝刀和扳手图标） + +3. 选择“Advanced options（高级选项）”（复选标记和线条图标） + +4. 选择“UEFI Firmware Settings（UEFI 固件设置）”（电路板和齿轮图标） + +5. 当提示“Restart to change UEFI firmware settings（重新启动以更改 UEFI 固件设置）”时，选择“Restart（重新启动）” + +6. 机器现在应该重新启动进入 BIOS + +7. 检查“Windows Boot Manager（Windows 启动管理器）”没有被移到启动顺序的顶部，如果在顶部，请修改掉 + +## 怪症 + +据观察，USB 初始化在冷启动时有竞争问题。因此，如果您从冷启动开始并尝试启动到 USB，您可能会发现自己启动到的是磁盘。 + +缓解措施： + +- 一个很有用的技巧，使用 `cmdline` 文件设置 `zircon.nodename=foo` 以在启动屏幕期间了解您是从 USB 启动还是从磁盘启动。 + +- 如果宏碁从磁盘启动但您想从 USB 启动，请移除并重新插入 USB 驱动器，然后使用 `ctrl-alt-del`（不是电源按钮）重新启动。 + +- 您可以从 bios 中判断 USB 是否已初始化，因为它会命名 USB 设备。 diff --git a/development/hardware/chromebook.md b/development/hardware/chromebook.md index 64c43eab..c77ae54f 100644 --- a/development/hardware/chromebook.md +++ b/development/hardware/chromebook.md @@ -1,123 +1,281 @@ + +# 在 Chromebook 上安装 Fuchsia + + +## 支持的 Chromebook + +这些 Chromebook 开发者经常使用，应当是稳定支持的。 + +* Google Pixelbook Go（_atlas_） + +### 以前支持的 Chromebook + +这些 Chromebook 受到“尽力而为”的支持，并且不会受到定期测试。 + +* Google Pixelbook（_eve_） + +### 其他 ChromeOS 设备 + +其他基于 x86 的 ChromeOS 设备可能工作，也可能不会工作。基于 ARM 的 ChromeOS 设备无法开箱即用。 + +## 前提条件 + + +请确保您为 Fuchsia 进行了 `chromebook-x64` 构建。 + +1. 完成[下载 Fuchsia 源代码][get-fuchsia-source]指南。 +2. 请在[配置和构建 Fuchsia][build-fuchsia]中设置您的构建配置，以使用如下的 Chromebook 产品： ```posix-terminal fx set workstation_eng.chromebook-x64 --release ``` + +## 更新 ChromeOS + +如果您的 Chromebook 从未启动过，请您最好将其启动，以检查重要的更新，步骤如下： + +1. 正常启动 Chromebook。通常，打开盖子会启动设备。如果没有启动，请使用位于设备左侧、靠近腕托位置的电源按钮。 + +2. 点按“开始使用”（Let's go）按钮。 + +3. 连接到有线或无线网络。 + +4. 接受条款，以进入更新检查步骤。 + +5. 设备应当检查并安装找到的更新。 + + +6. 更新重启之后，点按左下角的“以访客身份浏览”（Browse as Guest）。 + + +7. 通过浏览器用户界面，前往“设置->关于 Chrome OS”（Settings->About Chrome OS）或“帮助->关于 Chrome OS”（Help->About Chrome +OS），确认新安装的版本。 + +## 为您的设备开启开发者模式 + +注意：这将会擦除保存在您 Chromebook 本地的任何状态。 + +1. 关闭 Chromebook 电源。 + +2. 进入恢复模式。同时按住 Esc+Refresh（键盘顶行的第一和第三个按钮）。接着按下电源按钮（设备的左下方）。 + +3. 按下 Ctrl+D，以在禁用 OS 验证的情况下启动。您应当看到“要关闭 OS 验证，请按下 ENTER。”（To turn OS verification OFF, press ENTER） + +4. 当您的设备重启时，您将收到 OS 验证已经关闭的确认信息。再次按下 Ctrl+D 进入开发者模式（Developer Mode）。 + +5. 等待设备自行完成重新配置，可能需要几分钟时间。设备最初可能看起来没有任何反应。请允许设备静置一到两分钟。在此过程的前期，您可能听到两次响亮的“哔”声。该过程在您再次听到两次响亮的“哔”声时完成。 + +6. 当开发者模式转换完成时，设备应当自行重启。现在您可以跳至“从 USB 启动”一节的步骤 #2 了。 + +## 从 USB 启动 + +1. 启动至 ChromeOS。 + +2. 您应当看到显示“OS 验证已关闭”（OS verification is OFF）的画面，在大约 30 秒后，启动会继续。请等待欢迎或登录界面加载。请**忽略**任何用于“启用调试功能”（Enable debugging features）的链接。 + +3. 按下 Ctrl+Alt+Refresh/F3 进入命令行界面。如果该组合键无效，请尝试再次重启 Chromebook。 + +4. 进入“chronos”用户，密码留空。 + +5. 运行 `sudo crossystem dev_boot_usb=1`，启用 USB 启动。 + +6. （**可选**）运行 `sudo crossystem dev_default_boot=usb`，将 USB 启动设为默认。 + +7. 将 USB 驱动器插入 Chromebook。 + +8. 键入 `sudo reboot` 进行重启。 + +9. 在“OS 验证已关闭”画面，按下 Ctrl+U 跳过超时等待并立即从 USB 启动。（要获取其他短路选项，请参阅[提示和技巧](#tips-and-tricks)） + +仅当您想要重新铺设（re-pave）或另行从网络启动设备时，才需要 USB 驱动器进行引导。 + +如果您未将 USB 启动设为默认（步骤 #6），那么在开机时，您将需要在灰色的“警告 OS 未验证”（warning OS-not verified）画面按下 Ctrl+U，以从 USB 启动。 + +如果设备试图从 USB 启动（可能是因为您将其设为了默认，或按下了 Ctrl+U）失败，那么您将听到一次相当响亮的“哔”声。 + +注意，已经观察到启动过程中 ChromeOS 引导加载程序 USB 枚举速度很慢。如果您在从 USB 启动时遇到问题，那么在设备通过引导加载程序前，移除其他 USB 设备可能会有所帮助；另外，也请避免使用 USB 集线器。 + +## 提示和技巧 {#tips-and-tricks} + +默认情况下，ChromeOS 引导加载程序的超时等待时间很长，以便您能够按下按键。要跳过此过程，您可以在警告 OS 无法验证的灰色画面中按下 Ctrl+D 或 Ctrl+U。Ctrl+D 将使设备跳过超时等待，并从其默认源启动。Ctrl+U将跳过超时等待，并从 USB 启动设备。 + +### 配置 Fuchsia 引导源 + +Fuchsia 具有称为 `cros_nvtool` 的 `crossystem` 等价物。您可以运行 `cros_nvtool set dev_boot_default
一些给予进程的初始句柄是被进程挂载到**命名空间**（namespace）中的目录。
[glossary.handle]: /glossary/README.md#handle \ No newline at end of file diff --git a/get-started/_common/intro/_zircon_syscall.md b/get-started/_common/intro/_zircon_syscall.md index 0cfc85f5..7d432a65 100644 --- a/get-started/_common/intro/_zircon_syscall.md +++ b/get-started/_common/intro/_zircon_syscall.md @@ -1,47 +1,85 @@ -## System calls + +## 系统调用 + +用户空间代码使用**系统调用**与内核空间对象交互。Zircon 有执行低层操作的系统调用，如： + +* 内存管理 +* 任务和进程管理 +* 进程间通信（IPC）与同步 +* 异常处理 +* 硬件支持服务（时钟、熵、设备 I/O） + + + +用户空间进程通过 `libzircon.so` 访问系统调用，这是一个 +[虚拟动态共享对象][glossary.virtual-dynamic-shared-object]（virtual Dynamic Shared Object，vDSO）。 +Zircon vDSO 是 ELF 格式的共享库，它被内核映射到每个新进程的地址空间。 +这个库被称为“虚拟”，是因为它是直接由内核映像暴露，而非从文件加载的。 + +大多数系统调用直接操作一个或多个[句柄][glossary.handle]。 +句柄是进程内部对内核空间对象的引用，表示为32位整数（`zx_handle_t`）。 +每个句柄声明了持有者具有的对句柄自身或引用的对象执行操作的特权，即**权利**（right）。 diff --git a/get-started/build_fuchsia.md b/get-started/build_fuchsia.md index 7e66e119..42057111 100644 --- a/get-started/build_fuchsia.md +++ b/get-started/build_fuchsia.md @@ -1,167 +1,267 @@ + +# 配置和构建 Fuchsia {#configure-and-build-fuchsia} +这篇文档将引导您在主机上配置并构建 Fuchsia。 + +步骤如下： + +1. [前提条件](#prerequisites) +1. [设置构建配置](#set-your-build-configuration) +1. [提升构建速度（可选）](#speed-up-the-build) +1. [构建 Fuchsia](#build-fuchsia) + +## 1. 前提条件 {#prerequisites} + +在开始之前，请先检查是否满足如下要求： + +* [源代码设置](#source-code-setup) +* [硬件要求](#hardware-requirements) + +### 源代码设置 {#source-code-setup} + +根据文档[下载 Fuchsia 源代码](/get-started/get_fuchsia_source.md)指示下载 Fuchsia 的源代码，然后在您的计算机上设置开发环境。 + +### 硬件要求 {#hardware-requirements} + +您只能在具有下列主机架构之一的计算机上构建 Fuchsia： + +- x86-64 Linux (只支持基于 Debian 系列的发行版) +- x86-64 macOS + +注意：不支持 Windows 和 ARM64。 + +## 2. 设置构建配置 {#set-your-build-configuration} + +Fuchsia 的构建配置告诉构建系统进行构建的产品，以及构建面向的平台。 + +要设置您的 Fuchsia 构建配置，请运行 [`fx set`][fx-set-reference] 命令： ```posix-terminal fx set {{ '' }}PRODUCT{{ '' }}.{{ '' }}BOARD{{ '' }} ``` - + +请替换以下选项： + +* `PRODUCT`（产品）：您想要构建的 Fuchsia 产品，比如：`core` 和 `workstation_eng`。 +* `BOARD`（板型）：产品的可执行文件架构，比如：`x64` 和 `qemu-x64`。 + +下面的示例将一项构建配置设置为 `core.qemu-x64`： ```posix-terminal fx set core.qemu-x64 ``` - + +在这个示例中： + + * `core` 是 Fuchsia 具备最小功能集的产品，包括常用的网络功能。 + * `qemu-x64` 是 Fuchsia 模拟器（FEMU）的 x64 架构这一板型，FEMU 基于开源模拟器 [QEMU][qemu]{:.external}。 + +另外，下面的例子将一项构建配置设置为 `workstation_eng.x64`，这常用于[在设备上安装 Fuchsia 工作站][build-workstation]： ```posix-terminal fx set workstation_eng.x64 ``` - + +要获取关于构建配置的更多信息，请参阅[配置构建](/development/build/fx.md#configure-a-build)。 + +## 3. 提升构建速度（可选） {#speed-up-the-build} + +注意：这一步对于构建 Fuchsia 而言并不是必需的，但是可以在您构建 Fuchsia 时节省很多时间，因此建议您完成该步骤。 + +要提升 Fuchsia 构建速度，您可以使用下列服务之一： + +* [启用 Goma](#enable-goma) +* [安装 ccache](#install-ccache) + +### 启用 Goma {#enable-goma} + +[Goma](https://chromium.googlesource.com/infra/goma/server/){:.external} 是一个分布式编译器服务，适用于 Chrome、Android 和 Fuchsia 等开源项目。 + +如果您能访问 Goma， 请在您的计算机上 Goma 客户端： ```posix-terminal fx goma ``` - + +### 安装 ccache {#install-ccache} + +如果您无法访问 Goma，但想在本地加速构建，则可以使用[ccache](https://ccache.dev/){:.external} 缓存之前构建的产物。
* {Linux}
-
+
+ 要在 Linux 上使用 `ccache`，请安装如下安装包：
```posix-terminal
sudo apt install ccache
```
* {macOS}
-
+
+ 对于 macOS ，请参阅[在 Mac 上使用 CCache](https://chromium.googlesource.com/chromium/src.git/+/HEAD/docs/ccache_mac.md){:.external} 中的安装步骤。
+
+如果您的 `CCACHE_DIR` 环境变量指向已有路径，那么 `ccache` 就会自动开启。
+
+要覆盖此默认行为，请为 `fx set` 指定以下标志：
+
+* 即使其他的加速项可用，也要强制使用 `ccache`，则：
fx set PRODUCT.BOARD --ccache
-
+
+* 要禁用 `ccache`：
fx set PRODUCT.BOARD --no-ccache
-
+
+## 4. 构建 Fuchsia {#build-fuchsia}
+
+[`fx build`][fx-build-reference] 命令可以把源代码构建打包，或者构建成其他的类型。
+
+要构建 Fuchsia，请运行以下命令：
+
+注意：构建时间一般为 90 分钟。
```posix-terminal
fx build
```
-
+
+当您修改源代码后，请再次运行命令 `fx build` 进行增量构建，或者运行 `fx -i build` 命令来开启一个监视进程，这个监视进程会在发现源代码更新时自动构建。
+
+要获取关于构建 Fuchsia 的更多信息，请参阅[执行构建](/development/build/fx.md#execute-a-build)。
+
+## 后续步骤
+
+要在您的计算机上启动 Fuchsia 模拟器 （FEMU），请参阅[开启 Fuchsia 模拟器](/get-started/set_up_femu.md)。
+
+不过，如果您想在硬件设备上运行 Fuchsia，请参阅[在设备上安装 Fuchsia](/development/hardware/README.md)。
+
diff --git a/get-started/explore_fuchsia.md b/get-started/explore_fuchsia.md
index c1e32ae8..8d148400 100644
--- a/get-started/explore_fuchsia.md
+++ b/get-started/explore_fuchsia.md
@@ -1,81 +1,116 @@
-# Explore Fuchsia {#explore-fuchsia}
+
+# 探索 Fuchsia {#explore-fuchsia}
-Once you have Fuchsia up and running on a device or emulator,
-check out the following resources:
+
+在设备或模拟器上启动并运行 Fuchsia 后，请参阅以下资源：
-* [Run ffx commands](#run-ffx-commands).
+
+* [运行 ffx 命令](#run-ffx-commands)。
+* [运行示例](#run-examples)。
+* [创建 Fuchsia 组件](#create-fuchsia-components)。
+* [贡献更改](#contribute-changes)。
-## Run ffx commands {#run-ffx-commands}
+
+## 运行 ffx 命令 {#run-ffx-commands}
-[`ffx`][ffx-overview] is a host tool for Fuchsia target workflows that
+
+[`ffx`][ffx-overview] 是 Fuchsia 目标工作流的主机工具，为所有 Fuchsia 环境和主机平台上提供一致的开发体验。
-The following are some of `ffx` command examples:
+
+以下是一些 `ffx` 命令示例：
-* Display the list of devices:
+
+* 显示设备列表：
```posix-terminal
ffx target list
```
-* Display the device information:
+
+* 显示设备信息：
```posix-terminal
ffx target show
```
-* Print the device logs:
+
+* 输出设备日志：
```posix-terminal
ffx log
```
-* Reboot the device:
+
+* 重启设备：
```posix-terminal
ffx target reboot
```
-## Run examples {#run-examples}
+
+## 运行示例
-To try out Fuchsia's sample software, check out the guides below:
+
+要试用 Fuchsia 的样例程序，请参阅如下指南：
-* [Run an example component](/development/run/run-examples.md)
+
+* [运行示例组件](/development/run/run-examples.md)
+* [运行测试组件](/development/run/run-test-component.md)
+* [运行端到端测试](/development/testing/run_an_end_to_end_test.md)
-## Create Fuchsia components {#create-fuchsia-components}
+
+## 创建 Fuchsia 组件 {#create-fuchsia-components}
+
+Fuchsia 中软件的最小可执行单元是[组件](/concepts/components/v2)，这些组件通过 [FIDL](/concepts/fidl/overview.md)（Fuchsia 接口定义语言）协议彼此交互。
-To learn more about Fuchsia components and FIDL, check out the guides below:
+
+要想了解更多有关 Fuchsia 组件和 FIDL 的信息，请参阅如下指南：
-* [Build components](/development/components/build.md)
+
+* [构建组件](/development/components/build.md)
+* [FIDL 概览](/development/languages/fidl/README.md)
+* [FIDL 教程](/development/languages/fidl/tutorials/overview.md)
-## Contribute changes {#contribute-changes}
+
+## 贡献更改 {#contribute-changes}
-When you're ready to contribute to the Fuchsia project,
-see [Contribute changes][contribute-changes].
+
+当您准备好为 Fuchsia 项目做出贡献时，请参阅[贡献更改][contribute-changes]。
-## See also
+
+## 参阅
-For more information on Fuchsia's development workflows,
-check out the following resources:
+
+要获取关于 Fuchsia 开发流程的更多信息，请参阅下列资源：
-* [fx workflows](/development/build/fx.md)
+
+* [fx 工作流程](/development/build/fx.md)
+* [工作流程技巧和问题](/development/source_code/workflow_tips_and_faq.md)
+* [配置编辑器](/development/editors/)
+* [源代码布局](/development/source_code/layout.md)
+* [构建系统](/development/build/build_system/index.md)
+
diff --git a/get-started/get_fuchsia_source.md b/get-started/get_fuchsia_source.md
index 7bb6eafa..5463aaf4 100644
--- a/get-started/get_fuchsia_source.md
+++ b/get-started/get_fuchsia_source.md
@@ -1,30 +1,52 @@
+
+# 下载 Fuchsia 源代码
+
+本指南说明了如何下载 Fuchsia 源代码以及在您的机器上部署开发环境。
+
+步骤如下：
+
+1. [执行预检查](#perform-a-preflight-check)。
+2. [安装必备软件包](#install-prerequisite-packages)。
+3. [下载 Fuchsia 源代码](#download-the-fuchsia-source-code)。
+4. [设置环境变量](#set-up-environment-variables)。
+5. [配置防火墙规则（可选）](#configure-firewall-rules)。
+
+
+## 1. 执行预检查 {#perform-a-preflight-check}
+
+Fuchsia 提供了一个预检查工具（[`ffx platform preflight`][ffx-platform-preflight]），这个工具可以测试您的机器，并会通知您在该机器上可能会影响从源代码构建 Fuchsia 的任何问题。
+
+注意：这个预检查工具只支持 x64 架构。目前 Fuchsia 不保证在其他宿主架构上能构建成功，比如 Windows 和 ARM64。
+
+运行如下命令：
* {Linux}
@@ -38,14 +60,22 @@ Run the following command:
curl -sO https://storage.googleapis.com/fuchsia-ffx/ffx-macos-x64 && chmod +x ffx-macos-x64 && ./ffx-macos-x64 platform preflight
```
+
+## 2. 安装必备软件包 {#install-prerequisite-packages}
+
+Fuchsia 要求 `curl`、 `file`、 `unzip` 以及 `git` 等工具是最新版。 `git` 版本需为 2.28 或以上。
* {Linux}
+
+ 安装（或更新）以下软件包：
```posix-terminal
sudo apt install curl file git unzip
@@ -53,56 +83,92 @@ of `git` needs to be 2.28 or higher.
* {macOS}
+
+ 安装 Xcode 命令行工具：
+
+ 注意：如果 `ffx platform preflight` 显示 Xcode 工具已经安装，则请跳过这一步。
```posix-terminal
xcode-select --install
```
+
+## 3. 下载 Fuchsia 源代码 {#download-the-fuchsia-source-code}
+
+Fuchsia 提供了一个[引导脚本](/scripts/bootstrap)，这个脚本会创建一个名为 `fuchsia` 的文件夹，并把 Fuchsia 源码下载到这里。
+
+下载 Fuchsia 源码要求您机器上有大约 2 GB 的存储空间。根据您的构建配置，之后在构建 Fuchsia 时，您还额外需要 80 到 90 GB 的存储空间。另外，下载过程中也会使用大量的内存。建议您在此过程中关闭其他非必要的进程。
+
+要下载 Fuchsia 源代码，请执行如下步骤：
+
+1. 选择一个 Fuchsia 源代码下载目录，例如：
+
+ 注意：您可以在任何目录下设置 Fuchsia。本指南选择 `$HOME` 作为示例。
```posix-terminal
cd $HOME
```
+
+1. 运行引导脚本：
+
+ 注意：下载 Fuchsia 源代码可能需要 60 分钟。
```posix-terminal
curl -s "https://fuchsia.googlesource.com/fuchsia/+/HEAD/scripts/bootstrap?format=TEXT" | base64 --decode | bash
```
+
+
+ 这个脚本会创建 `fuchsia` 目录，并且下载源代码。
+
+ 如果您在脚本运行期间看到了 `Invalid authentication credentials` 错误信息，请参考[认证错误](#authentication-error)章节寻求帮助。
+
+## 4. 设置环境变量 {#set-up-environment-variables}
+
+Fuchsia 建议您按照如下操作更新 shell 配置文件：
+
+* 添加 `.jiri_root/bin` 目录到您的 `PATH` 环境变量
+
+ Fuchsia 源码中的 `.jiri_root/bin` 目录包含了 [`jiri`](https://fuchsia.googlesource.com/jiri) 和 [`fx`](/development/build/fx.md) 工具，这些是 Fuchsia 工作流中的必备工具。Fuchsia 使用 `jiri` 工具在 Fuchsia 的项目中管理仓库，而 `fx` 工具能够帮助配置、构建、运行以及调试 Fuchsia。Fuchsia 的工具链需要可以在您的 `PATH` 环境变量中找到 `jiri` 工具。
+
+* 使用“source”命令导入 `scripts/fx-env.sh` 文件
+
+ 虽然这并不是必须的，但是使用“source”命令导入 [`fx-env.sh`](/scripts/fx-env.sh) 文件可以在您的终端中启用一系列有用的 shell 函数。比如，它会创建 `FUCHSIA_DIR` 环境变量，以及提供 `fd` 命令用来在目录中导航时提供自动补全 （要获取更多信息，请参阅 `fx-env.sh` 中的注释）。
+
+注意：如果您不想更新您的 shell 配置，则请参阅[在不更新 PATH 变量的情况下准备 Fuchsia](#work-on-fuchsia-without-updating-your-path)。
+
+要更新您的 shell 配置文件来设置 Fuchsia 的环境变量，请执行如下步骤：
+
+1. 使用文本编辑器打开您的 `~/.bash_profile` 文件（在以下示例中，我们使用 [Nano][nano]{:.external} 文本编辑器）：
+
+ 注意：本指南使用 `bash` 终端作为示例，如果您使用 `zsh`，请在后续步骤中请替换 `~/.bash_profile` 为 `~/.zprofile`：
```posix-terminal
nano ~/.bash_profile
```
+
+1. 在您的 `~/.bash_profile` 文件中添加如下配置：
+
+ 注意：如果您的 Fuchsia 源码不在 `~/fuchsia` 目录下，则请替换 `~/fuchsia` 为您的 Fuchsia 目录。
```sh
export PATH=~/fuchsia/.jiri_root/bin:$PATH
source ~/fuchsia/scripts/fx-env.sh
```
+
+1. 保存文件并退出。
+
+1. 要更新环境变量，请运行如下命令：
```posix-terminal
source ~/.bash_profile
```
+
+1. 验证您可以在您的 `fuchsia` 目录内运行如下命令且没有报错：
```posix-terminal
jiri help
@@ -169,85 +269,151 @@ do the following:
fx help
```
+
+## 5. 配置防火墙规则（可选） {#configure-firewall-rules}
+
+注意：这一步对构建或者运行 Fuchsia 并不是必需的。但是推荐您进行该步骤，以确保 Fuchsia 模拟器实例能在 Linux 上流畅运行。
+
+（**仅限 Linux**）如果您计划在 Linux 中运行 Fuchsia，那么建议您运行如下命令，在宿主机上允许 Fuchsia 特定流量：
```posix-terminal
fx setup-ufw
```
+
+该脚本需要 `sudo` 权限（会要求您输入密码）来设置适当的防火墙规则。（要获取关于该脚本的更多信息，请参考 [`setup-ufw`][setup-ufw]）。
+
+## 后续步骤
+
+要构建您第一个 Fuchsia 系统镜像，请参阅[配置和构建 Fuchsia](/get-started/build_fuchsia.md)。
+
+## 附录
+
+### 认证错误 {#authentication-error}
+
+如果您在引导脚本运行过程中看到了 `Invalid authentication credentials`（无效的认证凭据）错误信息，那么您的 `~/.gitcookies` 文件中可能含有来自 `googlesource.com` 中一些仓库的 cookie，引导脚本想要匿名检查。
+
+要解决该错误，请使用以下方式之一：
+
+* 按照屏幕上的指示为指定仓库获取密码。
+* 删除 `.gitcookies` 文件中有问题的 cookie。
+
+
+### 在不更新 PATH 变量的情况下准备 Fuchsia {#work-on-fuchsia-without-updating-your-path}
+
+下面的章节为[设置环境变量](#set-up-environment-variables)章节提供了替代方法：
+
+* [把工具复制到二进制目录](#copy-the-tool-to-your-binary-directory)
+* [添加符号链接到二进制目录](#add-a-symlink-to-your-binary-directory)
+
+#### 把工具复制到二进制目录 {#copy-the-tool-to-your-binary-directory}
+
+如果您不想更新您的环境变量，但是想在任何目录中使用 `jiri` 工具，那么请把 `jiri` 工具复制到 `~/bin` 目录中，比如：
+
+注意：如果您的 Fuchsia 源码不在 `~/fuchsia` 目录中，则请把 `~/fuchsia` 替换为您的 Fuchsia 目录。
```posix-terminal
cp ~/fuchsia/.jiri_root/bin/jiri ~/bin
```
+
+但是，您必须在没有 `sudo` 的情况下对 `~/bin` 有写访问权限。否则，`jiri` 无法自动保持最新版本。
+
+#### 添加符号链接到二进制目录 {#add-a-symlink-to-your-binary-directory}
+
+同样地，如果您想在不更新环境变量的情况下使用 `fx` 工具，则请在 `~/bin` 路径中添加您 `fx` 工具的链接文件，比如：
+
+注意：如果您的 Fuchsia 源码不在 `~/fuchsia` 目录中，则请把 `~/fuchsia` 替换为您的 Fuchsia 目录。
```posix-terminal
ln -s ~/fuchsia/scripts/fx ~/bin
```
-
+
+或者，请直接使用 `fx` 工具的路径来运行，比如：
```posix-terminal
./scripts/fx help
```
-
+
+无论哪种情况，您都需要 `jiri` 工具在您的 `PATH` 环境变量中。
[ffx-platform-preflight]: https://fuchsia.dev/reference/tools/sdk/ffx#preflight
diff --git a/get-started/learn-fuchsia.md b/get-started/learn-fuchsia.md
index bcbb26ab..fa5890b7 100644
--- a/get-started/learn-fuchsia.md
+++ b/get-started/learn-fuchsia.md
@@ -1,31 +1,55 @@
+
+# 使用入门
+
+Fuchsia 是一个现代化开源操作系统，它简单、安全、可更新以及运行效率高。同时提供了操作系统的核心功能，比如系统资源管理、驱动框架以及软件抽象。Fuchsia 是一种通用操作系统，旨在助力多样化的硬件和软件生态系统。
+
+## SDK 还是源代码树?
+
+Fuchsia 是 Google 积极开发的一个开源项目。参与 Fuchsia 的方式有两种：您可以使用 Fuchsia 的 SDK 来为 Fuchsia 构建产品和软件，或者向源代码树贡献代码以构建 Fuchsia 平台。
+
+## SDK——为 Fuchsia 构建软件
+
+Fuchsia 的 SDK 配套有一些工具帮助您开始开发运行在 Fuchsia 上的软件。在您开始开发软件之前，建议您了解 Fuchsia SDK 的基础知识。
+
+SDK 基础知识
+
+## 源代码树——向 Fuchsia 贡献代码
+
+由于 Fuchsia 是一个开源项目，因而您可以为 Fuchsia 源代码树贡献代码。在您开始贡献代码之前，建议您了解关于 Fuchsia 平台的基础知识，以便理解 Fuchsia 的工作原理。
+
Fundamentals for contributors
\ No newline at end of file
+ href="/get-started/learn">针对贡献人员的基础知识
diff --git a/get-started/learn/intro/architecture.md b/get-started/learn/intro/architecture.md
index aab7cae8..fb7f06da 100644
--- a/get-started/learn/intro/architecture.md
+++ b/get-started/learn/intro/architecture.md
@@ -1,3 +1,4 @@
-# Fuchsia architecture
+
+# Fuchsia 架构
<<../../_common/intro/_architecture.md>>
diff --git a/get-started/learn/intro/packages.md b/get-started/learn/intro/packages.md
index d675445f..fb39ce46 100644
--- a/get-started/learn/intro/packages.md
+++ b/get-started/learn/intro/packages.md
@@ -1,4 +1,5 @@
-# Software delivery
+
+# 软件交付
<<../../_common/intro/_packages_intro.md>>
@@ -6,26 +7,40 @@
<<../../_common/intro/_packages_storing.md>>
+
+## 练习：包
+
+在之前的本系列代码练习中，虽然您可能没有意识到，但您已经体验过到设备的软件按需交付。在本练习中，您将进一步揭开它的神秘面纱，了解到包被交付和存储到 Fuchsia 设备中的过程的具体细节。
<<../_common/_restart_femu.md>>
+
+### 启动本地包服务器
+
+运行如下命令，以启动包服务器并允许模拟器加载软件包：
```posix-terminal
fx serve-updates
```
-
+
+该命令打印的输出类似如下所示。它表示服务器正在运行，并已成功将模拟器注册为目标设备：
```none {:.devsite-disable-click-to-copy}
[serve-updates] Discovery...
@@ -37,22 +52,40 @@ running and has successfully registered the emulator as a target device:
[pm auto] client count: 1
```
+
+### 检查包服务器
+
+`fx serve-updates` 命令会启动用于将包交付到目标设备的 **本地包服务器**。该服务器默认在 8083 端口上运行。
+
+在浏览器中访问 `http://localhost:8083`，会加载出一个当前包仓库中可用的包的列表的网页。列表中的每一项都是可被交付到设备的包。
+
+### 监视包加载
+
+包由 Fuchsia 设备按需解析并加载。让我们在 `spinning-square` 示例包上进行操作来稍作展示。
+
+在设备命令行中，您可以确定某个已知的包目前是否在设备上。
```posix-terminal
fx shell pkgctl pkg-status fuchsia-pkg://fuchsia.com/spinning-square-rs
@@ -63,22 +96,34 @@ Package in registered TUF repo: yes (merkle=ef65e2ed...)
Package on disk: no
```
+
+打开新终端，开始流式传输 `pkg-resolver` 的设备日志。
```posix-terminal
ffx log --filter pkg-resolver
```
+
+这里展示了从包服务器加载的包的所有实例。
+
+在设备命令行中，尝试解析包：
```posix-terminal
fx shell pkgctl resolve fuchsia-pkg://fuchsia.com/spinning-square-rs
```
+
+注意 `pkg-resolver` 的输出中增加的新行：
```none {:.devsite-disable-click-to-copy}
[pkg-resolver][pkg-resolver][I] Fetching blobs for fuchsia-pkg://devhost/spinning-square-rs: [
@@ -88,7 +133,10 @@ Notice the new lines added to the log output for `pkg-resolver`:
[pkg-resolver][pkg-resolver][I] resolved fuchsia-pkg://fuchsia.com/spinning-square-rs as fuchsia-pkg://devhost/spinning-square-rs to 21967ecc643257800b8ca14420c7f023c1ede7a76068da5faedf328f9d9d3649 with TUF
```
+
+在设备命令行中，再次在设备上查看包状态：
```posix-terminal
fx shell pkgctl pkg-status fuchsia-pkg://fuchsia.com/spinning-square-rs
@@ -99,30 +147,48 @@ Package in registered TUF repo: yes (merkle=ef65e2ed...)
Package on disk: yes (path=/pkgfs/versions/ef65e2ed...)
```
+
+Fuchsia 解析了包并按需从本地 TUF 仓库中将其加载了！
+
+### 探索包的元数据
+
+现在 `spinning-square` 包已经成功解析，接下来可以探索包内容。在解析之后，包就可以在目标设备上用它的内容地址引用。
+
+在设备命令行中，可以使用 `pkgctl get-hash` 命令来确认 `spinning-square` 的包摘要。
```posix-terminal
fx shell pkgctl get-hash fuchsia-pkg://fuchsia.com/spinning-square-rs
```
+
+该命令会返回如下的唯一包摘要：
```none {:.devsite-disable-click-to-copy}
ef65e2ed...
```
+
+使用 `pkgctl open` 命令并提供完整的包摘要，来查看包内容。
```posix-terminal
fx shell pkgctl open {{ '' }}ef65e2ed...{{ '' }}
@@ -154,17 +220,30 @@ package contents:
/data/vulkan/explicit_layer.d/VkLayer_khronos_validation.json
```
+
+这个命令列出了包的元数据和包中的每个内容 BLOB（Binary Large OBject，二进制大型对象）。其中的 `bin/` 项目对应可执行文件，`lib/`
+项目对应共享库依赖，还有后面的额外元数据和资源。
+
+## 接下来是？
+
+祝贺！您现在对 Fuchsia 的独特性和这样一个新平台的设计目标都有了更好的理解。
+
+在下一个模块中，您将了解到有关 Fuchsia 这个开源项目和用于构建与自定义系统的工具的更多知识：
Building Fuchsia
+ href="/get-started/learn/build">构建 Fuchsia
diff --git a/get-started/learn/intro/sandboxing.md b/get-started/learn/intro/sandboxing.md
index 426101cf..68191dac 100644
--- a/get-started/learn/intro/sandboxing.md
+++ b/get-started/learn/intro/sandboxing.md
@@ -1,5 +1,6 @@
{% import 'docs/_common/_doc_widgets.md' as widgets %}
-# Software isolation model
+
+# 软件隔离模型
<<../../_common/intro/_sandboxing_intro.md>>
@@ -7,30 +8,48 @@
<<../../_common/intro/_sandboxing_namespaces.md>>
-## Exercise: Namespaces
+
+## 练习：命名空间
+
+在本练习中，您将使用命令行来更详细地探索组件的命名空间（namespace）的内容。
<<../_common/_start_femu.md>>
-### Find a component in the hub
+
+### 在 hub 中找到一个组件
+
+Fuchsia 提供了 [Hub](/concepts/components/v2/hub.md) 作为诊断接口，
+用于获取系统中运行的组件实例的信息。
+您可以使用 hub 的目录结构来探索组件及其命名空间。
+
+连接到设备命令行并输入以下 `ls` 命令
+来列出 `/hub-v2/children/core/children` 下的 `core` 领域（realm）的组件:
```posix-terminal
fx shell ls /hub-v2/children/core/children
@@ -45,10 +64,16 @@ build-info
...
```
+
+这是许多核心 Fuchsia 系统组件的一个列表。要查看更多关于特定组件的详细信息，可以列出它的目录内容。
+
+对 `http-client` 组件试试这个:
```posix-terminal
fx shell ls /hub-v2/children/core/children/network/children/http-client
@@ -65,10 +90,14 @@ resolved
url
```
-### Explore the namespace and outgoing directory
+
+### 探索命名空间和出口目录
+
+您将在 hub 内部的 `exec/in` 路径下找到运行中组件的**命名空间**。
```posix-terminal
fx shell ls /hub-v2/children/core/children/network/children/http-client/exec/in
@@ -80,16 +109,27 @@ pkg
svc
```
-Here are some quick highlights of each element:
+
+对每个元素简单说明如下:
+
+* `config/`: 组件的配置数据
+* `pkg/`: 组件的包的内容
+* `svc/`: 可供组件使用的系统服务
+
+列出 `svc/` 目录的内容。这个目录包含
+[服务节点](https://fuchsia.dev/reference/fidl/fuchsia.io#NodeInfo)，
+表示提供给这个组件的系统服务。
```posix-terminal
fx shell ls /hub-v2/children/core/children/network/children/http-client/exec/in/svc
@@ -101,13 +141,22 @@ fuchsia.net.name.Lookup
fuchsia.posix.socket.Provider
```
+
+每个服务都通过一个公有协议访问，其由一个
+ [Fuchsia 接口定义语言（Fuchsia Interface Definition Language，FIDL)][glossary.FIDL]接口定义。
+组件通过其**出口目录**（outgoing directory）来提供系统服务，
+这个目录被映射到 hub 内部的 `exec/out` 路径。
+
+列出 `svc/` 出口目录来查看这个组件提供的系统服务。
```posix-terminal
fx shell ls /hub-v2/children/core/children/network/children/http-client/exec/out/svc
@@ -117,11 +166,18 @@ fx shell ls /hub-v2/children/core/children/network/children/http-client/exec/out
fuchsia.net.http.Loader
```
+
+我们将在以后更详细地探索 FIDL 协议及如何访问各种服务。
diff --git a/get-started/set_up_femu.md b/get-started/set_up_femu.md
index 0ddf5502..81b7fc42 100644
--- a/get-started/set_up_femu.md
+++ b/get-started/set_up_femu.md
@@ -1,193 +1,353 @@
+
+# 启动 Fuchsia 模拟器
+
+本指南提供关于在您的设备上安装和启动 Fuchsia 模拟器（FEMU）的方法说明。
+
+步骤如下：
+
+1. [前提条件](#prerequisites)。
+1. [为 FEMU 构建 Fuchsia](#build-fuchsia-for-femu)。
+1. [启用 VM 加速（可选）](#enable-vm-acceleration)。
+1. [启动 FEMU](#start-femu)。
+1. [发现 FEMU](#discover-femu)。
+
+
+## 1. 前提条件 {#prerequisites}
+
+运行 FEMU 需要您完成以下指南：
+
+ * [下载 Fuchsia 源代码][get-fuchsia-source]
+ * [配置和构建 Fuchsia][build-fuchsia]
+
+## 2. 为 FEMU 构建 Fuchsia {#build-fuchsia-for-femu}
+
+要运行 FEMU，您首先要构建一个支持模拟器环境的 Fuchsia 系统镜像。本指南使用 `qemu-x64` 板型和 `workstation_eng` 产品作为示例。
+
+要构建 FEMU 的 Fuchsia 镜像，请执行以下操作：
+
+1. 设置 Fuchsia 构建配置：
```posix-terminal
fx set workstation_eng.qemu-x64 --release
```
+
+2. 构建 Fuchsia：
```posix-terminal
fx build
```
+
+要获取关于支持的板型和产品的更多信息，请参阅 [Fuchsia 模拟器（FEMU）][femu-overview]概述页面。
+
+## 3. 启用 VM 加速（可选） {#enable-vm-acceleration}
+
+（**仅限Linux**）大部分 Linux 设备支持通过 KVM 进行 VM 加速，这大大提高了模拟器的性能和可用性。
+
+如果您的设备可以使用 KVM，请更新您的组权限来启用 KVM。
* {Linux}
+
+ 要在您的设备上启用 KVM，请执行以下操作：
+
+ 注意：您只需要在每台设备上执行一次。
+
+ 1. 在您的设备上添加您自己到 `kvm` 组：
```posix-terminal
sudo usermod -a -G kvm ${USER}
```
+
+ 1. 注销与您设备的所有桌面会话，然后重新登录。
+
+ 1. 要验证 KVM 配置正确，请运行以下命令：
```posix-terminal
if [[ -r /dev/kvm ]] && grep '^flags' /proc/cpuinfo | grep -qE 'vmx|svm'; then echo 'KVM is working'; else echo 'KVM not working'; fi
```
+
+ 验证此命令输出以下行：
```none {:.devsite-disable-click-to-copy}
KVM is working
```
+
+ 如果您看到 `KVM not working`，那么您可能需要重启您的设备，以使权限修改生效。
* {macOS}
+
+ macOS 无需额外的设置。
+
+ 在 macOS 上 Fuchsia 模拟器使用的是 [Hypervisor 框架][hypervisor-framework]{: .external}，而不是 KVM。
+
+## 4. 启动 FEMU {#start-femu}
+
+### 启动包服务器
+
+在启动模拟器之前，请启动包服务器。
+
+要启动包服务器，请运行以下命令：
```posix-terminal
fx serve
```
+
+注意：或者，您可以将 `fx serve` 进程置于后台。
+
+### 启动模拟器
+
+要在您的 Linux 设备启动模拟器，请执行以下操作：
* {Linux}
+
+ 1. 通过运行以下命令配置 upscript：
+
+ 注意：如果您的设备使用了防火墙，您可能需要应用一些额外的配置来允许模拟器访问网络。这通常通过运行“upscript”来完成，该脚本为当前进程设置接口和防火墙访问规则。如果您位于企业网络，请联系您的内部网络团队来查看他们是否有现行的 upscript 供您使用。
+
+ 如果您没有使用防火墙，那么还需要进行一些配置才能启用 tun/tap 网络。位于 {{ '' }}FUCHSIA_ROOT{{ '' }}/scripts/start-unsecure-internet.sh 的 upscript 示例应该适用于大多数非企业网络。
```posix-terminal
ffx config set emu.upscript {{ '' }}FUCHSIA_ROOT{{ '' }}/scripts/start-unsecure-internet.sh
```
+
+ * `start-unsecure-internet.sh` 是一个 upscript 示例。
+ * `FUCHSIA_ROOT` 是您 Fuchsia 目录的路径。
+
+ 1. 启动 FEMU
+
+ 1. 要启动可以访问外部网络的模拟器，请运行以下命令：
```posix-terminal
ffx emu start --net tap
```
+
+ * `--net` 指定模拟器的网络模式。`--net tap` 附加到 Tun/Tap 接口。
+
+ 1. 要启动不可访问外部网络的模拟器，请运行以下命令：
```posix-terminal
ffx emu start --net none
```
+
+ 启动模拟器会打开一个标题为 **Fuchsia Emulator** 的新窗口，当模拟器完成启动后，您会返回到命令提示符，模拟器会在后台运行。
* {macOS}
+
+ 要在 macOS 上启动 FEMU，请执行以下操作：
+
+ 1. 启动 FEMU：
```posix-terminal
ffx emu start
```
+
+ 如果您在 macOS 上第一次（包括在重启后的第一次）启动 FEMU，则会有窗口弹出，询问您是否要允许 `aemu` 进程在您的设备上运行。请点击 **允许**（Allow）。
+
+ 该命令打开一个标题为 **Fuchsia Emulator** 的新窗口。当模拟器启动完成后，您会返回到命令提示符，模拟器会在后台运行。
+
+ 2. （可选）如果您需要指定已启动的 Fuchsia 模拟器，您可以在同一终端运行 `fx set-device` 命令。
```posix-terminal
fx set-device {{ '' }}NAME{{ '' }}
```
+
+ 请替换以下内容：
+
+ * `NAME`：请从 `ffx emu list` 或 `ffx target list` 命令的输出中选择希望使用的值。`fuchsia-emulator` 为默认值。
+
+
+## 5. 发现 FEMU {#discover-femu}
+
+要将 Fuchsia 模拟器发现为正在运行的 Fuchsia 设备，请运行以下命令：
```posix-terminal
ffx target list
```
+
+该命令的输出类似于以下内容：
```none {:.devsite-disable-click-to-copy}
$ ffx target list
@@ -195,52 +355,93 @@ NAME SERIAL TYPE STATE ADDRS/
fuchsia-emulator | GPU 仿真方式 | +说明 | +标记 | +
|---|---|---|
| 硬件（主机 GPU） | +直接使用主机设备的 GPU 进行 GPU 处理。 | +ffx emu start --gpu host |
+
| 软件（主机 CPU） | +使用主机设备的 CPU 来模拟 GPU 处理。 | +ffx emu start --gpu guest |
+
| SwiftShader | +使用 SwiftShader 库来模拟 GPU 处理。 | +ffx emu start --gpu swiftshader_indirect |
+
| 自动 | +如果有可用的 GPU 硬件，则解析为 host，如果没有可用的 GPU 硬件，则解析为 swiftshader_indirect。auto 是当前默认值。 |
+ ffx emu start --gpu auto |
+