From c6ccb4deb7cca902d2d5e16ba03d7ceedc16bfa3 Mon Sep 17 00:00:00 2001 From: godofredoc Date: Wed, 12 Apr 2023 10:17:27 -0700 Subject: [PATCH] Add docs on how to debug global generators. (flutter/engine#41102) Add docs on how to debug global generators. --- engine/src/flutter/ci/builders/README.md | 223 ++++++++++++----------- 1 file changed, 113 insertions(+), 110 deletions(-) diff --git a/engine/src/flutter/ci/builders/README.md b/engine/src/flutter/ci/builders/README.md index 12fcaacaf1..dd411c5cb0 100644 --- a/engine/src/flutter/ci/builders/README.md +++ b/engine/src/flutter/ci/builders/README.md @@ -6,51 +6,40 @@ Flutter Engine Build Definition Language uses json to describe a complex build u **Go Link: flutter.dev/go/engine-build-definition-language** -**Created:** 01/2023 / **Last updated: **01/2023 - +**Created:** 01/2023 / **Last updated:**01/2023 ## WHAT PROBLEM IS THIS SOLVING? Engine builds are a complex combination of recipe source code, gn+ninja commands, fuzzy dependencies hidden by running everything in a single builder, and multiple helper scripts using bash and python to generate artifacts combining build system outputs. This complexity is error prone and impacts the velocity of the whole team as adding|removing|updating artifacts require multiple coordinated pull requests and an in-depth knowledge of the engine source code, build system, recipes and infrastructure. -The build definition language targets the following goals: - - - - - -* Remove complexity of the engine build system describing the builds in a single place and using a common language. -* Remove the requirement for engine developers to learn recipes and python. -* Make slow builds faster with automated and efficient sharding. -* Add clarity about what a build is doing by clearly defining its components. -* Simplify builds by separating build, test, generate and archive steps. -* Get early feedback through presubmit on changes adding/deleting/updating engine artifacts. +The build definition language targets the following goals: +* Remove complexity of the engine build system describing the builds in a single place and using a common language. +* Remove the requirement for engine developers to learn recipes and python. +* Make slow builds faster with automated and efficient sharding. +* Add clarity about what a build is doing by clearly defining its components. +* Simplify builds by separating build, test, generate and archive steps. +* Get early feedback through presubmit on changes adding/deleting/updating engine artifacts. ## BACKGROUND Engine builds use LUCI recipes to build, test and archive artifacts. The workflow requires to checkout the engine repository, run gn, run ninja, create artifacts and upload them to GCS. These steps are implemented differently for different platforms usually by copy/pasting blocks of recipe code. This copy/paste process generated a large and complex [engine.py](https://cs.opensource.google/flutter/recipes/+/main:recipes/engine/engine.py) recipe (2K+ lines of code) which is difficult to update/maintain without breaking the builds. -Having the build logic as a sequence of build steps in a monolithic recipe makes it very difficult to identify dependencies in between sub-builds, sometimes duplicating logic in multiple places and making it very difficult for engineers to add/remove logic. - +Having the build logic as a sequence of build steps in a monolithic recipe makes it very difficult to identify dependencies in between sub-builds, sometimes duplicating logic in multiple places and making it very difficult for engineers to add/remove logic. #### Audience Flutter Engine contributors that add/update/remove builds, platforms and artifacts from the build system. - #### Glossary - - -* **[recipes](https://github.com/luci/recipes-py)** - domain specific language for specifying sequences of subprocess calls in a cross-platform and testable way. -* **Generator **- scripts in dart, python or bash that generates artifacts combining the output of sub-builds. -* **Builder** - a combination of configuration and recipes used with a given commit to build artifacts and test them. -* **Build** - a builder running with specific properties, repository and commit. -* **[Gn](https://gn.googlesource.com/gn/)**, a meta-build system that generates build files for [Ninja](https://ninja-build.org/). -* **[Ninja](https://ninja-build.org)**, Ninja is a small build system with a focus on speed. -* **CAS**, a service that stores arbitrary binary blobs addressed by (hash of) their content. It is specialized for low latency, high volume query/read/write operations. - +* **[recipes](https://github.com/luci/recipes-py)** - domain specific language for specifying sequences of subprocess calls in a cross-platform and testable way. +* **Generator**- scripts in dart, python or bash that generates artifacts combining the output of sub-builds. +* **Builder** - a combination of configuration and recipes used with a given commit to build artifacts and test them. +* **Build** - a builder running with specific properties, repository and commit. +* **[Gn](https://gn.googlesource.com/gn/)**, a meta-build system that generates build files for [Ninja](https://ninja-build.org/). +* **[Ninja](https://ninja-build.org)**, Ninja is a small build system with a focus on speed. +* **CAS**, a service that stores arbitrary binary blobs addressed by (hash of) their content. It is specialized for low latency, high volume query/read/write operations. ## OVERVIEW @@ -62,12 +51,10 @@ On top of the current use cases the definition language also supports configurat The definition language makes heavy use of GN and Ninja to move most of the build/test/archive logic to the flutter/engine repository. This will help us remove most of the logic from recipes and make the recipes implementation generic and reusable by Dart & Flutter teams. - #### Non-goals Using a format different from json to describe the engine builds. - ## USAGE EXAMPLES Engine builds will be translated one to one using the build definition language with one file per build. The build definition files will be stored in the [flutter/engine/ci/builders](https://cs.opensource.google/flutter/engine/+/main:ci/builders/) directory. @@ -76,7 +63,6 @@ The [engine orchestrator recipe](https://cs.opensource.google/flutter/recipes/+/ Ci\_yaml file is the glue sticking all the components together. A new build will be added to the [.ci.yaml](https://cs.opensource.google/flutter/engine/+/main:.ci.yaml) file with a property pointing to the build definition file to be used by engine\_v2 recipes. The following is an example of a build configuration referencing [android\_aot\_engine.json](https://cs.opensource.google/flutter/engine/+/main:ci/builders/mac_android_aot_engine.json): - ``` - name: Mac mac_android_aot_engine recipe: engine_v2/engine_v2 @@ -88,43 +74,33 @@ Ci\_yaml file is the glue sticking all the components together. A new build will ``` - - ## DETAILED DESIGN/DISCUSSION -Flutter's LUCI Infrastructure uses the engine build configuration language to build, test and archive the engine artifacts. The goal of the configurations using the build definition language is to move all the build, test and archive logic out of recipes and bring it to the engine repository. +Flutter's LUCI Infrastructure uses the engine build configuration languageto build, test and archive the engine artifacts. The goal of the configurations using the build definition language is to move all the build, test and archive logic out of recipes and bring it to the engine repository. The following is a non-exhaustive list of the benefits of moving to build configurations files: - - -* No need to coordinate changes to recipes, engine and build configurations when adding new builds or artifacts. -* Adding new artifacts can be tested on presubmit. -* Having the archive logic in GN ensures the artifacts are created correctly, the expected dependencies are built, and the archives contain only what is generated by the build targets and their dependencies. -* The builds are simplified to a GN command followed by a ninja command. -* Artifacts are explicitly described in the configuration allowing post processing tasks like code signing. -* Scripts used as generators either local or global follow a very simple interface to ensure they can be plugged out of the box in the build system. - +* No need to coordinate changes to recipes, engine and build configurations when adding new builds or artifacts. +* Adding new artifacts can be tested on presubmit. +* Having the archive logic in GN ensures the artifacts are created correctly, the expected dependencies are built, and the archives contain only what is generated by the build targets and their dependencies. +* The builds are simplified to a GN command followed by a ninja command. +* Artifacts are explicitly described in the configuration allowing post processing tasks like code signing. +* Scripts used as generators either local or global follow a very simple interface to ensure they can be plugged out of the box in the build system. ### Assumptions To keep the build definition language simple the following assumptions were made during its design: - - -* A build can be expressed as a set of independent sub-builds. -* A sub-build can be defined as a sequence of gn, ninja, self contained test scripts, self contained generator scripts. -* All the sub-builds required by a global generator are defined within the same configuration file. - +* A build can be expressed as a set of independent sub-builds. +* A sub-build can be defined as a sequence of gn, ninja, self contained test scripts, self contained generator scripts. +* All the sub-builds required by a global generator are defined within the same configuration file. ### Build configuration language - #### Build configuration file The build configuration is a json file containing a list of builds, tests, generators and archives. The following is an example of an empty configuration file: - ``` { "builds": [], @@ -137,19 +113,16 @@ The build configuration is a json file containing a list of builds, tests, gene } ``` - Build configuration files have to be checked into the engine[/ci/builder](https://github.com/flutter/engine/tree/main/ci/builders) directory where engine v2 recipes will be reading them from. A configuration file defines a top level builder that will show up as a column in the [Flutter Dashboard](https://flutter-dashboard.appspot.com/#/build?repo=engine&branch=master). - #### Build A build is a dictionary with a gn command, a ninja command, zero or more generator commands, zero or more local tests, zero or more local generators and zero or more output artifacts. The following is the high level structure of the build component: - ``` { "archives": [], @@ -162,17 +135,12 @@ The following is the high level structure of the build component: } ``` - -Each build element will be translated to an independent sub-build and its entire out directory will be uploaded to CAS. - +Each build element will be translated to an independent sub-build and its entire out directory will be uploaded to CAS. ##### Archive An archive component is used to tell the recipes which artifacts are generated by the build and where to upload them. - - - ``` { "name": "host_debug", @@ -184,52 +152,41 @@ An archive component is used to tell the recipes which artifacts are generated b } ``` - Description of the fields: - - -* **Name:** Used to identify the archive inside CAS. -* **Base\_path:** The portion of the path to remove before uploading to its destination. In the example the base\_path **“out/host\_debug/zip\_archives”** will be extracted from the include path **"out/host\_debug/zip\_archives/linux-x64/artifacts.zip"** before uploading to GCS, e.g. <bucket>/flutter/<commit>/linux-x64/artifacts.zip. -* **Type:** The type of storage to use. Currently only **“GCS”** and **“CAS”** are supported. -* **Include\_paths:** A list of strings representing paths to artifacts generated by the build that need to be uploaded to a given destination. - +* **Name:** Used to identify the archive inside CAS. +* **Base\_path:** The portion of the path to remove before uploading to its destination. In the example the base\_path **“out/host\_debug/zip\_archives”** will be extracted from the include path **"out/host\_debug/zip\_archives/linux-x64/artifacts.zip"** before uploading to GCS, e.g. <bucket>/flutter/<commit>/linux-x64/artifacts.zip. +* **Type:** The type of storage to use. Currently only **“GCS”** and **“CAS”** are supported. +* **Include\_paths:** A list of strings representing paths to artifacts generated by the build that need to be uploaded to a given destination. ##### Drone\_dimensions A list of strings with key value pairs separated by an equal sign. These dimensions are used to select the bot where the sub-build will be running. - ``` "drone_dimensions": [ "device_type=none", "os=Linux" ] ``` - In the previous example, the build containing this drone\_dimensions component will run on a bot with a Linux OS that does not have any devices attached to it. - ##### Gclient\_variables A dictionary with the gclient variable as key and its content as value. This dictionary is passed to gclient during a gclient sync operation to add/remove gclient dependencies. - ``` "gclient_variables": { "download_android_deps": false } ``` - The example above is used to avoid downloading the [android sdk dependencies](https://cs.opensource.google/flutter/engine/+/main:DEPS;l=80) in builders that do not need it. - ##### Gn A list of strings representing flags passed to the [tools/gn](https://cs.opensource.google/flutter/engine/+/master:tools/gn?q=gn&ss=flutter%2Fengine) script. The strings can be in the form of “--flag=value” or “--flag” followed by “value”. - ``` "gn": [ "--runtime-mode", @@ -239,15 +196,12 @@ A list of strings representing flags passed to the [tools/gn](https://cs.opensou ], ``` - -The previous example will prepare the configurations to build a host debug version using a prebuilt dart sdk and also build the embedder examples. - +The previous example will prepare the configurations to build a host debug version using a prebuilt dart sdk and also build the embedder examples. ##### Ninja A dictionary with two keys: “config” which references the configs created by gn and “target” which is a list of strings with the Ninja targets to build. - ``` "ninja": { "config": "host_debug", @@ -258,16 +212,11 @@ A dictionary with two keys: “config” which references the configs created by }, ``` - In the example above the ninja command will use the configuration for host\_debug and will build artifacts and embedder targets as described by the [flutter/build/archives/BUILD.gn](https://cs.opensource.google/flutter/engine/+/master:build/archives/BUILD.gn) file. - - - ##### Tests -This section of the build configuration will be referred to as the local tests. This section contains a list of dictionaries with configurations for the scripts and parameters used to run tests inside the current build unit. These tests should not reference or use anything outside of the commit checkout or the outputs generated by running the gn and ninja sections of the build config. - +This section of the build configuration will be referred to as the local tests. This section contains a list of dictionaries with configurations for the scripts and parameters used to run tests inside the current build unit. These tests should not reference or use anything outside of the commit checkout or the outputs generated by running the gn and ninja sections of the build config. ``` "tests": [ @@ -287,22 +236,18 @@ This section of the build configuration will be referred to as the local tests. ] ``` - Description of the fields: - - -* **Language,** the executable used to run the script, e.g. python3. -* **Name,** the name of the step running the script. -* **Parameters**, flags or parameters passed to the script. -* **Script**, the path to the script to execute relative to the checkout directory. -* **Type**, the test type. (Deprecate? Test on the build config will be always local) +* **Language,** the executable used to run the script, e.g. python3. +* **Name,** the name of the step running the script. +* **Parameters**, flags or parameters passed to the script. +* **Script**, the path to the script to execute relative to the checkout directory. +* **Type**, the test type. (Deprecate? Test on the build config will be always local) The test scripts will run in a deferred context (failing the step only after logs have been uploaded). The tester and builder recipes provide an environment variable called FLUTTER\_LOGS\_DIR pointing a temporary directory where the test runner can place any logs|artifacts needed to debug issues. At the end of the test execution the content of FLUTTER\_LOGS\_DIR will be uploaded to Google Cloud Storage before signaling the pass | fail test state. Note that to keep the recipes generic they don’t know anything about what the test script is doing and it is the responsibility of the test script to copy the relevant files to the FLUTTER\_LOGS\_DIR directory. - #### Generators Generators are scripts used to generate artifacts combining the output of two or more sub-builds. The most common use case is to generate FAT binaries for Mac/iOS artifacts. @@ -311,38 +256,31 @@ Generators can be written in any language but they require to follow some guidan The guidelines are as follows: - - -* Flags receiving paths to resources from multiple sub-builds need to use paths relative to the checkout directory. If there are global generators in a build configuration, the engine\_v2 recipes will download the full archives of the sub-builds to the checkout/out/<sub-build name> directory. -* Flags receiving paths to output directories must use paths relative to the out folder. This is to be able to reference the artifacts in the global archives section. -* The script is in charge of generating the final artifact, e.g. if the script generates multiple files that will be zipped later then it is the script responsibility to generate the final zip. -* If the generator is producing a Mac/iOS artifact then it is the script responsibility to embed the signing metadata. +* Flags receiving paths to resources from multiple sub-builds need to use paths relative to the checkout directory. If there are global generators in a build configuration, the engine\_v2 recipes will download the full archives of the sub-builds to the checkout/out/<sub-build name> directory. +* Flags receiving paths to output directories must use paths relative to the out folder. This is to be able to reference the artifacts in the global archives section. +* The script is in charge of generating the final artifact, e.g. if the script generates multiple files that will be zipped later then it is the script responsibility to generate the final zip. +* If the generator is producing a Mac/iOS artifact then it is the script responsibility to embed the signing metadata. Generators contain a single property “tasks” which is a list of tasks to be performed. - ``` "generators": { "tasks": [] } ``` - The example above represents a generator configuration with an empty list of tasks. - ##### Task -Task is a dictionary describing the scripts to be executed. +Task is a dictionary describing the scripts to be executed. The properties description is as follows: - - -* **Name**, the name of the step running the script. -* **Parameters**, flags passed to the script. Both input and output paths must be relative to the checkout directory. -* **Script**, the script path relative to the checkout repository. -* **Language**, the script language executable to run the script. If empty it is assumed to be bash. +* **Name**, the name of the step running the script. +* **Parameters**, flags passed to the script. Both input and output paths must be relative to the checkout directory. +* **Script**, the script path relative to the checkout repository. +* **Language**, the script language executable to run the script. If empty it is assumed to be bash. ``` { @@ -360,6 +298,7 @@ The properties description is as follows: "script": "flutter/sky/tools/create_full_ios_framework.py", "language": "python3" } + ``` @@ -371,6 +310,7 @@ The archives component provides instructions to upload the artifacts generated b ``` + "archives": [ { "source": "out/debug/artifacts.zip", @@ -381,6 +321,7 @@ The archives component provides instructions to upload the artifacts generated b "destination": "ios-objcdoc.zip" } ] + ``` @@ -436,4 +377,66 @@ The migration to use the build definition language depends on the release | vali * A change in the engine repository to remove the old build configurations from .ci.yaml file and updating the artifact destination in the builds using the build definition language will be landed. -* A change to remove old recipes will be landed in the recipes repository. +* A change to remove old recipes will be landed in the recipes repository. + + +## Triaging global generators + +Global generators can run locally if all their sub-build dependencies are +downloaded. This section explains how to triage a local generator. + +### Prerequisites (one time installation) + + +#### Install CAS utility + +CAS client is required to download the sub-build artifacts. To install +it in your machine run the following steps: + +* `mkdir $HOME/tools` +* Download and unzip CAS binaries from + https://chrome-infra-packages.appspot.com/p/infra/tools/luci/cas +* Add $HOME/tools to path and your ~/.bashrc + +#### Gclient engine checkout + +Create a gclient checkout following instructions from +[Setting up the engine environment](https://github.com/flutter/flutter/wiki/Setting-up-the-Engine-development-environment). + +### Download sub-builds to the gclient checkout out folder + +CAS sub-build artifacts can be downloaded using information from a LUCI build. +Using https://ci.chromium.org/p/flutter/builders/prod/Mac%20mac_ios_engine/2818 +as an example the execution details from steps 13 - 17 show the commands to +download the archives. `-dir` parameter needs to be updated to point to the +relative or full path to the out folder in your gclient checkout. + +These are the commands to execute for our example build: + +``` + +pushd /src/out +cas download -cas-instance projects/chromium-swarm/instances/default_instance -digest 39f15436deaed30f861bdd507ba6297f2f26a2ff13d45acfd8819dbcda346faa/88 -dir ./ +cas download -cas-instance projects/chromium-swarm/instances/default_instance -digest bdec3208e70ba5e50ee7bbedaaff4588d3f58167ad3d8b1c46d29c6ac3a18c00/94 -dir ./ +cas download -cas-instance projects/chromium-swarm/instances/default_instance -digest d19edb65072aa9d872872b55d3c270db40c6a626c8a851ffcb457a28974f3621/84 -dir ./ +cas download -cas-instance projects/chromium-swarm/instances/default_instance -digest ac6f08662d18502cfcd844771bae736f4354cb3fe209552fcf2181771e139e0b/86 -dir ./ +cas download -cas-instance projects/chromium-swarm/instances/default_instance -digest 1d4d1a3b93847451fe69c1939d7582c0d728b198a40abd06f43d845117ef3214/86 -dir ./ + +``` + +The previous commands will create the ios_debug, ios_debug_sim, ios_debug_sim_arm64, +ios_profile, and ios_release folders with the artifacts generated by its +corresponding sub-builds. + +Once the checkout and dependencies are available locally we can cd|pushd to the +root of the client checkout and run the global generator. The command can be +copied verbatim from the executions details of the build. + +The following example will run the generator to create the ios artifacts: + +``` + +python3 flutter/sky/tools/create_full_ios_framework.py --dst out/release \ +--arm64-out-dir out/ios_release --simulator-x64-out-dir out/ios_debug_sim \ +--simulator-arm64-out-dir out/ios_debug_sim_arm64 --dsym --strip +```