Revision control
Copy as Markdown
# Building Ads-Client Locally for Android Testing
This guide covers how to build the ads-client component locally and test it with Firefox for Android (Fenix).
## Prerequisites
Before building ads-client for Android, ensure you have completed the initial Application Services setup:
1. Follow the [main building instructions](../../../docs/building.md) to set up your development environment
2. Verify you have the required tools installed (Rust, NDK, gyp, ninja, etc.)
3. Ensure you can successfully run `cargo test` in the application-services root
## Initial Setup
### 1. Install Required NDK Version
The ads-client component requires NDK version 29.0.14206865. (Keep updated with docs linked above) Install it using one of these methods:
**Via Android Studio:**
1. Open Android Studio
2. Navigate to Settings/Preferences → Appearance & Behavior → System Settings → Android SDK
3. Click the "SDK Tools" tab
4. Check "Show Package Details"
5. Expand "NDK (Side by side)"
6. Check version **29.0.14206865**
7. Click Apply
**Via command line:**
```bash
$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --install "ndk;29.0.14206865"
```
### 2. Configure local.properties
Create or edit `local.properties` in the application-services root directory:
```properties
sdk.dir=/path/to/Android/sdk
ndk.dir=/path/to/Android/sdk/ndk/29.0.14206865
# Optimize build speed by targeting specific architectures
# For Apple Silicon Mac with ARM64 emulator:
rust.targets=darwin-aarch64,arm64
# For Intel Mac with x86 emulator:
# rust.targets=darwin-x86-64,x86
```
Replace `/path/to/Android/sdk` with your actual Android SDK path (typically `~/Library/Android/sdk` on macOS or `~/Android/Sdk` on Linux).
### 3. Build NSS Libraries
NSS libraries must be built before compiling the ads-client component:
```bash
cd libs
./build-all.sh android
cd ..
```
Note: This script must be run from within the `libs/` directory.
## Building and Publishing Locally
### Manual Publishing
To build ads-client and publish it to your local Maven repository:
```bash
./gradlew publishToMavenLocal
```
This command will:
1. Compile the Rust code for ads-client
2. Generate UniFFI bindings (Kotlin interfaces)
3. Generate Glean metrics code
4. Compile the Android/Kotlin code
5. Package the AAR file
6. Publish to `~/.m2/repository`
The build typically takes 10-20 minutes for a full build, or 1-3 minutes for incremental builds.
### Verify Publication
Check that ads-client was published successfully:
```bash
ls ~/.m2/repository/org/mozilla/appservices/ads-client/
```
You should see a version directory (e.g., `149.0a1`) containing the published artifacts.
## Testing with Firefox for Android (Fenix)
### Configure Fenix for Auto-Publishing
The recommended approach is to use the auto-publishing workflow, which automatically builds and publishes application-services when you build Fenix.
#### 1. Configure local.properties
Edit `mozilla-central/local.properties` (in the root of your mozilla-central checkout) and add:
```properties
autoPublish.application-services.dir=/absolute/path/to/application-services
```
Replace `/absolute/path/to/application-services` with the full path to your application-services checkout.
If the file doesn't exist, create it. It should already contain your `sdk.dir` configuration. The complete file will look like:
```properties
sdk.dir=/path/to/Android/sdk
autoPublish.application-services.dir=/absolute/path/to/application-services
```
#### 2. Disable Gradle Configuration Cache
The auto-publishing workflow requires disabling the Gradle configuration cache. You must disable it in **both** gradle.properties files:
**File 1:** `mozilla-central/gradle.properties` (root)
Find and comment out:
```properties
# org.gradle.configuration-cache=true
```
**File 2:** `mozilla-central/mobile/android/fenix/gradle.properties`
Find and comment out:
```properties
# org.gradle.configuration-cache=true
```
Both files must have this setting disabled for auto-publishing to work correctly. Fenix has its own gradle.properties that can override the root configuration.
### Building Fenix in Android Studio
1. Open Android Studio
2. Select **File → Open**
3. Navigate to `mozilla-central/mobile/android/fenix`
4. Click **Open**
When Android Studio syncs the project, it will:
- Detect the auto-publish configuration
- Build application-services from your local checkout
- Publish to local Maven
- Configure Fenix to use the local artifacts
The initial sync may take 10-20 minutes as it builds all components.
### Running Fenix
After the build completes:
1. Select your target device or emulator in Android Studio
2. Click the Run button (green play icon) or press `Shift + F10`
3. Fenix will launch with your local ads-client changes
## Troubleshooting
### Build Failures
**Problem:** Gradle can't find NDK
- **Solution:** Verify `ndk.dir` in `local.properties` points to the correct NDK version (29.0.14206865)
**Problem:** UniFFI binding errors or "Unresolved reference" errors
- **Solution:** Clean the build and regenerate:
```bash
./gradlew clean
./gradlew publishToMavenLocal
```
**Problem:** Package naming conflicts
- **Solution:** Ensure the following are consistent:
- `uniffi.toml`: `package_name = "mozilla.appservices.adsclient"`
- `android/build.gradle`: `namespace 'org.mozilla.appservices.adsclient'`
- Directory structure: `android/src/main/java/mozilla/appservices/adsclient/`
### Auto-Publishing Not Working
If Fenix doesn't auto-publish application-services:
1. Verify `local.properties` uses an absolute path (not relative)
2. Confirm gradle configuration cache is disabled in `gradle.properties`
3. Try "Invalidate Caches and Restart" in Android Studio
4. Check the Android Studio
## Additional Resources
- [Main Application Services Building Guide](../../../docs/building.md)
- [Auto-Publishing Workflow Documentation](../../../docs/howtos/locally-published-components-in-fenix.md)
- [Android FAQs](../../../docs/android-faqs.md)
- [ads-client Usage Documentation](./usage.md)