mozilla
/
application-services
зеркало из
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

Draft of updates to the building.md docs

This commit is contained in:
Janet Dragojevic 2021-03-18 19:24:44 -04:00
Родитель 554b68e588
Коммит 983b9a69ec
2 изменённых файлов: 126 добавлений и 117 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

30
README.md
Просмотреть файл

@ -10,7 +10,7 @@ Get in touch with other community members on Matrix, the mailing list or through
- Matrix: [#sync:mozilla.org](https://chat.mozilla.org/#/room/#sync:mozilla.org) ([How to connect](https://wiki.mozilla.org/Matrix#Connect_to_Matrix))
- Mailing list: application-services@mozilla.com
### Building
### Building the Rust Components
1. Clone or Download the repository:
```shell
git clone https://github.com/mozilla/application-services
@ -26,10 +26,19 @@ git submodule update --recursive
cargo test
```
The application-services library's primary consumers are both Fenix (Firefox on Android) and Firefox iOS. Assure you are able to run integration tests for both by following the instructions to build for Android and iOS integrations.
### Consumer build, integration and testing
The application-services library primary consumers are Fenix (Firefox on Android) and Firefox iOS. Assure you are able to run integration tests (for Android and iOS if using MacOS) by following the instructions to build for Android and iOS integrations.
* Build instructions to test [Fenix integration](https://github.com/mozilla/application-services/blob/main/docs/build.md#building-for-fenix) (2 hrs)
#### Android integration builds and helpful tools
* Build instructions to test [Fenix / android-components integration](https://github.com/mozilla/application-services/blob/main/docs/build.md#building-for-fenix) (2 hrs)
* [Fenix Auto-publication workflow for android-components and application-services](https://github.com/mozilla-mobile/fenix/#auto-publication-workflow-for-android-components-and-application-services)
* [Nimbus: using local servers for development](https://github.com/mozilla-mobile/fenix/#using-nimbus-servers-during-local-development)
#### Firefox for iOS integration
* Build instructions to test [Firefox iOS integration](https://github.com/mozilla/application-services/blob/main/docs/build.md#building-for-firefox-ios) (2 hrs)
#### Firefox Desktop
* Build instructions to test [Firefox Desktop integration](https://github.com/mozilla/application-services/blob/main/docs/build.md#building-for-firefox-desktop) (?? hrs)
### Documentation
@ -44,16 +53,16 @@ code in this repository
### Rust Components
* [./components/](components) contains the source for each component, and its
[./components/](components) contains the source for each component, and its
FFI bindings.
* See [./components/logins/](components/logins) for an example, where you can
* See [./components/logins/](components/logins) for an example, where you can
find:
* The shared [rust code](components/logins/src).
* The mapping into a [C FFI](components/logins/ffi).
* The [Kotlin bindings](components/logins/android) for use by Android
* The shared [rust code](components/logins/src).
* The mapping into a [C FFI](components/logins/ffi).
* The [Kotlin bindings](components/logins/android) for use by Android
applications.
* The [Swift bindings](components/logins/ios) for use by iOS applications.
* See [./components/fxa-client](components/fxa-client) for an example the uses
* The [Swift bindings](components/logins/ios) for use by iOS applications.
* See [./components/fxa-client](components/fxa-client) for an example the uses
[uniffi](https://github.com/mozilla/uniffi-rs/) to generate API wrappers for
multiple languages, such as Kotlin and Swift.
@ -65,6 +74,7 @@ code in this repository
with FxA, access encryption keys for sync, and more.
* [logins](components/logins) - for storage and syncing of a user's saved login
credentials
* [nimbus](components/nimbus) - for integrating with Mozilla's [experimentation](https://mozilla.github.io/experimenter-docs/) platform for Firefox
* [places](components/places) - for storage and syncing of a user's saved
browsing history
* [push](components/push) - for applications to receive real-time updates via

213
docs/building.md
Просмотреть файл

@ -1,121 +1,120 @@
# Building Application Services
## Introduction
When working on application-services Rust Components it's important to set up your environment for both building the application-services library, but also for Android or iOS as appropriate to test your changes in our clients.
First of all, let us remind the reader that were are not dealing with a classic Rust project where you can run `cargo build` and you are ready to go. Sorry.
In fact, the project involves multiple build systems: `autoconf` for dependencies such as NSS or SQLCipher, `cargo` for the Rust common code, then either `gradle` (Android) or `XCode` (iOS) for the platform-specific wrappers.
The guide will make sure your system is configured appropriately to run these build systems without issues.
## First time builds
## Common (Desktop) build environment
Building for the first time is more complicated than a typical Rust project.
To build for an end-to-end experience that enables you to test changes in our
client applications like Fenix and Firefox iOS, there are a number of build
systems required for all the dependencies. The initial setup is likely to take
a number of hours to complete.
Ensure this section works for you before jumping to the Android/iOS specific sections.
- System-level dependencies
- gyp
- Using apt: `apt install gyp`
- [manual install](https://github.com/mogemimi/pomdog/wiki/How-to-Install-GYP)
- [ninja-build](https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages)
- tcl
- Using apt: `apt install tclsh`
- [manual install](https://www.tcl.tk/software/tcltk/)
- python3
- zlib
- Using apt: `apt install zlib1g-dev`
- Already installed on macOS by XCode.
## Building the Rust Components
Note that we have a guide if you happen to use [WSL](howtos/wsl-build-guide.md).
*Complete this section before moving to the android/iOS build instructions.*
Ensure you have fetched the submodules first:
1. Install Rust
1. Install Rust: [via rustup](https://www.rust-lang.org/tools/install)
1. [set your version](https://doc.rust-lang.org/edition-guide/rust-2018/rustup-for-managing-rust-versions.html) to match the version specified in the [rust-toolchain](../rust-toolchain) file.
1. Run: `rustc --version` to confirm.
1. Install your system dependencies - follow the instructions below for Linux, MacOS or Windows
1. Install the application-services required submodules
1. Run: `git submodule init`
1. Run: `git submodule update --recursive`
1. Check dependencies, environment variables and test
1. Run: `./libs/verify-desktop-environment.sh`
1. Run: `cargo test`
Once you have successfully run `./libs/verify-desktop-environment.sh` and `cargo test` you can move to the **Building for Fenix** and **Building for iOS** sections below to setup your local environment for testing with our client applications.
#### Linux
1. Install the system dependencies required for building NSS
1. Install gyp: `apt install gyp` (required for NSS)
1. Install ninja-build: [via package for distribution](https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages#package-managers)
1. Install python3: [3.6 via python.org](https://docs.python.org/3/using/unix.html)
1. Install zlib: `apt install zlib1g-dev`
1. Install the system dependencies required for SQLcipher
1. Install tcl: `apt install tclsh` (required for SQLcipher)
#### MacOS
1. Install Xcode: check the [ci config](../.circleci/config) for the correct
version.
1. Install Xcode tools: `xcode-select --install`
1. Install homebrew: [via homebrew](https://brew.sh/) (its what we use for ci)
1. Install the system dependencies required for building NSS
1. Install ninja: `brew install ninja`
1. Install gyp (via https://github.com/mogemimi/pomdog/wiki/How-to-Install-GYP)
1. Install swift-protobuf: `brew install swift-protobuf`
#### Windows
*Install windows build tools*
> Why [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/about)?
>
> It's currently tricky to get some of these builds working on Windows, primarily due to our use of SQLcipher. By using WSL it is possible to get builds working, but still have them published to your "native" local maven cache so it's available for use by a "native" Android Studio.
1. Install [WSL](https://docs.microsoft.com/en-us/windows/wsl/about) (recommended over native tooling)
1. Install unzip: `sudo apt install unzip`
1. Install python3: `sudo apt install python3` *Note: must be python 3.6*
1. Install system build tools: `sudo apt install build-essential`
1. Install zlib: `sudo apt-get install zlib1g-dev`
1. Install tcl: `sudo apt install tcl-dev`
---
## Building for Fenix
The instructions here assume that you are building for Fenix in order test your changes in on Fenix and want to take advantage of the
[Fenix Auto-publication workflow for android-components and application-services](https://github.com/mozilla-mobile/fenix/#auto-publication-workflow-for-android-components-and-application-services)
1. Install Android SDK, JAVA, NDK and set required env vars
1. Clone the [Fenix](https://github.com/mozilla-mobile/fenix/) repository (not in a-s)
1. Clone the [android-components](https://github.com/mozilla-mobile/android-components/) repository (not in a-s)
1. Install [Java **8**] for your system
1. Set `JAVA_HOME` to point to the JDK 8 installation directory.
1. Download and install [Android Studio](https://developer.android.com/studio/#downloads)
1. Set `ANDROID_SDK_ROOT` and `ANDROID_HOME` to the Android Studio sdk location and add it to your rc file.
1. Configure the required versions of NDK
`Configure menu > System Settings > Android SDK > SDK Tools > NDK > Show Package Details > NDK (Side by side)`
- 21.3.6528147 (required by Fenix)
- 21.0.6113669 (required by a-s)
1. If you are on Windows using WSL - drop to the section below, Windows setup
for Android (WSL) before proceeding.
1. Check dependencies, environment variables and test
1. Run `./libs/verify-android-environment.sh`
2. Follow instructions and rerun until it is successful.
### Windows setup for Android (via WSL)
Note: For non-Ubuntu linux versions, it may be necessary to execute `$ANDROID_HOME/tools/bin/sdkmanager "build-tools;26.0.2" "platform-tools" "platforms;android-26" "tools"`. See also [this gist](https://gist.github.com/fdmnio/fd42caec2e5a7e93e12943376373b7d0) for additional info.
#### Configure Maven
Configure maven to use the native windows maven repository - then, when doing ./gradlew install from WSL, it ends up in the Windows maven repo. This means we can do a number of things with Android Studio in "native" windows and have then work correctly with stuff we built in WSL.
1. Install maven: `sudo apt install maven`
1. Confirm existence of (or create) a `~/.m2` folder
1. In the `~/.m2` create a file called `settings.xml`
1. Add the content below replacing `{username}` with your username:
```
git submodule init
git submodule update --recursive
<settings>
<localRepository>/mnt/c/Users/{username}/.m2/repository</localRepository>
</settings>
```
---
The following command will ensure your environment variables are set properly and build the dependencies needed by the project:
## Building for Firefox iOS
```
./libs/verify-desktop-environment.sh
```
1. Install Carthage: `brew install carthage`
1. Install [xcpretty](https://github.com/xcpretty/xcpretty#installation): `gem install xcpretty`
1. Run `./libs/verify-ios-environment.sh` to check your setup and environment
variables.
1. Make any corrections recommended by the script and re-run.
1. Follow the guide for [using local a-s builds in iOS](https://github.com/mozilla/application-services/blob/main/docs/howtos/locally-published-components-in-ios.md#using-locally-published-components-in-firefox-for-ios)
You can then run the Rust tests using:
```
cargo test
```
## Android development
### Java 8
Using any other version than 8 __will__ mess up your build and is not supported.
Please ensure `JAVA_HOME` points to the JDK 8 installation directory.
### Setting up the Android SDK
#### Through Android Studio
1. Download and install Android Studio and let it install the SDK for you.
1. In the "SDK Manager" window, find out the location of the SDK.
1. Set `ANDROID_SDK_ROOT` and `ANDROID_HOME` (technically deprecated 🤷‍♂️) to this location and add it to your rc file.
#### Manually
Visit https://developer.android.com/studio/ and download the "Command line tools".
Install the SDK by executing:
```
> cd ~
> mkdir -p android-sdk/cmdline-tools
> cd android-sdk/cmdline-tools
> unzip {path-to.zip}
> # Don't forget to write these to your rc file!
> export ANDROID_SDK_ROOT=$HOME/android-sdk
> export ANDROID_HOME=$ANDROID_SDK_ROOT
> $ANDROID_SDK_ROOT/cmdline-tools/tools/bin/sdkmanager --licenses
```
### Rust targets, NDK
After the Android SDK is installed, run the following script that will ll install the necessary Rust targets, the Android NDK and has built-in and helpful messages to ensure you will be able to compile for Android properly:
```
./libs/verify-android-environment.sh
````
You may have to run the above script multiple times till it succeeds, once it does you can try building using:
```
./gradlew assembleDebug
```
## iOS development
### Extra dependencies
- Carthage
- swift-protobuf
- xcpretty.
The following command will ensure your environment is ready to build the project for iOS:
```
./libs/verify-ios-environment.sh
````
The Xcode project is located at `megazords/ios/MozillaAppServices.xcodeproj`.
## (Optional) Dev tool
You can also install and use `asdev` to help you run the above commands, you can do that by running the following:
```
cargo dev-install
```
This will allow your to run all the above commands without having to remember where the scripts are. You will be able to do
```
cargo verify_env
```
Which would run all three verification scrips. To check what other commands the dev tool supports, run `cargo asdev -h` or open the dialog using `cargo asdev`
> Note: The built Xcode project is located at `megazords/ios/MozillaAppServices.xcodeproj`.