Building¶
To build Envoy Mobile, your system must also be set up for building Envoy. To get started, you can use this quick start guide.
Ensure that the envoy submodule is initialized when cloning by using --recursive:
git clone https://github.com/lyft/envoy-mobile.git --recursive
If the repo was not initially cloned recursively, you can manually initialize the Envoy submodule:
git submodule update --init
Bazel requirements¶
Envoy Mobile is compiled using the version of Bazel specified in the .bazelversion file.
To simplify build consistency across environments, bazelisk is used. Follow these Envoy instructions to install bazelisk as bazel.
Android requirements¶
- Android SDK Platform 29
- Android NDK 21
iOS requirements¶
- Xcode 12.2
- Swift 5.x
- Note: Requirements are listed in the .bazelrc file and CI scripts
Android AAR¶
Envoy Mobile can be compiled into an .aar file for use with Android apps.
This command is defined in the main BUILD file of the repo, and may be run locally:
bazel build android_dist --config=android --fat_apk_cpu=<arch1,arch2>
Upon completion of the build, you’ll see an envoy.aar file at dist/envoy.aar.
Alternatively, you can use the prebuilt artifact from Envoy Mobile’s releases or from Maven.
The envoy_mobile_android Bazel rule defined in the dist BUILD file provides
an example of how this artifact may be used.
When building the artifact for release (usage outside of development), be sure to include the
--config=release-android option, along with the architectures for which the artifact is being built:
bazel build android_dist --config=release-android --fat_apk_cpu=x86,armeabi-v7a,arm64-v8a
For a demo of a working app using this artifact, see the Hello World example.
iOS static framework¶
Envoy Mobile supports being compiled into a .framework for consumption by iOS apps.
This command is defined in the main BUILD file of the repo, and may be run locally:
bazel build ios_dist --config=ios
Upon completion of the build, you’ll see a Envoy.framework directory at
dist/Envoy.framework.
Alternatively, you can use the prebuilt artifact from Envoy Mobile’s releases or from CocoaPods.
The envoy_mobile_ios Bazel rule defined in the dist BUILD file provides an
example of how this artifact may be used.
When building the artifact for release (usage outside of development), be sure to include the
--config=release-ios option, along with the architectures for which the artifact is being built:
bazel build ios_dist --config=release-ios --ios_multi_cpus=i386,x86_64,armv7,arm64
For a demo of a working app using this artifact, see the Hello World example.
Maven¶
Envoy Mobile Android artifacts are also uploaded to Maven, and can be accessed/downloaded here.
CocoaPods¶
If you use CocoaPods on iOS, you can add the following to your Podfile to use the latest version
of the prebuilt Envoy Mobile framework.
pod 'EnvoyMobile'
Building Envoy Mobile with private Extensions¶
Similar to Envoy, Envoy Mobile has bazel targets that allows the library to be built as a git submodule in a consuming project. This setup enables creating private extensions, such as filters.
Extensions¶
The top-level envoy_build_config directory allows Envoy Mobile to tap into Envoy’s already existing selective extensions system. Additionally, Envoy Mobile requires force registration of extensions in the extension_registry.cc/h files due to static linking.
In order to override the extensions built into Envoy Mobile create an envoy_build_config directory
and include the following in the WORKSPACE file:
local_repository(
name = "envoy_build_config",
# Relative paths are also supported.
path = "/somewhere/on/filesystem/envoy_build_config",
)
Deploying Envoy Mobile Locally¶
Android¶
To deploy Envoy Mobile’s aar to your local maven repository, run the following commands:
# To build Envoy Mobile. --fat_apk_cpu takes in a list of architectures: [x86|armeabi-v7a|arm64-v8a].
bazelisk build android_dist --config=android --fat_apk_cpu=x86
# To publish to local maven.
dist/sonatype_nexus_upload.py --files dist/envoy.aar dist/envoy-pom.xml --local
The version deployed will be LOCAL-SNAPSHOT. These artifacts can be found in your local maven directory (~/.m2/repository/io/envoyproxy/envoymobile/envoy/LOCAL-SNAPSHOT/)