Ant 集成

Sencha Cmd 是一个跨平台命令行工具。在底层，Sencha Cmd 使用 Apache Ant 来提供其大部分功能。本指南描述了此接口中 Sencha Cmd 最重要的部分。

先决条件

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

• Sencha Cmd 简介
• 使用 Sencha Cmd

Ant

Apache Ant 长期以来一直是 Java 开发社区的支柱，但从本质上讲，Ant 是一个基于 XML 的跨平台脚本平台。它是一个“平台”而不是“语言”，因为 Ant 可以轻松地合并 JAR 形式的代码库，或者您可以使用许多受支持的脚本语言之一作为 Ant 脚本的一部分。

Ant 当然可以调用其他程序（如 Sencha Cmd），传递参数和处理退出代码，但 Ant 特别擅长的是操作文件。这是因为 Ant 被设计用于构建脚本。

正如 高级 Sencha Cmd 指南中提到的，Sencha Cmd 以 JAR 文件形式交付，并将其核心功能公开为 Ant 库（或 antlib）。Sencha Cmd 的命令行级别以及 SDK 特定的处理都在此层之上实现。因此，您在一个方面可以做的任何事情，都可以在另一个方面做。

如果您正在使用 Ant，则最好在此级别与 Sencha Cmd 接口，而不是通过命令行界面重复调用。

<taskdef resource="com/sencha/ant/antlib.xml" 
         classpath="${cmd.dir}/sencha.jar"
         loaderref="senchaloader"/>

当 Ant 脚本使用 sencha ant ... 执行时，cmd.dir 属性会在入口处定义。否则，Ant 脚本或执行方必须以适合本地机器的方式确定 cmd.dir。

x-sencha-init

此任务从当前目录中基于 "sencha.cfg" 文件加载配置属性。这通常由需要 Sencha Cmd 并且特定于 Sencha 应用程序构建的 Ant 脚本完成。

<x-sencha-init/>

这还将加载任何可用的 Sencha Cmd “扩展”定义的任何 Ant 任务，例如 x-compass-compile。

x-sencha-command

此命令等效于命令行界面。参数放置在此标记的正文文本中，每行一个参数。空格在两端被修剪，因此缩进级别并不重要。缩进的一个很好的用法是阐明命令结构，像这样

<x-sencha-command>
    compile
        --classpath=app,sdk/src
        page
            --in=app/index.html
            --out=build/index.html
</x-sencha-command>

因为每一行都是一个参数，所以空格不是特殊的，不应被转义或引用。

Ant 属性被扩展，因此以下（相当传统的样式）也有效

<x-sencha-command>
    compile
        --classpath=${app.dir},${sdk.dir}/src
        page
            --in=${app.dir}/index.html
            --out=${build.dir}/index.html
</x-sencha-command>

最后，支持注释，因此您可以记录命令或临时禁用部分，而无需删除它们。此外，空白行将被跳过

<x-sencha-command>
    compile
        # Include the app folder and the sdk/src folder
        --classpath=${app.dir},${sdk.dir}/src

        # Turn off debugging (comment next line to leave debug enabled):
        # --debug=false

        page
            # The application main page:
            --in=${app.dir}/index.html

            # The compiled page goes in build folder along with "all-classes.js":
            --out=${build.dir}/index.html
</x-sencha-command>

x-extend-classpath

此任务扩展当前 ClassLoader 的类路径。这有时是必要的，以便在类路径中包含 "sencha.jar"，但在 Ant 脚本启动且必须动态扩展类路径的其他情况下也很有用。

<x-extend-classpath>
    <jar path="${cmd.dir}/sencha.jar/>
</x-extend-classpath>

可以列出所需数量的 JAR。

x-generate

此任务以两种基本模式从模板生成输出：file 和 dir。也就是说，模板生成器可以获得单个源文件或源文件夹。

模板

源文件的名称决定了它是否应作为“模板”处理

• .tpl = Ext.XTemplate

例如，"foo.js.tpl" 将用于使用 XTemplate 引擎生成 "foo.js"。

合并文件

在可能需要更改文件原始生成内容（即，重新生成目标）的情况下，".merge" 后缀非常有用。这种情况的主要用例是应用程序的 "app.js" 文件。

在处理 ".merge" 文件时，x-generate 执行以下步骤

1. 将目标文件（例如，"app.js"）移动到一旁（例如，作为 "app.js.$old"）。
2. 在目标位置生成新版本的文件（例如，"app.js"）。
3. 使用数据存储，重新生成基本版本（例如，"app.js.$base"）。也就是说，上次生成的版本。
4. 对这些文件执行 3 向合并，并更新目标文件。
5. 报告任何合并冲突。

通常情况下（与 "app.js" 一样），".merge" 文件也是 ".tpl"。例如，对于 "app.js"，源文件是 "app.js.tpl.merge"。

要启用此模式，必须为 x-generate 提供指向数据存储（JSON 文件）的 store 属性。

神圣文件

生成代码时，文件分为两个基本类别：机器维护和用户维护。然而，即使对于最终将由用户维护的文件，最好在初始生成时提供启动器或骨架文件。

