You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: Jules.md
+43-17Lines changed: 43 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,6 +3,7 @@
3
3
This guide provides essential information for working within the `firebase-android-sdk` repository.
4
4
5
5
## Table of Contents
6
+
6
7
-[Environment Setup](#environment-setup)
7
8
-[Testing](#testing)
8
9
-[API Surface](#api-surface)
@@ -15,16 +16,23 @@ This guide provides essential information for working within the `firebase-andro
15
16
16
17
## Environment Setup
17
18
18
-
To work with this repository, the Android SDK must be installed. Use the `sdkmanager` command-line tool for this purpose.
19
+
To work with this repository, the Android SDK must be installed. Use the `sdkmanager` command-line
20
+
tool for this purpose.
19
21
20
22
1.**Install Android SDK Command-Line Tools**:
21
-
- If not already installed, download the command-line tools from the [Android Studio page](https://developer.android.com/studio#command-line-tools-only).
23
+
24
+
- If not already installed, download the command-line tools from the
25
+
[Android Studio page](https://developer.android.com/studio#command-line-tools-only).
22
26
- Create a directory for the Android SDK, e.g., `android_sdk`.
23
-
- Unzip the downloaded package. This will create a `cmdline-tools` directory. Move this directory to `android_sdk/cmdline-tools/latest`.
27
+
- Unzip the downloaded package. This will create a `cmdline-tools` directory. Move this
28
+
directory to `android_sdk/cmdline-tools/latest`.
24
29
- The final structure should be `android_sdk/cmdline-tools/latest/`.
25
30
26
31
2.**Install required SDK packages**:
27
-
- Use `sdkmanager` to install the necessary platforms, build tools, and other packages. For example:
32
+
33
+
- Use `sdkmanager` to install the necessary platforms, build tools, and other packages. For
34
+
example:
35
+
28
36
```bash
29
37
# List all available packages
30
38
sdkmanager --list
@@ -35,14 +43,19 @@ To work with this repository, the Android SDK must be installed. Use the `sdkman
35
43
# Accept all licenses
36
44
sdkmanager --licenses
37
45
```
46
+
38
47
- Refer to the specific requirements of the project to determine which packages to install.
39
48
40
49
3. **Configure for integration tests**:
50
+
41
51
- To run integration tests, a `google-services.json` file is required.
42
52
- Place this file in the root of the repository.
43
53
44
54
4. **Install NDK for specific projects**:
45
-
- Some projects, like `firebase-crashlytics-ndk`, require a specific version of the Android NDK. You can install it using `sdkmanager`. For example, to install NDK version 21.4.7075529, you would run `sdkmanager "ndk;21.4.7075529"`. Always refer to the project's `README.md` for the exact version required.
55
+
- Some projects, like `firebase-crashlytics-ndk`, require a specific version of the Android NDK.
56
+
You can install it using `sdkmanager`. For example, to install NDK version 21.4.7075529, you
57
+
would run `sdkmanager "ndk;21.4.7075529"`. Always refer to the project's `README.md` for the
58
+
exact version required.
46
59
47
60
---
48
61
@@ -51,6 +64,7 @@ To work with this repository, the Android SDK must be installed. Use the `sdkman
51
64
This repository uses two main types of tests:
52
65
53
66
1. **Unit Tests**:
67
+
54
68
- These tests run on the local JVM.
55
69
- To execute unit tests for a specific project, run:
56
70
```bash
@@ -71,38 +85,50 @@ This repository uses two main types of tests:
71
85
72
86
The public API of the Firebase SDKs is managed using a set of annotations:
73
87
74
-
- `@PublicApi`: Marks APIs that are intended for public consumption by developers.
75
-
- `@KeepForSdk`: Marks APIs that are intended for use by other Firebase SDKs. These APIs will trigger a linter error if used by developers outside of a Firebase package.
76
-
- `@Keep`: Marks APIs that need to be preserved at runtime, usually due to reflection. This annotation should be used sparingly as it prevents Proguard from removing or renaming the code.
88
+
- `@PublicApi`: Marks APIs that are intended for public consumption by developers.
89
+
- `@KeepForSdk`: Marks APIs that are intended for use by other Firebase SDKs. These APIs will
90
+
trigger a linter error if used by developers outside of a Firebase package.
91
+
- `@Keep`: Marks APIs that need to be preserved at runtime, usually due to reflection. This
92
+
annotation should be used sparingly as it prevents Proguard from removing or renaming the code.
77
93
78
94
---
79
95
80
96
## Best Practices
81
97
82
-
- **Code Formatting**: The repository uses `spotless` for code formatting. To format the code in a specific project, run:
83
-
```bash
84
-
./gradlew :<firebase-project>:spotlessApply
85
-
```
86
-
- **Dependency Management**: Dependencies are managed using Gradle. Be mindful of the impact of new dependencies on the size of the SDKs.
98
+
- **Code Formatting**: The repository uses `spotless` for code formatting. To format the code in a
99
+
specific project, run:
100
+
```bash
101
+
./gradlew :<firebase-project>:spotlessApply
102
+
```
103
+
- **Dependency Management**: Dependencies are managed using Gradle. Be mindful of the impact of new
104
+
dependencies on the size of the SDKs.
87
105
88
106
---
89
107
90
108
## Common Patterns
91
109
92
110
This repository uses a combination of dependency injection frameworks:
93
111
94
-
- **`firebase-components`**: This is a custom dependency injection framework used for discovery and dependency injection between different Firebase SDKs. It allows SDKs to register their components and declare dependencies on other components. The initialization is managed by `FirebaseApp`.
112
+
- **`firebase-components`**: This is a custom dependency injection framework used for discovery and
113
+
dependency injection between different Firebase SDKs. It allows SDKs to register their components
114
+
and declare dependencies on other components. The initialization is managed by `FirebaseApp`.
95
115
96
-
- **Dagger**: Dagger is used for internal dependency injection within individual SDKs. This helps to create more testable and maintainable code. Dagger components are typically instantiated within the `ComponentRegistrar` of an SDK, which allows for the injection of dependencies from `firebase-components` into the Dagger graph.
116
+
- **Dagger**: Dagger is used for internal dependency injection within individual SDKs. This helps to
117
+
create more testable and maintainable code. Dagger components are typically instantiated within
118
+
the `ComponentRegistrar` of an SDK, which allows for the injection of dependencies from
119
+
`firebase-components` into the Dagger graph.
97
120
98
121
---
99
122
100
123
## External Dependencies
101
124
102
-
Do not add new external dependencies to the project unless explicitly asked to do so. The Firebase SDKs are designed to be lightweight, and adding new dependencies can increase the size of the final artifacts.
125
+
Do not add new external dependencies to the project unless explicitly asked to do so. The Firebase
126
+
SDKs are designed to be lightweight, and adding new dependencies can increase the size of the final
127
+
artifacts.
103
128
104
129
---
105
130
106
131
## Updating this Guide
107
132
108
-
If new patterns or conventions are discovered, update this guide to ensure it remains a useful resource.
133
+
If new patterns or conventions are discovered, update this guide to ensure it remains a useful
0 commit comments