@fluidframework/建设工具

这个软件包包含两个工具:

• fluid-build: 构建支持快速递增建设的任务调度器.
• fluid-type-test-generator: 生成类型兼容性测试

虽然这些工具是为"流体框架回波"而建的,但是它们可以被普遍化,也可以适用于其他回波. 以下内容和例子将侧重于流体框架回波.

运行这些工具( 命令行)

要使用,可以在全球安装软件包,也可以使用您的软件包:

• 在流体框架还原中运行 pnpm i 在根中,并使用称为它的npm脚本(例如: build:fast(中文(简体) )
• 全球安装该特定版本 @fluidframework/build-tools 并直接调用其二进制( ex) fluid-build(中文(简体) )

从本地的建筑副本中运行 。 首先在此目录中构建 :

pnpm i
pnpm run build

要么说:

• 直接援引:使用 node bin/<tool-name> 在此目录中或 node build-tools/packages/build-tools/bin/<tool-name> 从流体回波根.
• 共线包: 使用 npm 链接 使用此软件包来覆盖 根包中使用的版本(这是 client 释放组,但往往也用于构建其他组. 这会让剧本像 build:fast 使用链接的版本.

fluid-build

fluid-build 是一个构建任务调度器。 它支持申报性任务和依赖性定义,递增 检测一系列工具和repo中的多工作空间(a.k.a.释放组).

Usage: fluid-build <options> [(<package regexp>|<path>) ...]
    [<package regexp> ...] Regexp to match the package name (default: all packages)
Options:
     --all                  Operate on all packages/monorepo (default: client monorepo). See also "-g" or "--releaseGroup".
  -c --clean                Same as running build script 'clean' on matched packages (all if package regexp is not specified)
  -d --dep                  Apply actions (clean/force/rebuild) to matched packages and their dependent packages
     --fix                  Auto fix warning from package check if possible
  -f --force                Force build and ignore dependency check on matched packages (all if package regexp is not specified)
  -? --help                 Print this message
     --install              Run npm install for all packages/monorepo. This skips a package if node_modules already exists: it can not be used to update in response to changes to the package.json.
     --workerMemoryLimitMB  Memory limit for worker threads in MiB
  -r --rebuild              Clean and build on matched packages (all if package regexp is not specified)
     --reinstall            Same as --uninstall --install.
  -g --releaseGroup         Release group to operate on
     --root <path>          Root directory of the Fluid repo (default: env _FLUID_ROOT_)
  -t --task <name>          target to execute (default:build)
     --symlink              Deprecated. Fix symlink between packages within monorepo (isolate mode). This configures the symlinks to only connect within each lerna managed group of packages. This is the configuration tested by CI and should be kept working.
     --symlink:full         Deprecated. Fix symlink between packages across monorepo (full mode). This symlinks everything in the repo together. CI does not ensure this configuration is functional, so it may or may not work.
     --uninstall            Clean all node_modules. This errors if some node_modules folder do not exist. If hitting this limitation, you can do an install first to work around it.
     --vscode               Output error message to work with default problem matcher in vscode
     --worker               Reuse worker threads for some tasks, increasing memory use but lowering overhead.
     --defroot <path> Default root directory of the Fluid repo if auto detect failed (default: env _FLUID_DEFAULT_ROOT_)
     --timer          Measure elapsed time of each step
     --logtime        Display the current time on every status message for logging
  -v --verbose        Verbose messages

流体框架回波示例:

复制回波后,可以在回波的根部安装所有包的依赖性:

fluid-build --install

你可以开始建造(递增):

fluid-build             # client packages
fluid-build -g server   # server packages
fluid-build --all       # all packages

构建选中的软件包( 以及依赖的任务) :

fluid-build packages/dds/map     # Build starting from the package in the packagedir if exist.  (If the path doesn't exist it is tread as an regex to package name)
fluid-build @fluidframework/map  # Build starting from the package @fluidframework/map since it is not an existing path
fluid-build merge                # Build any package that has "merge" in the name

构建选定任务 :

fluid-build -t tsc               # only run the task `tsc` (and dependent tasks) in all package of the current release group (client release group at the root)
fluid-build -t build:esnext map  # only run the task `build:esnext` (and dependent tasks) in package that has "map" in the name

清洁和重建:

fluid-build --rebuild merge     # clean and build packages matching 'merge' in any repo
fluid-build --clean common      # cleaning packages containing 'common' in any repo

任务和依赖性定义

fluid-build 使用任务和依赖性定义来构建构建图。 它被用来确定哪些任务和 运行的命令。 包的默认定义位于根 fluidBuild.config.cjs 文档 tasks 属性. 这个定义适用于repo中的所有软件包(但不放出组根). 在此默认定义中指定的脚本任务和依赖性 不需要在每个软件包上出现,如果不找到它就会被忽略.

任务定义是一个对象,任务名称作为密钥,任务依赖和配置来定义任务的行动. 详情见定义 TaskDefinitionsOnDisk 内 ./src/common/fluid 任务定义

例如:

module.exports = {
   tasks: {
      "build": {
         dependsOn: [ "tsc", "build:test" ]           // Depends on the `tsc` nad `build:esnext` task in the same package
         script: false                                // Don't trigger a npm script
      }
      "tsc": [ "^tsc"],                               // Depends on `tsc` task of all of the dependent packages
                                                      // (if the task exists)
      "build:test": [ "tsc" ],                        // Depends on `tsc` task
      "clean": {
         before: ["*"],                               // If the task "clean" is specified, it runs before all other task
      }
      "prettier": [],                                 // No dependent tasks
   }
}

每个软件包都可以通过增加以下任务定义来强化任务定义: fluidBuild.tasks 内 package.json。 。 。 .

例如:

{
    "fluidBuild": {
        "tasks": {
            "build": ["...", "build:docs", "copy:docs"],
            "tsc": ["...", "typetests:gen"], // Depends on "typetests:gen", including dependencies
            // in default definition (i.e. "^tsc" in the above example)
            "build:test": [
                "@fluidframework/merge-tree#build:test" // Overrides default, depends only on "build:test" task
                // in dependent package "@fluidframework/merge-tree"
            ],
            "copy:docs": {
                "after": ["build:docs"] // if "build:docs" is triggered, "copy:docs" only run after it
            },
            "webpack": ["^tsc"] // Depends on `tsc` task of all of the dependent packages
            // (if the task exists)
        }
    }
}

扩展任务处理器配置文件

对于已知的任务处理者来说 eslint, (中文(简体) ), tsc, (中文(简体) ), api-extractor, 等, (中文(简体) ), fluid-build 自动跟踪它们的配置文件( 如 .eslintrc, (中文(简体) ), tsconfig.json, (中文(简体) ), api-extractor.json) (中文(简体) ). 然而,您可能想要跟踪额外的配置文件,这些配置文件会影响任务,但不会被自动发现.

您可以指定额外的配置文件以使用 additionalConfigFiles 任务属性 files 配置 。 文件路径可以相对于软件包目录,也可以使用特殊符号 ${repoRoot} 以查找寄存器根的参考文件.

全球配置实例( E)fluidBuild.config.cjs:

module.exports = {
   tasks: {
      "eslint": {
         files: {
            additionalConfigFiles: ["${repoRoot}/common/build/eslint-config-fluid/flat.mts"]
         }
      }
   }
}

软件包级别扩展示例( E)package.json:

{
   "fluidBuild": {
      "tasks": {
         "eslint": {
            "files": {
               "additionalConfigFiles": ["...", ".eslintrc.local.json"]  // Extends global additionalConfigFiles
            }
         }
      }
   }
}

举例来说:

• 全球配置使用 ${repoRoot} 在寄存器根处的参考文件,取消了对相对路径的需要,如 ../../
• 这个 ${repoRoot} 所有软件包无论在目录结构中的深度如何,符号都一样
• 特定软件包通过添加扩展此列表 .eslintrc.local.json 使用 "..." 语法
• 如果其中任何文件发生变化, 任务将会重建 eslint.config.mts eslint 自动发现的文件

这个 "..." 语法的工作方式与任务依赖性相同 - 它包括从全局定义中继承的配置. 无 "...",包级配置完全取代了全局配置.

这个 ${repoRoot} 符号也可以用于 inputGlobs 财务报告和审定财务报表 outputGlobs 用于在寄存器根处引用文件的宣告任务.

更多实例和使用案例,见 附加配置文件示例。 。 。 .

在构建放行组时,默认情况下会触发发布组内所有包上的任务. 这也意味着 不考虑发布组根的脚本.

通过添加可以启用对组根脚本的支持 fluidBuild.tasks 给释放组的 package.json。 。 。 . fluid-build 如果为任务指定了定义, 将会遵循定义, 或者如果脚本不引用, 将会触发根脚本 fluid-build。 。 。 . 如果剧本不存在,或者开始于 fluid-build,然后流体构建将回到触发任务的默认行为 在发布组内的所有软件包上。 “全球定义”没有得到支持。 任务定义 fluidBuild.config.cjs 仅适用于包,而不是释放组根. 释放组根脚本必须在 fluidBuild.tasks 区域 package.json。 。 。 .

货币

fluid-build 将基于建构图中的依赖性信息平行地运行任务。 任务已排入队列 当所有依赖性都是"完成"时. 默认, fluid-build 将执行最多数量的任务 CPU. 这可能会被 --concurrency 选项.

递增和任务

fluid-build 支持增量检测以检查某项任务是否已经更新并且不需要重建到 缩短建设时间。 它根据激活的命令有不同的探测. 见对象定义 executableToLeafTask 内 ./src/fluid 建设/任务/任务 Factory.ts 全文 任务列表.

以下是一些任务检测机制.

Tsc 任务

对于TypeScript编译器(TSC), fluid-build 使用编译器已经生成的增量构建信息 当启用增量构建选项时。 虽然 tsc 还利用这一信息避免重新汇编, tsc 在引用时,仍需要较长的时间来检测. fluid-build 绕过这个并读取增量构建来获取所有 它依赖于和比较文件散列前后的输入文件,以检查输入文件是否被更改.

埃斯林特/ Apiextractor 任务

eslint 财务报告和审定财务报表 api-extractor 这些都是“tsc依赖”的任务,并有类似的递增规则。 它会 检测任务是否需要基于任何 tsc 在构建图中声明的依赖任务(过滤到) 如果可能,则在包件内)。 然后,它复制的内容 tsc 建立这些依附任务的信息以及 该版本和配置 eslint 财务报告和审定财务报表 api-extractor 并生成一个“ done” 文件。 比较内容 当前状态和以前的构建将决定是否需要引用任务.

环境变量

以下环境变量可用于控制增量构建行为. 默认情况下, 使用一些任务 用于增量检测的文件时间戳。 设置这些变量为 "1" 允许基于内容的散列, 避免在时间戳不进行有意义的内容修改的情况下(如在git操作后)进行虚假重建 或文件副本).