这称为“神圣”文件，并通过源文件扩展名 ".default" 标识。也就是说，源文件只是一个默认值，不会替换现有文件。

例如，可能需要生成一个启动器 "readme.txt" 文件，但保留用户在稍后重新生成期间可能已更改的任何内容。为此，源文件将命名为 readme.txt.default。

有时，神圣文件也是模板。这可以通过添加两个扩展名来完成，例如，"readme.txt.tpl.default"。此 "readme.txt" 文件是一个神圣文件，最初是从模板生成的。

参数

模板生成需要数据或参数。最简单的参数形式使用 param 属性

<x-generate ...>
    <param name="bar" value="42" />
</x-generate>

参数也可以从文件中加载，如下所示

<x-generate ...>
    <load file="data.properties"/>
</x-generate>

以下文件类型会自动识别

• ".cfg" 或 ".properties" = 标准 Java 属性文件。
• ".json" = JSON 数据文件。

如果文件没有这些扩展名之一，但它是属性文件或 JSON，则可以将 type 属性指定为 json 或 properties，如下所示

<x-generate ...>
    <load file="data.props" type="properties" />
    <load file="data" type="json" />
</x-generate>

注意。 参数按指定的顺序应用。如果遇到重复的名称，则会替换它们。

x-generate file tofile

x-generate 最简单的形式是使用 file 属性将单个模板文件转换为指定的输出文件

<x-generate file="foo.js.tpl" tofile="build/foo.js">
    <param name="bar" value="42" />
</x-generate>

源文件名决定了进程如何进行（以及使用哪个模板引擎以及它是否是神圣的），但仅此而已。

x-generate file todir

在许多情况下，您可以省略目标文件名，而只指定文件夹，如下所示

<x-generate file="foo.js.tpl" todir="build">
    <param name="bar" value="42" />
</x-generate>

这会在 "build" 文件夹中生成 "foo.js"（使用 XTemplate）。

除了避免冗余之外，这种形式还允许源文件名是模板，例如

<x-generate file="{name}.js.tpl" todir="build">
    <param name="name" value="foobar" />
    <param name="bar" value="42" />
</x-generate>

源文件以指定的名称存在（即，"{name}.js.tpl"），但此名称使用 XTemplate 引擎和提供的参数进行转换，以确定目标文件名。

在上述情况下，"foobar.js" 在 build 目录中生成。

x-generate dir todir

x-generate 的最终形式在源文件夹上运行，并在目标文件夹中生成内容，例如

<x-generate dir="templates/foo" todir="build/foo">
    <param name="bar" value="42" />
    <load file="data.json"/>
</x-generate>

在这种形式中，生成器递归读取 "templates/foo" 中的文件和子文件夹，并应用适当的模板引擎。它还保留神圣文件。所有文件和文件夹名称都作为 XTemplate 模板处理。

x-compress-js

根据以下选项（属性）压缩 JavaScript 源代码

• srcfile：要压缩的源文件。
• outfile：要生成的输出文件（默认为 srcfile）。
• charset：输入/输出文件的字符集。
• header：可选文本，包含在文件开头的注释块中。
• linebreak：断线的列号（默认为 -1，不换行）。
• obfuscate：False 表示不混淆本地符号（默认为 true）。
• disableoptimizations：True 表示禁用所有内置优化。
• preservesemi：True 表示保留所有分号。
• verbose：True 表示启用额外的诊断消息。

x-compress-css

根据以下选项（属性）压缩 CSS 源代码

• srcfile：要压缩的源文件。
• outfile：要生成的输出文件（默认为 srcfile）。
• charset：输入/输出文件的字符集。
• header：可选文本，包含在文件开头的注释块中。
• linebreak：断线的列号。
• verbose：True 表示启用额外的诊断消息。

x-strip-js

此任务从 JS 文件中删除注释（行和/或块）。支持以下选项

• srcfile：要剥离的源文件
• outfile：要生成的输出文件（默认为 srcfile）。
• header：可选文本，包含在文件开头的注释块中。
• blockcomments：True（默认值）表示剥离块注释（“/ ... /”）。
• linecomments：True（默认值）表示剥离行注释（“//”）。
• keepfirstcomment：True（默认值）表示保留 JS 文件中的第一个注释。

  This is typically a copyright.
  

• whitespace：True 表示也剥离空白。

x-get-env

将环境变量值存储在指定的属性中。首先精确匹配环境变量名称的大小写，但如果找不到精确的大小写匹配，它将选择一个忽略大小写的匹配（如果存在）。

<x-get-env name="PATH" property="env.path"/>

与“properties”任务相比，应优先使用此任务来读取环境变量，因为这反映了 Ant 属性变量的精确大小写，Ant 属性区分大小写，但环境变量（如“Path”）至少在 Windows 上不区分大小写。

x-escape

此任务转义字符串并将转义后的字符串存储在指定的属性中。

<x-escape string="${some.text}" property="some.text.js" type="json"/>
<x-escape string="${some.text}" property="some.text.xml" type="xml"/>