Sencha 编译器参考

Sencha Cmd 中的主要组件之一是其编译器，它提供了一个 JavaScript 到 JavaScript 的、感知框架的优化器。优化器“理解”您的高级 Ext JS 和 Sencha Touch 代码，并生成尽可能最小的、最高效的代码来支持这些高级抽象。

先决条件

在继续之前，建议阅读以下指南

• Sencha Cmd 简介
• 编译器友好代码指南
• 使用 Sencha Cmd

集合和当前集合

在后台，编译器管理一组源文件并分析这些文件以确定其依赖项。所有文件集合由 classpath 确定

sencha compile -classpath=common,app ...

在此示例中，编译器从指定文件夹列表中递归加载 "*.js"。所有文件集合定义了所有后续操作的基础（即，定义其“universe”）。

编译器使用的默认 classpath 来自以下配置属性

${framework.classpath},${workspace.classpath},${app.classpath}

在运行高级命令（如 sencha app build）时，Sencha Cmd 将知道正在使用的 SDK，并加载适当的配置以及将该框架的 "src" 文件夹包含在 classpath 中。在这些上下文之外使用编译器时，您可能需要使用 -sdk 开关

sencha -sdk /path/to/sdk compile -classpath=common,app ...

编译器的输出命令（例如，concat 和 metadata）对名为“当前集合”的文件集合进行操作。当前集合最初等于所有文件的 universe，但可以使用提供的许多命令对其进行操作以执行集合操作。

注意 使用编译器时，您经常会看到使用 and 命令链接机制的相当长的命令行。此外，在实际用例中，对于较长的命令行，您应该考虑使用 Ant 或“响应文件”。请参阅 高级 Sencha Cmd。

在此指南中，所有命令行都是完整的（且可能很长），以尽可能清晰地保持示例。

框架和类路径

最终，编译器需要到达所需 SDK 的 "src" 文件夹，但仅将其添加到 -classpath 中并不能产生最佳结果。相反，如上例所示，应使用 -sdk 开关来告知编译器正在使用哪个 Sencha 框架。这将使编译器能够理解特定于框架的事物，例如暗示类依赖项的配置属性（例如 Ext.data.Store 上的 model 配置）。

使用 concat 生成输出

编译器最终是关于给定一些输入编写有用的输出。concat 命令以适当的依赖顺序连接当前文件集合的源代码。

一个必需的参数是 -out，它指示输出文件的名字。其他选项会影响生成的文件。您可以为压缩选择以下选项之一

• -compress - 使用默认压缩器压缩生成的文件。目前这与 -yui 相同。
• -closure - 使用 Google Closure Compiler 压缩生成的文件。
• -yui - 使用 YUI Compressor 压缩源文件。
• -strip - 从输出文件中删除注释，但保留空格。此选项将“ext-all-debug-w-comments.js”转换为“ext-all-debug.js”。

以下命令从单个源读取中生成三种输出风格。

sencha -sdk sdk compile \
    exclude -namespace Ext.chart and \
    concat ext-all-nocharts-debug-w-comments.js and \
    -debug=true \
    concat -strip ext-all-nocharts-debug.js and \
    -debug=false \
    concat -yui ext-all-nocharts.js

生成元数据

编译器还可以以多种有用的方式生成元数据，例如，所有源文件的名字、按依赖顺序排列的文件集合等。要查看可用的内容，请参阅 生成元数据 指南。

保存和还原集合

当您需要生成多个输出文件时，保存当前集合以供以后使用会非常有帮助

sencha -sdk sdk compile \
    exclude -namespace Ext.chart and \
    save nocharts and \
    ...
    restore nocharts and \
    ...

save 命令对当前集合进行快照，并将其存储在给定的名字下（在此示例中为 nocharts）。

保存集合最简单的用法是使用 restore 命令，该命令执行相反的操作，并将当前集合还原到 save 时的状态。

集合操作

编译器提供的许多命令被归类为集合操作，这些操作对集合进行操作并生成集合。在编译器的情况下，这意味着文件或类的集合。让我们首先了解一下集合术语。

一点集合论

有三种经典集合操作