示例

FLUID_BUILD_ENABLE_COPYFILES_HASH=1 fluid-build

工作模式( 实验)

使用选项的工人模式 --worker, (中文(简体) ), fluid-build 将创建工作流程, 用于运行一些工具 而不是产生新的过程。 这可以加速大约29%的建设.

工人模式目前处于实验状态,而非默认状态。 一个缺点是工人的过程会开始 积累内存,在大小上增长到多GB,以及记忆有限的dev环境可能会受到不利影响.

发行组定义

发布组基本上是由工作空间管理的软件包组. fluid-build 支持多个发布组和 在同一repo内的独立软件包。 Repo 结构在 fluidBuild.config.cjs 位于根基处 背书在 repoPackages 属性。 见 流体构建. config.cjs 对于它的样子 喜欢.

除错追踪

fluid-build 使用 debug 软件包,用于调查和诊断问题。 下面是一些痕迹 名称 fluid-build 用户.

流体构造: 正体

跟踪初始化 fluid-build,包括根目录推论、包装和选择(基于命令行) 范围).

流体构造:任务:定义

用于调试将任务定义和依赖定义从默认值中合并在一起的逻辑 fluidBuild.config.cjs 位于根部 会 议 日 程 和 议 程 repo 和本地软件包 package.json。它将放弃每个软件包的全部综合定义.

流体构造:任务:init*

这些痕迹显示了构建图中的任务和关系,用以诊断任务依赖性和订购问题. 调试痕迹可以为单个步骤或所有步骤所启用.

• fluid-build:task:init - 追踪创建的任务,以显示包含哪些任务
• fluid-build:task:init:defdep - 追踪因扩大和解决任务定义而产生的任务依赖性
• fluid-build:task:init:dep - 追踪叶子任务的完整构建图(单一命令引用)
• fluid-build:task:init:weight - 为每项任务分配的重量(优先优先进行较高重量)

流体构建:任务:触发

追踪每个任务被触发的原因 。 有助于诊断增量建设的问题.

流体构造:任务:执行*

这些痕迹显示任务的执行流程,以显示任务在行动中的引用.

• fluid-build:task:exec - 追踪任务是否被跳过,或者如果它运行,任务的开始和完成
• fluid-build:task:queue - 跟踪任务完成后的队列
• fluid-build:task:exec:wait - 在队列中跟踪任务的等待时间( 任务准备排出后执行的延迟)

其他积分:* 痕迹

• fluid-build:task:error - 追踪任务中任何操作的详细错误信息