diff --git a/.agents/skills/firebase-cpp-builder/SKILL.md b/.agents/skills/firebase-cpp-builder/SKILL.md new file mode 100644 index 0000000000..1103971536 --- /dev/null +++ b/.agents/skills/firebase-cpp-builder/SKILL.md @@ -0,0 +1,122 @@ +--- +name: firebase-cpp-builder +description: + Instructions and workflows for building the Firebase C++ SDK natively. Use + this skill when you need to compile the C++ SDK per-product (e.g., auth, + database) across different platforms (Desktop, iOS, Android). +--- + +# Building the Firebase C++ SDK + +This skill provides instructions on how to build the Firebase C++ SDK directly +from source, specifically tailored for building individual products (like +`firebase_auth`, `firebase_database`, etc.). + +## Prerequisites + +Before building, ensure that your Python environment is set up with all required dependencies, especially if you plan to use helper scripts: + +- **Python Dependencies**: Run `pip install -r scripts/gha/python_requirements.txt` to install required libraries (such as `attrs`, `absl-py`, etc.). + +## 1. Desktop Builds (Mac, Linux, Windows) + +The easiest way to build for Desktop is to use the Python helper script from the +repository root: + +```bash +python3 scripts/gha/build_desktop.py -a --build_dir +``` + +_(Plenty more options: run `python3 scripts/gha/build_desktop.py --help` for +info.)_ + +Alternatively, you can build manually with CMake. The build process will +automatically download necessary dependencies. + +```bash +mkdir desktop_build +cd desktop_build +cmake .. +cmake --build . --target firebase_ -j +``` + +_Example: `cmake --build . --target firebase_auth -j`_ + +## 2. iOS Builds + +For iOS, you can use the convenience script from the repository root: + +```bash +./build_scripts/ios/build.sh -b ios_build_dir -s . +``` + +_(Run `./build_scripts/ios/build.sh -h` for more options.)_ + +Alternatively, you can use CMake's native Xcode generator manually. Ensure you +have CocoaPods installed if building products that depend on iOS SDK Pods. + +```bash +mkdir ios_build +cd ios_build +cmake .. -G Xcode -DCMAKE_SYSTEM_NAME=iOS +cmake --build . --target firebase_ -j +``` + +Alternatively, you can build XCFrameworks using the helper script: + +```bash +python3 scripts/gha/build_ios_tvos.py -s . -b ios_tvos_build +``` + +## 3. Android Builds + +For Android, use the convenience script from the repository root: + +```bash +./build_scripts/android/build.sh android_build_dir . +``` + +_(You can also specify an STL variant with the 3rd parameter. Run the script +without any parameters to see the usage.)_ + +Alternatively, when building the Firebase C++ SDK manually for Android, the +repository uses a Gradle wrapper where each product has its own subproject. + +To build a specific product's AARs, run the gradle build task for that module: + +```bash +./gradlew ::build +``` + +_Example: `./gradlew :auth:build` or `./gradlew :database:build`_ + +Note that as part of the build process, each library generates a ProGuard file +in its build directory (e.g., `/build/.pro`). + +## CMake Target Naming Convention + +When using CMake directly (for Desktop or iOS/tvOS), the targets are +consistently named `firebase_`. + +Common targets include: + +- `firebase_app` +- `firebase_analytics` +- `firebase_auth` +- `firebase_database` +- `firebase_firestore` +- `firebase_functions` +- `firebase_messaging` +- `firebase_remote_config` +- `firebase_storage` + +## Product Naming Disambiguation (`firebase_auth` vs `auth`) + +Different build tools use different naming conventions for products in this repository: + +- **CMake Targets (Desktop/iOS)**: Typically prefixed with `firebase_` (e.g., `firebase_auth`). +- **Gradle Subprojects (Android)**: Typically use the raw module name (e.g., `:auth:build`). +- **Python Scripts** (e.g., `build_desktop.py`, `build_testapps.py`): Typically use the raw module name (e.g., `--t auth`). + +> [!TIP] +> If you are unsure about the exact product name or supported flags, run Python scripts with `--help` (e.g., `build_desktop.py --help`). For shell scripts, run without parameters (Android) or with `-h` (iOS) to see usage. diff --git a/.agents/skills/firebase-cpp-commenting-standards/SKILL.md b/.agents/skills/firebase-cpp-commenting-standards/SKILL.md new file mode 100644 index 0000000000..a65ba2d02f --- /dev/null +++ b/.agents/skills/firebase-cpp-commenting-standards/SKILL.md @@ -0,0 +1,78 @@ +# Firebase C++ Commenting Standards + +Guidelines for writing Doxygen documentation for C++ and Objective-C public APIs in the Firebase C++ SDK. + +## Overview +All public-facing methods, classes, and properties should be documented using Doxygen-style triple-slash `///` or block comments `/** ... */`. + +## C++ Standards + +### 1. General Format +Use `///` for single-line or multi-line brief comments. +Use `@brief` to explicitly define the summary. + +```cpp +/// @brief A brief description of the class or function. +``` + +### 2. Classes and Structs +Classes should have a summary of their purpose. Use `@see` for related links. + +```cpp +/// @brief Options that control the creation of a Firebase App. +/// @if cpp_examples +/// @see firebase::App +/// @endif +class AppOptions { ... }; +``` + +### 3. Methods and Functions +Always document parameters using `@param[in]` / `@param[out]` and return values using `@return` or `@returns`. + +```cpp +/// @brief Load default options from the resource file. +/// +/// @param options Options to populate from a resource file. +/// +/// @return An instance containing the loaded options if successful. +static AppOptions* LoadDefault(AppOptions* options); +``` + +### 4. Conditional Documentation (SWIG/Unity) +For Unity/C# bindings, use `` tags and `@if swig_examples`. These are parsed by the SWIG commenting pipeline and ignored by the standard C++ Doxyfile. + +```cpp +/// @if cpp_examples +/// To create a firebase::App object, the Firebase application identifier +/// and API key should be set using set_app_id() and set_api_key() +/// respectively. +/// @endif +/// +/// @if swig_examples +/// To create a FirebaseApp object, the Firebase application identifier +/// and API key should be set using AppId and ApiKey respectively. +/// @endif +/// +``` + +--- + +## Objective-C and iOS/tvOS Standards + +Objective-C wrappers should also follow standard Doxygen conventions, especially if they are used to bridge to C++. + +### 1. Class Properties + +```objc +/// @brief The App ID of the Firebase App. +@property(nonatomic, readonly) NSString *appID; +``` + +--- + +## Checklist +- [ ] Are you using `///` for public API comments? +- [ ] Do you have a `@brief` for the method? +- [ ] Are all parameters documented with `@param`? +- [ ] Is the return value documented with `@return`? +- [ ] Are you using `` tags if the documentation needs to differ for Unity/C#? diff --git a/.agents/skills/firebase-cpp-formatter/SKILL.md b/.agents/skills/firebase-cpp-formatter/SKILL.md new file mode 100644 index 0000000000..6b5cc6bf8f --- /dev/null +++ b/.agents/skills/firebase-cpp-formatter/SKILL.md @@ -0,0 +1,68 @@ +--- +name: firebase-cpp-formatter +description: + Formatting workflow for C++ and Objective-C code in the Firebase C++ SDK. Use + when modifying source code and ensuring compliance with the repository's + clang-format rules. +--- + +# Code Formatting for Firebase C++ SDK + +This skill provides instructions on how to properly format C++ and Objective-C +code before creating a pull request or committing changes in the +`firebase-cpp-sdk` repository. The primary tool is `scripts/format_code.py`. + +## Prerequisites + +Before running the formatting script, ensure that your Python environment is set up with all required dependencies: + +- **Python Dependencies**: Run `pip install -r scripts/gha/python_requirements.txt` to install the required libraries (such as `attrs`, `absl-py`, etc.). + +## Workflows + +### 1. Formatting Specific Changed Files (Git Diff) + +If you have made code changes locally in a git branch, the easiest way to ensure +all your changes are formatted properly is to use the `-git_diff` argument. This +automatically detects which files have changed compared to `main` and formats +them. + +```bash +python3 scripts/format_code.py -git_diff +``` + +_Tip:_ You can also append `-verbose` for extensive logging about formatting +changes. + +### 2. Formatting a Specific Directory + +If you are working on a feature within a particular Firebase SDK (e.g., +`database`), you can recursively format that entire directory: + +```bash +python3 scripts/format_code.py -d database -r +``` + +To target multiple directories (e.g., both `database` and `app`): + +```bash +python3 scripts/format_code.py -d database -d app -r +``` + +### 3. Formatting Specific Files + +If you are pressed for time and only want to format specific files rather than +analyzing whole directories, use the `-f` flag: + +```bash +python3 scripts/format_code.py -f path/to/file1.cc -f path/to/file2.h +``` + +### 4. Dry Run (Check without Formatting) + +If you only want to detect the number of files that _need_ formatting without +actually modifying them, append the `--noformat_file` flag: + +```bash +python3 scripts/format_code.py -git_diff --noformat_file +``` diff --git a/.agents/skills/firebase-cpp-test-runner/SKILL.md b/.agents/skills/firebase-cpp-test-runner/SKILL.md new file mode 100644 index 0000000000..4b8e45aedc --- /dev/null +++ b/.agents/skills/firebase-cpp-test-runner/SKILL.md @@ -0,0 +1,97 @@ +--- +name: firebase-cpp-test-runner +description: + Workflows for locally building and running test apps for the Firebase C++ SDK + across Android, iOS, and Desktop. Use when validating new features or bug + fixes. +--- + +# Test Runner for Firebase C++ SDK + +This skill outlines the workflows and convenience scripts required to locally +build and run tests for the Firebase C++ SDK across Android, iOS, and Desktop +platforms. + +## Prerequisites + +Before building integration tests, ensure that your Python environment is set up with all required dependencies, and that you have the private Google Services configuration files present: + +- **Python Dependencies**: Run `pip install -r scripts/gha/python_requirements.txt` to install the required libraries (such as `attrs`, `absl-py`, etc.). +- **Android and Desktop Config Files**: `google-services.json` must be present in `/integration_test/`. +- **iOS Config Files**: `GoogleService-Info.plist` must be present in `/integration_test/`. + +## Using the `build_testapps.py` Helper Script + +The easiest and standard way to build integration tests locally across platforms +is to use the `build_testapps.py` script. + +### Building for Android + +To build an Android integration test application for specific products (e.g., +`auth` and `database`), run the following command from the repository root: + +```bash +python3 scripts/gha/build_testapps.py --p Android --t auth,database -output_directory ./android_testapp +``` + +This builds an Android app at +`build/outputs/apk/debug/integration_test-debug.apk` within the product's +module, which you can run on an Android emulator or physical device. Use +`./gradlew clean` to clean up the build artifacts. + +### Building for iOS + +To build iOS testapps for a specific product (e.g., `auth`): + +```bash +python3 scripts/gha/build_testapps.py --t auth --p iOS +``` + +_Note:_ You must have a Mac environment with Xcode and Cocoapods to build iOS +tests successfully. + +### Building for Desktop + +To build a desktop integration test application for a specific product (e.g., `auth`), run the following command from the repository root: + +```bash +python3 scripts/gha/build_testapps.py --p Desktop --t auth +``` + +You can specify the architecture with the `--arch` flag (e.g., `--arch x64`, `--arch x86`, or `--arch arm64`). + +## Manual Integration Test Builds (Alternative) + +If you need more control, you can build tests manually from within the +`integration_test/` (or `integration_test_internal/`) directories. + +### Android Manual Build + +```bash +cd /integration_test +cp path_to_google_services_files/google-services.json . +export FIREBASE_CPP_SDK_DIR=path_to_cpp_git_repo +./gradlew build +``` + +### Desktop Manual Build + +```bash +cd /integration_test +cp path_to_google_services_files/google-services.json . +mkdir desktop_build && cd desktop_build +cmake .. -DFIREBASE_CPP_SDK_DIR=/path/to/firebase_cpp_sdk && cmake --build . -j +``` + +Once the build is finished, run the generated `integration_test` binary. + +## Product Naming Disambiguation (`firebase_auth` vs `auth`) + +Different build tools use different naming conventions for products in this repository: + +- **CMake Targets (Desktop/iOS)**: Typically prefixed with `firebase_` (e.g., `firebase_auth`). +- **Gradle Subprojects (Android)**: Typically use the raw module name (e.g., `:auth:build`). +- **Python Scripts** (e.g., `build_testapps.py`): Typically use the raw module name (e.g., `--t auth`). + +> [!TIP] +> If you are unsure about the exact product name or supported flags, run Python scripts with `--help` (e.g., `build_testapps.py --help`). For shell scripts, run without parameters (Android) or with `-h` (iOS) to see usage.