Миграция в Bazel

load("//tools:defaults.bzl", "ts_library")

TEST_SRCS = [
    "**/*_test.ts",
    "image_test_util.ts",
]

# Компилирует большую часть tfjs-core с использованием модуля `@tensorflow/tfjs-core/dist`.
ts_library(
    name = "tfjs-core_src_lib",
    srcs = glob(
        ["**/*.ts"],
        exclude = TEST_SRCS + ["index.ts"],
    ),
    module_name = "@tensorflow/tfjs-core/dist",
    deps = [
        "@npm//@types",
        "@npm//jasmine-core",
        "@npm//seedrandom",
    ],
)
```# Компилирует входной файл `index.ts` из `tfjs-core` отдельно от остальных источников,
# чтобы использовать имя модуля `@tensorflow/tfjs-core` вместо `@tensorflow/tfjs-core/dist`.
ts_library(
    name = "tfjs-core_lib",
    srcs = ["index.ts"],
    module_name = "@tensorflow/tfjs-core",
    deps = [
        ":tfjs-core_src_lib",
    ],
)

load("//tools:tfjs_bundle.bzl", "tfjs_bundle")

tfjs_bundle(
    name = "tf-core",
    entry_point = "//tfjs-core/src:index.ts",
    external = [
        "node-fetch",
        "util",
    ],
    umd_name = "tf",
    deps = [
        "//tfjs-core/src:tfjs-core_lib",
        "//tfjs-core/src:tfjs-core_src_lib",
    ],
)

load("//tools:defaults.bzl", "ts_library")
``````md
### Обновите точку входа для тестов
Многие пакеты имеют файл `src/run_tests.ts` (или аналогичный), который они используют для выбора тестов для выполнения. Этот файл определяет пути к файлам с тестами, используемым Jasmine. Поскольку выходные данные Bazel располагаются в другом месте, пути к файлам с тестами должны быть обновлены. Например, следующие пути
```ts
const coreTests = 'node_modules/@tensorflow/tfjs-core/src/tests.ts';
const unitTests = 'src/**/*_test.ts';

const coreTests = 'tfjs-core/src/tests.js';
const unitTests = 'the-package-name/src/**/*_test.js';

