From b1ba6f5f3f26d1673fb2a632b581f52c76670ffb Mon Sep 17 00:00:00 2001 From: Bryan Oltman Date: Tue, 9 May 2023 14:11:23 -0700 Subject: [PATCH 1/5] doc: update building_engine.md --- BUILDING_ENGINE.md | 94 ++++++++++++++++++++++++++++------------------ 1 file changed, 58 insertions(+), 36 deletions(-) diff --git a/BUILDING_ENGINE.md b/BUILDING_ENGINE.md index e863e31..2aea837 100644 --- a/BUILDING_ENGINE.md +++ b/BUILDING_ENGINE.md @@ -26,7 +26,7 @@ of configuration to get it to work. The best way I found was to install: https://github.com/bbqsrc/cargo-ndk -``` +```bash cargo install cargo-ndk rustup target add \ aarch64-linux-android \ @@ -37,63 +37,83 @@ rustup target add \ Once you have cargo-ndk installed, you can build the updater library: -``` +```bash cargo ndk --target aarch64-linux-android --target armv7-linux-androideabi build --release ``` ### Setting up to build the Flutter Engine: -https://github.com/flutter/flutter/wiki/Setting-up-the-Engine-development-environment -https://github.com/flutter/flutter/wiki/Compiling-the-engine - -The .gclient file I recommend is: +- [Install the dependencies for building the Flutter engine](https://github.com/flutter/flutter/wiki/Setting-up-the-Engine-development-environment#getting-dependencies) +- Outside of any existing git repository, create an empty directory named `engine`. +- Paste the following text into a file named `.gclient`: + ```python + solutions = [ + { + "managed": False, + "name": "src/flutter", + "url": "git@github.com:shorebirdtech/engine.git", + "custom_deps": {}, + "deps_file": "DEPS", + "safesync_url": "", + }, + ] + ``` +- Run `gclient sync` to download the Flutter engine source code (this will take a while). +- Run `cd src/flutter` to change into the Flutter engine source directory. +- Run `git checkout codepush` to switch to the `codepush` branch. +- Run `gclient sync` again. + +The above, as one set of commands: + +```bash +mkdir engine && \ + cd engine && \ + curl https://raw.githubusercontent.com/shorebirdtech/build_engine/main/build_engine/dot_gclient > .gclient && \ + gclient sync && \ + cd src/flutter && \ + git checkout codepush && \ + gclient sync ``` -solutions = [ - { - "managed": False, - "name": "src/flutter", - "url": "git@github.com:shorebirdtech/engine.git", - "custom_deps": {}, - "deps_file": "DEPS", - "safesync_url": "", - }, -] -``` -(We should probably just check that in somewhere.) -Once you have that set up and `gclient sync` has run, you will need -to switch your flutter checkout to the `codepush` branch: +The `updater` source should now be in `src/third_party/updater`. -``` -cd src/flutter -git checkout codepush -``` +TEST .gclient embed: -And then `gclient sync` again. +https://github.com/shorebirdtech/build_engine/blob/main/build_engine/dot_gclient -The `updater` source should now be in `src/third_party/updater`. +TODO: do we need to link to these? +- https://github.com/flutter/flutter/wiki/Setting-up-the-Engine-development-environment +- https://github.com/flutter/flutter/wiki/Compiling-the-engine ## Building Flutter Engine -We have scripts to perform the builds for all Android targets in: +You can either build the full set of Android targets using a script (that +should/will eventually be a Docker container) or you can build targets +individually. + +### Build all Android targets for release +The script to build all Android targets is at https://github.com/shorebirdtech/build_engine/blob/main/build_engine/build.sh -But you can also do so manually. Here is building for Android arm64: +### Build individual Android targets +You can also build Android targets manually. E.g., this builds Android arm64: -``` +```bash ./flutter/tools/gn --android --android-cpu arm64 --runtime-mode=release ninja -C out/android_release_arm64 ``` -The linking step for android_release_arm64 is _much_ longer than other platforms -we may need to use unopt or debug builds for faster iteration. +The linking step for android_release_arm64 is _much_ longer than other +platforms - we may need to use unopt or debug builds for faster iteration. I also add `&& say "done"` to the end of the ninja command so I know when it's -done (because it takes minutes). Often I'm editing/buiding from within the updater -directory so my command is: +done (because it takes minutes). Often I'm editing/building from within the +updater directory so my command is: -``` -cargo ndk --target aarch64-linux-android build --release && ninja -C ../../out/android_release_arm64 && say "done" +```bash +cargo ndk --target aarch64-linux-android build --release && \ + ninja -C ../../out/android_release_arm64 && \ + say "done" ``` ## Running with your local engine @@ -102,4 +122,6 @@ cargo ndk --target aarch64-linux-android build --release && ninja -C ../../out/a When testing on my machine I use something like: -```shorebird --local-engine-src-path=$HOME/Documents/GitHub/engine --local-engine=android_release_arm64 run``` +```bash +shorebird --local-engine-src-path=$HOME/Documents/GitHub/engine --local-engine=android_release_arm64 run +``` From 63b83ac067cc5f0ec59e268741f8d274d6ddda13 Mon Sep 17 00:00:00 2001 From: Bryan Oltman Date: Tue, 9 May 2023 14:12:45 -0700 Subject: [PATCH 2/5] cleanup --- BUILDING_ENGINE.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/BUILDING_ENGINE.md b/BUILDING_ENGINE.md index 2aea837..47b7b72 100644 --- a/BUILDING_ENGINE.md +++ b/BUILDING_ENGINE.md @@ -43,7 +43,8 @@ cargo ndk --target aarch64-linux-android --target armv7-linux-androideabi build ### Setting up to build the Flutter Engine: -- [Install the dependencies for building the Flutter engine](https://github.com/flutter/flutter/wiki/Setting-up-the-Engine-development-environment#getting-dependencies) +These steps assume that you have [installed the dependencies for building the Flutter engine](https://github.com/flutter/flutter/wiki/Setting-up-the-Engine-development-environment#getting-dependencies). + - Outside of any existing git repository, create an empty directory named `engine`. - Paste the following text into a file named `.gclient`: ```python @@ -77,11 +78,7 @@ mkdir engine && \ The `updater` source should now be in `src/third_party/updater`. -TEST .gclient embed: - -https://github.com/shorebirdtech/build_engine/blob/main/build_engine/dot_gclient - -TODO: do we need to link to these? +References: - https://github.com/flutter/flutter/wiki/Setting-up-the-Engine-development-environment - https://github.com/flutter/flutter/wiki/Compiling-the-engine From 735fd620fd1abc5c5cd6ef3c352df8e85f7281cc Mon Sep 17 00:00:00 2001 From: Bryan Oltman Date: Tue, 9 May 2023 15:35:05 -0700 Subject: [PATCH 3/5] update --- BUILDING_ENGINE.md | 76 ++++++++++++++++++++++++++-------------------- 1 file changed, 43 insertions(+), 33 deletions(-) diff --git a/BUILDING_ENGINE.md b/BUILDING_ENGINE.md index 47b7b72..72fcad4 100644 --- a/BUILDING_ENGINE.md +++ b/BUILDING_ENGINE.md @@ -46,33 +46,15 @@ cargo ndk --target aarch64-linux-android --target armv7-linux-androideabi build These steps assume that you have [installed the dependencies for building the Flutter engine](https://github.com/flutter/flutter/wiki/Setting-up-the-Engine-development-environment#getting-dependencies). - Outside of any existing git repository, create an empty directory named `engine`. -- Paste the following text into a file named `.gclient`: - ```python - solutions = [ - { - "managed": False, - "name": "src/flutter", - "url": "git@github.com:shorebirdtech/engine.git", - "custom_deps": {}, - "deps_file": "DEPS", - "safesync_url": "", - }, - ] - ``` +- Paste the context of https://raw.githubusercontent.com/shorebirdtech/build_engine/main/build_engine/dot_gclient into a file named `.gclient`. - Run `gclient sync` to download the Flutter engine source code (this will take a while). -- Run `cd src/flutter` to change into the Flutter engine source directory. -- Run `git checkout codepush` to switch to the `codepush` branch. -- Run `gclient sync` again. -The above, as one set of commands: +Or, as one set of commands: ```bash mkdir engine && \ cd engine && \ curl https://raw.githubusercontent.com/shorebirdtech/build_engine/main/build_engine/dot_gclient > .gclient && \ - gclient sync && \ - cd src/flutter && \ - git checkout codepush && \ gclient sync ``` @@ -93,32 +75,60 @@ The script to build all Android targets is at https://github.com/shorebirdtech/build_engine/blob/main/build_engine/build.sh ### Build individual Android targets -You can also build Android targets manually. E.g., this builds Android arm64: +You can also build Android targets manually. + +Build `host_release`: ```bash -./flutter/tools/gn --android --android-cpu arm64 --runtime-mode=release -ninja -C out/android_release_arm64 +cd src && \ + ./flutter/tools/gn --runtime-mode=release && \ + ninja -C out/host_release && \ + say "done" ``` -The linking step for android_release_arm64 is _much_ longer than other -platforms - we may need to use unopt or debug builds for faster iteration. - -I also add `&& say "done"` to the end of the ninja command so I know when it's -done (because it takes minutes). Often I'm editing/building from within the -updater directory so my command is: +Build the engine for Android arm64: ```bash -cargo ndk --target aarch64-linux-android build --release && \ +cd src && \ + ./flutter/tools/gn --android --android-cpu arm64 --runtime-mode=release && \ + cd third_party/updater && \ + cargo ndk --target aarch64-linux-android build --release && \ ninja -C ../../out/android_release_arm64 && \ say "done" ``` +{% note %} + +> TODO: +> +> The "Build the engine for Android arm64" step should/will eventually be +> condensed to: +> ```bash +> cd src && \ +> ./flutter/tools/gn --android --android-cpu arm64 --runtime-mode=release && \ +> ninja -C out/android_release_arm64 +> ``` +> See https://github.com/shorebirdtech/shorebird/issues/463. + +{% endnote %} + +{% note %} + +In both of the examples above, `&& say "done"` is appended to the end of the +long-running ninja command to alert me when it has finished. The `say` command +is only available on macOS. + +{% endnote %} + + ## Running with your local engine -`shorebird` commands support `--local-engine-src-path` and `--local-engine` just like `flutter` commands do. +`shorebird` commands support `--local-engine-src-path` and `--local-engine`, +just like `flutter` commands do. -When testing on my machine I use something like: +When testing on my machine, I use something like: ```bash -shorebird --local-engine-src-path=$HOME/Documents/GitHub/engine --local-engine=android_release_arm64 run +$PATH_TO_ENGINE_SRC="$HOME/Documents/GitHub/engine/src" +shorebird --local-engine-src-path=$PATH_TO_ENGINE_SRC --local-engine=android_release_arm64 run ``` From d167b66fc83fe033b14a7b36368f660553dcf846 Mon Sep 17 00:00:00 2001 From: Bryan Oltman Date: Tue, 9 May 2023 15:38:43 -0700 Subject: [PATCH 4/5] cleanup --- BUILDING_ENGINE.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/BUILDING_ENGINE.md b/BUILDING_ENGINE.md index 72fcad4..d7e00b6 100644 --- a/BUILDING_ENGINE.md +++ b/BUILDING_ENGINE.md @@ -101,8 +101,7 @@ cd src && \ > TODO: > -> The "Build the engine for Android arm64" step should/will eventually be -> condensed to: +> The "Build the engine for Android arm64" step will eventually be condensed to: > ```bash > cd src && \ > ./flutter/tools/gn --android --android-cpu arm64 --runtime-mode=release && \ From 7b3e451dac2b9c0bfce96fbe6d8c428242a2d586 Mon Sep 17 00:00:00 2001 From: Bryan Oltman Date: Tue, 9 May 2023 15:42:31 -0700 Subject: [PATCH 5/5] Remove {% note %} tags that don't work --- BUILDING_ENGINE.md | 19 ++++++------------- 1 file changed, 6 insertions(+), 13 deletions(-) diff --git a/BUILDING_ENGINE.md b/BUILDING_ENGINE.md index d7e00b6..347f4f9 100644 --- a/BUILDING_ENGINE.md +++ b/BUILDING_ENGINE.md @@ -97,9 +97,7 @@ cd src && \ say "done" ``` -{% note %} - -> TODO: +> **TODO** > > The "Build the engine for Android arm64" step will eventually be condensed to: > ```bash @@ -109,16 +107,11 @@ cd src && \ > ``` > See https://github.com/shorebirdtech/shorebird/issues/463. -{% endnote %} - -{% note %} - -In both of the examples above, `&& say "done"` is appended to the end of the -long-running ninja command to alert me when it has finished. The `say` command -is only available on macOS. - -{% endnote %} - +> **📝 NOTE** +> +> In both of the examples above, `&& say "done"` is appended to the end of the +> long-running ninja command to alert me when it has finished. The `say` command +> is only available on macOS. ## Running with your local engine