Revision control
Copy as Markdown
# Adding a new component to Application Services
This is a rapid-fire list for adding a component from scratch and generating Kotlin/Swift bindings.
## The Rust Code
Your component should live under `./components` in this repo.
Use `cargo new --lib ./components/<your_crate_name>`to create a new library crate.
See the [Guide to Building a Rust Component](./building-a-rust-component.md) for general
advice on designing and structuring the actual Rust code, and follow the
[Dependency Management Guidelines](../dependency-management.md) if your crate
introduces any new dependencies.
API will get exposed to foreign-language bindings. Place the following in your `Cargo.toml`:
```
[dependencies]
uniffi = { workspace = true }
```
New components should prefer using the
a UDL file based approach. If you do use a UDL file, add this to `Cargo.toml` as well.
```
[build-dependencies]
uniffi = { workspace = true }
```
Include your new crate in the `application-services` workspace, by adding
it to the `members` and `default-members` lists in the `Cargo.toml` at
the root of the repository.
Run `cargo check -p <your_crate_name>` in the repository root to confirm that
things are configured properly. This will also have the side-effect of updating
`Cargo.lock` to contain your new crate and its dependencies.
## The Android Bindings
Run the `start-bindings android <your_crate_name> <component_description>` command to auto-generate the initial code. Follow the directions in the output.
You will end up with a directory structure something like this:
* `components/<your_crate_name>/`
* `Cargo.toml`
* `uniffi.toml`
* `src/`
* Rust code here.
* `android/`
* `build.gradle`
* `src/`
* `main/`
* `AndroidManifest.xml`
### Dependent crates
If your crate uses types from another crate in it's public API, you need to include a dependency for
the corresponding project in your `android/build.gradle` file.
For example, suppose use the `remote_settings::RemoteSettingsServer` type in your public API so that
consumers can select which server they want. In that case, you need to a dependency on the
remotesettings project:
```
dependencies {
api project(":remotesettings")
}
```
### Hand-written code
You can include hand-written Kotlin code alongside the automatically
generated bindings, by placing `.kt`` files in a directory named:
* `./android/src/test/java/mozilla/appservices/<your_crate_name>/`
You can write Kotlin-level tests that consume your component's API,
by placing `.kt`` files in a directory named:
* `./android/src/test/java/mozilla/appservices/<your_crate_name>/`.
You can run the tests with `./gradlew <your_crate_name>:test`
## The iOS Bindings
* Run the `start-bindings ios <your_crate_name>` command to auto-generate the initial code
* Run `start-bindings ios-focus <your_crate_name>` if you also want to expose your component to Focus.
* Follow the directions in the output.
You will end up with a directory structure something like this:
* `components/<your_crate_name>/`
* `Cargo.toml`
* `uniffi.toml`
* `src/`
* Rust code here.
* `ios/`
* `Generated/`
* Generated Swift code will be written into this directory.
### Adding your component to the Swift Package Manager Megazord
> *For more information on our how we ship components using the Swift Package Manager, check the [ADR that introduced the Swift Package Manager](../adr/0003-swift-packaging.md)*
Add your component into the iOS ["megazord"](../design/megazords.md) through the Xcode project, which can only really by done using the Xcode application, which can only really be done if you're on a Mac.
1. Open `megazords/ios-rust/MozillaTestServices/MozillaTestServices.xcodeproj` in Xcode.
1. In the Project navigator, add a new Group for your new component, pointing to
the `./ios/` directory you created above. Add the following entries to the Group:
* Any hand-written `.swift `files for your component
> Make sure that the "Copy items if needed" option is **unchecked**, and that
nothing is checked in the "Add to targets" list.
The result should look something like this:
Click on the top-level "MozillaTestServices" project in the navigator, then go to "Build Phases".
Finally, in the Project navigator, add a sub-group named "Generated", pointing to the `./Generated/` subdirectory, and
containing entries for the files generated by UniFFI:
* `<your_crate_name>.swift`
* `<your_crate_name>FFI.h`
Make sure that "Copy items if needed" is unchecked, and that nothing is checked in "Add to targets".
> Double-check that `<your_crate_name>.swift` does **not** appear in the "Compile Sources" section.
The result should look something like this:
Build the project in Xcode to check whether that all worked correctly.
To add Swift tests for your component API, create them in a file under
`megazords/ios-rust/MozillaTestServicesTests/`. Use this syntax to import
your component's bindings from the compiled megazord:
```
@testable import MozillaTestServices
```
In Xcode, navigate to the `MozillaTestServicesTests` Group and add your
new test file as an entry. Select the corresponding target, click on
"Build Phases", and add your test file to the list of "Compile Sources".
The result should look something like this:
Use the Xcode Test Navigator to run your tests and check whether
they're passing.
### Hand-written code
You can include hand-written Swift code alongside the automatically
generated bindings, by placing `.swift` files in a directory named:
`./ios/<your_crate_name>/`.
Make sure that this code gets distributed. Edit `taskcluster/scripts/build-and-test-swift.py` and:
- Add the path to the directory containing any hand-written swift code to `SOURCE_TO_COPY`
- Optionally also to `FOCUS_SOURCE_TO_COPY` if your component is also targeting Firefox Focus
### Distribute your component with `rust-components-swift`
The Swift source code and generated UniFFI bindings are distributed to consumers (eg: Firefox iOS) through [`rust-components-swift`](https://github.com/mozilla/rust-components-swift).
Your component should now automatically get included in the next `rust-component-swift` nightly release.