• 交集 - 两个集合的交集是一个只包含两个集合中都有的元素的集合。

• 并集 - 两个集合的并集是一个包含两个集合中任一集合中元素的集合。

• 差集 - 两个集合的差集是由第一个集合中不在第二个集合中的所有元素组成的集合。

  

集合 include 和 exclude

这两个集合操作可能是最常见（且灵活）的集合操作。两者都支持这些基本开关

• -namespace - 匹配在指定命名空间中定义类型的文件。
• -class - 匹配特定定义的类型。
• -file - 使用 Ant 风格的 glob 模式匹配文件名和/或文件夹名（“”仅匹配文件名字符，而“*”匹配文件夹）。
• -tag - 匹配具有指定标签的任何文件（见下文）。
• -set - 存在于任何指定命名集合中的文件。

在所有这些情况下，下一个命令行参数都是用逗号分隔的匹配条件列表。此外，单个 exclude 或 include 可以根据需要具有任意多个开关/值对。

因此，让我们从一个简单的示例开始，构建一个 "ext-all-no-charts-debug-w-comments.js"。

sencha -sdk sdk compile \
    exclude -namespace Ext.chart and \
    ...

这里发生的事情是我们仅从 Ext JS 源（在 "sdk/src" 中）开始，它们都是“当前集合”的一部分。然后，我们通过排除 Ext.chart 命名空间中的所有文件执行集合差集。然后，当前集合等效于 "ext-all.js"，但没有使用 Chart 包。

使用 -not 否定 include 和 exclude

include 和 exclude 都支持丰富的匹配条件。这由 -not 开关完成，它否定其后的匹配条件。这意味着包含或排除的文件都是不符合条件的文件。

例如

sencha -sdk sdk compile -classpath=js \
    ... \
    exclude -not -namespace Ext and \
    ...

exclude 命令从当前集合中排除不在 Ext 命名空间中的任何类。

all 集合

在某些情况下，将当前集合恢复为所有文件或空集合非常方便。要执行此操作，只需使用带有 -all 开关的 include 或 exclude。以之前的示例为基础

sencha -sdk sdk compile -classpath=js \
    ... \
    include -all and \
    ... \
    exclude -all and \
    ...

在 include -all 之后，当前集合是所有文件。在 exclude -all 之后，它是空集合。

并集

如前所示，include 命令是集合并集的一种形式：它执行当前集合与匹配文件集合的并集。有时希望不将当前集合包含在并集中，而仅包含那些与所需条件匹配的文件。这就是 union 命令的作用。

union 命令具有 include 的所有选项。考虑此 union 命令

sencha -sdk sdk compile -classpath=js ... and \
    union -namespace Ext.grid,Ext.chart and \
    ...

它完全等效于以下一对 exclude 和 include 命令

sencha -sdk sdk compile -classpath=js ... and \
    exclude -all and \
    include -namespace Ext.grid,Ext.chart and \
    ...

传递性/递归并集

最重要的集合操作之一是显式指定的所有文件及其所需的所有文件的并集。这是构建过程的核心，因为这是选择所需文件集合的方式。因此，如果你有一组小型顶级文件来启动进程，比如类 MyApp.App，则可以使用

sencha -sdk sdk compile -classpath=app \
    union -r -class MyApp.App and \
    ...

union 命令从没有当前集合开始，仅包含类 MyApp.App，然后继续递归包含它所需的所有内容。生成的当前集合是应用程序所需的所有文件。

交集（严格）

intersect 命令在其支持的条件方面不太灵活：它只接受命名集合（使用 -set）。

sencha -sdk sdk compile -classpath=common,page1/src,page2/src \
    ... \
    intersect -set page1,page2 and \
    ... \

此命令对两个页面集合求交集，并生成它们的交集作为当前集合。

交集（模糊）

在处理两个以上集合时，intersect 有一个名为 -min 的选项，用于设置当前集合中的成员资格阈值。

例如，

sencha compile ... \
    intersect -min=2 -set page1,page2,page3 and \
    ...

intersect 的这种用法在当前集中生成在三个指定的集中找到的两个集中存在的所有文件。

