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. 对这些文件执行三向合并并更新目标文件。
5. 报告任何合并冲突。

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

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

神圣文件

在生成代码时，文件分为两大类：机器维护和用户维护。然而，最好在初始生成时提供一个 starter 或 skeleton 文件，即使对于最终将由用户维护的文件也是如此。

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

例如，您可能希望生成一个 starter "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 文件 tofile

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

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

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

x-generate 文件 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"/>

应该优先于“属性”任务来读取环境变量，因为这反映了变量在 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"/>