Наша конфигурация тестирования позволяет точно настраивать, какие именно тесты будут запущены через `setTestEnvs` и `setupTestFilters` в файле `jasmine_util.ts`, который используется в пользовательском файле входа Jasmine `setup_test.ts`. Эта конфигурация плохо работает вместе с [jasmine_node_test](https://bazelbuild.github.io/rules_nodejs/Jasmine.html#jasmine_node_test), которая предоставляет свой собственный файл входа для запуска Jasmine. Вместо этого мы используем правило [nodejs_test](https://bazelbuild.github.io/rules_nodejs/Built-ins.html#nodejs_test).

`tfjs-core/BUILD.bazel`
```starlark
load("@build_bazel_rules_nodejs//:index.bzl", "js_library", "nodejs_test")

# Это необходимо для того, чтобы тесты имели доступ к
# файлу package.json, так как src/version_test.ts использует 'require()' для его чтения.
js_library(
    name = "package_json",
    srcs = [
        ":package.json",
    ],
)

nodejs_test(
    name = "tfjs-core_node_test",
    data = [
        ":package_json",
        "//tfjs-backend-cpu/src:tfjs-backend-cpu_lib",
        "//tfjs-core/src:tfjs-core_lib",
        "//tfjs-core/src:tfjs-core_src_lib",
        "//tfjs-core/src:tfjs-core_test_lib",
    ],
    entry_point = "//tfjs-core/src:test_node.ts",
    link_workspace_root = True,
    tags = ["ci"],
)

load("//tools:defaults.bzl", "esbuild")
```esbuild(
    name = "tfjs-core_test_bundle",
    testonly = True,
    entry_point = "setup_test.ts",
    external = [
        # тесты WebWorker вызывают 'require("@tensorflow/tfjs")',
        # который является внешним относительно пакета тестов.
        # Примечание: это не целевой объект Bazel. Это просто строка.
        "@tensorflow/tfjs",
        "worker_threads",
        "util",
    ],
    sources_content = True,
    deps = [
        ":tfjs-core_lib",
        ":tfjs-core_test_lib",
        "//tfjs-backend-cpu/src:tfjs-backend-cpu_lib",
        "//tfjs-core:package_json",
    ],
)

```Сборка esbuild затем используется в макроопределении tfjs_web_test, которое использует [karma_web_test](https://bazelbuild.github.io/rules_nodejs/Concatjs.html#karma_web_test) для предоставления его браузеру для выполнения. Разные браузеры BrowserStack можно включать или отключать с помощью аргумента `browsers`, а полный список браузеров находится в `tools/karma_template.conf.js`. Тесты BrowserStack автоматически маркируются как `ci`.````tfjs-core/BUILD.bazel`
```starларк
load("//tools:tfjs_web_test.bzl", "tfjs_web_test")

tfjs_web_test(
    name = "tfjs-core_test",
    srcs = [
        "//tfjs-core/src:tfjs-core_test_bundle",
    ],
    browsers = [
        "bs_chrome_mac",
        "bs_firefox_mac",
        "bs_safari_mac",
        "bs_ios_12",
        "bs_android_10",
        "win_10_chrome",
    ],
    static_files = [
        # Here are the files to ensure that source mapping tables are available
        "//tfjs-core/src:tfjs-core_test_bundle",
        # For web worker
        ":tf-core.min.js",
        ":tf-core.min.js.map",
        "//tfjs-backend-cpu:tf-backend-cpu.min.js",
        "//tfjs-backend-cpu:tf-backend-cpu.min.js.map",
    ],
)

load("//tools:enumerate_tests.bzl", "enumerate_tests")
```# Генерирует файл 'tests.ts', который импортирует все точки входа тестов.
enumerate_tests(
    name = "tests",
    srcs = [":all_test_entrypoints"], # all_test_entrypoints является группой файлов
    root_path = "tfjs-core/src",
)
```### Обновление файла package.json
1. Убедитесь, что точки входа в файле package.json совпадают с выходами, сгенерированными командами `tfjs_bundle` и `ts_library`. Пример можно найти в файле [tfjs-core/package.json](https://github.com/tensorflow/tfjs/blob/a32cc50dbd0dce2e6a53bb962eedc0d87a064b1e/tfjs-core/package.json#L6-L12).
   1. Основная точка входа должна указывать на пакет для Node.js, `dist/tf-package-name.node.js`.
   2. Поля `jsnext:main` и `module` должны указывать на выход ESModule `dist/index.js`, созданный командой `copy_ts_library_to_dist`.
2. Если пакет имеет браузерные тесты, обновите поле `sideEffects`, чтобы включить файлы `.mjs`, сгенерированные командой `ts_library` в директории `. /src` (например, `src/foo.mjs`). Bazel выдает прямым образом в `src`, хотя мы копируем эти выходы в `dist` с помощью другой команды Bazel, браузерные тестовые пакеты всё ещё импортируют из `src`, поэтому нам нужно пометить их как `sideEffects`.

### Пакет для npm
Мы используем правило [pkg_npm](https://bazelbuild.github.io/rules_nodejs/Built-ins.html#pkg_npm) для создания и публикации пакета в npm. Однако, перед тем как объявить пакет, требуется выполнить несколько шагов. Для большинства пакетов мы распространяем все наши скомпилированные выходные данные в директории `dist`.Однако из-за того, как работает правило `ts_library`, оно создает выходные данные в том же каталоге, откуда были скомпилированы исходные файлы (кроме того, они появляются в выводной директории Bazel `dist-bin`). Нам нужно скопировать эти файлы из `src` в `dist`, при этом гарантируя, что Bazel осведомлен об этой операции копирования (чтобы мы могли продолжать использовать `pkg_npm`).Нам также нужно скопировать несколько других файлов в `dist`, таких как бандлы, созданные с помощью `tfjs_bundle`, а также создать [miniprogram](https://walkthechat.com/wechat-mini-programs-simple-introduction/) файлы для WeChat.

Для копирования файлов обычно используется правило `copy_to_dist`. Это правило создает символические ссылки на все файлы в `srcs` и помещает их в дерево файлов с такой же структурой в `dest_dir` (по умолчанию это `dist`).

Однако просто скопировать выходные данные правила `ts_library` невозможно, так как его стандартные выходные данные — это файлы объявлений `.d.ts`. Нам нужно извлечь желаемые модули ES `.mjs` и переименовать их, чтобы они имели расширение `.js`. Правило `copy_ts_library_to_dist` выполняет эту переименовку и также копирует файлы в `dist` (включая файлы объявлений `.d.ts`).

```starlark
load("//tools:copy_to_dist.bzl", "copy_ts_library_to_dist")

copy_ts_library_to_dist(
    name = "copy_src_to_dist",
    srcs = [
        "//tfjs-core/src:tfjs-core_lib",
        "//tfjs-core/src:tfjs-core_src_lib",
        "//tfjs-core/src:tfjs-core_test_lib",
    ],
    root = "src", # Рассматриваем 'src' как корневую директорию копирования
                  # (то есть создается 'dist/index.js' вместо 'dist/src/index.js').
    dest_dir = "dist", # Куда копировать файлы. По умолчанию это 'dist', поэтому этот параметр можно опустить в данном случае.
)

Копируем файлы минифицированной программы, используя правило `copy_file`, которое копирует отдельный файл в указанное место.```starlark
load("@bazel_skylib//rules:copy_file.bzl", "copy_file")

copy_file(
    name = "copy_miniprogram",
    src = ":tf-core.min.js",
    out = "dist/miniprogram/index.js",
)

copy_file(
    name = "copy_miniprogram_map",
    src = ":tf-core.min.js.map",
    out = "dist/miniprogram/index.js.map",
)

load("@build_bazel_rules_nodejs//:index.bzl", "pkg_npm")

pkg_npm(
    name = "tfjs-core_pkg",
    package_name = "@tensorflow/tfjs-core",
    srcs = [
        # Добавьте любые статические файлы, которые пакет должен содержать здесь
        "package.json",
        "README.md",
    ],
    tags = ["ci"],
    deps = [
        ":copy_bundles",
        ":copy_miniprogram",
        ":copy_miniprogram_map",
        ":copy_src_to_dist",
        ":copy_test_snippets", # <- Это только в core, поэтому опущено его определение в этих документах.
    ],
)

{
    "scripts": {
        "publish-npm": "bazel run :tfjs-core_pkg.publish"
    }
}

### Обновление путей `package.json` в зависимых пакетах

Если ни один пакет не зависит от вашего пакета (то есть ни одно `package.json` файл не ссылается на ваш пакет через зависимость `link`), то вы можете пропустить этот раздел. Как основная особенность своего дизайна, Bazel располагает выходные данные в отдельной директории от источников. Выходные данные ссылаются на `dist/bin/[package-name]/.....` вместо того, чтобы появляться в `[package-name]/dist`. Из-за различия местоположения все последующие пакеты должны обновить свои файлы `package.json`, чтобы указывать на новые выходные данные. Однако из-за некоторых деталей работы Bazel и алгоритма разрешения модулей Node.js, мы не можем напрямую использовать `link:` для выходных данных Bazel. Вместо этого мы поддерживаем псевдо-пакет `link-package`, где копируем выходные данные Bazel. Этот пакет позволяет правильно разрешать модули Node между выходными данными Bazel, так как он имеет свой собственный каталог `node_modules`. Этот пакет никогда не будет опубликован и будет удален после завершения миграции.

#### Добавьте пакет в `link-package`
Добавьте ваш пакет в список `PACKAGES` в скрипте `build_deps.ts` в директории `link-package`. Для пакета с npm-названием `@tensorflow/tfjs-foo` директория пакета в многопроектной системе и значение, которое следует добавить в `PACKAGES`, должны быть одинаковыми — `tfjs- Yöntem foo`. Название цели `pkg_npm` пакета должно быть `tfjs-foo_pkg`.

---

Корректировка:

#### Добавьте пакет в `link-package`
Добавьте ваш пакет в список `PACKAGES` в скрипте `build_deps.ts` в директории `link-package`. Для пакета с npm-названием `@tensorflow/tfjs-foo` директория пакета в многопроектной системе и значение, которое следует добавить в `PACKAGES`, должны быть одинаковыми — `tfjs-foo`. Название цели `pkg_npm` пакета должно быть `tfjs-foo_pkg`.```typescript
const PACKAGES: ReadonlySet<string> = new Set([
  ..., 'tfjs-foo',
]);

"devDependencies": {
  "@tensorflow/tfjs-core": "link:../link-package/node_modules/@tensorflow/tfjs-core",
  "@tensorflow/tfjs-foo": "link:../link-package/node_modules/@tensorflow/tfjs-foo",
},

"scripts": {
  "build-deps": "....... && yarn build-tfjs-foo" // <-- 删除'yarn build-tfjs-foo'。
  "build-tfjs-foo": "remove this script", // <-- 同时在这里也删除它。
}

"paths": {
  ...,
  "@tensorflow/the-new-package": ["the-new-package/src/index.ts"],
  "@tensorflow/the-new-package/dist/*": ["the-new-package/src/*"]
}

Удалите скрипт `lint` из файла `package.json`, файл `tslint.json`, и шаг `lint` из файла `cloudbuild.yml` пакета. Удалите зависимости, связанные с `tslint`, из файла `package.json` пакета и выполните `yarn` для генерации нового файла `yarn.lock`.### Обновление или удаление `cloudbuild.yml`
Обновите `cloudbuild.yml`, чтобы удалить все шаги, которые теперь создаются с помощью Bazel. Эти шаги будут выполнены в рамках шага `bazel-tests`, который выполняется до других шагов пакетов. Любое правило Bazel, помеченное как `ci`, будет тестироваться / строиться в CI.Учтите, что пути вывода созданных Bazel файлов будут отличаться, поэтому любые оставшиеся шаги, которые теперь зависят от выходных данных Bazel, могут потребовать обновления. Выходные данные Bazel расположены в `tfjs/dist/bin/...`.

Если все шаги файла `cloudbuild.yml` теперь обрабатываются Bazel, его можно удалить. Не удаляйте пакет из `tfjs/scripts/package_dependencies.json`.

Перестроите золотые файлы `cloudbuild`, запустив `yarn update-cloudbuild-tests` в корне репозитория.

### Отправка в Git
Перед отправкой в Git запустите линтер Bazel, выполнив команды `yarn bazel:format` и `yarn bazel:lint-fix` в корне репозитория. Мы запускаем линтер в CI, так что если ваша сборка проваливается только в CI, некорректно отформатированные файлы могут быть причиной проблемы.

### Готово!
🎉🎉🎉## Примечания для проверки PR* Убедитесь, что пакет добавлен в `BAZEL_PACKAGES` в [e2e/scripts/publish-tfjs-ci.sh](https://github.com/tensorflow/tfjs/blob/master/e2e/scripts/publish-tfjs-ci.sh#L61).
* Убедитесь, что пакет добавлен в `BAZEL_PACKAGES` в [scripts/publish-npm.ts](https://github.com/tensorflow/tfjs/blob/master/scripts/publish-npm.ts#L31).
* Убедитесь, что пакет, сгенерированный командой `pkg_npm`, содержит все необходимые файлы, такие как README.
* Убедитесь, что пакет добавлен в `package.json` связывающего пакета и что下游包更新为指向链接包的副本而不是包目录。
* Для браузерных тестов может быть полезно проверить, что все желаемые конфигурации браузера будут выполняться ночью в CI.
* Убедитесь, что браузерные тесты включают все требуемые тесты. Правило `enumerate_tests` обычно необходимо для запуска тестов браузером.
* Убедитесь, что возможно больше шагов cloud-build были преобразованы в Bazel, и что эти шаги удалены из файла cloud-build.
* Если сборка и тесты полностью обрабатываются Bazel и не требуют других шагов cloud-build, убедитесь, что файл `cloudbuild.yml` пакета удален. Не удаляйте пакет из [scripts/package_dependencies.json](https://github.com/tensorflow/tfjs/blob/master/scripts/package_dependencies.json).
* Убедитесь, что тесты отмечены как `nightly` или `ci` (`tfjs_web_test` автоматически маркирует тесты как `nightly` и `ci`).
* Убедитесь, что основное правило `pkg_npm` отмечено как `ci` или `nightly`, чтобы все части сборки были протестированы.
* Убедитесь, что скрипты `package.json` обновлены и что `package.json` включает `@bazel/bazelisk` как зависимость для разработки.* Убедитесь, что пакет имеет скрипт `build-npm` и скрипт `publish-npm`. Эти скрипты используются скриптом выпуска.
* Проверьте размеры сгенерированных пакетов и убедитесь, что они не содержат непредвиденные файлы. Проверьте файлы `_stats` для получения информации об этом.
* Убедитесь, что пакет добавлен в [общий tslint tsconfig репозитория](tsconfig_tslint.json) и что его оригинальные скрипты линтера удалены.