Docs: Changes to source.android.com - 230969164 Add details about supported deviceless tests by Android Partner Docs <[email protected]> - 230954177 Devsite localized content from translation request 1089952. by Android Partner Docs <[email protected]> - 230924636 Devsite localized content from translation request 1092604. by Android Partner Docs <[email protected]> - 230924621 Devsite localized content from translation request 1091268. by Android Partner Docs <[email protected]> - 230811847 Please review this new content for "Automotive Power Mana... by Janet Davies <[email protected]> - 230794111 Add HWASan to the docs ready for bootcamp. by Android Partner Docs <[email protected]> - 230779068 Link to NDK docs on DAC from first reference to Make by Android Partner Docs <[email protected]> - 230744983 Devsite localized content from translation request 1092191. by Android Partner Docs <[email protected]> - 230744981 Devsite localized content from translation request 1093422. by Android Partner Docs <[email protected]> - 230744964 Devsite localized content from translation request 1094193. by Android Partner Docs <[email protected]> - 230742820 Moving Marshmallow 6.0 to No Release Planned as CTS 6.0 w... by Android Partner Docs <[email protected]> - 230614628 Fixed broken links (they were relative and not absolute f... by Christina Nguyen <[email protected]> - 230384953 Remove rogue parenthesis by Danielle Roberts <[email protected]> - 230375898 Fix broken links to subpages with absolute paths by Android Partner Docs <[email protected]> - 230364707 Devsite localized content from translation request 1093572. by Android Partner Docs <[email protected]> - 230364690 Devsite localized content from translation request 1093439. by Android Partner Docs <[email protected]> - 230364619 Devsite localized content from translation request 1089936. by Android Partner Docs <[email protected]> - 230364605 Devsite localized content from translation request 1086836. by Android Partner Docs <[email protected]> - 230364588 Devsite localized content from translation request 1093713. by Android Partner Docs <[email protected]> - 230364494 Devsite localized content from translation request 1093448. by Android Partner Docs <[email protected]> - 230364465 Devsite localized content from translation request 1091295. by Android Partner Docs <[email protected]> - 230364454 Devsite localized content from translation request 1092609. by Android Partner Docs <[email protected]> - 230364368 Devsite localized content from translation request 1048174. by Android Partner Docs <[email protected]> - 230364354 Devsite localized content from translation request 1047598. by Android Partner Docs <[email protected]> - 230364346 Devsite localized content from translation request 1089969. by Android Partner Docs <[email protected]> - 230020584 Update the guide for using vendor provided bcc by Android Partner Docs <[email protected]> - 229999258 Fix a typo in gsi.html by Android Partner Docs <[email protected]> - 229997798 Add file_patterns attribute documentation by Android Partner Docs <[email protected]> - 229991256 Update the characters for zh-cn and zh-tw in the Security... by Danielle Roberts <[email protected]> - 229977174 Moving time zones to Updates (from Permissions); also upd... by Heidi von Markham <[email protected]> - 229831729 Devsite localized content from translation request 1090171. by Android Partner Docs <[email protected]> - 229831714 Devsite localized content from translation request 1090622. by Android Partner Docs <[email protected]> - 229831667 Devsite localized content from translation request 1015775. by Android Partner Docs <[email protected]> - 229831656 Devsite localized content from translation request 1088392. by Android Partner Docs <[email protected]> - 229831644 Devsite localized content from translation request 1090166. by Android Partner Docs <[email protected]> - 229581198 Devsite localized content from translation request 1086821. by Android Partner Docs <[email protected]> - 229425689 Fixing typos for Shutdown (to shutdown) by Heidi von Markham <[email protected]> - 229416134 Update a paragraph in the permission model section of the... by Luke Haviland <[email protected]> - 229402835 Devsite localized content from translation request 553155. by Android Partner Docs <[email protected]> - 229305053 Devsite localized content from translation request 1091266. by Android Partner Docs <[email protected]> - 229305046 Devsite localized content from translation request 1091273. by Android Partner Docs <[email protected]> - 229245843 Devsite localized content from translation request 1015221. by Android Partner Docs <[email protected]> - 228916961 Fix typo by Kenneth Lau <[email protected]> - 228796242 Change "Optional" to "Required" by Kenneth Lau <[email protected]> - 228720589 Devsite localized content from translation request 1090636. by Android Partner Docs <[email protected]> - 228612958 Added Joshua Laney's information to November security ack... by Luke Haviland <[email protected]> - 228585561 Update versions file by Kenneth Lau <[email protected]> - 228557861 Devsite localized content from translation request 1089965. by Android Partner Docs <[email protected]> - 228541590 Fix HTML. by Android Partner Docs <[email protected]> - 228525372 Replace unresolved variable reference in localized files. by Android Partner Docs <[email protected]> - 228439111 Add missing < by Android Partner Docs <[email protected]> - 228436522 Adding the January Android bulletin acknowledgements by Luke Haviland <[email protected]> - 228407590 Correct the naming of EGL extension, and point the link t... by Android Partner Docs <[email protected]> - 228395277 Rename Test Config to Build Config to better reflect Soon... by Android Partner Docs <[email protected]> - 228340013 Devsite localized content from translation request 1044284. by Android Partner Docs <[email protected]> - 228340002 Devsite localized content from translation request 1048178. by Android Partner Docs <[email protected]> - 228339974 Devsite localized content from translation request 1089289. by Android Partner Docs <[email protected]> - 228339806 Devsite localized content from translation request 999875. by Android Partner Docs <[email protected]> - 228339785 Devsite localized content from translation request 1046259. by Android Partner Docs <[email protected]> - 228339757 Devsite localized content from translation request 1049718. by Android Partner Docs <[email protected]> - 228267452 Add information on gdbclient.py by Kenneth Lau <[email protected]> - 228261450 Adding the Android AOSP links to the Android January secu... by Luke Haviland <[email protected]> - 228247613 Fill in security levels for December 2018 builds. by Android Partner Docs <[email protected]> - 228241115 Add January 2019 builds. by Android Partner Docs <[email protected]> - 228208289 Remove _toc-*.yaml files that are no longer used due to r... by Christina Nguyen <[email protected]> - 228205865 Devsite localized content from translation request 1048626. by Android Partner Docs <[email protected]> - 228205856 Devsite localized content from translation request 1048155. by Android Partner Docs <[email protected]> - 228205845 Devsite localized content from translation request 1047886. by Android Partner Docs <[email protected]> - 228186179 Adding the January 2019 security Android/Pixel bulletins. by Luke Haviland <[email protected]> - 228183717 Add BCC native stack dump documentation by Android Partner Docs <[email protected]> - 228181974 Devsite localized content from translation request 1089935. by Android Partner Docs <[email protected]> - 227911224 Add more information on cts-dev and also --skip-precondit... by Android Partner Docs <[email protected]> - 227772142 Update image path by Danielle Roberts <[email protected]> - 227719040 Fix broken links by Kenneth Lau <[email protected]> - 227715850 Devsite localized content from translation request 1045494. by Android Partner Docs <[email protected]> - 227715841 Devsite localized content from translation request 1044265. by Android Partner Docs <[email protected]> - 227715826 Devsite localized content from translation request 1087340. by Android Partner Docs <[email protected]> - 227709199 Fix path on images by Danielle Roberts <[email protected]> - 227620512 Devsite localized content from translation request 1032286. by Android Partner Docs <[email protected]> - 227620508 Devsite localized content from translation request 1087344. by Android Partner Docs <[email protected]> - 227620485 Devsite localized content from translation request 1087104. by Android Partner Docs <[email protected]> - 227620481 Devsite localized content from translation request 1046261. by Android Partner Docs <[email protected]> - 227620479 Devsite localized content from translation request 1087239. by Android Partner Docs <[email protected]> - 227617540 Devsite localized content from translation request 1007762. by Android Partner Docs <[email protected]> - 227617535 Devsite localized content from translation request 1089145. by Android Partner Docs <[email protected]> - 227617491 Devsite localized content from translation request 1087109. by Android Partner Docs <[email protected]> - 227617482 Devsite localized content from translation request 1047584. by Android Partner Docs <[email protected]> - 227617480 Devsite localized content from translation request 1089449. by Android Partner Docs <[email protected]> - 227617378 Devsite localized content from translation request 1087099. by Android Partner Docs <[email protected]> - 227610447 Add variable tag to CTS downloads page by Danielle Roberts <[email protected]> - 227595909 Add link to camera section on CTS setup page by Kenneth Lau <[email protected]> - 227595777 Change title to title case by Kenneth Lau <[email protected]> - 227546776 Newline between function and param descriptions. by Android Partner Docs <[email protected]> - 227546753 Small edits to system best practices by Danielle Roberts <[email protected]> - 227033873 Document "run cts-dev" command, present CTS V2 first by Android Partner Docs <[email protected]> - 226772000 Devsite localized content from translation request 1041964. by Android Partner Docs <[email protected]> - 226552899 Announce Adiantum on SAC home page by Danielle Roberts <[email protected]> - 226550934 Add Adiantum docs to encryption section by Danielle Roberts <[email protected]> - 226530870 Devsite localized content from translation request 1046265. by Android Partner Docs <[email protected]> - 226497667 Devsite localized content from translation request 1047878. by Android Partner Docs <[email protected]> (And 26 more changes) PiperOrigin-RevId: 230969164 Change-Id: I2bf51b3793304247e04b953816961605fe1ba4bf
diff --git a/zh-cn/setup/build/building-kernels.html b/zh-cn/setup/build/building-kernels.html index ba49ca1..c21736a 100644 --- a/zh-cn/setup/build/building-kernels.html +++ b/zh-cn/setup/build/building-kernels.html
@@ -27,7 +27,7 @@ <p>本部分中的所有示例均使用 <a href="devices.html#hikey-boards">hikey</a> 内核。</p> <h2 id="figuring-out-which-kernel-to-build">选择内核</h2> -<p>此表列出了内核源代码和二进制文件的名称及所在位置：<table> +<p>此表列出了内核源代码和二进制文件的名称及所在位置：</p><table> <tbody><tr> <th>设备</th> <th>二进制文件所在的位置</th> @@ -198,7 +198,7 @@ </tr> </tbody></table> -</p><p>确定要使用的设备项目之后，请查看内核二进制文件的 Git 日志。设备项目采用 <code>device/<var>VENDOR</var>/<var>NAME</var></code> 形式。</p> +<p>确定要使用的设备项目之后，请查看内核二进制文件的 Git 日志。设备项目采用 <code>device/<var>VENDOR</var>/<var>NAME</var></code> 形式。</p> <pre class="devsite-click-to-copy"> <code class="devsite-terminal">git clone https://android.googlesource.com/kernel/hikey-linaro</code>
diff --git a/zh-cn/setup/build/building.html b/zh-cn/setup/build/building.html index 5da6d10..274f8af 100644 --- a/zh-cn/setup/build/building.html +++ b/zh-cn/setup/build/building.html
@@ -20,7 +20,7 @@ limitations under the License. --> -<p>以下关于编译 Android 源代码树的说明适用于所有分支，<code>master</code> 除外。编译命令的基本顺序如下：</p> +<p>以下关于编译 Android 源代码树的说明适用于所有分支，包括 <code>master</code>。编译命令的基本顺序如下：</p> <h2 id="obtaining-proprietary-binaries">下载专有二进制文件</h2> @@ -30,7 +30,7 @@ <h3 id="downloading-proprietary-binaries">下载专有二进制文件</h3> -<p>对于运行带标记的 AOSP 版本分支的受支持设备，您可以从 <a href="https://developers.google.com/android/drivers" class="external">Google 的驱动程序</a>下载相关的官方二进制文件。有了这些二进制文件，您将有权使用采用非开源代码的其他硬件功能。在针对某种设备编译 <code>master</code> 分支时，请使用位于 Android 源代码树的 <code>vendor/</code> 层次结构中的二进制文件。</p> +<p>对于运行带标记的 AOSP 版本分支的受支持设备，您可以从 <a href="https://developers.google.com/android/drivers" class="external">Google 的驱动程序</a>下载相关的官方二进制文件。有了这些二进制文件，您将有权使用采用非开源代码的其他硬件功能。要编译 AOSP 的 master 分支，请使用<a href="https://developers.google.com/android/blobs-preview" class="external">二进制文件预览</a>。在针对某种设备编译 master 分支时，请使用适用于<a href="/setup/start/build-numbers.html">最新编号版本</a>的二进制文件或具有最新日期的二进制文件。</p> <h3 id="extracting-proprietary-binaries">解压专有二进制文件</h3>
diff --git a/zh-cn/setup/build/dashboard.html b/zh-cn/setup/build/dashboard.html new file mode 100644 index 0000000..86de96c --- /dev/null +++ b/zh-cn/setup/build/dashboard.html
@@ -0,0 +1,43 @@ +<html devsite><head> + <title>持续集成信息中心</title> + <meta name="project_path" value="/_project.yaml"/> + <meta name="book_path" value="/_book.yaml"/> + </head> + <body> + <!-- + Copyright 2018 The Android Open Source Project + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + --> + +<p>通过<a href="https://en.wikipedia.org/wiki/Continuous_integration" class="external">持续集成</a>信息中心 (<a href="https://ci.android.com/" class="external">ci.android.com</a>)，您可以清楚了解 Android 开源项目 (AOSP) 所使用的系统。</p> + +<p>AOSP 的贡献者可以通过此信息中心来监控其提交的内容何时会集成到源代码树中。状态颜色可以显示集成的更改是否已在我们的所有编译类型中编译成功。为方便起见，每个编译版本中的编译软件工件都可供下载。</p> + +<p>每一行表示在 Android 的自动编译器中完成的一个编译。每一列表示一个编译目标/编译类型组合。网格中会显示正在进行的编译和已完成的编译。系统会使用黄色背景来标识正在进行的编译，使用红色背景来标识失败的编译，使用绿色背景来标识成功的编译。完成编译后，您可以下载相应的编译软件工件，只需点击 <span class="material-icons">get_app</span>（<strong>查看软件工件</strong>）图标即可（此图标可链接到可下载软件工件的页面）。选择一个方形即可在屏幕底部打开一个面板，其中包含“详细信息”标签（相关日志记录会保留在这里）、“更改”标签（其中会列出已纳入相应编译的更改）以及另一个指向编译软件工件的链接。新编译完成后，此信息中心会自动刷新。</p> + +<p>此信息中心可以在 <a href="https://ci.android.com" class="external">ci.android.com</a> 上找到</p> + +<figure><img src="../images/dashboard.png" alt="信息中心图片"/><figcaption><b>图 1</b>：持续集成信息中心</figcaption></figure> + +<p>此信息中心的属性包括：</p><p> +</p><ul> + <li><b>分支名称</b>：出现编译的 git 分支的名称</li> + <li><b>编译软件工件</b>：用于查看和下载此编译版本中的软件工件的链接</li> + <li><b>版本号</b>：每个编译版本的唯一 ID</li> + <li><b>编译目标</b>：设备配置</li> + <li><b>编译类型</b>：目标的确切配置，可以是 user、userdebug 或 eng。如需了解详情，请参阅<a href="/setup/build/building#choose-a-target">选择目标</a></li> + <li><b>更改链接</b>：链接到此版本中包含的更改</li> + <li><b>永久链接</b>：指向此编译版本在 <a href="https://ci.android.com" class="external">ci.android.com</a> 上的页面的永久链接</li> + +</ul></body></html> \ No newline at end of file
diff --git a/zh-cn/setup/build/gsi.html b/zh-cn/setup/build/gsi.html index 262d2da..056d682 100644 --- a/zh-cn/setup/build/gsi.html +++ b/zh-cn/setup/build/gsi.html
@@ -21,17 +21,20 @@ limitations under the License. --> -<p>常规系统映像 (GSI) 是包含已针对 Android 设备调整配置的系统映像。这种映像被视为所有 Android 设备应该都能顺利运行且包含未经修改的 Android 开源项目 (AOSP) 代码的“纯 Android”实现。 +<p>常规系统映像 (GSI) 是指已针对 Android 设备调整配置的系统映像。GSI 包含未经修改的 Android 开源项目 (AOSP) 代码，任何运行 Android 8.1 及以上版本的 Android 设备都可以顺利运行这种代码，因此我们将 GSI 视为“纯 Android”实现。 </p> -<p>GSI 中的内容不依赖于供应商映像。为了验证 GSI 的独立性，Android 设备的系统映像会被替换为 GSI，然后通过<a href="/compatibility/vts/">供应商测试套件 (VTS)</a> 和<a href="/compatibility/cts/">兼容性测试套件 (CTS)</a> 进行全面测试。同样，您可以使用 GSI 替换自己的系统映像，以验证 Android 设备能够正确实现供应商接口。 +<p>GSI 合规性是 <a href="/compatibility/overview">Android 兼容性计划</a>的一部分。为确保运行最新版 Android 的设备能够正确实现供应商接口，我们将 Android 设备的系统映像替换为 GSI，然后使用<a href="/compatibility/vts/">供应商测试套件 (VTS)</a> 和<a href="/compatibility/cts/">兼容性测试套件 (CTS)</a> 对设备进行测试。 +</p> + +<aside class="note"><strong>注意</strong>：本文介绍的 GSI 内容面向的是 Android OEM 和 ROM 开发者；Android 应用开发者应该参考 <a href="https://developer.android.com/topic/generic-system-image/">developer.android.com</a>，了解面向开发者的 GSI 详细信息。 +</aside> + +<p>开始使用 GSI 之前，请先阅读下面几节内容，详细了解 <a href="#gsi-configuration-and-variances">GSI 配置</a>（和允许的差异）、<a href="#gsi-types">类型</a>（Android GSI 和旧版 GSI）以及<a href="#vendor-binaries-and-vndk-dependencies">供应商二进制文件和 VNDK 依赖项</a>。准备好使用 GSI 后，请为设备目标<a href="#building-gsis">下载并编译 GSI</a>，然后<a href="#flashing-gsis">将 GSI 刷写</a>到 Android 设备。 </p> <h2 id="gsi-configuration-and-variances">GSI 配置和差异</h2> -<p>GSI 的目标是为所有 Android 设备提供特定的通用配置，同时允许不同的供应商设备之间存在差异。当前的 GSI 基于 Android 9。 -</p> - <p>当前的 GSI 具有以下配置：</p> <ul> @@ -52,7 +55,7 @@ <h2 id="gsi-types">GSI 类型</h2> -<p>GSI 类型取决于设备搭载的 Android 版本。Android 9 支持以下 GSI：</p> +<p>用于合规性测试的 GSI 取决于设备搭载的 Android 版本。Android 9 支持以下 GSI：</p> <table> <tbody><tr> @@ -72,22 +75,18 @@ </tr> </tbody></table> -<aside class="note"> - <strong>注意</strong>：要为某个设备确定合适的 GSI，请将此设备连接到工作站，然后运行 <code>adb shell getprop ro.product.first_api_level</code>。如果 API 级别为 28，则使用 Android GSI；如果 API 级别为 27，则使用旧版 GSI。如果没有系统属性，则说明此设备可能不受支持。 -</aside> - -<p>所有 GSI 都是从 Android 9 代码库编译的。是否支持旧版 GSI 取决于设备的供应商接口实现，并非所有搭载 Android 8.0 或 Android 8.1 的设备都能使用旧版 GSI。有关详情，请参阅<a href="#vendor-binaries-and-vndk-dependencies">供应商二进制文件和 VNDK 依赖项</a>。 +<p>所有 GSI 都是从 Android 9 代码库编译的。 </p> <h3 id="changes-in-p-gsis">Android 9 GSI 变更</h3> -<p>搭载 Android 9 的设备必须使用 Android 9 GSI，Android 9 GSI 与早期 GSI 相比存在以下主要变化：</p> +<p>搭载 Android 9 的设备必须使用 Android 9 GSI 测试合规性，Android 9 GSI 与早期 GSI 相比存在以下主要变化：</p> <ul> <li><strong>合并 GSI 和模拟器</strong>。GSI 是根据模拟器产品（例如，<code>aosp_arm64</code>、<code>aosp_x86</code> 等）的系统映像编译的。</li> <li><strong>System-as-root</strong>。在以前的 Android 版本中，不支持 A/B 更新的设备可以在 <code>/system</code> 目录下装载系统映像。在 Android 9 中，系统映像的 root 作为设备的 root 装载。</li> <li><strong>64 位 binder 接口</strong>。在 Android 8.x 中，32 位 GSI 使用 32 位 binder 接口。Android 9 不支持 32 位 binder 接口，因此 32 位 GSI 和 64 位 GSI 都使用 64 位 binder 接口。</li> - <li><strong>强制执行 VNDK</strong>。在 Android 8.1 中，VNDK 是可选的。在 Android 9 中，VNDK 是强制性的，这意味着 <code>BOARD_VNDK_RUNTIME_DISABLE</code> <strong>不可</strong>设置 (<code>BOARD_VNDK_RUNTIME_DISABLE := # must not be set</code>)。</li> + <li><strong>强制执行 VNDK</strong>。在 Android 8.1 中，VNDK 是可选的。在 Android 9 中，VNDK 是强制性的，这意味着<strong>不得</strong>设置 <code>BOARD_VNDK_RUNTIME_DISABLE</code> (<code>BOARD_VNDK_RUNTIME_DISABLE := # must not be set</code>)。</li> <li><strong>兼容的系统属性</strong>。Android 9 支持对兼容的系统属性进行访问检查：<code>PRODUCT_COMPATIBLE_PROPERTY_OVERRIDE := true</code>。</li> </ul> @@ -95,7 +94,7 @@ <h3 id="changes-in-legacy-gsis">Android 9 旧版 GSI 变更</h3> -<p>升级到 Android 9 的设备可以使用名称带后缀 <code>_ab</code> 或 <code>_a</code> 的旧版 GSI 产品（例如，<code>aosp_arm64_ab</code>、<code>aosp_x86_a</code>）。此 GSI 支持以下升级用例：</p> +<p>升级到 Android 9 的设备可以使用名称带有 <code>_ab</code> 或 <code>_a</code> 后缀的旧版 GSI 产品（例如，<code>aosp_arm64_ab</code>、<code>aosp_x86_a</code>）测试合规性。此 GSI 支持以下升级用例：</p> <ul> <li>具有 Android 8.1 供应商接口实现的设备</li> @@ -132,11 +131,11 @@ <table> <tbody><tr> <th>用例</th> - <th>供应商二进制文件版本</th> + <th>供应商<br />二进制文件<br />版本</th> <th><code>BOARD_VNDK_VERSION</code></th> <th><code>BOARD_VNDK_RUNTIME_DISABLE</code></th> - <th>旧版 GSI 系统二进制文件版本</th> - <th>旧版 GSI 支持</th> + <th>旧版 GSI<br />系统二进制文件版本</th> + <th>旧版 GSI 支持情况</th> </tr> <tr> <td>0</td> @@ -191,9 +190,7 @@ <p>最常见的受支持用例是 2，其中旧版 GSI 支持运行 Android 8.1 且使用 <code>BOARD_VNDK_VERSION</code> 进行编译（而未通过设置 <code>BOARD_VNDK_RUNTIME_DISABLE</code> 进行编译，即，未停用运行时强制执行）的设备。 </p> -<p>两个不受支持的用例是 1.a 和 1.b，其中旧版 GSI 不支持运行 Android 8.1 且未使用 <code>BOARD_VNDK_VERSION</code> 或通过设置 <code>BOARD_VNDK_RUNTIME_DISABLE</code> 进行编译（即，运行时强制执行已停用）的设备。这些设备不受支持，因为它们的供应商二进制文件依赖于 Android 8.1 非 VNDK 共享库，这些库未包含在旧版 GSI 中。</p> - -<p>要使这些设备与旧版 GSI 兼容，供应商必须执行以下操作之一：</p> +<p>两个不受支持的用例是 1.a 和 1.b，其中旧版 GSI 不支持运行 Android 8.1 且未使用 <code>BOARD_VNDK_VERSION</code> 或通过设置 <code>BOARD_VNDK_RUNTIME_DISABLE</code> 进行编译（即，运行时强制执行已停用）的设备。之所以不支持这些设备，是因为这些设备的供应商二进制文件依赖于 Android 8.1 非 VNDK 共享库，而旧版 GSI 中不包含这些库。要使这些设备与旧版 GSI 兼容，供应商必须执行以下操作之一：</p> <ul> <li>启用 <code>BOARD_VNDK_VERSION</code>，但未设置 <code>BOARD_VNDK_RUNTIME_DISABLE</code>（用例 2）<br /><br />或<br /><br /></li> @@ -202,13 +199,13 @@ <h2 id="building-gsis">编译 GSI</h2> -<p>自 Android 9 开始，每个 Android 版本都在 AOSP 上拥有一个名为 <code><var>DESSERT</var>-gsi</code> 的 GSI 分支（例如，<code>pie-gsi</code> 是 Android 9 的 GSI 分支）。GSI 分支包含应用了所有<a href="/security/bulletin/">安全补丁程序</a>和 <a href="#contributing-to-a-gsi">GSI 补丁程序</a> 的 Android 内容。 +<p>从 Android 9 开始，每个 Android 版本都在 AOSP 上拥有一个名为 <code><var>DESSERT</var>-gsi</code> 的 GSI 分支（例如，<code>pie-gsi</code> 是 Android 9 的 GSI 分支）。GSI 分支包含应用了所有<a href="/security/bulletin/">安全补丁程序</a>和 <a href="#contributing-to-gsis">GSI 补丁程序</a>的 Android 内容。 </p> -<p>要编译 GSI，请从 GSI 分支进行<a href="/setup/build/downloading">下载</a>，然后<a href="/setup/build/building#choose-a-target">选择 GSI 编译目标</a>，从而设置 Android 源代码树。请根据以下编译目标表确定设备应使用哪个 GSI 版本。编译完成后，GSI 便会成为系统映像（例如 <code>system.img</code>）并显示在输出文件夹 <code>out/target/product/<strong>generic_arm64_ab</strong></code> 中。编译还会输出 <code>vbmeta.img</code>；对于使用 <a href="/security/verifiedboot/avb">Android 验证启动</a>的设备，您可以将其用于停用验证启动。 +<p>要编译 GSI，请从 GSI 分支进行<a href="/setup/build/downloading">下载</a>，然后<a href="/setup/build/building#choose-a-target">选择 GSI 编译目标</a>，从而设置 Android 源代码树。请根据以下编译目标表确定设备应使用哪个 GSI 版本。编译完成后，GSI 便会成为系统映像（例如 <code>system.img</code>）并显示在输出文件夹 <code>out/target/product/<strong>generic_arm64_ab</strong></code> 中。编译还会输出 <code>vbmeta.img</code>；您可以利用此映像在使用 <a href="/security/verifiedboot/avb">Android 验证启动</a>的设备上停用验证启动。 </p><p> -</p><p>示例：以下命令可在 GSI 分支 <code>pie-gsi</code> 上编译旧版 GSI 编译目标 <code>aosp_arm64_ab-userdebug</code>：</p> +</p><p>例如，要在 GSI 分支 <code>pie-gsi</code> 上编译旧版 GSI 编译目标 <code>aosp_arm64_ab-userdebug</code>，请运行以下命令：</p> <pre class="prettyprint"> $ repo init -u https://android.googlesource.com/platform/manifest -b pie-gsi @@ -362,12 +359,12 @@ <em>**可以根据要求添加</em> <aside class="aside"> - <strong>注意</strong>：在未来的 Android 版本中可能会移除这些编译目标。 + <strong>注意：</strong>在未来的 Android 版本中可能会移除这些编译目标。 </aside> -<h2 id="flashing-gsis">刷写 GSI</h2> +<h2 id="flashing-gsis">刷写 GSI 的要求</h2> -<p>Android 设备可能具有不同的设计，因此不可能通过单个命令或单组指令将 GSI 刷写到特定设备上。请使用以下常规步骤作为指南：</p> +<p>Android 设备可能具有不同的设计，因此不可能通过单个命令或单组指令将 GSI 刷写到特定设备上。您可以向 Android 设备的制造商索要详细的刷写说明，也可以参考以下常规步骤：</p> <ol> <li>确保设备具备以下条件： @@ -375,9 +372,7 @@ <li>支持 HIDL-HAL 接口。</li> <li>用于解锁设备的方法（以便能够使用 <code>fastboot</code> 对其进行刷写）。</li> <li>用于停用验证启动的方法（例如 <a href="/security/verifiedboot/">vboot 1.0</a>、<a href="/security/verifiedboot/avb">AVB</a> 等）。</li> - <li>解锁设备，使其可通过 <code>fastboot</code> 进行刷写。</li> - <aside class="note"> - <strong>注意</strong>：请通过 Android 源代码树来编译 <code>fastboot</code>，以确保您拥有其最新版本。</aside> + <li>解锁设备，使其可通过 <code>fastboot</code> 刷写。（为确保您拥有最新版本的 <code>fastboot</code>，请从 Android 源代码树进行编译。）</li> </ul> </li> <li>停用验证启动。</li> @@ -386,7 +381,7 @@ <li>重新启动设备。</li> </ol> -<p>例如，要将 GSI 刷写到 Pixel 2 设备，请执行以下操作：</p> +<p>例如，要将 GSI 刷写到任何 Pixel 设备，请执行以下操作：</p> <ol> <li><a href="/setup/build/running#booting-into-fastboot-mode">启动到引导加载程序模式</a>，然后<a href="/setup/build/running#unlocking-the-bootloader">解锁引导加载程序</a>。</li>
diff --git a/zh-cn/setup/build/jack.html b/zh-cn/setup/build/jack.html index 50696dc..56e5e7a 100644 --- a/zh-cn/setup/build/jack.html +++ b/zh-cn/setup/build/jack.html
@@ -21,7 +21,7 @@ --> <aside class="warning"> - <strong>警告</strong>：自 <a href="https://android-developers.googleblog.com/2017/03/future-of-java-8-language-feature.html" class="external">2017 年 3 月 14 日的这份公告</a>发布之后，Jack 工具链便被弃用了。Jack 是 Android 6.0 - 8.1 的默认 Android 编译工具链。 + <strong>警告</strong>：自 <a href="https://android-developers.googleblog.com/2017/03/future-of-java-8-language-feature.html" class="external">2017 年 3 月 14 日的这份公告</a>发布之后，Jack 工具链已被弃用。Jack 是 Android 6.0 - 8.1 的默认 Android 编译工具链。 </aside> <p>Jack 是一种 Android 工具链，用于将 Java 源代码编译成 Android dex 字节码。要使用 Jack，您只需使用标准的 Makefile 命令来编译源代码树或您的项目即可，无需进行任何其他操作。Android 8.1 是使用 Jack 的最后一个版本。</p> @@ -34,7 +34,7 @@ <h3 id="jack_library">Jack 库格式</h3> -<p>Jack 具有自己的 .jack 文件格式，其中包含相应库的预编译 dex 代码，可实现更快速的编译（dex 预处理）。</p> +<p>Jack 有自己的 .jack 文件格式，其中包含相应库的预编译 dex 代码，可实现更快速的编译（dex 预处理）。</p> <img src="../images/jack_library.png" alt="Jack 库文件内容"/> <figcaption><strong>图 2.</strong> Jack 库文件内容</figcaption> @@ -87,7 +87,7 @@ </tr> <tr> <td>编译因“Cannot launch background server”（无法启动后台服务器）而失败</td> -<td>最可能的原因是您计算机上的 TCP 端口都被占用了。您可以通过修改 <code>$HOME/.jack</code>（<code>SERVER_PORT_SERVICE</code> 和 <code>SERVER_PORT_ADMIN</code> 变量）来更改端口。要解决这种问题，请通过修改 <code>$HOME/.jack</code> 并将 <code>SERVER</code> 更改为 false 来停用 Jack 编译服务器。遗憾的是，这将大大降低编译速度，并可能会迫使您使用加载控制（<code>make</code> 的选项 <code>-l</code> ）启动 <code>make -j</code>。</td> +<td>最可能的原因是您计算机上的 TCP 端口都被占用了。您可以通过修改 <code>$HOME/.jack</code>（<code>SERVER_PORT_SERVICE</code> 和 <code>SERVER_PORT_ADMIN</code> 变量）来更改端口。要解决这种问题，请通过修改 <code>$HOME/.jack</code> 并将 <code>SERVER</code> 更改为 false 来停用 Jack 编译服务器。但是，这将大大降低编译速度，并可能会迫使您使用加载控制（<code>make</code> 的选项 <code>-l</code> ）启动 <code>make -j</code>。</td> </tr> <tr> <td>编译卡住了，没有任何进展</td>
diff --git a/zh-cn/setup/build/running.html b/zh-cn/setup/build/running.html index 06dc2f6..d8df1fb 100644 --- a/zh-cn/setup/build/running.html +++ b/zh-cn/setup/build/running.html
@@ -258,7 +258,7 @@ <p><code>lunch</code> 菜单中提供了建议的设备编译系统，在不使用任何参数的情况下运行 <code>lunch</code> 命令即可查看。 您可以从 developers.google.com 下载 Nexus 设备的出厂映像和二进制文件。请参阅<a href="requirements#binaries">设备二进制文件</a>进行下载。有关详情以及其他资源，请参阅<a href="building.html#obtaining-proprietary-binaries">下载专有二进制文件</a>。 -<table> +</p><table> <thead> <tr> <th>设备</th> @@ -395,7 +395,7 @@ </tbody> </table> -</p><aside class="note"><strong>注意</strong>：请不要在原本搭载 Android 4.1.2 或更高版本的 Nexus 7 上使用 Android 4.1.1。</aside> +<aside class="note"><strong>注意</strong>：请不要在原本搭载 Android 4.1.2 或更高版本的 Nexus 7 上使用 Android 4.1.1。</aside> <h2 id="flashing-a-device">刷写设备</h2>
diff --git a/zh-cn/setup/community.html b/zh-cn/setup/community.html index 0bb9f7f..08a3069 100644 --- a/zh-cn/setup/community.html +++ b/zh-cn/setup/community.html
@@ -181,35 +181,35 @@ <p><em>使用明确、相关的内容主题。</em> 这对每个人都会有所帮助，包括那些尝试回答您问题的人，以及可能在日后查找相关信息的人。</p> </li> <li> -<p><em>在您的帖子中提供充足的详细信息。</em> 提供代码或日志片段、屏幕截图标注以及类似的详细信息有助于获得更理想的结果，并能促成更有效的讨论。如需在提问时如何措辞方面的实用指导，请参阅<a href="http://www.catb.org/%7Eesr/faqs/smart-questions.html">提问的智慧</a>。</p> +<p><em>在您的帖子中提供充足的详细信息。</em> 提供代码或日志片段、屏幕截图标注以及类似的详细信息有助于获得更理想的结果，并能促成更有效的讨论。要查看有关在提问时如何措辞的实用指导，请参阅<a href="http://www.catb.org/%7Eesr/faqs/smart-questions.html">提问的智慧</a>。</p> </li> </ul> <h3 id="mailing">论坛规则</h3> -<p>我们喜欢简单，讨厌各种限制，因此我们的政策极其简要。以下规则说明了我们对 Android 论坛订阅者的要求。 +<p>我们喜欢简单，讨厌各种限制，因此我们的规则极其简要。我们在以下规则中说明了我们对 Android 论坛订阅者的要求。 </p><ul> -<li>请保持友善的态度：对他人保持礼貌和尊重是 Android 文化的重要组成部分，我们希望参与 Android 社区的每个人都和我们一样毫无保留地接受这一点。<em></em>保持礼貌并不意味着我们彼此之间不能以具有建设性的方式表达异议，但我们在表达异议时必须要有礼貌。无论出于任何原因，都不能敌视或轻视任何人；如果您认为自己有这种情绪，那么在发帖之前请三思。移动开发是一项非常严肃的业务，但也有很多乐趣。让我们保持这种状态，努力打造最友善的开放源代码社区之一。 +<li>请保持友善的态度：对他人保持礼貌和尊重是 Android 文化的重要组成部分，我们希望参与 Android 社区活动的每个人都和我们一样毫无保留地接受这一点。<em></em>保持礼貌并不意味着我们相互之间不能提出有建设性的异议，但我们在表达异议时必须要有礼貌。无论出于何种原因，都不能对任何人表现出轻视或敌意；如果您认为自己有这种情绪，发帖之前请三思。移动开发是一项非常严肃的工作，但同时也充满着乐趣。让我们保持这种状态，努力打造最友善的开源社区之一。 </li> -<li>允许讨论的主题：我们的大多数论坛都用于讨论与 Android 相关的技术话题或方便用户互相帮助。<em></em>一般情况下，我们不会对在论坛中讨论的主题进行严格限制：只要主题在某种程度上与 Android 相关，都可以在我们的论坛中进行讨论。我们欢迎大家公布和讨论与 Android 相关的产品、库、出版物和其他有趣的新闻，但请不要同时在多个论坛中发帖。请仅在与您的内容最相关的论坛中发帖。我们甚至欢迎讨论批判 Android 的文章和想法（但请保持礼貌！）- 毕竟，如果我们不听取意见，就无法改进。 +<li>允许讨论的主题：我们的大多数论坛都用于讨论与 Android 相关的技术话题或方便用户互相帮助。<em></em>一般情况下，我们不会对在论坛中讨论的主题进行严格限制：只要主题在某种程度上与 Android 相关，都可以在我们的论坛中进行讨论。我们欢迎大家公布和讨论与 Android 相关的产品、库、出版物和其他有趣的新闻，但请不要同时在多个论坛中发帖。请仅在与您的内容最相关的论坛中发帖。我们甚至欢迎讨论批判 Android 的文章和想法（但要保持礼貌态度！）- 毕竟，如果我们不听取意见，就无法改进。 </li> <li>工作论坛：我们的某些论坛被视为“工作论坛”（旨在为完成特定任务提供支持）。<em></em>在这些论坛中，我们不欢迎与主题无关的讨论。如果您要进行一般讨论，我们通常会要求您使用其他论坛。由于人们会利用这些论坛来完成相关工作，因此我们会采取积极的举措来减少无关的内容。我们希望您能够尊重贡献者们的宝贵时间，并使用适当的论坛进行一般讨论。 </li> -<li>垃圾内容：我们非常讨厌垃圾内容，这种心情正如我们崇尚礼貌和尊重一样强烈，因此我们保留限制垃圾讨论内容的权利。<em></em>如果有人发布纯属垃圾的内容，我们会立即并永久禁止发布者使用相应论坛。 +<li>垃圾内容：我们非常讨厌垃圾内容，这种心情和我们崇尚礼貌和尊重一样强烈，因此我们保留限制讨论垃圾内容的权利。<em></em>如果有人发布纯粹的垃圾内容，我们会立即并永久禁止发布者使用相应论坛。 </li> </ul> -<p>友善是最重要的规则。请谨记：在任何情况下，我们的社区都不欢迎不尊重他人和粗鲁的行为。我们没有制定正式的政策来对付捣乱者，也希望永远都不需要制定这样的政策。不过，我们承诺会尽最大努力保证公平，并且始终会先尝试警告对方，警告无果后再禁止其使用相应论坛。</p> +<p>友善是最重要的规则。请记住：在任何情况下，我们的社区都不欢迎不尊重他人和粗鲁的行为。我们并没有制定正式的规则来处理捣乱者，也希望永远都不需要制定这样的规则。不过，我们承诺会尽最大努力保证公平公正，并且我们始终会先尝试警告对方，警告无果后再禁止其使用相应论坛。</p> <h3 id="contacting">与管理员联系</h3> -<p>如果您发现有人言行粗鲁，请制止他们。您也是相应论坛的一份子，因此您不必因为他人的无礼行为不是针对您而予以容忍。切记要有礼有节！请勿火上浇油。</p> -<p>不过，如果您发现难以容忍的违规行为，想要举报垃圾内容，有强烈意见或想与管理员交流，请随时与论坛所有者联系。这是我们的职责所在！</p> +<p>如果您发现有人言行粗鲁，请制止他们。您也是论坛的一份子，不必因为无礼行为不是针对您而采取容忍态度。切记要有礼有节！请勿火上浇油。</p> +<p>不过，如果您发现有出格的违规行为，想要举报垃圾内容，有重要意见或想与管理员交流，请随时与论坛所有者联系。这是我们的职责所在！</p> -<h3 id="using-email-with-google-groups">通过电子邮件参与 Google 网上论坛</h3> -<p>您可以使用任意电子邮件客户端参与论坛交流，而不必使用 <a href="https://groups.google.com/">Google 网上论坛</a>网站。要在不使用 Google 网上论坛网站的情况下订阅某个论坛，请使用上文列表中“通过电子邮件订阅”后的链接。</p> +<h3 id="using-email-with-google-groups">通过电子邮件参与 Google 网上论坛交流</h3> +<p>您可以不通过 <a href="https://groups.google.com/">Google 网上论坛</a>网站，而使用电子邮件客户端参与论坛交流。如果不想通过 Google 网上论坛网站订阅某个论坛，可以使用上文列表中“通过电子邮件订阅”下的链接订阅。</p> <p>要设置如何通过电子邮件接收论坛帖子，请执行以下操作：</p> <ol> <li> -<p>通过 Google 网上论坛网站登录到相应论坛。例如，对于 android-platform 论坛，请使用 <a href="https://groups.google.com/forum/?fromgroups#!forum/android-platform">https://groups.google.com/forum/?fromgroups#!forum/android-platform</a>。</p> +<p>通过 Google 网上论坛网站登录论坛。例如，要访问 android-platform 论坛，请使用 <a href="https://groups.google.com/forum/?fromgroups#!forum/android-platform">https://groups.google.com/forum/?fromgroups#!forum/android-platform</a>。</p> </li> <li> <p>点击右侧的“我的成员资格”。</p> @@ -219,7 +219,7 @@ </li> </ol> <h2 id="android-on-irc">在 IRC 上讨论 Android</h2> -<p>Android 在 <a href="http://freenode.net/">freenode</a> 上有 IRC 频道。我们在 <a href="irc://irc.freenode.net/">irc.freenode.net</a> 上维护着两个官方 IRC 频道（通过该网站的 <a href="http://webchat.freenode.net/">freenode webchat</a> 访问）</p> +<p>Android 在 <a href="http://freenode.net/">freenode</a> 上有 IRC 频道。我们在 <a href="irc://irc.freenode.net/">irc.freenode.net</a> 上开设了两个官方 IRC 频道（通过该网站的 <a href="http://webchat.freenode.net/">freenode webchat</a> 访问）</p> <ul> <li> <p><a href="irc://irc.freenode.net/android">#android</a> - 用于讨论一般性 Android 问题和移植问题</p> @@ -246,7 +246,7 @@ </ul> <h2 id="for-business-inquiries">关于 Google 移动服务许可方面的问题</h2> -<p>请通过 <a href="https://www.android.com/gms/contact/">GMS 联系</a>表单咨询关于 <a href="https://www.android.com/gms/">Google 移动服务</a>许可的问题。其他非 GMS 合作伙伴关系问询可发送至 <a href="mailto:[email protected]">[email protected]</a>。</p> +<p>请通过 <a href="https://www.android.com/gms/contact/">GMS 联系</a>表单发送关于 <a href="https://www.android.com/gms/">Google 移动服务</a>许可的问题。其他非 GMS 合作伙伴关系问询可发送至 <a href="mailto:[email protected]">[email protected]</a>。</p> <p>我们会阅读收到的每封邮件，但无法一一进行回复。如果我们能够提供帮助，一定会与您联系！</p>
diff --git a/zh-cn/setup/contribute/code-style.html b/zh-cn/setup/contribute/code-style.html index 6e72c8f..41a1623 100644 --- a/zh-cn/setup/contribute/code-style.html +++ b/zh-cn/setup/contribute/code-style.html
@@ -20,127 +20,176 @@ limitations under the License. --> -<p>以下代码样式是向 Android 开源项目 (AOSP) 贡献 Java 代码时必须严格遵守的规则。如果向 Android 平台贡献的代码没有遵守这些规则，则通常不会被接受。<em></em>我们知道，并非所有现有的代码都遵守这些规则，但我们希望所有新代码都遵守这些规则。</p> +<p>以下代码样式是向 Android 开源项目 (AOSP) 贡献 Java 代码时必须严格遵守的规则。如果向 Android 平台贡献的代码没有遵守这些规则，则通常不会被接受。<em></em>我们知道，并非所有现有的代码都遵守这些规则，但我们希望所有新代码都遵守这些规则。 +</p> -<p class="note"><strong>注意</strong>：这些规则针对的是 Android 平台，Android 应用开发者可以不遵守这些规则。应用开发者可以遵守他们选择的标准，如 <a href="https://google.github.io/styleguide/javaguide.html">Google Java 样式指南</a>。</p> +<aside class="note"> + <strong>注意</strong>：这些规则针对的是 Android 平台，Android 应用开发者可以不遵守这些规则。应用开发者可以遵守他们选择的标准，如 <a href="https://google.github.io/styleguide/javaguide.html" class="external">Google Java 样式指南</a>。 +</aside> <h2 id="java-language-rules">Java 语言规则</h2> -<p>Android 遵循标准 Java 编码规范以及下文所述的其他规则。</p> -<h3 id="dont-ignore-exceptions">请勿忽略异常</h3> -<p>开发者可能会倾向于编写完全忽略异常的代码，例如：</p> -<pre><code>void setServerPort(String value) { + <p>Android 遵循标准 Java 编码规范以及下文所述的其他规则。 + </p> + + <h3 id="dont-ignore-exceptions">请勿忽略异常</h3> + + <p>开发者可能会倾向于编写完全忽略异常的代码，例如：</p> + +<pre class="prettyprint"> + void setServerPort(String value) { try { serverPort = Integer.parseInt(value); } catch (NumberFormatException e) { } -} -</code></pre> -<p>千万不要这样做。虽然您可能认为自己的代码永远不会遇到这种错误，或者无需费心处理这种错误，但像上例那样忽略异常会在您的代码中埋下隐患，这种错误总有一天会被他人触发。您必须有原则地处理代码中的每个异常；具体处理方式因情况而异。</p> -<p><em>无论何时，只要遇到空的 catch 子句，就应该保持警惕。当然，在某些时候，空的 catch 语句确实没什么问题，但至少你得想一想。在 Java 中，无论怎么小心都不为过。- <a href="http://www.artima.com/intv/solid4.html">James Gosling</a></em></p> -<p>可接受的替代方案（按优先顺序排列）包括：</p> -<ul> -<li>将异常抛给方法调用者。 -<pre><code>void setServerPort(String value) throws NumberFormatException { - serverPort = Integer.parseInt(value); -} -</code></pre> -</li> -<li>抛出一个适合您的抽象级别的新异常。 -<pre><code>void setServerPort(String value) throws ConfigurationException { + } +</pre> + + <p>千万不要这样做。虽然您可能认为自己的代码永远不会遇到这种错误，或者无需费心处理这种错误，但像上例那样忽略异常会在您的代码中埋下隐患，这种错误总有一天会被他人触发。您必须有原则地处理代码中的每个异常；具体处理方式因情况而异。 + </p> + + <p class="inline-block">“无论何时，只要遇到空的 catch 子句，就应该保持警惕。<em>当然，在某些时候，空的 catch 语句确实没什么问题，但至少你得想一想。</em>在 Java 中，无论怎么小心都不为过。- <a href="http://www.artima.com/intv/solid4.html" class="external">James Gosling</a> + </p> + + <p>可接受的替代方案（按优先顺序排列）包括：</p> + + <ul> + <li>将异常抛给方法调用者。 +<pre class="prettyprint"> + void setServerPort(String value) throws NumberFormatException { + serverPort = Integer.parseInt(value); + } +</pre> + </li> + <li>抛出一个适合您的抽象级别的新异常。 +<pre class="prettyprint"> + void setServerPort(String value) throws ConfigurationException { try { serverPort = Integer.parseInt(value); } catch (NumberFormatException e) { throw new ConfigurationException("Port " + value + " is not valid."); } -} -</code></pre> -</li> -<li>妥善处理错误，并替换 catch {} 块中的相应值。 -<pre><code>/** Set port. If value is not a valid number, 80 is substituted. */ + } +</pre> + </li> + <li>妥善处理错误，并替换 <code>catch {}</code> 块中的相应值。 +<pre class="prettyprint"> + /** Set port. If value is not a valid number, 80 is substituted. */ -void setServerPort(String value) { + void setServerPort(String value) { try { serverPort = Integer.parseInt(value); } catch (NumberFormatException e) { serverPort = 80; // default port for server } -} -</code></pre> -</li> -<li>捕获异常并抛出一个新的 <code>RuntimeException</code>。这样做比较危险，因此请仅在下述情况下采用这种方案：您确定，如果发生此错误，最适当的处理方式就是让应用崩溃。 -<pre><code>/** Set port. If value is not a valid number, die. */ + } +</pre> + </li> + <li>捕获异常并抛出一个新的 <code>RuntimeException</code>。这样做比较危险，因此请仅在下述情况下采用这种方案：您确定，如果发生此错误，最适当的处理方式就是让应用崩溃。 -void setServerPort(String value) { +<pre class="prettyprint"> + /** Set port. If value is not a valid number, die. */ + + void setServerPort(String value) { try { serverPort = Integer.parseInt(value); } catch (NumberFormatException e) { throw new RuntimeException("port " + value " is invalid, ", e); } -} -</code></pre> -<p class="note"><strong>注意</strong>：原始异常会传递到 RuntimeException 的构造函数。如果您的代码必须采用 Java 1.3 进行编译，则必须忽略表示原因的异常。</p> -</li> -<li>最后一种方案：如果您确信忽略异常是合适的处理方式，那么您可以忽略异常，但您必须添加备注以充分说明理由： -<pre><code>/** If value is not a valid number, original port number is used. */ -void setServerPort(String value) { + } +</pre> + <aside class="note"> + <strong>注意</strong>：原始异常会传递到 RuntimeException 的构造函数。如果您的代码必须采用 Java 1.3 进行编译，则必须忽略表示原因的异常。 + </aside> + </li> + <li>最后一种方案：如果您确信忽略异常是合适的处理方式，那么您可以忽略异常，但您必须添加备注以充分说明理由：<pre class="prettyprint"> + /** If value is not a valid number, original port number is used. */ + + void setServerPort(String value) { try { serverPort = Integer.parseInt(value); } catch (NumberFormatException e) { // Method is documented to just ignore invalid user input. // serverPort will just be unchanged. } -} -</code></pre> -</li> -</ul> + } +</pre> + </li> + </ul> -<h3 id="dont-catch-generic-exception">请勿捕获常规异常</h3> -<p>在捕获异常时，开发者可能会为了偷懒而倾向于采用以下处理方式：</p> -<pre><code>try { - someComplicatedIOFunction(); // may throw IOException - someComplicatedParsingFunction(); // may throw ParsingException - someComplicatedSecurityFunction(); // may throw SecurityException - // phew, made it all the way -} catch (Exception e) { // I'll just catch all exceptions - handleError(); // with one generic handler! -} -</code></pre> -<p>千万不要这样做。几乎所有情况下都不适合捕获常规异常或 Throwable（最好不要捕获 Throwable，因为它包含 Error 异常）。这样做非常危险，因为这意味着系统会在处理应用级错误期间捕获到您从未预料到的异常（包括 ClassCastException 之类的 RuntimeException）。它掩盖了代码的故障处理属性，也就是说，如果有人在您所调用的代码中添加了一种新类型的异常，编译器不会帮助您意识到您需要采取不同的方式来处理该错误。在大多数情况下，您不应以相同的方式处理不同类型的异常。</p> -<p>这条规则的特例是：在测试代码和顶级代码中，您希望捕获所有类型的错误（以防它们显示在界面中或者以便一直进行批处理作业）。在这些情况下，您可以捕获常规异常（或 Throwable）并适当地处理错误。但在这样做之前，请务必三思，然后添加备注以说明为何在此处执行这类操作是安全之举。</p> -<p>捕获常规异常的替代方案：</p> -<ul> -<li> -<p>在单个 try 之后将每个异常作为单独的 catch 块分别进行捕获。这样做可能显得比较笨拙，但仍比捕获所有异常更可取。请注意，不要在 catch 块中过多地重复使用代码。</p></li><p></p> + <h3 id="dont-catch-generic-exception">请勿捕获常规异常</h3> -<li> -<p>通过多个 try 块重构您的代码，使得错误处理过程更精细。从解析中分离出 IO，然后分别处理每种情况下的错误。</p> -</li> -<li> -<p>重新抛出异常。很多时候，您无需在该级别捕获异常，只需让相应方法抛出异常即可。</p> -</li> -</ul> -<p>请谨记：异常是您的朋友！当编译器抱怨您没有捕获异常时，别闷闷不乐！您应该微笑：因为编译器让您能够更加轻松地捕获代码中的运行时错误。</p> -<h3 id="dont-use-finalizers">请勿使用终结器</h3> -<p>终结器可以在对象被垃圾回收器回收时执行一段代码。虽然终结器非常便于进行资源清理（尤其是外部资源），但并不能保证终结器何时被调用（甚至根本不会被调用）。</p> -<p>Android 不使用终结器。在大多数情况下，您可以通过良好的异常处理流程实现终结器功能。如果您的确需要终结器，请定义一个 close() 方法（或类似方法），并注明需要调用该方法的确切时间（有关示例，请参阅 InputStream）。这种情况下，可以（但并非必须）在终结器中输出简短的日志消息，前提是不会输出大量日志消息。</p> + <p>在捕获异常时，开发者可能会为了偷懒而倾向于采用以下处理方式：</p> -<h3 id="fully-qualify-imports">完全合格的导入</h3> -<p>当您想要使用 foo 包中的 Bar 类时，可以使用以下两种方式导入：</p> -<ul> -<li><code>import foo.*;</code> -<p>可能会减少 import 语句的数量。</p></li> -<li><code>import foo.Bar;</code> -<p>明确指出实际使用了哪些类，而且代码对于维护者来说更易读。</p></li></ul> -<p>使用 <code>import foo.Bar;</code> 导入所有 Android 代码。对于 Java 标准库（<code>java.util.*</code>、<code>java.io.*</code> 等）和单元测试代码 (<code>junit.framework.*</code>)，确立了一种明确的例外情况。</p> +<pre class="prettyprint"> + try { + someComplicatedIOFunction(); // may throw IOException + someComplicatedParsingFunction(); // may throw ParsingException + someComplicatedSecurityFunction(); // may throw SecurityException + // phew, made it all the way + } catch (Exception e) { // I'll just catch all exceptions + handleError(); // with one generic handler! + } +</pre> + + <p>千万不要这样做。几乎所有情况下都不适合捕获常规异常或 Throwable（最好不要捕获 Throwable，因为它包含 Error 异常）。这样做非常危险，因为这意味着系统会在处理应用级错误期间捕获到您从未预料到的异常（包括 ClassCastException 之类的 RuntimeException）。它掩盖了代码的故障处理属性，也就是说，如果有人在您所调用的代码中添加了一种新类型的异常，编译器不会帮助您意识到您需要采取不同的方式来处理该错误。在大多数情况下，您不应以相同的方式处理不同类型的异常。 + </p> + + <p>这条规则的特例是：在测试代码和顶级代码中，您希望捕获所有类型的错误（以防它们显示在界面中或者以便一直进行批处理作业）。在这些情况下，您可以捕获常规异常（或 Throwable）并适当地处理错误。但在这样做之前，请务必三思，然后添加备注以说明为何在此处执行这类操作是安全之举。 + </p> + + <p>捕获常规异常的替代方案：</p> + + <ul> + <li>在单次 try 操作之后将每个异常作为单独的 catch 块分别进行捕获。这样做可能显得比较笨拙，但仍比捕获所有异常更可取。请注意，不要在 catch 块中过多地重复使用代码。 + </li> + <li>通过多个 try 块重构您的代码，使得错误处理过程更精细。从解析中分离出 IO，然后分别处理每种情况下的错误。 + </li> + <li>重新抛出异常。很多时候，您无需在该级别捕获异常，只需让相应方法抛出异常即可。 + </li> + </ul> + + <p>请谨记：异常是您的朋友！当编译器抱怨您没有捕获异常时，别闷闷不乐！您应该微笑：因为编译器让您能够更加轻松地捕获代码中的运行时错误。 + </p> + + <h3 id="dont-use-finalizers">请勿使用终结器</h3> + + <p>终结器可以在对象被垃圾回收器回收时执行一段代码。虽然终结器非常便于进行资源清理（尤其是外部资源），但并不能保证终结器何时被调用（甚至根本不会被调用）。 + </p> + + <p>Android 不使用终结器。在大多数情况下，您可以通过良好的异常处理流程实现终结器功能。如果您的确需要终结器，请定义一个 close() 方法（或类似方法），并注明需要调用该方法的确切时机（有关示例，请参阅 InputStream）。这种情况下，可以（但并非必须）在终结器中输出简短的日志消息，前提是不会输出大量日志消息。 + </p> + + <h3 id="fully-qualify-imports">完全合格的导入</h3> + + <p>当您想要使用 foo 包中的 Bar 类时，可以使用以下两种方式导入：</p> + + <ul> + <li><code>import foo.*;</code> + <p>可能会减少 import 语句的数量。</p> + </li> + <li><code>import foo.Bar;</code> + <p>明确指出实际使用了哪些类，而且代码对于维护者来说更清晰易读。 + </p> + </li> + </ul> + + <p>使用 <code>import foo.Bar;</code> 导入所有 Android 代码。对于 Java 标准库（<code>java.util. + </code>、<code>java.io.*</code> 等）和单元测试代码 (<code>junit.framework.*</code>)，确立了一种明确的例外情况。 + </p> <h2 id="java-library-rules">Java 库规则</h2> -<p>使用 Android 的 Java 库和工具需要遵守相关规范。在某些情况下，具体规范发生了一些重大变化，旧代码可能使用的是已弃用的模式或库。使用此类代码时，可以继续遵循现有样式。不过，在创建新组件时，请不要再使用已弃用的库。</p> + + <p>使用 Android 的 Java 库和工具需要遵守相关规范。在某些情况下，具体规范发生了一些重大变化，旧代码使用的可能是已弃用的模式或库。使用此类代码时，可以继续遵循现有样式。不过，在创建新组件时，请不要再使用已弃用的库。 + </p> <h2 id="java-style-rules">Java 样式规则</h2> -<h3 id="use-javadoc-standard-comments">使用 Javadoc 标准备注</h3> -<p>每个文件都应该在顶部放置版权声明，其后是 package 和 import 语句（各个块之间用空行分隔），最后是类或接口声明。在 Javadoc 备注中说明类或接口的作用。</p> -<pre><code>/* + <h3 id="use-javadoc-standard-comments">使用 Javadoc 标准备注</h3> + + <p>每个文件都应该在顶部放置版权声明，其后是 package 和 import 语句（各个块之间用空行分隔），最后是类或接口声明。在 Javadoc 备注中说明类或接口的作用。 + </p> +<pre class="prettyprint"> +/* * Copyright 2018 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); @@ -171,37 +220,62 @@ public class Foo { ... } -</code></pre> -<p>您编写的每个类和重要的公开方法都必须包含 Javadoc 备注，至少用一句话说明类或方法的用途。<em></em>句式应以第三人称描述性动词开头。</p> -<p>示例：</p> -<pre><code>/** Returns the correctly rounded positive square root of a double value. */ +</pre> + + <p>您编写的每个类和重要的公共方法都必须包含 Javadoc 备注，至少用一句话说明类或方法的用途。<em></em>句式应以第三人称描述性动词开头。 + </p> + + <p><strong>示例</strong></p> + +<pre class="prettyprint"> +/** Returns the correctly rounded positive square root of a double value. */ + static double sqrt(double a) { ... } -</code></pre> -<p>或</p> -<pre><code>/** +</pre> + + <p>或</p> + +<pre class="prettyprint"> +/** * Constructs a new String by converting the specified array of * bytes using the platform's default character encoding. */ public String(byte[] bytes) { ... } -</code></pre> -<p>对于普通的 get 和 set 方法（如 <code>setFoo()</code>），您无需编写 Javadoc，要写也不过是“设置 Foo”。如果该方法执行更复杂的操作（例如强制实施约束条件或具有重大副作用），那么您必须添加备注。如果属性“Foo”的意思不明确，您也应该添加备注。 -</p><p>您所编写的每一种方法（无论是公开方法还是其他方法）都将受益于 Javadoc。公开方法是 API 的一部分，因此需要 Javadoc。Android 目前并不强制要求采用特定样式来编写 Javadoc 备注，但建议您参照<a href="http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html">如何为 Javadoc 工具编写文档备注</a>中的说明。</p> +</pre> -<h3 id="write-short-methods">编写简短方法</h3> -<p>在可行的情况下，尽量编写短小精炼的方法。我们了解，有些情况下较长的方法是恰当的，因此对方法的代码长度没有做出硬性限制。如果某个方法的代码超出 40 行，请考虑是否可以在不破坏程序结构的前提下对其拆解。</p> + <p>对于普通的 get 和 set 方法（如 <code>setFoo()</code>），您无需编写 Javadoc 备注，要写也不过是“sets Foo”。如果该方法执行更复杂的操作（例如强制实施约束条件或具有重大副作用），那么您必须添加备注。如果属性“Foo”的意思不明确，您也应该添加备注。 + </p> -<h3 id="define-fields-in-standard-places">在标准位置定义字段</h3> -<p>在文件的顶部或者在使用它们的方法之前定义字段。</p> + <p>您所编写的每一种方法（无论是公共方法还是其他方法）都将受益于 Javadoc 备注。公共方法是 API 的一部分，因此需要添加 Javadoc 备注。Android 目前并不强制要求采用特定样式来编写 Javadoc 备注，但建议您参照<a href="http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html" class="external">如何为 Javadoc 工具编写文档备注</a>一文中的说明。 + </p> -<h3 id="limit-variable-scope">限制变量的作用域</h3> -<p>尽可能缩小局部变量的作用域。这样做有助于提高代码的可读性和可维护性，并降低出错的可能性。每个变量应该在包含变量所有使用场合的最内层的块中进行声明。</p> -<p>局部变量应该在首次使用时声明。几乎每个局部变量声明都应该包含一个初始化程序。如果您还没有足够的信息来合理地初始化某个变量，请推迟到信息充足时再进行声明。</p> -<p>try-catch 语句是例外情况。如果通过一个会抛出受检异常的方法的返回值来初始化变量，则必须在 try 块中进行初始化。如果该值必须在 try 块之外使用，那么您必须在 try 块之前对其进行声明，因为它在 try 块中尚无法合理地初始化：</p> -<pre><code>// Instantiate class cl, which represents some sort of Set + <h3 id="write-short-methods">编写简短方法</h3> + + <p>在可行的情况下，尽量编写短小精炼的方法。我们了解，有些情况下较长的方法是恰当的，因此对方法的代码长度没有做出硬性限制。如果某个方法的代码超出 40 行，请考虑是否可以在不破坏程序结构的前提下对其拆解。 + </p> + + <h3 id="define-fields-in-standard-places">在标准位置定义字段</h3> + + <p>在文件的顶部或者在使用它们的方法之前定义字段。 + </p> + + <h3 id="limit-variable-scope">限制变量的作用域</h3> + + <p>尽可能缩小局部变量的作用域。这样做有助于提高代码的可读性和可维护性，并降低出错的可能性。每个变量都应该在包含变量所有使用场合的最内层的块中进行声明。 + </p> + + <p>局部变量应该在首次使用时声明。几乎每个局部变量声明都应该包含一个初始化程序。如果您还没有足够的信息来合理地初始化某个变量，请推迟到信息充足时再进行声明。 + </p> + + <p>try-catch 语句是一种例外情况。如果通过一个会抛出受检异常的方法的返回值来初始化变量，则必须在 try 块中进行初始化。如果该值必须在 try 块之外使用，那么您必须在 try 块之前对其进行声明，因为它在 try 块中尚无法合理地初始化：</p> + +<pre class="prettyprint"> +// Instantiate class cl, which represents some sort of Set + Set s = null; try { s = (Set) cl.newInstance(); @@ -213,9 +287,12 @@ // Exercise the set s.addAll(Arrays.asList(args)); -</code></pre> -<p>不过，即使是这种情况，也可以通过将 try-catch 块封装在某个方法中来避免：</p> -<pre><code>Set createSet(Class cl) { +</pre> + + <p>不过，即使是这种情况，也可以通过将 try-catch 块封装在某个方法中来避免：</p> + +<pre class="prettyprint"> +Set createSet(Class cl) { // Instantiate class cl, which represents some sort of Set try { return (Set) cl.newInstance(); @@ -231,86 +308,102 @@ // Exercise the set Set s = createSet(cl); s.addAll(Arrays.asList(args)); -</code></pre> -<p>循环变量应该在 for 语句本身中进行声明，除非有令人信服的理由不这么做：</p> -<pre><code>for (int i = 0; i < n; i++) { +</pre> + + <p>循环变量应该在 for 语句本身中进行声明，除非有令人信服的理由不这么做：</p> + +<pre class="prettyprint"> +for (int i = 0; i < n; i++) { doSomething(i); } -</code></pre> -<p>和</p> -<pre><code>for (Iterator i = c.iterator(); i.hasNext(); ) { +</pre> + + <p>和</p> + +<pre class="prettyprint"> +for (Iterator i = c.iterator(); i.hasNext(); ) { doSomethingElse(i.next()); } -</code></pre> +</pre> -<h3 id="order-import-statements">为 import 语句排序</h3> -<p>import 语句的顺序为：</p> -<ol> -<li> -<p>导入 Android 包</p> -</li> -<li> -<p>导入第三方包（<code>com</code>、<code>junit</code>、<code>net</code>、<code>org</code>）</p> -</li> -<li> -<p><code>java</code> 和 <code>javax</code></p> -</li> -</ol> -<p>要完全符合 IDE 设置，导入顺序应为：</p> -<ul> -<li> -<p>每个分组内按字母顺序排序，其中大写字母开头的语句位于小写字母开头的语句前面（例如 Z 在 a 前面）。</p> -</li> -<li> -<p>每个主要分组（<code>android</code>、<code>com</code>、<code>junit</code>、<code>net</code>、<code>org</code>、<code>java</code>、<code>javax</code>）之间用空行隔开。</p> -</li> -</ul> -<p>最初对于语句顺序并没有样式要求，这意味着 IDE 经常会改变顺序，或者 IDE 开发者必须停用自动导入管理功能并手动维护导入语句。这样相当不方便。当提及 Java 样式时，开发者们喜欢的样式五花八门，最终针对 Android 简单归结为“选择一种兼容一致的排序方式”。因此我们选择了一种样式，更新了样式指南，并让 IDE 遵循该指南。我们希望 IDE 用户在编写代码时，系统对所有软件包的导入都符合此模式，无需再进行额外的工程处理。</p> -<p>这种样式是按以下原则选取的：</p> -<ul> -<li> -<p>用户希望先看到的导入往往位于顶部 (<code>android</code>)。</p> -</li> -<li> -<p>用户最不希望看到的导入往往位于底部 (<code>java</code>)。</p> -</li> -<li> -<p>用户可以轻松遵循的样式。</p> -</li> -<li> -<p>IDE 可以遵循的样式。</p> -</li> -</ul> -<p>将静态导入置于所有其他导入之上（与常规导入一样的排序方式）。</p> + <h3 id="order-import-statements">为 import 语句排序</h3> -<h3 id="use-spaces-for-indentation">使用空格缩进</h3> -<p>我们使用四 (4) 个空格来缩进块，而不要使用制表符。如果您有疑问，请与周围的代码保持一致。</p> -<p>我们使用八 (8) 个空格来缩进自动换行，包括函数调用和赋值。正确示例如下：</p> -<pre><code>Instrument i = + <p>import 语句的顺序为：</p> + + <ol> + <li>导入 Android 包</li> + <li>导入第三方包（<code>com</code>、<code>junit</code>、<code>net</code>、<code>org</code>）</li> + <li> + <code>java</code> 和 <code>javax</code> + </li> + </ol> + + <p>要完全符合 IDE 设置，导入顺序应为：</p> + + <ul> + <li>每个分组内按字母顺序排序，其中大写字母开头的语句位于小写字母开头的语句前面（例如 Z 在 a 前面）。 + </li> + <li>每个主要分组（<code>android</code>、<code>com</code>、<code>junit</code>、<code>net</code>、<code>org</code>、<code>java</code>、<code>javax</code>）之间用空行隔开。 + </li> + </ul> + + <p>最初对于语句顺序并没有样式要求，这意味着 IDE 经常会改变顺序，或者 IDE 开发者必须停用自动导入管理功能并手动维护导入语句。这样相当不方便。当提及 Java 样式时，开发者们喜欢的样式五花八门，最终针对 Android 简单归结为“选择一种兼容一致的排序方式”。因此我们选择了一种样式，更新了样式指南，并让 IDE 遵循该指南。我们希望 IDE 用户在编写代码时，使系统对所有软件包的导入都符合此模式，无需再进行额外的工程处理。 + </p> + + <p>这种样式是按以下原则选取的：</p> + + <ul> + <li>用户希望先看到的导入往往位于顶部 (<code>android</code>)。 + </li> + <li>用户最不希望看到的导入往往位于底部 (<code>java</code>)。 + </li> + <li>用户可以轻松遵循的样式。 + </li> + <li>IDE 可以遵循的样式。 + </li> + </ul> + + <p>将静态导入置于所有其他导入之上（与常规导入一样的排序方式）。 + </p> + + <h3 id="use-spaces-for-indentation">使用空格缩进</h3> + + <p>我们使用四 (4) 个空格来缩进块，绝不要使用制表符。如果您有疑问，请与周围的代码保持一致。 + </p> + + <p>我们使用八 (8) 个空格来缩进自动换行，包括函数调用和赋值。 + </p> + + <p><span class="compare-better">推荐</span></p> + +<pre class="prettyprint"> +Instrument i = someLongExpression(that, wouldNotFit, on, one, line); -</code></pre> -<p>错误示例如下：</p> -<pre><code>Instrument i = - someLongExpression(that, wouldNotFit, on, one, line); -</code></pre> +</pre> -<h3 id="follow-field-naming-conventions">遵循字段命名规范</h3> -<ul> -<li> -<p>非公开且非静态字段的名称以 m 开头。</p> -</li> -<li> -<p>静态字段的名称以 s 开头。</p> -</li> -<li> -<p>其他字段以小写字母开头。</p> -</li> -<li> -<p>公开静态 final 字段（常量）为全部大写并用下划线连接 (ALL_CAPS_WITH_UNDERSCORES)。</p> -</li> -</ul> -<p>例如：</p> -<pre><code>public class MyClass { + <p><span class="compare-worse">不推荐</span></p> + +<pre class="prettyprint"> +Instrument i = + someLongExpression(that, wouldNotFit, on, one, line); +</pre> + + <h3 id="follow-field-naming-conventions">遵循字段命名规范</h3> + + <ul> + <li>非公共且非静态字段的名称以 m 开头。 + </li> + <li>静态字段的名称以 s 开头。 + </li> + <li>其他字段以小写字母开头。 + </li> + <li>公共静态 final 字段（常量）要全部大写并用下划线连接 (ALL_CAPS_WITH_UNDERSCORES)。</li> + </ul> + + <p>例如：</p> + +<pre class="prettyprint"> +public class MyClass { public static final int SOME_CONSTANT = 42; public int publicField; private static MyClass sSingleton; @@ -318,10 +411,14 @@ private int mPrivate; protected int mProtected; } -</code></pre> -<h3 id="use-standard-brace-style">使用标准大括号样式</h3> -<p>左大括号不单独占一行，与其前面的代码位于同一行：</p> -<pre><code>class MyClass { +</pre> + + <h3 id="use-standard-brace-style">使用标准大括号样式</h3> + + <p>左大括号不单独占一行，与其前面的代码位于同一行：</p> + +<pre class="prettyprint"> +class MyClass { int func() { if (something) { // ... @@ -332,133 +429,204 @@ } } } -</code></pre> -<p>我们需要在条件语句周围添加大括号。例外情况：如果整个条件语句（条件和主体）适合放在同一行，那么您可以（但不是必须）将其全部放在一行上。例如，我们接受以下样式：</p> -<pre><code>if (condition) { +</pre> + + <p>我们需要在条件语句周围添加大括号。例外情况：如果整个条件语句（条件和主体）适合放在同一行，那么您可以（但不是必须）将其全部放在一行上。例如，我们接受以下样式：</p> + +<pre class="prettyprint"> +if (condition) { body(); } -</code></pre> -<p>同样也接受以下样式：</p> -<pre><code>if (condition) body(); -</code></pre> -<p>但不接受以下样式：</p> -<pre><code>if (condition) +</pre> + + <p>同样也接受以下样式：</p> + +<pre class="prettyprint">if (condition) body();</pre> + + <p>但不接受以下样式：</p> + +<pre class="prettyprint"> +if (condition) body(); // bad! -</code></pre> +</pre> -<h3 id="limit-line-length">限制代码行长度</h3> -<p>您的代码中每一行文本的长度都应该不超过 100 个字符。虽然关于此规则存在很多争论，但最终决定仍是以 100 个字符为上限，不过存在以下例外情况：<em></em></p> -<ul> -<li>如果备注行包含长度超过 100 个字符的示例命令或文字网址，那么为了便于剪切和粘贴，该行可以超过 100 个字符。</li> -<li>导入语句行可以超出此限制，因为用户很少会看到它们（这也简化了工具编写流程）。</li> -</ul> + <h3 id="limit-line-length">限制代码行长度</h3> -<h3 id="use-standard-java-annotations">使用标准 Java 注释</h3> -<p>注释应该位于同一语言元素的其他修饰符之前。简单的标记注释（例如 @Override）可以与语言元素列在同一行。如果有多个注释或参数化注释，则应各占一行并按字母顺序排列。</p> -<p>Java 中 3 个预定义注释的 Android 标准做法如下：</p> -<ul> -<li><code>@Deprecated</code>：在不建议使用注释元素时，必须使用 @Deprecated 注释。如果您使用 @Deprecated 注释，则还必须为其添加 @deprecated Javadoc 标记，并且该标记应该指定一个替代实现方案。另外请注意，@Deprecated 方法应该仍然可以使用。<em></em>如果您看到带有 @deprecated Javadoc 标记的旧代码，请添加 @Deprecated 注释。 -</li> -<li><code>@Override</code>：当某个方法替换了超类中的声明或实现时，必须使用 @Override 注释。例如，如果您使用 @inheritdocs Javadoc 标记，并且派生于某个类（而非接口），则必须再为方法添加 @Override 注释，说明该方法替换了父类的方法。</li> -<li><code>@SuppressWarnings</code>：@SuppressWarnings 注释应该仅在无法消除警告的情况下使用。如果某个警告通过了“无法消除”测试，则必须使用 @SuppressWarnings 注释，以确保所有警告都会反映出代码中的实际问题。<em></em> -<p>当需要 @SuppressWarnings 注释时，必须在前面添加一个 TODO 备注，用于说明“无法消除”情况。这通常会标识出是哪个违规类使用了糟糕的接口。例如：</p> -<pre><code>// TODO: The third-party class com.third.useful.Utility.rotate() needs generics + <p>您的代码中每一行文本的长度都不应超过 100 个字符。虽然关于此规则存在很多争论，但最终决定仍是以 100 个字符为上限，不过存在以下例外情况：<em></em></p> + + <ul> + <li>如果备注行包含长度超过 100 个字符的示例命令或文字网址，那么为了便于剪切和粘贴，该行可以超过 100 个字符。 + </li> + <li>导入语句行可以超出此限制，因为用户很少会看到它们（这也简化了工具编写流程）。 + </li> + </ul> + + <h3 id="use-standard-java-annotations">使用标准 Java 注释</h3> + + <p>注释应该位于同一语言元素的其他修饰符之前。简单的标记注释（例如 @Override）可以与语言元素列在同一行。如果有多个注释或参数化注释，则应各占一行并按字母顺序排列。 + </p> + + <p>Java 中 3 个预定义注释的 Android 标准做法如下：</p> + + <ul> + <li> + <code>@Deprecated</code>：在不建议使用注释元素时，必须使用 @Deprecated 注释。如果您使用 @Deprecated 注释，则还必须为其添加 @deprecated Javadoc 标记，并且该标记应该指定一个替代实现方案。另外请注意，@Deprecated 方法应该仍然可以使用。<em></em>如果您看到带有 @deprecated Javadoc 标记的旧代码，请添加 @Deprecated 注释。 + </li> + <li> + <code>@Override</code>：当某个方法替换了超类中的声明或实现时，必须使用 @Override 注释。例如，如果您使用 @inheritdocs Javadoc 标记，并且派生于某个类（而非接口），则必须再为方法添加 @Override 注释，说明该方法替换了父类的方法。 + </li> + <li> + <code>@SuppressWarnings</code>：@SuppressWarnings 注释应该仅在无法消除警告的情况下使用。如果某个警告通过了“无法消除”测试，则必须使用 @SuppressWarnings 注释，以确保所有警告都会反映出代码中的实际问题。<em></em> + + <p>当需要 @SuppressWarnings 注释时，必须在前面添加一个 TODO 备注，用于说明“无法消除”情况。这通常会标识出是哪个违规类使用了糟糕的接口。例如： + </p> + +<pre class="prettyprint"> +// TODO: The third-party class com.third.useful.Utility.rotate() needs generics @SuppressWarnings("generic-cast") List<String> blix = Utility.rotate(blax); -</code></pre> -<p>当需要 @SuppressWarnings 注释时，您应该重构代码以分离出需要使用该注释的软件元素。</p> -</li> -</ul> +</pre> -<h3 id="treat-acronyms-as-words">将首字母缩写词视为字词</h3> -<p>在为变量、方法和类命名时，请将首字母缩写词和缩写形式视为字词，使名称更具可读性：</p> -<table> -<thead> -<tr> -<th>良好</th> -<th>不佳</th> -</tr> -</thead> -<tbody> -<tr> -<td>XmlHttpRequest</td> -<td>XMLHTTPRequest</td> -</tr> -<tr> -<td>getCustomerId</td> -<td>getCustomerID</td> -</tr> -<tr> -<td>class Html</td> -<td>class HTML</td> -</tr> -<tr> -<td>String url</td> -<td>String URL</td> -</tr> -<tr> -<td>long id</td> -<td>long ID</td> -</tr> -</tbody> -</table> -<p>由于 JDK 和 Android 代码库在首字母缩写词上非常不一致，几乎也不可能与周围的代码保持一致。因此，请务必将首字母缩写词视为字词。</p> + <p>当需要 @SuppressWarnings 注释时，您应该重构代码以分离出需要使用该注释的软件元素。 + </p> + </li> + </ul> -<h3 id="use-todo-comments">使用 TODO 备注</h3> -<p>为代码使用 TODO 备注是短期的临时解决方案，或者说足够好但并不完美。TODO 备注应该以全部大写的字符串 TODO 开头，后跟一个冒号：</p> -<pre><code>// TODO: Remove this code after the UrlTable2 has been checked in. -</code></pre> -<p>和</p> -<pre><code>// TODO: Change this to use a flag instead of a constant. -</code></pre> -<p>如果您的 TODO 采用“在未来的某个日期做某事”的形式，请确保在其中包含一个非常具体的日期（“在 2005 年 11 月前修复”）或者一个非常具体的事件（“在所有生产环境合成器都可处理 V7 协议后移除此代码”）。</p> + <h3 id="treat-acronyms-as-words">将首字母缩写词视为字词</h3> -<h3 id="log-sparingly">谨慎使用日志记录</h3> -<p>虽然日志记录非常有必要，但对性能却有明显的负面影响，如果不能保持一定程度的简洁性，就会迅速失去其实用性。日志记录工具提供以下 5 种不同级别的日志记录：</p> -<ul> -<li><code>ERROR</code>：在出现极其严重的情况时使用。例如，某些事件会导致用户可见的后果，如果不明确删除某些数据、卸载应用、清除数据分区或重写整个设备（或更糟），则无法恢复。系统一直会记录此级别的日志。一般情况下，最好向统计信息收集服务器报告能够说明 ERROR 级别的一些日志记录情况的问题。</li> -<li><code>WARNING</code>：在出现比较严重和意外的情况时使用。例如，某些事件会导致用户可见的后果，但是通过执行某些明确的操作（从等待或重启应用，一直到重新下载新版应用或重新启动设备）可在不丢失数据的情况下恢复。系统一直会记录此级别的日志。可以考虑向统计信息收集服务器报告能够说明 WARNING 级别的一些日志记录情况的问题。</li> -<li><code>INFORMATIVE:</code>用于记录大多数人感兴趣的信息。例如，当检测到某种情况会造成广泛的影响时，尽管不一定是错误，系统也会记录下来。这种情况应该仅由一个被视为该领域最具权威性的模块来记录（避免由非权威组件重复记录）。系统一直会记录此级别的日志。 -</li> -<li><code>DEBUG</code>：用于进一步记录设备上发生的可能与调查和调试意外行为相关的情况。您应该只记录收集有关组件的足够信息所需的信息。如果您的调试日志是主要日志，那么您可能应采用 VERBOSE 级别的日志记录。 -<p>系统会记录此级别的日志（即使在发布版本中），并且周围要有 <code>if (LOCAL_LOG)</code> 或 <code>if (LOCAL_LOGD)</code> 块，其中 <code>LOCAL_LOG[D]</code> 在您的类或子组件中定义。这样一来，系统有可能停用所有此类日志记录。因此，<code>if (LOCAL_LOG)</code> 块中不得包含有效逻辑。为日志编译的所有字符串也需要放在 <code>if -(LOCAL_LOG)</code> 块中。如果日志记录调用会导致字符串编译在 <code>if (LOCAL_LOG)</code> 块之外发生，则不应将其重构为方法调用。</p> -<p>有些代码仍然在使用 <code>if (localLOGV)</code>。虽然名称并不规范，但也可接受。</p> -</li> -<li><code>VERBOSE</code>：用于记录其他所有信息。系统仅针对调试版本记录此级别的日志，并且周围要有 <code>if (LOCAL_LOGV)</code> 块（或同类块），以便能够默认编译。所有字符串编译都将从发布版本中删除，并且需要在 <code>if (LOCAL_LOGV)</code> 块中显示。 -</li> -</ul> -<p><em>注意事项：</em> </p> -<ul> -<li>在指定模块中，除了 VERBOSE 级别之外，一个错误应该只报告一次（如果可能的话）。在模块内的单个函数调用链中，只有最内层的函数应当返回错误，同一模块中的调用者只能添加一些明显有助于隔离问题的日志记录。</li> -<li>在一个模块链中，除了 VERBOSE 级别之外，当较低级别的模块检测到来自较高级别模块的无效数据时，低级模块应该只在 DEBUG 日志中记录该情况，并且仅当该日志提供的信息对调用者来说无法获取时进行记录。具体来说，当抛出异常（异常中应该会包含所有相关信息）或者所记录的所有信息都包含在错误代码中时，则不需要记录此类情况。这在框架和应用之间的交互中尤为重要，而且由第三方应用造成的情况经过框架妥善处理后，不应该触发高于 DEBUG 级别的日志记录。应该触发 INFORMATIVE 级别或更高级别日志记录的唯一情况是，模块或应用在其自身级别或更低级别检测到错误。</li> -<li>当事实证明某些日志记录可能会发生多次时，最好实施一种频率限制机制来防止出现具有相同（或非常相似）信息的大量重复日志副本。</li> -<li>失去网络连接属于完全在预期之内的常见情况，没必要记录下来。如果失去网络连接后导致在应用内出现某种后果，则应该记录为 DEBUG 或 VERBOSE 级别（具体取决于后果是否足够严重以及足够意外，足以记录在发布版本中）。</li> -<li>如果在第三方应用可访问或代表第三方应用的文件系统上拥有完整的文件系统，则不应该记录高于 INFORMATIVE 级别的日志。</li> -<li>来自任何不受信任来源（包括共享存储空间中的任何文件或通过任何网络连接获取的数据）的无效数据被视为符合预期，在被检测到无效时不应触发高于 DEBUG 级别的任何日志记录（甚至应该尽可能地限制日志记录）。</li> -<li>请注意，在对 String 使用 <code>+</code> 运算符时，它会隐式创建一个具有默认缓冲区（大小为 16 个字符）的 <code>StringBuilder</code>，还可能会创建其他临时 String 对象。例如，显式创建 StringBuilder 并不比依赖默认的“+”运算符成本更高（实际上可能更高效）。请注意，即使没有读取日志信息，调用 <code>Log.v()</code> 的代码也会在发布版本中进行编译和执行，包括编译字符串。</li> -<li>任何供其他人阅读并且在发布版本中提供的日志记录都应当简洁明了、合理易懂。这包括一直到 DEBUG 级别的所有日志记录。</li> -<li>在内容有意义的情况下尽可能使日志记录在一行之内。一行长度在 80 到 100 个字符内是完全可以接受的，应当尽可能避免长度超过 130 或 160 个字符（包括标记的长度）。</li> -<li>绝不能使用高于 VERBOSE 级别的日志记录报告成功事件。</li> -<li>用于诊断难以重现的问题的临时日志记录应采用 DEBUG 或 VERBOSE 级别，并且应当包裹在 if 块中，以便在编译期间将其完全停用。</li> -<li>请务必谨慎，避免在日志中泄露安全方面的信息。应避免提供个人信息，且必须避免提供有关受保护内容的信息。这在编写框架代码时尤为重要，因为事先无法轻易得知哪些是个人信息或受保护的内容，哪些不是。</li> -<li>请勿使用 <code>System.out.println()</code>（或针对原生代码使用 <code>printf()</code>）。System.out 和 System.err 会重定向到 /dev/null，因此您的 print 语句不会产生可见效果。不过，为这些调用编译的所有字符串仍会得以执行。</li> -<li><em>日志记录的黄金法则是，您的日志不一定要将其他日志排挤出缓冲区，正如其他日志不会这样对您的日志一样。</em></li> -</ul> + <p>在为变量、方法和类命名时，请将首字母缩写词和缩写形式视为字词，使名称更具可读性：</p> -<h3 id="be-consistent">保持一致</h3> -<p>总而言之：保持一致。如果您正在修改代码，请花几分钟时间看一下周围的代码并确定其样式。如果该代码在 if 语句周围使用空格，那么您也应该这样做。如果代码备注的周围是用星号组成的小方框，您也应该将备注放在这样的小方框内。</p> -<p>制定样式规范的目的是整理出通用的编码词汇表，以便人们可以专注于您所说的内容，而不是您表达的方式。我们在此提出整体样式规则，让用户都知道这一词汇表，但局部样式也很重要。如果您添加到文件的代码看起来与其周围的现有代码明显不同，那么当读者读到此处时，这些代码会打乱他们的节奏。请尽量避免这种情况。</p> + <table> + <thead> + <tr> + <th>良好</th> + <th>不佳</th> + </tr> + </thead> + <tbody> + <tr> + <td>XmlHttpRequest</td> + <td>XMLHTTPRequest</td> + </tr> + <tr> + <td>getCustomerId</td> + <td>getCustomerID</td> + </tr> + <tr> + <td>class Html</td> + <td>class HTML</td> + </tr> + <tr> + <td>String url</td> + <td>String URL</td> + </tr> + <tr> + <td>long id</td> + <td>long ID</td> + </tr> + </tbody> + </table> + + <p>由于 JDK 和 Android 代码库在首字母缩写词上非常不一致，几乎也不可能与周围的代码保持一致。因此，请务必将首字母缩写词视为字词。 + </p> + + <h3 id="use-todo-comments">使用 TODO 备注</h3> + + <p>为代码使用 TODO 备注是短期的临时解决方案，或者说足够好但并不完美。TODO 备注应包含全部大写的字符串 TODO，后跟一个冒号。</p> + +<pre class="prettyprint"> +// TODO: Remove this code after the UrlTable2 has been checked in. +</pre> + + <p>和</p> + +<pre class="prettyprint"> +// TODO: Change this to use a flag instead of a constant. +</pre> + + <p>如果您的 TODO 采用“在未来的某个日期做某事”的形式，请确保在其中包含一个非常具体的日期（“在 2005 年 11 月前修复”）或者一个非常具体的事件（“在所有生产环境合成器都可处理 V7 协议后移除此代码”）。 + </p> + + <h3 id="log-sparingly">谨慎使用日志记录</h3> + + <p>虽然日志记录非常有必要，但对性能却有明显的负面影响，如果不能保持一定程度的简洁性，就会迅速失去其实用性。日志记录工具提供以下 5 种不同级别的日志记录：</p> + + <ul> + <li> + <code>ERROR</code>：在出现极其严重的情况时使用。例如，某些事件会导致用户可见的后果，如果不明确删除某些数据、卸载应用、擦除数据分区或重写刷写整个设备（或更糟），则无法恢复。系统一直会记录此级别的日志。一般情况下，最好向统计信息收集服务器报告能够说明 ERROR 级别的一些日志记录情况的问题。 + </li> + <li> + <code>WARNING</code>：在出现比较严重和意外的情况时使用。例如，某些事件会导致用户可见的后果，但是通过执行某些明确的操作（从等待或重启应用，一直到重新下载新版应用或重新启动设备）可在不丢失数据的情况下恢复。系统一直会记录此级别的日志。可以考虑向统计信息收集服务器报告能够说明 WARNING 级别的一些日志记录情况的问题。 + </li> + <li> + <code>INFORMATIVE:</code>用于记录大多数人感兴趣的信息。例如，当检测到某种情况会造成广泛的影响时，尽管不一定是错误，系统也会记录下来。这种情况应该仅由一个被视为该领域最具权威性的模块来记录（避免由非权威组件重复记录）。系统一直会记录此级别的日志。 + </li> + <li> + <code>DEBUG</code>：用于进一步记录设备上发生的可能与调查和调试意外行为相关的情况。您应该只记录收集有关组件的足够信息所需的信息。如果您的调试日志是主要日志，那么您可能应采用 VERBOSE 级别的日志记录。 + + <p>系统会记录此级别的日志（即使在发布版本中），并且周围要有 <code>if (LOCAL_LOG)</code> 或 <code>if + LOCAL_LOGD)</code> 块，其中 <code>LOCAL_LOG[D]</code> 在您的类或子组件中定义。这样一来，系统有可能停用所有此类日志记录。因此，<code>if (LOCAL_LOG)</code> 块中不得包含有效逻辑。为日志编译的所有字符串也需要放在 <code>if (LOCAL_LOG)</code> 块中。如果日志记录调用会导致字符串编译在 <code>if (LOCAL_LOG)</code> 块之外发生，则不应将其重构为方法调用。 + </p> + + <p>有些代码仍然在使用 <code>if (localLOGV)</code>。虽然名称并不规范，但也可接受。 + </p> + </li> + <li> + <code>VERBOSE</code>：用于记录其他所有信息。系统仅针对调试版本记录此级别的日志，并且周围要有 <code>if (LOCAL_LOGV)</code> 块（或同类块），以便能够默认编译。所有字符串编译都将从发布版本中删除，并且需要在 <code>if (LOCAL_LOGV)</code> 块中显示。 + </li> + </ul> + + <h4="log-sparingly-notes">注意：<ul> + <li>在指定模块中，除了 VERBOSE 级别之外，一个错误应该只报告一次（如果可能的话）。在模块内的单个函数调用链中，只有最内层的函数应当返回错误，同一模块中的调用者只能添加一些明显有助于隔离问题的日志记录。 + </li> + <li>在一个模块链中，除了 VERBOSE 级别之外，当较低级别的模块检测到来自较高级别模块的无效数据时，较低级别的模块应该只在 DEBUG 日志中记录该情况，并且仅当该日志提供的信息对调用者来说无法获取时进行记录。具体来说，当抛出异常（异常中应该会包含所有相关信息）或者所记录的所有信息都包含在错误代码中时，则不需要记录此类情况。这在框架和应用之间的交互中尤为重要，而且由第三方应用造成的情况经过框架妥善处理后，不应该触发高于 DEBUG 级别的日志记录。应该触发 INFORMATIVE 级别或更高级别日志记录的唯一情况是，模块或应用在其自身级别或更低级别检测到错误。 + </li> + <li>当事实证明某些日志记录可能会发生多次时，最好实施一种频率限制机制来防止出现具有相同（或非常相似）信息的大量重复日志副本。 + </li> + <li>失去网络连接属于完全在预期之内的常见情况，没必要记录下来。如果失去网络连接后导致在应用内出现某种后果，则应该记录为 DEBUG 或 VERBOSE 级别（具体取决于后果是否足够严重以及足够意外，足以记录在发布版本中）。 + </li> + <li>如果在第三方应用可访问或代表第三方应用的文件系统上拥有完整的文件系统，则不应该记录高于 INFORMATIVE 级别的日志。</li> + <li>来自任何不受信任来源（包括共享存储空间中的任何文件或通过任何网络连接获取的数据）的无效数据被视为符合预期，在被检测到无效时不应触发高于 DEBUG 级别的任何日志记录（甚至应该尽可能地限制日志记录）。 + </li> + <li>请注意，在对 String 使用 <code>+</code> 运算符时，它会隐式创建一个具有默认缓冲区（大小为 16 个字符）的 <code>StringBuilder</code>，还可能会创建其他临时 String 对象。例如，显式创建 StringBuilder 并不比依赖默认的“+”运算符成本更高（实际上可能更高效）。请注意，即使没有读取日志信息，调用 <code>Log.v()</code> 的代码也会在发布版本中进行编译和执行，包括编译字符串。 + </li> + <li>任何供其他人阅读并且在发布版本中提供的日志记录都应当简洁明了、合理易懂。这包括一直到 DEBUG 级别的所有日志记录。 + </li> + <li>在内容有意义的情况下尽可能使日志记录在一行之内。一行长度在 80 到 100 个字符内是完全可以接受的，应当尽可能避免长度超过 130 或 160 个字符（包括标记的长度）。 + </li> + <li>绝不能使用高于 VERBOSE 级别的日志记录报告成功事件。</li> + <li>用于诊断难以重现的问题的临时日志记录应采用 DEBUG 或 VERBOSE 级别，并且应当包裹在 if 块中，以便在编译期间将其完全停用。 + </li> + <li>请务必谨慎，避免在日志中泄露安全方面的信息。应避免提供个人信息，且必须避免提供有关受保护内容的信息。这在编写框架代码时尤为重要，因为事先无法轻易得知哪些是个人信息或受保护的内容，哪些不是。 + </li> + <li> + 请勿使用 <code>System.out.println()</code>（或针对原生代码使用 <code>printf()</code>）。System.out 和 System.err 会重定向到 /dev/null，因此您的 print 语句不会产生可见效果。不过，为这些调用编译的所有字符串仍会得以执行。 + </li> + <li> + <em>日志记录的黄金法则是，您的日志不一定要将其他日志排挤出缓冲区，正如其他日志不会这样对您的日志一样。</em> + </li> + </ul> + + <h3 id="be-consistent">保持一致</h3> + + <p>总而言之：保持一致。如果您正在修改代码，请花几分钟时间看一下周围的代码并确定其样式。如果该代码在 if 语句周围使用空格，那么您也应该这样做。如果代码备注的周围是用星号组成的小方框，您也应该将备注放在这样的小方框内。 + </p> + + <p>制定样式规范的目的是整理出通用的编码词汇表，以便人们可以专注于您所说的内容，而不是您表达的方式。我们在此提出整体样式规则，让用户都知道这一词汇表，但局部样式也很重要。如果您添加到文件的代码看起来与其周围的现有代码明显不同，那么当读者读到此处时，这些代码会打乱他们的节奏。请尽量避免这种情况。 + </p> <h2 id="javatests-style-rules">Javatests 样式规则</h2> -<p>请遵循测试方法的命名规范，并使用下划线将被测试的内容与被测试的具体情况区分开来。这种样式可让您更容易看出正在测试的情况。例如：</p> -<pre><code>testMethod_specificCase1 testMethod_specificCase2 + + <p>请遵循测试方法的命名规范，并使用下划线将被测试的内容与被测试的具体情况区分开来。这种样式可让您更容易看出正在测试的情况。例如：</p> + +<pre class="prettyprint"> +testMethod_specificCase1 testMethod_specificCase2 void testIsDistinguishable_protanopia() { ColorMatcher colorMatcher = new ColorMatcher(PROTANOPIA) assertFalse(colorMatcher.isDistinguishable(Color.RED, Color.BLACK)) assertTrue(colorMatcher.isDistinguishable(Color.X, Color.Y)) } -</code></pre> +</pre> -</body></html> \ No newline at end of file +</h4="log-sparingly-notes"></body></html> \ No newline at end of file
diff --git a/zh-cn/setup/contribute/read-bug-reports.html b/zh-cn/setup/contribute/read-bug-reports.html index e8ebb99..34e0c61 100644 --- a/zh-cn/setup/contribute/read-bug-reports.html +++ b/zh-cn/setup/contribute/read-bug-reports.html
@@ -267,7 +267,7 @@ </section> <h2 id="activities">Activity</h2> -<p><a href="http://developer.android.com/guide/components/activities.html">Activity</a> 是一种应用组件，可为用户提供一个可交互的屏幕，用来执行某些操作（例如拨打电话号码、拍照、发送电子邮件等）。从错误报告的角度来看，<a href="http://developer.android.com/reference/android/app/Activity.html">Activity</a> 是用户可以执行的一项明确具体的操作，这使得查找在崩溃期间处于聚焦状态的 Activity 变得非常重要。Activity 通过 ActivityManager 运行进程，因此找出指定 Activity 的所有进程停止和启动事件也有助于进行问题排查。</p> +<p><a href="http://developer.android.com/guide/components/activities.html">Activity</a> 是一种应用组件，可为用户提供一个可交互的屏幕，用来执行某些操作（例如拨号、拍照、发送电子邮件等）。从错误报告的角度来看，<a href="http://developer.android.com/reference/android/app/Activity.html">Activity</a> 是用户可以执行的一项明确具体的操作，这使得查找在崩溃期间处于聚焦状态的 Activity 变得非常重要。Activity 通过 ActivityManager 运行进程，因此找出指定 Activity 的所有进程停止和启动事件也有助于进行问题排查。</p> <h3 id="history-focused-activities">查看处于聚焦状态的 Activity</h3> <p>要查看记录的处于聚焦状态的 Activity，请搜索 <code>am_focused_activity</code>。</p> @@ -744,7 +744,7 @@ </section> <h2 id="processes">进程</h2> -<p>错误报告中含有大量进程数据，其中包括启动和停止时间、运行时时长、相关服务、<code>oom_adj</code> 得分等。要详细了解 Android 如何管理进程，请参阅<a href="http://developer.android.com/guide/components/processes-and-threads.html">进程和线程</a>。</p> +<p>错误报告中含有大量进程数据，包括启动和停止时间、运行时时长、相关服务、<code>oom_adj</code> 得分等。要详细了解 Android 如何管理进程，请参阅<a href="http://developer.android.com/guide/components/processes-and-threads.html">进程和线程</a>。</p> <h3 id="process-runtime">确定进程运行时</h3> <p><code>procstats</code> 部分包含有关进程及相关服务已运行时长的完整统计信息。要快速获得便于用户阅读的摘要，请搜索 <code>AGGREGATED OVER</code> 以查看最近 3 个小时或 24 个小时的数据，然后搜索 <code>Summary:</code> 以查看进程列表、这些进程已以各种优先级运行的时长，以及它们使用 RAM 的情况（格式为“最小-平均-最大 PSS”/“最小-平均-最大 USS”）。</p>
diff --git a/zh-cn/setup/develop/64-bit-builds.html b/zh-cn/setup/develop/64-bit-builds.html index 0c967e1..46fc03f 100644 --- a/zh-cn/setup/develop/64-bit-builds.html +++ b/zh-cn/setup/develop/64-bit-builds.html
@@ -28,7 +28,7 @@ <p>对于可执行文件和应用，编译系统默认仅编译 64 位版本，但您可以使用一个全局 <code>BoardConfig.mk</code> 变量或针对特定模块的变量来替换此设置。</p> -<p class="caution"><strong>注意</strong>：如果某个应用提供了一个可供其他应用（32 位或 64 位）使用的 API，那么在该应用的清单中，<code>android:multiarch</code> 属性的值必须设为 <code>true</code>，以避免可能出现的错误。</p> +<p class="caution"><strong>注意</strong>：如果某个应用提供了可供其他应用（32 位或 64 位）使用的 API，为避免可能出现的错误，必须在该应用的清单中将 <code>android:multiarch</code> 属性的值设为 <code>true</code>。</p> <h2 id="product_configuration">产品配置</h2>
diff --git a/zh-cn/setup/start/brands.html b/zh-cn/setup/start/brands.html index 1366b4e..01f13e1 100644 --- a/zh-cn/setup/start/brands.html +++ b/zh-cn/setup/start/brands.html
@@ -106,6 +106,6 @@ </p><h2 id="Questions">问题</h2> -<p>如需了解更多品牌使用信息，请提交<a href="https://support.google.com/contact/partner_brand_approval">合作伙伴品牌咨询表单</a>，与 Android 合作伙伴营销团队联系。</p> +<p>如需了解有关品牌使用的更多信息，请提交<a href="https://support.google.com/contact/partner_brand_approval">合作伙伴品牌咨询表单</a>，与 Android 合作伙伴营销团队联系。</p> </body></html> \ No newline at end of file
diff --git a/zh-cn/setup/start/build-numbers.html b/zh-cn/setup/start/build-numbers.html index 745c0d8..4968354 100644 --- a/zh-cn/setup/start/build-numbers.html +++ b/zh-cn/setup/start/build-numbers.html
@@ -1,5 +1,5 @@ <html devsite><head> - <title>代号、标记和细分版本号</title> + <title>代号、标签和版本号</title> <meta name="project_path" value="/_project.yaml"/> <meta name="book_path" value="/_book.yaml"/> </head> @@ -209,6 +209,18 @@ </thead> <tbody> <tr> + <td>PQ1A.181205.006</td> + <td>android-9.0.0_r21</td> + <td>Pie</td> + <td>Pixel 3 XL、Pixel 3</td> + </tr> + <tr> + <td>PQ1A.181205.002</td> + <td>android-9.0.0_r19</td> + <td>Pie</td> + <td>Pixel 2 XL、Pixel 2</td> + </tr> + <tr> <td>PPR2.181005.003.A1</td> <td>android-9.0.0_r18</td> <td>Pie</td> @@ -307,6 +319,18 @@ <td>2018-08-05</td> </tr> <tr> + <td>OPM8.181205.001</td> + <td>android-8.1.0_r53</td> + <td>Oreo</td> + <td>Pixel C</td> + </tr> + <tr> + <td>OPM7.181205.001</td> + <td>android-8.1.0_r52</td> + <td>Oreo</td> + <td>Nexus 5X、Nexus 6P</td> + </tr> + <tr> <td>OPM8.181105.002</td> <td>android-8.1.0_r51</td> <td>Oreo</td>
diff --git a/zh-cn/setup/start/p-release-notes.html b/zh-cn/setup/start/p-release-notes.html index 8a7cab6..dedb7ca 100644 --- a/zh-cn/setup/start/p-release-notes.html +++ b/zh-cn/setup/start/p-release-notes.html
@@ -346,7 +346,7 @@ <h4 id="vendor_init">Vendor_init</h4> -<p><a href="/security/selinux/vendor-init">供应商初始化</a>中介绍了相关更新，这些更新旨在弥补通过使用单独的 SELinux 域拆分的 Treble system/vendor 分区（以便利用供应商专属权限运行 <code>/vendor</code> 命令）中存在的 init 进程访问漏洞。</p> +<p><a href="/security/selinux/vendor-init">供应商 init</a> 中介绍了相关更新，这些更新旨在使用单独的 SELinux 域，利用供应商专属权限运行 <code>/vendor</code> 命令来填补 Treble 系统/供应商拆分中存在的 init 进程访问漏洞。</p> <h4 id="system_properties">系统属性</h4> @@ -528,11 +528,11 @@ <h3 id="gnss_satellite_selection">GNSS 卫星选择</h3> -<p>使用新的全球导航卫星系统 (GNSS) HAL（1.1 版及更高版本）时，Android 框架会监控 Android 设置。合作伙伴可以通过 Google Play 服务或其他系统更新来这些设置。这些设置可告知 GNSS HAL 是否不应使用某些 GNSS 卫星。在持续出现 GNSS 卫星或星群错误时，或者为了更快地响应使用不同的时制和外部事件（例如闰秒和/或日或周数滚动增加）混合星群时可能发生的 GNSS HAL 实现问题时，这些设置非常有用。</p> +<p>使用新的全球导航卫星系统 (GNSS) HAL（1.1 版及更高版本）时，Android 框架会监控 Android 设置。合作伙伴可以通过 Google Play 服务或其他系统更新来更改这些设置。这些设置可告知 GNSS HAL 是否不应使用某些 GNSS 卫星。在持续出现 GNSS 卫星或星群错误时，或者为了更快地响应使用不同的时制和外部事件（例如闰秒和/或日或周数滚动增加）混合星群时可能发生的 GNSS HAL 实现问题时，这些设置非常有用。</p> <h3 id="gnss_hardware_model">GNSS 硬件型号</h3> -<p>在 Android 9 中，GNSS HAL 1.1 或更高版本可以将有关硬件 API 的信息传递给平台。平台需要实现 <code>IGnssCallback</code> 接口并向 HAL 传递一个句柄。GNSS HAL 通过 <a href="https://developer.android.com/reference/android/location/LocationManager#getGnssHardwareModelName()" class="external"><code>LocationManager#getGnssHardwareModelName()</code></a> API 传递硬件型号信息。设备制造商应与其 GNSS HAL 提供商合作，以尽可能提供此信息。</p> +<p>在 Android 9 中，GNSS HAL 1.1 或更高版本可以将有关硬件 API 的信息传递给平台。平台需要实现 <code>IGnssCallback</code> 接口并向 HAL 传递一个句柄。GNSS HAL 通过 <a href="https://developer.android.com/reference/android/location/LocationManager#getGnssHardwareModelName()" class="external"><code>LocationManager#getGnssHardwareModelName()</code></a> API 传递硬件型号信息。设备制造商应与其 GNSS HAL 提供商合作，以尽可能提供相关信息。</p> <h2 id="permissions">权限</h2> @@ -550,7 +550,7 @@ <p>Android 9 改进了对带宽估测的支持。如果 Android 应用知道可用的数据带宽，则可以更好地决定用于视频通话和视频串流的分辨率。</p> -<p>在运行 Android 6.0 及更高版本的设备上，想获得移动网络带宽估算值的调用程序会调用 <a href="https://developer.android.com/reference/android/net/ConnectivityManager.html#requestBandwidthUpdate(android.net.Network)" class="external"><code>ConnectivityManager.requestBandwidthUpdate()</code></a>，而且框架可以提供下行链路带宽估算值。<em></em></p> +<p>在运行 Android 6.0 及更高版本的设备上，想获得移动网络带宽估算值的调用程序会调用 <a href="https://developer.android.com/reference/android/net/ConnectivityManager.html#requestBandwidthUpdate(android.net.Network)" class="external"><code>ConnectivityManager.requestBandwidthUpdate()</code></a>，并且框架可以提供下行链路带宽估算值。<em></em></p> <p>但是，在运行 Android 9 或更高版本的设备上，当带宽估算值发生显著变化时，<a href="https://developer.android.com/reference/android/net/ConnectivityManager.NetworkCallback.html#onCapabilitiesChanged(android.net.Network,%20android.net.NetworkCapabilities)" class="external"><code>onNetworkCapabilitiesChanged()</code></a> callback 会自动触发，并且调用 <code>requestBandwidthUpdate()</code> 是空操作；系统会为关联的 <a href="https://developer.android.com/reference/android/net/NetworkCapabilities#getlinkdownstreambandwidthkbps" class="external"><code>getLinkDownstreamBandwidthKbps()</code></a> 和 <a href="https://developer.android.com/reference/android/net/NetworkCapabilities#getlinkupstreambandwidthkbps" class="external"><code>getLinkUpstreamBandwidthKbps()</code></a> 填入由物理层提供的已更新信息。</p> @@ -577,7 +577,7 @@ <li><p><strong>SystemBackupAgent</strong>：在此版本及更高版本的 Android 中，<code>restoreAnyVersion = false</code>。不支持从更高版本的 API 进行恢复。</p></li> <li><p><strong>SettingsBackupAgent</strong>：从此版本开始，<code>restoreAnyVersion = true</code>。 通过验证程序提供部分支持。如果目标操作系统中存在某项设置的验证程序，则可以从更高版本的 API 恢复该设置。添加任何设置都应附带该设置的验证程序。请查看相关类以了解详情。</p></li> -<li><p>ROM 中包含的任何<strong>自定义备份代理</strong>都应做到以下两点：当备份数据格式发生不兼容的更改时，递增其版本号；如果其代理未做好准备，无法根据未来版本的代码处理备份数据，则应确保 <code>restoreAnyVersion = false</code>（默认值）。</p></li> +<li><p>ROM 中包含的任何<strong>自定义备份代理</strong>都应做到以下两点：一旦备份数据格式发生不兼容的更改，就应递增其版本号；如果其代理未做好准备，无法根据未来版本的代码处理备份数据，则应确保 <code>restoreAnyVersion = false</code>（默认值）。</p></li> </ul> <h2 id="enterprise">企业</h2>
diff --git a/zh-cn/setup/start/site-updates.html b/zh-cn/setup/start/site-updates.html index 6a5ede1..db00447 100644 --- a/zh-cn/setup/start/site-updates.html +++ b/zh-cn/setup/start/site-updates.html
@@ -39,22 +39,22 @@ <h3 id="set-up">“设置”(Setup) 更名为“设置”(Set up)</h3> <p>主“设置”(Setup) 标签的名称略微做了一点改动，改成了<strong>设置</strong> (Set up)，以便与用于后续主要标签的动词保持一致。<em></em> -<strong>下载</strong>和<strong>编译</strong>内容已拆分为不同的子标签，以便于访问其中包含的页面。“开发”子部分已更名为<strong>创建</strong>子标签，以避免与新增的顶级同名<strong>开发</strong>标签混淆。<em></em></p> +<strong>下载</strong>和<strong>编译</strong>内容已拆分为不同的子标签，以便于访问其中包含的页面。“开发”子部分已更名为<strong>创建</strong>子标签，以避免与新增的顶级同名标签<strong>开发</strong>相混淆。<em></em></p> -<p>之前在“兼容性”>“与我们联系”页面上提供的信息现已合并到主<strong>设置 > 联系方式（社区）</strong>列表中。<em></em> +<p>以前在“兼容性”>“与我们联系”页面上提供的信息现已合并到主<strong>设置 > 联系方式（社区）</strong>列表中。<em></em> </p> <h3 id="design">“兼容性”更名为“设计”</h3> -<p>以前在“兼容性”顶级标签中提供的信息现位于<strong>设计</strong>下。<em></em>要大致了解该计划以及指向新的《Android 兼容性定义文档》(CDD) 的链接，请参阅<strong>兼容性</strong>子标签。<em></em></p> +<p>以前在“兼容性”顶级标签中提供的信息现位于<strong>设计</strong>下。<em></em>要大致了解该计划以及新版《Android 兼容性定义文档》(CDD) 的链接，请参阅<strong>兼容性</strong>子标签。<em></em></p> -<p>在相关更改中，关于《Android 兼容性测试套件》(CTS) 的说明以及常规的调试信息已移至新的<strong>测试</strong>子标签。<em></em><strong>显示</strong>和<strong>设置</strong>菜单指南已转移到专用子标签。</p> +<p>在相关更改中，将关于《Android 兼容性测试套件》(CTS) 的说明以及常规的调试信息移到了新的<strong>测试</strong>子标签中。<em></em><strong>显示</strong>和<strong>设置</strong>菜单指南已转移到专用子标签。</p> <h3 id="develop">“移植”更名为“开发”</h3> -<p>“移植”标签已更名为<strong>开发</strong>，以更好地体现此标签中包含的说明。<em></em>本文档主要侧重于实现各个接口，可帮助您编写将设备连接到 Android 操作系统所需的驱动程序。</p> +<p>为了更好地体现标签中包含的说明，已将“移植”标签更名为<strong>开发</strong>。<em></em>本文档主要侧重于实现各个接口，可帮助您编写将设备连接到 Android 操作系统所需的驱动程序。</p> -<p>因此，描述总体 HIDL 格式的<strong>架构</strong>部分已移至<strong>设计</strong>标签，以便在开发周期早期的规划阶段予以考虑。<em></em><strong>引导加载程序</strong>内容现在位于<strong>设计 > 架构</strong>下，同时引入了<strong>交互性</strong>子标签，以包含输入、传感器和相关信息。<em></em><em></em></p> +<p>因此，描述总体 HIDL 格式的<strong>架构</strong>部分已移至<strong>设计</strong>标签，以便在开发周期早期的规划阶段予以考虑。<em></em><strong>引导加载程序</strong>内容现在位于<strong>设计 > 架构</strong>下，并且引入了<strong>交互性</strong>子标签，以包含输入、传感器和相关信息。<em></em><em></em></p> <p><strong>连接</strong>部分已经过重新整理，包含<strong>蓝牙和 NFC</strong>、<strong>通话和短信</strong>、<strong>运营商</strong>和 <strong>WLAN</strong> 子部分。此外，WLAN 部分还包含以下新文章：</p> @@ -68,7 +68,7 @@ <h3 id="configure">“微调”更名为“配置”</h3> -<p>“微调”标签已更名为<strong>配置</strong>，因为除了自定义和优化步骤之外，还会包含其他信息。<em></em>现在，您可以在<strong>企业</strong>下方找到以前的“设备管理”子部分。<em></em>ART 和 Dalvik 内容位于 <strong>ART</strong> 下方，无线下载 (OTA) 更新信息位于<strong>更新</strong>下方。<em></em><em></em></p> +<p>“微调”标签已更名为<strong>配置</strong>，因为除了自定义和优化步骤之外，还会包含其他信息。<em></em>现在，您可以在<strong>企业</strong>下方找到以前的“设备管理”子部分，<em></em>在 <strong>ART</strong> 下方找到 ART 和 Dalvik 内容，在<strong>更新</strong>下方找到无线下载 (OTA) 更新信息。<em></em><em></em></p> <h2 id="Dec-2017">2017 年 12 月</h2> <p> @@ -127,8 +127,7 @@ </p> <h2 id="Nov-2017">2017 年 11 月</h2> -<p> -“源代码”部分已更名为<a href="/setup"><em>设置</em></a>。<em></em>我们设置了重定向，以确保旧网址仍可正常运行。 +<p>“源代码”部分已更名为<a href="/setup"><em>设置</em></a>。<em></em>我们设置了重定向，以确保旧网址仍可正常运行。 </p> <h2 id="Sept-2017">2017 年 9 月</h2> @@ -173,9 +172,8 @@ <h4>模糊测试</h4> <p> -AOSP 提供了用于测试 <a href="/devices/tech/dalvik/">Android Runtime (ART)</a> 基础架构的全新模糊测试套件。全新的工具包 JFuzz 以及经过改进的 DexFuzz 现在可以直接在 AOSP 中获得，并且随附了相关文档。请参阅： - <a href="https://android.googlesource.com/platform/art/+/master/tools/jfuzz/README.md">https://android.googlesource.com/platform/art/+/master/tools/jfuzz/README.md</a> - <a href="https://android.googlesource.com/platform/art/+/master/tools/dexfuzz/README">https://android.googlesource.com/platform/art/+/master/tools/dexfuzz/README</a> +AOSP 提供了用于测试 <a href="/devices/tech/dalvik/">Android Runtime (ART)</a> 基础架构的全新模糊测试套件。全新的工具包 JFuzz 以及经过改进的 DexFuzz 现在可以直接在 AOSP 中获得，并且随附了相关文档。请参阅：<a href="https://android.googlesource.com/platform/art/+/master/tools/jfuzz/README.md">https://android.googlesource.com/platform/art/+/master/tools/jfuzz/README.md</a> +<a href="https://android.googlesource.com/platform/art/+/master/tools/dexfuzz/README">https://android.googlesource.com/platform/art/+/master/tools/dexfuzz/README</a> </p> <p> 无需执行任何操作，即可实现或使用这些新工具。必要时您可以对这些工具进行更改，就像您可以更改运行时/编译器一样。 @@ -337,8 +335,7 @@ </p> <ul> <li>如果 Activity 或应用的<a href="https://developer.android.com/guide/topics/ui/multi-window.html#configuring" class="external">大小可调整</a>，则允许 Activity 填充屏幕。 - </li><li> -如果 Activity 或应用的大小不可调整，或者平台会强制调整 Activity 的大小，则允许应用窗口根据 <a href="https://developer.android.com/reference/android/R.attr.html#maxAspectRatio" class="external">maxAspectRatio</a> 值，以不超过此值的宽高比显示。 + </li><li>如果 Activity 或应用的大小不可调整，或者平台会强制调整 Activity 的大小，则允许应用窗口根据 <a href="https://developer.android.com/reference/android/R.attr.html#maxAspectRatio" class="external">maxAspectRatio</a> 值，以不超过此值的宽高比显示。 <ul> <li>对于在搭载 Android 8.0 的设备上运行的应用，默认值为当前设备的宽高比。</li> <li>对于在搭载较低版本 Android 的设备上运行的应用，默认值为 16:9。</li> @@ -380,8 +377,7 @@ <p> 他们必须确保自己的代码不含未定义的行为（通过使用 UBSan 等工具），以使之不易受到新工具链带来的问题的影响。所有工具链都始终在 AOSP 中直接更新。远远在 OC 发布之前，所有功能便都已可用，因此 OEM 应已遵循相关规定。 </p> -<p> -如需常规说明，请参阅<a href="https://llvm.org/" class="external">公开的 Clang/LLVM</a> 文档；如需 Android 专属指南，请参阅 AOSP 中的 <a href="https://android.googlesource.com/platform/external/clang/+/master/ReadmeAndroid.md" class="external">Android Clang/LLVM</a> 文档集。最后，请加入 <a href="https://groups.google.com/forum/#!forum/android-llvm">android-llvm</a> 公开论坛，以获取帮助和参与开发。 +<p>如需常规说明，请参阅<a href="https://llvm.org/" class="external">公开的 Clang/LLVM</a> 文档；如需 Android 专属指南，请参阅 AOSP 中的 <a href="https://android.googlesource.com/platform/external/clang/+/master/ReadmeAndroid.md" class="external">Android Clang/LLVM</a> 文档集。最后，请加入 <a href="https://groups.google.com/forum/#!forum/android-llvm">android-llvm</a> 公开论坛，以获取帮助和参与开发。 </p> <h3 id="drm-kms">DRM/KMS</h3> @@ -441,12 +437,11 @@ <p> <a href="https://developer.android.com/reference/android/printservice/PrintService.html" class="external">打印服务</a>是一款应用，可用于发现打印机并将其呈现给设备的打印框架。在较低的 Android 版本中，用户必须搜索并安装第三方打印服务才能进行打印。 </p> -<p> -Android 8.0 在 <code><a href="https://android.googlesource.com/platform/packages/services/BuiltInPrintService/" class="external">platform/packages/services/BuiltInPrintService/</a></code> 中纳入了一项默认打印服务，以便用户在新型打印机上进行打印，而无需安装额外的应用。此实现支持符合以下条件的打印机：使用互联网打印协议 (IPP) 进行通信，并使用 PCLm、PWG-Raster 或 PDF 发送可打印的内容。要使用旧式打印机，用户应安装 <a href="https://android.googlesource.com/platform/frameworks/base/+/master/packages/PrintRecommendationService/" class="external">PrintRecommendationService</a> 推荐的应用（如<a href="https://youtu.be/M_JGeGLpOKs?t=16m20s" class="external">此 I/O 演示</a>中所示）。 +<p>Android 8.0 在 <code><a href="https://android.googlesource.com/platform/packages/services/BuiltInPrintService/" class="external">platform/packages/services/BuiltInPrintService/</a></code> 中纳入了一项默认打印服务，借助该服务，用户无需安装额外的应用就可以在现代打印机上打印。此实现支持符合以下条件的打印机：使用互联网打印协议 (IPP) 进行通信，并使用 PCLm、PWG-Raster 或 PDF 发送可打印的内容。要使用旧式打印机，用户应安装 <a href="https://android.googlesource.com/platform/frameworks/base/+/master/packages/PrintRecommendationService/" class="external">PrintRecommendationService</a> 推荐的应用（如<a href="https://youtu.be/M_JGeGLpOKs?t=16m20s" class="external">此 I/O 演示</a>中所示）。 </p><h3 id="reference">参考资料更新</h3> <p> -顶级导航菜单中添加了<a href="/reference/">参考资料</a>部分。它属于 <a href="/devices/architecture/treble">Treble</a> 版本的一部分，其中添加了 <a href="/reference/hidl/">HIDL 参考资料</a>部分。<a href="/reference/tradefed/">Trade Federation</a> 和<a href="/reference/hal/">旧版 HAL</a> 参考文档已更新。 +顶级导航菜单中添加了<a href="/reference/">参考资料</a>部分。在 <a href="/devices/architecture/treble">Treble</a> 版本中，添加了 <a href="/reference/hidl/">HIDL 参考资料</a>部分。更新了 <a href="/reference/tradefed/">Trade Federation</a> 和<a href="/reference/hal/">旧版 HAL</a> 参考文档。 </p> <h3 id="settings-menu">“设置”菜单</h3> @@ -496,8 +491,7 @@ <figcaption><strong>图 1</strong> 网站的新移动视图</figcaption> <h3 id="top-tabs">新的顶级标签</h3> -<p> -<em></em>之前的“设备”标签已更名为<a href="/devices/">移植</a>，同时之前的“核心技术”子标签已更名为<em></em><a href="/devices/tech/">微调</a>，并移到了网站顶部，以便更好地显示给用户。 +<p>之前的“设备”标签已更名为<a href="/devices/">移植</a>，同时之前的“核心技术”子标签已更名为<a href="/devices/tech/">微调</a>，并移到了网站顶部，以便更好地显示给用户。<em></em><em></em> </p> <h3 id="security-forefront">“安全性”标签排在了前列</h3> @@ -511,8 +505,7 @@ </p> <h3 id="code-links">每页都有的代码链接</h3> -<p> -只需点击每个页面右上角的<strong>转到源代码</strong>按钮，即可访问 <a href="https://android.googlesource.com/" class="external">AOSP 代码库</a>。 +<p>只需点击每个页面右上角的<strong>转到源代码</strong>按钮，即可访问 <a href="https://android.googlesource.com/" class="external">AOSP 代码库</a>。 </p> <h3 id="comprehensive-footers">包罗广泛的页脚</h3>