/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/general-translation-guide.md b/general-translation-guide.md index 5d52bbde..f79451a3 100644 --- a/general-translation-guide.md +++ b/general-translation-guide.md @@ -69,8 +69,12 @@ 1. 英文和中文非标点、数字和中文非标点间请用 1 个空格分割；英文或数字与中文标点间请不要空格。可以考虑使用[该软件](https://pypi.org/project/zhlint/)或类似程序进行自动化排版。 +1. **请不要参照英文写法在译文段落内添加单个换行**。单个换行会使得渲染后的文档内出现多余的空格。 + 1. 为提高校对时文本的可读性，请尽量分段翻译，避免一次性注释过多段落并进行大段翻译。 + + ### 翻译规范 1. 请至少在同一目录下保持措辞一致。 @@ -120,7 +124,7 @@ 1. 原文是内联代码格式的、具有可读性的非代码内容的。 1. 原文描述的是英文语境内容，强调了该处英文形式，且具有准确中文翻译的。 - 则请使用下面的方式标注： + 对于**所在位置不是标题中的**，请使用下面的方式标注： - 如果原文不涉及全称和简称问题，则请在译文对应位置后使用全角括号标注英文原文。另外，如果原文在代码区内，则请在代码区外标注。 - 如果原文同时具有全称和简称，或原文是未给出全称的专业术语简称，则请在译文对应位置后使用全角括号依次标注全称和简称，并在中间使用全角逗号分隔。另外，如果原文在代码区内，则请在代码区外标注。 @@ -149,6 +153,11 @@ 具体地，第一例中只包含全称，因此正常使用全角括号标注；第二例中包含了英文简称，故在全角括号中依次标注全称和简称，并使用全角逗号分隔；第三例在 [Google 公司的帮助文档](https://developer.android.com/guide/platform#:~:text=%E9%A2%84%E5%85%88%20(AOT)%20%E5%92%8C-,%E5%8D%B3%E6%97%B6%20(JIT)%20%E7%BC%96%E8%AF%91,-%E4%BC%98%E5%8C%96%E7%9A%84)中已有译例，因此按照固定方式翻译和标注。 + 对于**所在位置是标题中的**，请使用下面的方法标注： + + - 如果在正文中出现了该概念，则应当在正文进行标注，而不应在标题中进行标注。 + - 如果在正文中未出现该概念，则除非：（1）翻译具有较大歧义性，或（2）在其他文章中再次出现（即证明本身是重要概念），这些情况可以在标题中标注原文，否则不应在标题中标注原文（即不进行标注）。 + - **原文作正文，标注译文。** 如果满足下列条件之一： 1. 原文是未适配中文的输出内容的。 diff --git a/get-started/_common/components/_debugging_intro.md b/get-started/_common/components/_debugging_intro.md index 7b37df46..510739ec 100644 --- a/get-started/_common/components/_debugging_intro.md +++ b/get-started/_common/components/_debugging_intro.md @@ -1,4 +1,7 @@ + +开发软件意味着要处理程序崩溃和发现错误的根源。Fuchsia 有一套工具来帮助识别和诊断组件中的问题，从分析崩溃日志到在核心代码中进行完整的逐步调试。 diff --git a/get-started/_common/components/_declaring_intro.md b/get-started/_common/components/_declaring_intro.md index 395e91b2..8ee335b4 100644 --- a/get-started/_common/components/_declaring_intro.md +++ b/get-started/_common/components/_declaring_intro.md @@ -1,15 +1,24 @@ + +每个组件（component）都有一个声明，描述组件属性和功能。对于在软件包中分发的组件，其声明使用**组件清单（component manifest）文件**表示，并在**组件解析器**的帮助下加载。 + +{: width="836"} + +请您使用组件清单语言（CML）文件声明组件。在构建时，组件清单编译器（`cmc`）工具会验证清单源并将其编译为二进制格式（`.cm`），并将其存储在组件的软件包中。在运行时，组件解析器将二进制清单文件加载到[组件管理器](/glossary/README.md#Component-Manager)的 [ComponentDecl](https://fuchsia.dev/reference/fidl/fuchsia.component.decl#Component) FIDL 结构中。 diff --git a/get-started/_common/components/_declaring_manifests.md b/get-started/_common/components/_declaring_manifests.md index dab204a6..2cbfe72c 100644 --- a/get-started/_common/components/_declaring_manifests.md +++ b/get-started/_common/components/_declaring_manifests.md @@ -1,9 +1,14 @@ -## Component manifests + +## 组件清单 + +CML 文件是以 `.cml` 扩展名结尾的 [JSON5](https://json5.org/){: .external} 文件。如下 CML 清单文件示例，描述了一个运行 ELF 二进制文件的简单组件，该文件向系统日志打印一条“Hello, World”信息： + +```json5 +{ + // 有关要运行的程序的信息。 + program: { + // 使用内置的 ELF 运行器。 + runner: "elf", + // 为此组件运行的二进制文件。 + binary: "bin/hello", + // 程序参数 + args: [ + "Hello", + "World!", + ], + }, + + // 此组件使用的能力。 + use: [ + { protocol: "fuchsia.logger.LogSink" }, + ], +} ``` + +该文件声明了关于组件的两个主要部分的信息： + +注意：要获取组件清单（component manifest）的更多详细信息，请参阅[组件清单](/concepts/components/v2/component_manifests.md)。 + +* `program`：描述可执行信息，例如二进制文件、程序参数和相关联的运行时。在此示例中，二进制文件被编译为 ELF 可执行文件并使用内置的 [ELF 运行器](/concepts/components/v2/elf_runner.md)。 + +* `use`：声明此组件运行所需的功能。在此示例中，`fuchsia.logger.LogSink` 协议使该组件能够向系统日志（syslog）写入消息。 diff --git a/get-started/_common/components/_declaring_shards.md b/get-started/_common/components/_declaring_shards.md index f752add6..e4b9db15 100644 --- a/get-started/_common/components/_declaring_shards.md +++ b/get-started/_common/components/_declaring_shards.md @@ -1,15 +1,23 @@ -## Manifest shards + +## 清单碎片 + +一些能力集合代表了系统中许多组件所共有的用例需求，例如日志记录。为了简化将这些能力纳入组件的过程，本框架将其抽象为**清单碎片**（Manifest shard），可将其纳入 CML 源文件中。 + +下面是一个与前面的示例等效的 CML。在这种情况下，通过包含 `diagnostics/syslog/client.shard.cml` 文件，而不是显式地声明 `fuchsia.logger.LogSink` 来提供必要的日志记录功能： + +```json5 +{ + include: [ "syslog/client.shard.cml" ], + + // 有关要运行的程序的信息。 + program: { + // 使用内置的 ELF 运行器。 + runner: "elf", + // 为此组件运行的二进制文件。 + binary: "bin/hello-world", + // 程序参数 + args: [ + "Hello", + "World!", + ], + }, +} +``` diff --git a/get-started/_common/components/_organizing_identifying.md b/get-started/_common/components/_organizing_identifying.md index 1c3fd62e..55ce8032 100644 --- a/get-started/_common/components/_organizing_identifying.md +++ b/get-started/_common/components/_organizing_identifying.md @@ -1,21 +1,31 @@ -## Identifying components + +## 组件的标记 + +组件由 URL 标识。框架借助**组件解析器**将组件 URL 解析为组件声明。解析器本身就是能够处理特定 URL 格式并获取组件清单、程序和资源的组件。 + +大多数组件都发布在 Fuchsia 包内，因此组件 URL 是对该包内组件清单的引用。请查看下面的示例： ```none fuchsia-pkg://fuchsia.com/{{ '' }}foo-package{{ '' }}#meta/{{ '' }}foo-component.cm{{ '' }} ``` + +组件实例由称为 **绰号（moniker）** 的拓扑路径引用来标识。组件的绰号将其在组件实例树中的位置指示为绝对或相对路径。例如，绰号路径 `/core/system-updater` 指的是存在于 `core` 领域中的 `system-updater` 的实例。 diff --git a/get-started/_common/components/_organizing_intro.md b/get-started/_common/components/_organizing_intro.md index 50f7b8de..8ef85e7c 100644 --- a/get-started/_common/components/_organizing_intro.md +++ b/get-started/_common/components/_organizing_intro.md @@ -1,24 +1,37 @@ + +系统中的所有组件组成一个有根的**组件实例树**。树中的父组件负责将其他组件的实例声明为其子组件并为它们提供能力。同时，子组件可以向父组件公开能力。这些组件实例和能力关系构成了**组件拓扑**。 + +任何父组件及其所有子组件在树中形成一个称为**领域**的组。领域使父级能够控制那些能力流入和流出其组件的子树，从而创建能力边界。这种封装允许领域在内部进行重组，而不会影响依赖于其公开能力的外部组件。 + +{: width="616"} + +在上图中，`fuchsia.example.Foo` 协议能力通过组件实例树从提供者路由到客户端。组件使用 `use` 关键字声明它们**需要**的能力： + +```json5 +{ + // 程序运行的有关信息。 + program: { + // 使用内置的 ELF 运行程序来运行二进制文件。 + runner: "elf", + // 运行该组件的二进制文件。 + binary: "bin/client", + }, + + // 此组件所需的能力。 + use: [ + { protocol: "fuchsia.example.Foo" }, + ], +} ``` + +组件使用组件清单中的 `capabilities` 部分声明它们实现或**提供**的能力。这使得组件框架知道该能力和它的提供者。请查看下面的 `provider.cml` 示例： + +```json5 +{ + // 程序运行的有关信息。 + program: { + // 使用内置的 ELF 运行程序来运行二进制文件。 + runner: "elf", + // 运行该组件的二进制文件。 + binary: "bin/provider", + }, + // 此组件提供的能力。 + capabilities: [ + { protocol: "fuchsia.example.Foo" }, + ], + // 通过此组件路由的能力。 + expose: [ + { + protocol: "fuchsia.example.Foo", + from: "self", + }, + ], +} +``` + + +`expose` 关键字使这个组件的能力通过它的父组件向其他领域提供，这也可能包括这个组件的子组件提供的能力。在这种情况下，能力的来源是 `self`，因为这个组件是提供者。 + +父组件控制领域内的**能力路由**，创建从客户端组件到提供者的显式路径。请查看以下 `parent.cml` 清单示例： ```json5 { @@ -96,18 +160,28 @@ example `parent.cml` manifest: } ``` + + + +父组件在领域中声明一组子组件，并使用 `offer` 关键字将能力路由到它们。用这种方法，父组件就决定了每个子组件能力的范围和来源。这也使拓扑中的多个组件能够提供相同的能力，因为组件框架依赖于显式路由来确定如何解析来自每个客户端的请求。 + +注意：要获取关于组件组织的更多详细信息，请参阅[组件拓扑](/concepts/components/v2/topology.md)。 diff --git a/get-started/_common/components/_organizing_lifecycle.md b/get-started/_common/components/_organizing_lifecycle.md index 7ae52f80..6e5a9e85 100644 --- a/get-started/_common/components/_organizing_lifecycle.md +++ b/get-started/_common/components/_organizing_lifecycle.md @@ -1,37 +1,65 @@ -## Component lifecycle + +## 组件生命周期 + +在组件拓扑中添加和移除组件实例时，会创建和销毁组件实例。这可以通过以下两种方式之一发生： + +* **静态地**：该实例在组件清单中被声明为树中另一个组件的子组件。静态组件仅当一个更新改变了组件拓扑时才会创建和销毁。 + +* **动态地**：实例在运行时使用 `fuchsia.component.Realm` 协议在组件 `collection` 中添加或移除。动态组件在系统关闭时销毁。 + +一旦组件被销毁，框架就会移除它的持久状态（比如本地存储）。 + +当一个组件尝试打开到另一组件的通道时（这称为**绑定**（binding）），框架会启动后者的一个组件实例。当连接到由组件所暴露的能力时，绑定会**隐式**发生。对已经启动的组件进行绑定，会连接到其当前运行的实例。 + + + +组件可能会通过退出程序（由组件的 `runner` 定义）自行停止，或者可能由框架在系统关闭时停止。在被销毁之前，框架将组件移动到**关闭**状态以表示它不能再次启动。 + +{: width="662"} + +注意：要获取关于组件状态和执行的更多详细信息，请参阅[组件生命周期](/concepts/components/v2/lifecycle.md)。 diff --git a/get-started/_common/components/_product_driver.md b/get-started/_common/components/_product_driver.md index e56a8b82..814fc730 100644 --- a/get-started/_common/components/_product_driver.md +++ b/get-started/_common/components/_product_driver.md @@ -1,13 +1,25 @@ + +## 驱动框架 + +与会话类似，Fuchsia 驱动框架使开发人员能够将产品特定的设备驱动程序实现为组件。一些驱动程序组件代表硬件接口控制器，例如 PCI 或 USB，而其他驱动程序组件则与终端设备交互，例如以太网控制器或键盘。 + +当设备被发现或连接到系统时，`driver_manager` 平台组件启动必要的驱动程序组件，将它们绑定到硬件接口，并管理它们的生命周期。 + +注：要获取关于驱动框架的更多细节，请参阅 [Fuchsia 驱动框架](/development/drivers/concepts/fdf.md)。 diff --git a/get-started/_common/components/_product_session.md b/get-started/_common/components/_product_session.md index d776e8c1..74b6d30e 100644 --- a/get-started/_common/components/_product_session.md +++ b/get-started/_common/components/_product_session.md @@ -4,12 +4,16 @@ Sessions are components that encapsulate a product’s user experience. The session framework serves as a boundary between the Fuchsia platform and the product-level user interaction. Each Fuchsia product defines a single session instance as the root of the product experience, which may or may not manage -additional child components. +additional child components. --> +会话是一系列封装了产品用户体验的组件。会话框架充当 Fuchsia 平台和产品级用户之间交流的边界。每个 Fuchsia 产品都将单个会话实例定义为产品体验的根，它可能管理，也可能不管理其他子组件。 + The `session_manager` platform component starts the session component on boot and offers it a fixed set of capabilities necessary to support the session framework APIs for elements such as window management, input event handling, or -accessibility. +accessibility. --> +`session_manager` 平台组件在启动时打开会话组件，并为其提供一组固定的功能，以支持诸如窗口管理、输入事件处理或无障碍功能等元素的会话框架 API。 -Note: For more details on the session framework, see -[Introduction to the session framework](/concepts/session/introduction.md). + +注: 要获取关于会话框架的更多细节，请参阅[会话框架介绍](/concepts/session/introduction.md)。 diff --git a/get-started/_common/components/_tests_intro.md b/get-started/_common/components/_tests_intro.md index 9b994c64..982d91d7 100644 --- a/get-started/_common/components/_tests_intro.md +++ b/get-started/_common/components/_tests_intro.md @@ -1,19 +1,31 @@ + +Fuchsia **测试运行器框架**（Test Runner Framework）使开发者能够使用各种语言和运行时为组件构建测试，并在目标设备上执行它们。该框架提供了实现 `fuchsia.test.Suite` 协议的**测试运行器**组件，并与通用的特定语言的测试框架（如 GoogleTest (C++)）集成。 + +`test_manager` 组件负责在 Fuchsia 设备上运行测试。它检查实现测试套件协议的组件，并将它们作为子组件启动。这意味着 `test_manager` 也负责为每个测试套件提供能力，即创建通常所谓的**测试领域**。 + +{: width="714"} + +`ffx test` 等开发者工具与设备上的 `test_manager` 进行通信，以执行测试套件并取回结果。 diff --git a/get-started/_common/fidl/_connecting_intro.md b/get-started/_common/fidl/_connecting_intro.md index 644a0b63..d1eecf71 100644 --- a/get-started/_common/fidl/_connecting_intro.md +++ b/get-started/_common/fidl/_connecting_intro.md @@ -1,3 +1,4 @@ + +协议句柄是一个很常见的对象，它提供了一个 FIDL 协议的实现，FIDL 协议可以通过组件命名空间找到。组件框架使用能力促进了[组件](/glossary/README.md#component)之间的协议发现。能力路由描述了哪个组件应该作为任何给定客户端的提供者。一旦确定了适当的组件，[组件管理器](/glossary/README.md#component-manager)就会使用每个组件命名空间中的句柄来启动组件之间的连接。 + +请参考以下 `fuchsia.example.Foo` 协议的示例： + +{: width="629"} + +该图强调了执行连接所涉及的主要元素： + +1. 提供者组件在清单的 `capabilities` 部分中静态地**声明**协议。这使组件框架能够执行能力路由。 + +2. 客户端组件在清单（manifest）的 `use` 部分静态地**请求**协议。如果能力路由成功，这将在客户端的命名空间中创建 `/svc/fuchsia.example.Foo` 协议项。 + +3. 提供者代码在运行时**发布**实现。这将在提供者传出目录中的 `/svc/fuchsia.example.Foo` 处创建一个协议项。 + +4. 客户端代码在运行时**连接**到协议句柄。这将与运行在提供者组件中的实现打开一个 FIDL 连接。 diff --git a/get-started/_common/fidl/_fidl_intro.md b/get-started/_common/fidl/_fidl_intro.md index 33d69954..02609832 100644 --- a/get-started/_common/fidl/_fidl_intro.md +++ b/get-started/_common/fidl/_fidl_intro.md @@ -1,11 +1,17 @@ + +Fuchsia 接口定义语言（FIDL）是用来描述 Fuchsia 程序使用的进程间通信（IPC）协议的语言。FIDL 为供应商提供了一种简化的声明语法，以便将接口定义为一种**协议**。支持的数据类型包括整数、浮点数、布尔运算、字符串和[句柄][glossary.handle]。这些可以被组织成更复杂的数组、向量、结构体、表格和联合体。 + +考虑以下用于 `Echo` 接口的 FIDL 协议的示例。 ```fidl library fuchsia.examples; @@ -15,27 +21,45 @@ library fuchsia.examples; {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/echo.test.fidl" region_tag="echo" adjust_indentation="auto" %} ``` + +FIDL 协议描述了一组**方法**，在通过通道发送消息时被调用。通道消息本身是异步的，发送方和接收方彼此可以独立操作。FIDL 方法引入了更高层次的语义，使 FIDL 交易的客户端和服务器端的编程更加符合传统习惯。 + +FIDL 支持以下方法类型： + +* **双向方法**：一个典型的方法调用是，接受可选的参数，其返回类型定义在 `->` 操作符之后。双向方法会阻塞调用方直到收到响应。在 `Echo` 的例子中，`EchoString()` 方法是一个双向的方法。 + +* **单向方法**：异步方法调用，立即返回而不等待响应。没有声明返回类型的方法被认为是客户端的单向方法。在 `Echo` 的例子中，`SendString()` 方法是一个单向的方法。 + +* **事件**：必要时，服务器端可以向客户端发送非请求信息，这种消息称为事件。事件在 `->` 操作符的返回端声明其方法名称。在 `Echo` 的例子中，`OnString()` 方法是一个事件。 + +注意：要获取 FIDL 语言语法和支持的类型的更多细节，请参阅 [FIDL 语言规范](/reference/fidl/language/language.md)。 [glossary.handle]: /glossary/README.md#handle diff --git a/get-started/_common/fidl/_overview.md b/get-started/_common/fidl/_overview.md index 1075fdb1..3e6be97e 100644 --- a/get-started/_common/fidl/_overview.md +++ b/get-started/_common/fidl/_overview.md @@ -1,22 +1,34 @@ + +您已经在 **Fuchsia 简介**中了解到，Zircon 提供了内核对象类型来支持 Fuchsia 的进程间通信（IPC）。这些对象类型定义了进程用来交换数据的特定机制。在这个框架内，Zircon 通道提供了一个基于消息的异步传输能力，即支持同时传递数据和一组句柄来授予访问权。 + +Zircon 通道是 **Fuchsia 接口定义语言**（Fuchsia Interface Definition Language，FIDL）所描述的更高层次的交互的基础，FIDL 是用来描述 Fuchsia 程序所使用的 IPC 协议的语言。FIDL 允许不同的客户和服务器相互进行操作，通过强制执行一套语义行为和在通道上操作的持久性格式来实现相互操作。 + +程序通过 **FIDL 编译器**生成的特定语言的绑定（binding）和库与 FIDL 协议进行交互，该编译器是用于隐藏 Zircon IPC 复杂性的一个抽象层。这使得我们可以引入熟悉的编程习惯，如结构化类型和同步执行。编译器为每种支持的语言都生成了绑定，因此供应商不需要维护客户端库。 + +{: width="870"} diff --git a/get-started/_common/fidl/_testing_intro.md b/get-started/_common/fidl/_testing_intro.md index b1611972..20be291d 100644 --- a/get-started/_common/fidl/_testing_intro.md +++ b/get-started/_common/fidl/_testing_intro.md @@ -1,3 +1,4 @@ + +[集成测试](https://en.wikipedia.org/wiki/Integration_testing){:.external} 侧重于验证组件的行为，因为它会与系统上其他组件进行交互。正因为如此，集成测试通常与主组件分开构建，并且可能将被测组件和其他依赖组件声明为子组件。根据测试的性质，依赖组件可以作为模拟（mock）或存根（stub）提供，以促进测试用例保持封闭性。 diff --git a/get-started/_common/intro/_architecture.md b/get-started/_common/intro/_architecture.md index 522c93d6..9455f7c9 100644 --- a/get-started/_common/intro/_architecture.md +++ b/get-started/_common/intro/_architecture.md @@ -1,29 +1,54 @@ + +![展示整个 Fuchsia 系统架构的高层图表的数据表，强调了核心组件和子系统] (/get-started/images/intro/fuchsia-architecture.png){: width="1080"} -The following architectural principles guide Fuchsia's design and development: + +以下架构性原则指导了 Fuchsia 的设计与开发： + +* [**简单：**][simple]Fuchsia 让创建、维护和集成软件与硬件在各种设备中都变得容易。 + +* [**安全：**][secure]Fuchsia 有着为现代计算设计的内核和软件模型。 + +* [**可升级：**][updatable]作为模块化操作系统，Fuchsia 允许内核、驱动和软件组件独立升级。 + +* [**高性能：**][performant]Fuchsia 为真实世界产品需求设计，并为性能优化。 + +系统的核心是 [Zircon][glossary.zircon]，它是处理系统启动与引导的内核和一组库。其他所有系统组件都实现于用户空间并被隔离，再次强化了**最小特权原则**。这些组件包括： + +* 设备驱动 +* 文件系统 +* 网络栈 [glossary.zircon]: /glossary/README.md#zircon [simple]: /concepts/principles/simple.md diff --git a/get-started/_common/intro/_components_intro.md b/get-started/_common/intro/_components_intro.md index fbdc8fe7..f4aef32b 100644 --- a/get-started/_common/intro/_components_intro.md +++ b/get-started/_common/intro/_components_intro.md @@ -1,20 +1,28 @@ -**Components** are the foundational building blocks of software running in + +**组件**是 Fuchsia 中运行的软件的基石。每一个组件都是可以组合的沙盒模块，相互之间通过功能交互。这提高了系统安全性并在各个组件之间建立了清晰的接口，使它们更容易更新或替换。 -In Fuchsia, **everything is a component** (almost). Recall from the previous + +Fuchsia 中**一切都是组件**（几乎）。回想一下之前对 Zircon 的讨论，内核有意设计得很小，大多数核心服务都是在用户空间中实现。这意味着在 Fuchsia 上运行的大多数软件都是采用组件框架实现的，包括： -* User-facing applications + +* 面向用户的应用 +* 设备驱动 +* 文件系统 +* 媒体编解码器 +* 网络栈 -Outside the kernel there are only a few low-level exceptions not using the -component framework, such as bootloaders and the `userboot` process. + +内核之外只有少数不使用组件框架的底层例外，如引导程序和 `userboot` 进程。 diff --git a/get-started/_common/intro/_overview.md b/get-started/_common/intro/_overview.md index 14ce6cb7..fd7b58c0 100644 --- a/get-started/_common/intro/_overview.md +++ b/get-started/_common/intro/_overview.md @@ -1,6 +1,9 @@ -Fuchsia is a new open source operating system created at Google from the kernel -up to meet the needs of today's growing ecosystem of connected devices. + +Fuchsia 是谷歌从内核创建的一种新的开源操作系统，旨在满足当今不断增长的互联设备生态系统的需求。 + -In this training module, you'll learn the core principles behind this new + +在本培训模块中，您将了解这一新操作系统背后的核心原理，并探索 Fuchsia 如何为开发人员在各种设备上创建经久耐用的产品和体验奠定基础。 diff --git a/get-started/_common/intro/_sandboxing_intro.md b/get-started/_common/intro/_sandboxing_intro.md index 2e22ab62..e73de119 100644 --- a/get-started/_common/intro/_sandboxing_intro.md +++ b/get-started/_common/intro/_sandboxing_intro.md @@ -1,3 +1,6 @@ + +在这一章中，您将学习 Zircon 内核对象如何使 Fuchsia 能够遵循**最少特权原则**，隔离进程并只授予他们需要的权限。 diff --git a/get-started/_common/intro/_sandboxing_namespaces.md b/get-started/_common/intro/_sandboxing_namespaces.md index 7fd4a275..add13543 100644 --- a/get-started/_common/intro/_sandboxing_namespaces.md +++ b/get-started/_common/intro/_sandboxing_namespaces.md @@ -1,11 +1,16 @@ -## Namespaces - + +## 命名空间 + +进程的命名空间包含了进程对外界的私有视图，并且控制了进程能够对 Fuchsia 系统造成多少影响。 +这有效地定义了进程所在的沙箱的规则。 -Namespaces are populated with various resource objects, including: - + +命名空间由各种资源对象填充，包括： + +* **文件**: 包含二进制数据的对象。 +* **目录**: 包含其他对象的对象。 +* **套接字**: 打开时建立连接的对象，如命名管道。 +* **协议和服务**: 打开时提供结构化服务的对象。 +* **设备**: 提供对硬件资源的访问的对象。 + +进程的创建者基于那些所请求的能力，来填充命名空间的内容。 +进程不能向自己的命名空间添加对象，因为这实际上相当于进程在授予自身访问那些对象的权限。 diff --git a/get-started/_common/intro/_sandboxing_sandboxing.md b/get-started/_common/intro/_sandboxing_sandboxing.md index b6027567..8c31049b 100644 --- a/get-started/_common/intro/_sandboxing_sandboxing.md +++ b/get-started/_common/intro/_sandboxing_sandboxing.md @@ -1,10 +1,17 @@ -## Sandboxing + +## 沙盒 + +当一个新进程被创建时，它没有任何能力。 +进程完全依赖于其创建者通过传给它的那些[句柄][glossary.handle]来提供能力。 +我们也可以说，空进程没有**环境权限**（ambient authority）。 + +因此，进程被创建时通常被赋予一些初始资源和能力。 +`fuchsia.process.Launcher` 协议提供了从一个可执行文件和一组内核对象句柄来在系统上创建新进程的低级接口。 +大多数软件使用组件框架，它简化了创建一个有一组标准的初始能力的新进程来执行一些代码的工作。 +您将在稍后更详细地探索组件。 - + +
一些给予进程的初始句柄是被进程挂载到**命名空间**（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 f3786636..7079e48f 100644
--- a/get-started/explore_fuchsia.md
+++ b/get-started/explore_fuchsia.md
@@ -1,11 +1,9 @@
-
-# 探索 Fuchsia {#explore-fuchsia}
+# Explore Fuchsia {#explore-fuchsia}
-
-在设备或模拟器上启动并运行 Fuchsia 后，请查看以下资源：
+Once you have Fuchsia up and running on a device or emulator,
+check out the following resources:
-
@@ -14,93 +12,75 @@ check out the following resources: -->
* [创建 Fuchsia 组件](#create-fuchsia-components)。
* [贡献更改](#contribute-changes)。
-
-## 运行 ffx 命令 {#run-ffx-commands}
+## Run ffx commands {#run-ffx-commands}
-
-[`ffx`][ffx-overview] 是 Fuchsia 目标工作流的主机工具，为所有 Fuchsia 环境和主机平台上提供一致的开发体验。
+and host platforms.
-
-以下是一些 `ffx` 命令示例：
+The following are some of `ffx` command examples:
-
-* 显示设备列表：
+* 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}
-
-要试用 Fuchsia 的样例程序，请参考如下指南：
+To try out Fuchsia's sample software, check out the guides below:
-
* [运行示例组件](/development/run/run-examples.md)
* [运行测试组件](/development/run/run-test-component.md)
* [运行端到端测试](/development/testing/run_an_end_to_end_test.md)
-
-## 创建 Fuchsia 组件 {#create-fuchsia-components}
+## Create Fuchsia components {#create-fuchsia-components}
-
-Fuchsia 中软件的最小可执行单元是[组件](/concepts/components/v2)，这些组件通过
-[FIDL](/concepts/fidl/overview.md)（Fuchsia 接口定义语言）协议彼此交互。
+Fuchsia 中软件的最小可执行单元是[组件](/concepts/components/v2)，这些组件通过 [FIDL](/concepts/fidl/overview.md)（Fuchsia 接口定义语言）协议彼此交互。
要想了解更多有关 Fuchsia 组件和 FIDL 的信息，请参考如下指南：
-
-* [构建组件](/development/components/build.md)
-* [FIDL 概览](/development/languages/fidl/README.md)
-* [FIDL 教程](/development/languages/fidl/tutorials/overview.md)
+* [FIDL tutorials](/development/languages/fidl/tutorials/overview.md)
-
-## 贡献更改 {#contribute-changes}
+## Contribute changes {#contribute-changes}
-
-当您准备好为 Fuchsia 项目做出贡献时，请参阅[贡献更改][contribute-changes]。
+When you're ready to contribute to the Fuchsia project,
+see [Contribute changes][contribute-changes].
-
-## 参阅
+## See also
-
-要获取关于 Fuchsia 开发流程的更多信息，请参阅下列资源：
+For more information on Fuchsia's development workflows,
+check out the following resources:
-
* [源代码布局](/development/source_code/layout.md)
* [构建系统](/development/build/build_system/index.md)
+
[components]: /concepts/components/v2
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/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/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/glossary-translation.md b/glossary-translation.md
index 8cf6039a..9394f686 100644
--- a/glossary-translation.md
+++ b/glossary-translation.md
@@ -12,6 +12,7 @@
| 英文原文 | 中文翻译对应词 | 备注 |
| ------------------------------ | ---------------------- | ----------------------------------------------------- |
+| accessibility | 无障碍功能 | G |
| application | 应用