|
| 1 | +# Agents |
| 2 | + |
| 3 | +This guide provides essential information for working within the `firebase-android-sdk` repository. |
| 4 | + |
| 5 | +## Environment Setup |
| 6 | + |
| 7 | +To work with this repository, the Android SDK must be installed. Use the `sdkmanager` command-line |
| 8 | +tool for this purpose. |
| 9 | + |
| 10 | +1. **Install Android SDK Command-Line Tools**: |
| 11 | + |
| 12 | + - If not already installed, download the command-line tools from the |
| 13 | + [Android Studio page](https://developer.android.com/studio#command-line-tools-only). |
| 14 | + - Create a directory for the Android SDK, e.g., `android_sdk`. |
| 15 | + - Unzip the downloaded package. This will create a `cmdline-tools` directory. Move this |
| 16 | + directory to `android_sdk/cmdline-tools/latest`. |
| 17 | + - The final structure should be `android_sdk/cmdline-tools/latest/`. |
| 18 | + |
| 19 | +2. **Install required SDK packages**: |
| 20 | + |
| 21 | + - Use `sdkmanager` to install the necessary platforms, build tools, and other packages. For |
| 22 | + example: |
| 23 | + |
| 24 | + ```bash |
| 25 | + # List all available packages |
| 26 | + sdkmanager --list |
| 27 | + |
| 28 | + # Install platform tools and the SDK for API level 33 |
| 29 | + sdkmanager "platform-tools" "platforms;android-33" |
| 30 | + |
| 31 | + # Accept all licenses |
| 32 | + yes | sdkmanager --licenses |
| 33 | + ``` |
| 34 | + |
| 35 | + - Refer to the specific requirements of the project to determine which packages to install. |
| 36 | + |
| 37 | +3. **Configure for integration tests**: |
| 38 | + |
| 39 | + - To run integration tests, a `google-services.json` file is required. |
| 40 | + - Place this file in the root of the repository. |
| 41 | + |
| 42 | +4. **Install NDK for specific projects**: |
| 43 | + - Some projects, like `firebase-crashlytics-ndk`, require a specific version of the Android NDK. |
| 44 | + You can install it using `sdkmanager`. For example, to install NDK version 21.4.7075529, you |
| 45 | + would run `sdkmanager "ndk;21.4.7075529"`. Always refer to the project's `README.md` for the |
| 46 | + exact version required. |
| 47 | +
|
| 48 | +--- |
| 49 | +
|
| 50 | +## Testing |
| 51 | +
|
| 52 | +This repository uses two main types of tests: |
| 53 | +
|
| 54 | +1. **Unit Tests**: |
| 55 | +
|
| 56 | + - These tests run on the local JVM. |
| 57 | + - To execute unit tests for a specific project, run: |
| 58 | + ```bash |
| 59 | + ./gradlew :<firebase-project>:check |
| 60 | + ``` |
| 61 | +
|
| 62 | +2. **Integration Tests**: |
| 63 | + - These tests run on a hardware device or emulator. |
| 64 | + - Ensure a `google-services.json` file is present in the repository root. |
| 65 | + - To execute integration tests for a specific project, run: |
| 66 | + ```bash |
| 67 | + ./gradlew :<firebase-project>:connectedCheck |
| 68 | + ``` |
| 69 | +
|
| 70 | +--- |
| 71 | +
|
| 72 | +## API Surface |
| 73 | +
|
| 74 | +The public API of the Firebase SDKs is managed using a set of annotations: |
| 75 | +
|
| 76 | +- `@PublicApi`: Marks APIs that are intended for public consumption by developers. |
| 77 | +- `@KeepForSdk`: Marks APIs that are intended for use by other Firebase SDKs. These APIs will |
| 78 | + trigger a linter error if used by developers outside of a Firebase package. |
| 79 | +- `@Keep`: Marks APIs that need to be preserved at runtime, usually due to reflection. This |
| 80 | + annotation should be used sparingly as it prevents Proguard from removing or renaming the code. |
| 81 | +
|
| 82 | +--- |
| 83 | +
|
| 84 | +## Common Patterns |
| 85 | +
|
| 86 | +This repository uses a combination of dependency injection frameworks: |
| 87 | +
|
| 88 | +- **`firebase-components`**: This is a custom dependency injection framework used for discovery and |
| 89 | + dependency injection between different Firebase SDKs. It allows SDKs to register their components |
| 90 | + and declare dependencies on other components. The initialization is managed by `FirebaseApp`. |
| 91 | +
|
| 92 | +- **Dagger**: Dagger is used for internal dependency injection within individual SDKs. This helps to |
| 93 | + create more testable and maintainable code. Dagger components are typically instantiated within |
| 94 | + the `ComponentRegistrar` of an SDK, which allows for the injection of dependencies from |
| 95 | + `firebase-components` into the Dagger graph. |
| 96 | +
|
| 97 | +--- |
| 98 | +
|
| 99 | +## Iteration Loop |
| 100 | +
|
| 101 | +After you make a change, here's the flow you should follow: |
| 102 | + |
| 103 | +- Format the code using `spotless`. It can be run with: |
| 104 | + ```bash |
| 105 | + ./gradlew :<firebase-project>:spotlessApply |
| 106 | + ``` |
| 107 | +- Run unit tests: |
| 108 | + ```bash |
| 109 | + ./gradlew :<firebase-project>:check |
| 110 | + ``` |
| 111 | +- If necessary, run integration tests based on the instructions above. |
| 112 | + |
| 113 | +--- |
| 114 | + |
| 115 | +## External Dependencies |
| 116 | + |
| 117 | +--- |
| 118 | + |
| 119 | +Do not add, under any circunstance, any new dependency to a SDK that does not already exists in the |
| 120 | +`gradle/libs.versions.toml`, and even then, only do it if cxexplicitly asked to do so. The Firebase |
| 121 | +SDKs are designed to be lightweight, and adding new dependencies can increase the size of the final |
| 122 | +artifacts. |
| 123 | + |
| 124 | +--- |
| 125 | + |
| 126 | +## Updating this Guide |
| 127 | + |
| 128 | +If new patterns or conventions are discovered, update this guide to ensure it remains a useful |
| 129 | +resource. |
0 commit comments