22
33This guide provides essential information for working within the ` firebase-android-sdk ` repository.
44
5+ ## Project Overview
6+
7+ This repository contains the source code for the Firebase Android SDKs. It is a large, multi-module
8+ Gradle project. The project is written in a mix of Java and Kotlin.
9+
10+ The project is structured as a collection of libraries, each representing a Firebase product or a
11+ shared component. These libraries are published as Maven artifacts to Google's Maven Repository.
12+
13+ ## Project Structure
14+
15+ The ` subprojects.cfg ` file lists all the subprojects in this repository. Each line in this file
16+ follows the format ` <project-path> # <project-type> ` , where ` project-type ` can be one of the
17+ following:
18+
19+ - ` sdk ` : A public-facing SDK that is published.
20+ - ` test ` : A test application or a test-only module.
21+ - ` util ` : A utility module that is not part of the public API.
22+ - ` directory ` : A directory containing other subprojects.
23+
24+ This file is useful for understanding the role of each subproject in the repository.
25+
526## Environment Setup
627
728To work with this repository, the Android SDK must be installed. Use the ` sdkmanager ` command-line
@@ -45,31 +66,78 @@ tool for this purpose.
4566 would run ` sdkmanager " ndk;21.4.7075529" ` ' s `README.md` for the
4667 exact version required.
4768
48- ---
69+ ## Building and Running
4970
50- ## Testing
71+ The project is built using Gradle. The `gradlew` script is provided in the root directory.
5172
52- This repository uses two main types of tests:
73+ ### Building
5374
54- 1. **Unit Tests** :
75+ To build the entire project, you can run the following command :
5576
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- ```
77+ ```bash
78+ ./gradlew build
79+ ```
6180
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- ```
81+ To build a specific project, you can run:
82+
83+ ```bash
84+ ./gradlew :<firebase-project>:build
85+ ```
86+
87+ ### Running Tests
88+
89+ The project has three types of tests: unit tests, integration tests, and smoke tests.
90+
91+ #### Unit Tests
92+
93+ Unit tests run on the local JVM. They can be executed with the following command:
94+
95+ ```bash
96+ ./gradlew :<firebase-project>:check
97+ ```
98+
99+ #### Integration Tests
100+
101+ Integration tests run on a hardware device or emulator. Before running integration tests, you need
102+ to add a `google-services.json` file to the root of the project.
103+
104+ To run integration tests on a local emulator, use the following command:
105+
106+ ```bash
107+ ./gradlew :<firebase-project>:connectedCheck
108+ ```
109+
110+ To run integration tests on Firebase Test Lab, use the following command:
111+
112+ ```bash
113+ ./gradlew :<firebase-project>:deviceCheck
114+ ```
115+
116+ ### Publishing
117+
118+ To publish a project locally, you can use the following command:
119+
120+ ```bash
121+ ./gradlew -PprojectsToPublish="<firebase-project>" publishReleasingLibrariesToMavenLocal
122+ ```
69123
70- ---
124+ ## Development Conventions
71125
72- ## API Surface
126+ ### Code Formatting
127+
128+ The project uses Spotless for code formatting. To format the code, run the following command:
129+
130+ ```bash
131+ ./gradlew spotlessApply
132+ ```
133+
134+ To format a specific project, run:
135+
136+ ```bash
137+ ./gradlew :<firebase-project>:spotlessApply
138+ ```
139+
140+ ### API Surface
73141
74142The public API of the Firebase SDKs is managed using a set of annotations:
75143
@@ -79,9 +147,7 @@ The public API of the Firebase SDKs is managed using a set of annotations:
79147- `@Keep`: Marks APIs that need to be preserved at runtime, usually due to reflection. This
80148 annotation should be used sparingly as it prevents Proguard from removing or renaming the code.
81149
82- ---
83-
84- ## Common Patterns
150+ ### Common Patterns
85151
86152This repository uses a combination of dependency injection frameworks:
87153
@@ -94,7 +160,22 @@ This repository uses a combination of dependency injection frameworks:
94160 the `ComponentRegistrar` of an SDK, which allows for the injection of dependencies from
95161 `firebase-components` into the Dagger graph.
96162
97- ---
163+ ### Proguarding
164+
165+ The project supports Proguarding. Proguard rules are defined in `proguard.txt` files within each
166+ project.
167+
168+ ## External Dependencies
169+
170+ Do not add, under any circunstance, any new dependency to a SDK that does not already exists in the
171+ `gradle/libs.versions.toml`, and even then, only do it if cxexplicitly asked to do so. The Firebase
172+ SDKs are designed to be lightweight, and adding new dependencies can increase the size of the final
173+ artifacts.
174+
175+ ## Contributing
176+
177+ Contributions are welcome. Please read the [contribution guidelines](/CONTRIBUTING.md) to get
178+ started.
98179
99180## Iteration Loop
100181
@@ -110,19 +191,6 @@ After you make a change, here's the flow you should follow:
110191 ` ` `
111192- If necessary, run integration tests based on the instructions above.
112193
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` 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-
126194# # Updating this Guide
127195
128196If new patterns or conventions are discovered, update this guide to ensure it remains a useful
0 commit comments