编译器指令

在许多情况下，将元数据嵌入到只有编译器会拾取的文件中非常有用。为此，编译器识别特殊行注释作为指令。这些指令是以 @ 前缀词开头的单行注释。例如

// @define Foo.bar.Thing

指令列表为

• // @charset
• // @tag
• // @define
• // @require

字符编码

没有标准方法来指定特定 JS 文件的字符编码。因此，Sencha Cmd 编译器理解以下指令

// @charset ISO-9959-1

这必须是 JS 文件的第一行。charset 右侧的值可以是任何有效的 Java 字符集 名称。默认值为“UTF-8”。

charset 指令用于描述输入文件到编译器的编码。这不会影响输出文件的编码。输入文件的内容在内部转换为 Unicode。

标记

在理想情况下，命名空间足以定义一组感兴趣的内容。然而，有时一组内容可能是相当任意的，甚至可以跨越命名空间边界。编译器可以跟踪文件中的任意标记，而不是将此问题移至命令行级别。

考虑示例

// @tag foo,bar

这将标记 foo 和 bar 分配给文件。这些标记可以在 include、exclude 和 union 命令中与它们的 -tag 选项一起使用。

处理“其他”JavaScript 文件

在某些情况下，JavaScript 文件定义类或对象，并且需要未根据 Ext.define 和 requires 或 Ext.require 表达的类或对象。使用 Ext.define，您仍然可以说一个类 requires 这样的东西，并且只要这些东西存在，动态加载器就不会抱怨（如果它们不存在，加载器将尝试加载它们，这很可能会失败）。

为了支持定义和需要类型的任意 JavaScript 方法，编译器还提供了这些指令

// @define Foo.bar.Thing
// @require Bar.foo.Stuff

这些指令在编译器中设置了相同的基本元数据，用于跟踪哪个文件定义了类型以及文件需要哪些类型。因此，在大多数情况下，这些指令完成的事情与具有 requires 属性的 Ext.define 相同。

您可以在不使用另一个指令的情况下在文件中使用其中任何一个指令。

条件编译

编译器支持条件编译指令，例如

foo: function () {
    //<debug>
    if (sometest) {
        Ext.log.warn("Something is wrong...");
    }
    //</debug>

    this.bar();
}

这可能是最实用的条件指令，您可以将其用于您希望在开发环境中运行但不在生产环境中运行的代码。

重要信息当您使用条件编译时，请记住，除非您始终运行已编译的代码，否则指令只是注释，并且条件代码将在开发期间“生效”。

debug 指令

在编译时，默认情况下，不检查任何预处理程序语句。因此，在这种情况下，结果是开发模式。如果我们打开 -debug，我们会得到一个非常相似的结果，但预处理程序处于活动状态。事实上，唯一的区别是预处理程序指令被删除了。

例如，此命令

sencha compile -classpath=... \
    -debug \
    ...

生成如下代码

foo: function () {
    if (sometest) {
        Ext.log.warn("Something is wrong...");
    }

    this.bar();
}

但是，此命令

sencha compile -classpath=... \
    -debug=false \
    ...

生成如下代码

foo: function () {
    this.bar();
}

您可以看到 if 测试和日志语句都被删除了。

if 指令

最通用的指令是 if。if 指令根据指令的属性测试一个或多个配置的选项，并在任何选项为 false 时删除块中的代码。

例如

//<if debug>
//</if>

这等效于 <debug> 指令。

app.json 中的 buildOptions 属性可用于指定其他编译器选项。例如，考虑以下块

{
    // ...
    "buildOptions": {
        "foo": true,
        "bar": false
    },
    // Can also be specified for a given build environment
    "production": {
        "buildOptions": {
            "foo": false
        }
    },
    // or even per build profile 
    "builds": {
        "abc": {
            "buildOptions": {
                "foo": true
            }
         },
         "xyz": {
             "buildOptions": {
                 "bar": true
             }
         }
     }
 }

上述内容允许像这样使用 if 指令

//<if foo>
console.log("foo is enabled!");
//</if>

//<if bar>
console.log("bar is enabled!");
//</if>