Skip to content

Commit 8882fce

Browse files
AustinBenoitAustinBenoit
authored
Add in some generic skills for cpp (#1845)
* Add in some generic skills for cpp * Add in clarity to skill for product naming,. * Clean up skills * Fix flag for formating
1 parent fb14082 commit 8882fce

4 files changed

Lines changed: 365 additions & 0 deletions

File tree

‎.agents/skills/firebase-cpp-builder/SKILL.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
name: firebase-cpp-builder
3+
description:
4+
Instructions and workflows for building the Firebase C++ SDK natively. Use
5+
this skill when you need to compile the C++ SDK per-product (e.g., auth,
6+
database) across different platforms (Desktop, iOS, Android).
7+
---
8+
9+
# Building the Firebase C++ SDK
10+
11+
This skill provides instructions on how to build the Firebase C++ SDK directly
12+
from source, specifically tailored for building individual products (like
13+
`firebase_auth`, `firebase_database`, etc.).
14+
15+
## Prerequisites
16+
17+
Before building, ensure that your Python environment is set up with all required dependencies, especially if you plan to use helper scripts:
18+
19+
- **Python Dependencies**: Run `pip install -r scripts/gha/python_requirements.txt` to install required libraries (such as `attrs`, `absl-py`, etc.).
20+
21+
## 1. Desktop Builds (Mac, Linux, Windows)
22+
23+
The easiest way to build for Desktop is to use the Python helper script from the
24+
repository root:
25+
26+
```bash
27+
python3 scripts/gha/build_desktop.py -a <arch> --build_dir <dir>
28+
```
29+
30+
_(Plenty more options: run `python3 scripts/gha/build_desktop.py --help` for
31+
info.)_
32+
33+
Alternatively, you can build manually with CMake. The build process will
34+
automatically download necessary dependencies.
35+
36+
```bash
37+
mkdir desktop_build
38+
cd desktop_build
39+
cmake ..
40+
cmake --build . --target firebase_<product> -j
41+
```
42+
43+
_Example: `cmake --build . --target firebase_auth -j`_
44+
45+
## 2. iOS Builds
46+
47+
For iOS, you can use the convenience script from the repository root:
48+
49+
```bash
50+
./build_scripts/ios/build.sh -b ios_build_dir -s .
51+
```
52+
53+
_(Run `./build_scripts/ios/build.sh -h` for more options.)_
54+
55+
Alternatively, you can use CMake's native Xcode generator manually. Ensure you
56+
have CocoaPods installed if building products that depend on iOS SDK Pods.
57+
58+
```bash
59+
mkdir ios_build
60+
cd ios_build
61+
cmake .. -G Xcode -DCMAKE_SYSTEM_NAME=iOS
62+
cmake --build . --target firebase_<product> -j
63+
```
64+
65+
Alternatively, you can build XCFrameworks using the helper script:
66+
67+
```bash
68+
python3 scripts/gha/build_ios_tvos.py -s . -b ios_tvos_build
69+
```
70+
71+
## 3. Android Builds
72+
73+
For Android, use the convenience script from the repository root:
74+
75+
```bash
76+
./build_scripts/android/build.sh android_build_dir .
77+
```
78+
79+
_(You can also specify an STL variant with the 3rd parameter. Run the script
80+
without any parameters to see the usage.)_
81+
82+
Alternatively, when building the Firebase C++ SDK manually for Android, the
83+
repository uses a Gradle wrapper where each product has its own subproject.
84+
85+
To build a specific product's AARs, run the gradle build task for that module:
86+
87+
```bash
88+
./gradlew :<product>:build
89+
```
90+
91+
_Example: `./gradlew :auth:build` or `./gradlew :database:build`_
92+
93+
Note that as part of the build process, each library generates a ProGuard file
94+
in its build directory (e.g., `<product>/build/<product>.pro`).
95+
96+
## CMake Target Naming Convention
97+
98+
When using CMake directly (for Desktop or iOS/tvOS), the targets are
99+
consistently named `firebase_<product>`.
100+
101+
Common targets include:
102+
103+
- `firebase_app`
104+
- `firebase_analytics`
105+
- `firebase_auth`
106+
- `firebase_database`
107+
- `firebase_firestore`
108+
- `firebase_functions`
109+
- `firebase_messaging`
110+
- `firebase_remote_config`
111+
- `firebase_storage`
112+
113+
## Product Naming Disambiguation (`firebase_auth` vs `auth`)
114+
115+
Different build tools use different naming conventions for products in this repository:
116+
117+
- **CMake Targets (Desktop/iOS)**: Typically prefixed with `firebase_` (e.g., `firebase_auth`).
118+
- **Gradle Subprojects (Android)**: Typically use the raw module name (e.g., `:auth:build`).
119+
- **Python Scripts** (e.g., `build_desktop.py`, `build_testapps.py`): Typically use the raw module name (e.g., `--t auth`).
120+
121+
> [!TIP]
122+
> 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.

‎.agents/skills/firebase-cpp-commenting-standards/SKILL.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Firebase C++ Commenting Standards
2+
3+
Guidelines for writing Doxygen documentation for C++ and Objective-C public APIs in the Firebase C++ SDK.
4+
5+
## Overview
6+
All public-facing methods, classes, and properties should be documented using Doxygen-style triple-slash `///` or block comments `/** ... */`.
7+
8+
## C++ Standards
9+
10+
### 1. General Format
11+
Use `///` for single-line or multi-line brief comments.
12+
Use `@brief` to explicitly define the summary.
13+
14+
```cpp
15+
/// @brief A brief description of the class or function.
16+
```
17+
18+
### 2. Classes and Structs
19+
Classes should have a summary of their purpose. Use `@see` for related links.
20+
21+
```cpp
22+
/// @brief Options that control the creation of a Firebase App.
23+
/// @if cpp_examples
24+
/// @see firebase::App
25+
/// @endif
26+
class AppOptions { ... };
27+
```
28+
29+
### 3. Methods and Functions
30+
Always document parameters using `@param[in]` / `@param[out]` and return values using `@return` or `@returns`.
31+
32+
```cpp
33+
/// @brief Load default options from the resource file.
34+
///
35+
/// @param options Options to populate from a resource file.
36+
///
37+
/// @return An instance containing the loaded options if successful.
38+
static AppOptions* LoadDefault(AppOptions* options);
39+
```
40+
41+
### 4. Conditional Documentation (SWIG/Unity)
42+
For Unity/C# bindings, use `<SWIG>` tags and `@if swig_examples`. These are parsed by the SWIG commenting pipeline and ignored by the standard C++ Doxyfile.
43+
44+
```cpp
45+
/// @if cpp_examples
46+
/// To create a firebase::App object, the Firebase application identifier
47+
/// and API key should be set using set_app_id() and set_api_key()
48+
/// respectively.
49+
/// @endif
50+
/// <SWIG>
51+
/// @if swig_examples
52+
/// To create a FirebaseApp object, the Firebase application identifier
53+
/// and API key should be set using AppId and ApiKey respectively.
54+
/// @endif
55+
/// </SWIG>
56+
```
57+
58+
---
59+
60+
## Objective-C and iOS/tvOS Standards
61+
62+
Objective-C wrappers should also follow standard Doxygen conventions, especially if they are used to bridge to C++.
63+
64+
### 1. Class Properties
65+
66+
```objc
67+
/// @brief The App ID of the Firebase App.
68+
@property(nonatomic, readonly) NSString *appID;
69+
```
70+
71+
---
72+
73+
## Checklist
74+
- [ ] Are you using `///` for public API comments?
75+
- [ ] Do you have a `@brief` for the method?
76+
- [ ] Are all parameters documented with `@param`?
77+
- [ ] Is the return value documented with `@return`?
78+
- [ ] Are you using `<SWIG>` tags if the documentation needs to differ for Unity/C#?

‎.agents/skills/firebase-cpp-formatter/SKILL.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
name: firebase-cpp-formatter
3+
description:
4+
Formatting workflow for C++ and Objective-C code in the Firebase C++ SDK. Use
5+
when modifying source code and ensuring compliance with the repository's
6+
clang-format rules.
7+
---
8+
9+
# Code Formatting for Firebase C++ SDK
10+
11+
This skill provides instructions on how to properly format C++ and Objective-C
12+
code before creating a pull request or committing changes in the
13+
`firebase-cpp-sdk` repository. The primary tool is `scripts/format_code.py`.
14+
15+
## Prerequisites
16+
17+
Before running the formatting script, ensure that your Python environment is set up with all required dependencies:
18+
19+
- **Python Dependencies**: Run `pip install -r scripts/gha/python_requirements.txt` to install the required libraries (such as `attrs`, `absl-py`, etc.).
20+
21+
## Workflows
22+
23+
### 1. Formatting Specific Changed Files (Git Diff)
24+
25+
If you have made code changes locally in a git branch, the easiest way to ensure
26+
all your changes are formatted properly is to use the `-git_diff` argument. This
27+
automatically detects which files have changed compared to `main` and formats
28+
them.
29+
30+
```bash
31+
python3 scripts/format_code.py -git_diff
32+
```
33+
34+
_Tip:_ You can also append `-verbose` for extensive logging about formatting
35+
changes.
36+
37+
### 2. Formatting a Specific Directory
38+
39+
If you are working on a feature within a particular Firebase SDK (e.g.,
40+
`database`), you can recursively format that entire directory:
41+
42+
```bash
43+
python3 scripts/format_code.py -d database -r
44+
```
45+
46+
To target multiple directories (e.g., both `database` and `app`):
47+
48+
```bash
49+
python3 scripts/format_code.py -d database -d app -r
50+
```
51+
52+
### 3. Formatting Specific Files
53+
54+
If you are pressed for time and only want to format specific files rather than
55+
analyzing whole directories, use the `-f` flag:
56+
57+
```bash
58+
python3 scripts/format_code.py -f path/to/file1.cc -f path/to/file2.h
59+
```
60+
61+
### 4. Dry Run (Check without Formatting)
62+
63+
If you only want to detect the number of files that _need_ formatting without
64+
actually modifying them, append the `--noformat_file` flag:
65+
66+
```bash
67+
python3 scripts/format_code.py -git_diff --noformat_file
68+
```

‎.agents/skills/firebase-cpp-test-runner/SKILL.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
name: firebase-cpp-test-runner
3+
description:
4+
Workflows for locally building and running test apps for the Firebase C++ SDK
5+
across Android, iOS, and Desktop. Use when validating new features or bug
6+
fixes.
7+
---
8+
9+
# Test Runner for Firebase C++ SDK
10+
11+
This skill outlines the workflows and convenience scripts required to locally
12+
build and run tests for the Firebase C++ SDK across Android, iOS, and Desktop
13+
platforms.
14+
15+
## Prerequisites
16+
17+
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:
18+
19+
- **Python Dependencies**: Run `pip install -r scripts/gha/python_requirements.txt` to install the required libraries (such as `attrs`, `absl-py`, etc.).
20+
- **Android and Desktop Config Files**: `google-services.json` must be present in `<product>/integration_test/`.
21+
- **iOS Config Files**: `GoogleService-Info.plist` must be present in `<product>/integration_test/`.
22+
23+
## Using the `build_testapps.py` Helper Script
24+
25+
The easiest and standard way to build integration tests locally across platforms
26+
is to use the `build_testapps.py` script.
27+
28+
### Building for Android
29+
30+
To build an Android integration test application for specific products (e.g.,
31+
`auth` and `database`), run the following command from the repository root:
32+
33+
```bash
34+
python3 scripts/gha/build_testapps.py --p Android --t auth,database -output_directory ./android_testapp
35+
```
36+
37+
This builds an Android app at
38+
`build/outputs/apk/debug/integration_test-debug.apk` within the product's
39+
module, which you can run on an Android emulator or physical device. Use
40+
`./gradlew clean` to clean up the build artifacts.
41+
42+
### Building for iOS
43+
44+
To build iOS testapps for a specific product (e.g., `auth`):
45+
46+
```bash
47+
python3 scripts/gha/build_testapps.py --t auth --p iOS
48+
```
49+
50+
_Note:_ You must have a Mac environment with Xcode and Cocoapods to build iOS
51+
tests successfully.
52+
53+
### Building for Desktop
54+
55+
To build a desktop integration test application for a specific product (e.g., `auth`), run the following command from the repository root:
56+
57+
```bash
58+
python3 scripts/gha/build_testapps.py --p Desktop --t auth
59+
```
60+
61+
You can specify the architecture with the `--arch` flag (e.g., `--arch x64`, `--arch x86`, or `--arch arm64`).
62+
63+
## Manual Integration Test Builds (Alternative)
64+
65+
If you need more control, you can build tests manually from within the
66+
`integration_test/` (or `integration_test_internal/`) directories.
67+
68+
### Android Manual Build
69+
70+
```bash
71+
cd <product>/integration_test
72+
cp path_to_google_services_files/google-services.json .
73+
export FIREBASE_CPP_SDK_DIR=path_to_cpp_git_repo
74+
./gradlew build
75+
```
76+
77+
### Desktop Manual Build
78+
79+
```bash
80+
cd <product>/integration_test
81+
cp path_to_google_services_files/google-services.json .
82+
mkdir desktop_build && cd desktop_build
83+
cmake .. -DFIREBASE_CPP_SDK_DIR=/path/to/firebase_cpp_sdk && cmake --build . -j
84+
```
85+
86+
Once the build is finished, run the generated `integration_test` binary.
87+
88+
## Product Naming Disambiguation (`firebase_auth` vs `auth`)
89+
90+
Different build tools use different naming conventions for products in this repository:
91+
92+
- **CMake Targets (Desktop/iOS)**: Typically prefixed with `firebase_` (e.g., `firebase_auth`).
93+
- **Gradle Subprojects (Android)**: Typically use the raw module name (e.g., `:auth:build`).
94+
- **Python Scripts** (e.g., `build_testapps.py`): Typically use the raw module name (e.g., `--t auth`).
95+
96+
> [!TIP]
97+
> 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.

0 commit comments

Comments
 (0)