Draft documentation #72

jhugman · 2024-08-17T16:58:07Z

First cut of the reference sections of the documentation.

The 48a01ca commit is likely the most interesting to readers and reviewers.

This is not ready to merge, but should be instructive nevertheless.

This is likely best reviewed via mdbook serve docs.

zzorba

Looks good, a couple small typos and one or two organizational notes.

Happy to review again when its finalized.

zzorba · 2024-08-19T13:05:26Z

docs/src/api/commandline.md

+Running the following command from within your project:
+
+```sh
+alias ubrn=$(pwd)/node_modules/.bin/uniffi-bindgen-react-native


Might be useful to include a comment about mono-repo support, or suggest they use this command instead which should work in both repo structures

UBRN_BIN=$(node -p "require('path').resolve(require.resolve('uniffi-bindgen-react-native/package.json'), '../../.bin/uniffi-bindgen-react-native')")

zzorba · 2024-08-19T13:07:24Z

docs/src/api/commandline.md

+```
+The checkout command can be operated in two ways, either:
+1. with a `REPO` argument and optional `--branch` argument. OR
+2. with a config file which may specify a repo and branch, or just a `directory`.


It's implied, but might be worth mentioning that you can just include a rust crate under rust_modules/{NAME}/Cargo.toml instead of executing this step.

zzorba · 2024-08-19T13:09:38Z

docs/src/api/commandline.md

+
+## `build android`
+
+Build the crate for use on an Android device or emulator, using `cargo ndk`, which in turn uses Android Native Development Kit.


One thing that we had to do here, was make sure that we were linking to the correct NDK.

This changes from RN version to version, but in our usage we had to set an ANDROID_NDK_HOME variable in our script for this to pick up the appropriate version.

You can find the version you need in your react-native android/build.gradle file in the ndkVersion variable.

export ANDROID_NDK_HOME=${ANDROID_SDK_ROOT}/ndk/26.1.10909125/

zzorba · 2024-08-19T13:23:34Z

docs/src/api/commandline.md

+Once the library files (one for each target) are created, they are copied into the `jniLibs` specified by the YAML configuration.
+
+```admonish note
+React Native requires that the Rust library be built as a static library. The CMake based build will combine the C++ with the static library into a shared object.


This feels like it might be best promoted to a 'preparing your Rust library' section. It could call this out, and maybe link to the Uniffi docs about how to tag functions to be exported?

Good plan. I will address a "Prepare your Rust library" in a different PR.

zzorba · 2024-08-19T13:24:34Z

docs/src/api/commandline.md

+
+
+## `generate bindings`
+Generate the just the bindings. In most cases, this command should not be called directly, but with the build, with `--and-generate`.


Remove extra the, Generate just the bindings

zzorba · 2024-08-19T13:31:02Z

docs/src/api/config-yaml.md

+
+This is to configure the build steps for the Rust, the bindings, and the turbo-module code for iOS.
+
+This section can be completely missed out, as sensible defaults are provided, but can also be customized:


grammar nit: completely missed out feels strange, maybe 'completely omitted'. Don't feel strongly, if this is a british vs american english thing.

zzorba · 2024-08-19T13:31:42Z

docs/src/api/config-yaml.md

+
+This list of [glob patterns](https://en.wikipedia.org/wiki/Glob_(programming)) of file that should not be generated or overwritten by the `--and-generate` flag, and the `generate turbo-module` command.
+
+This is useful if you want to customize one or more of the generated files, and not losen those changes.


"not lose those changes"

zzorba · 2024-08-19T13:32:45Z

docs/src/api/turbo-module-files.md

+- For iOS:
+	- a `Module.h` and `Module.mm` file which receives the codegen'd install method calls, and digs around to find the `jsi::Runtime` and `react::CallInvoker`. It then calls into the generic C++ install code.
+- To build for iOS:
+	- A podspec file to tell Xcode about the generated files, and the framework name/location.


framework name/location for the compiled rust library.

jhugman · 2024-10-02T19:34:50Z

crates/ubrn_cli/src/config/mod.rs

+        .trim_matches('-')
+        .trim_matches('_')
+        .to_string()
+}


I'm going to start slowly work out where this is needed and where it isn't. Selectively adding trim_react_native_2 to defaults until everything works.

This might be something good to ask Johannes in our matrix room, he seems to know about these things.

zzorba

LGTM

zzorba · 2024-10-02T19:45:42Z

docs/src/api/commandline.md

+```json
+{
+  "scripts": {
+    "ubrn": "npx uniffi-bindgen-react-native"


so fwiw at least in my repo, just having uniffi-bindgen-react-native as a dependency was seemingly enough to let me call yarn ubrn without issue? Maybe that's a yarn thing, I think its fine to keep this documentation since it won't hurt.

Relates to: #109 I'm not sure if this is strictly necessary anymore because once I had it done, I realized that #72 has stripped the `reactnative` prefix from the package name again. So technically UBRN's current output should work with what create-react-native-library generates without this change applied. It might not hurt either way though?

jhugman requested review from wesc and zzorba August 17, 2024 16:58

jhugman marked this pull request as draft August 17, 2024 16:58

zzorba approved these changes Aug 19, 2024

View reviewed changes

jhugman force-pushed the jhugman/docs-1 branch from 48a01ca to 6a81a7a Compare October 2, 2024 19:18

jhugman added 4 commits October 2, 2024 20:30

Docs: Docs for command line, config file and getting started

fefaa3d

Fixup several small bugs/inconsistencies found while documenting

3d8fc52

Fixup turbo-module templates to work with getting started guides

b91a05e

Increment version to match uniffi-rs

327e15f

jhugman force-pushed the jhugman/docs-1 branch from 6a81a7a to 327e15f Compare October 2, 2024 19:32

jhugman commented Oct 2, 2024

View reviewed changes

jhugman marked this pull request as ready for review October 2, 2024 19:35

jhugman requested a review from zzorba October 2, 2024 19:35

jhugman merged commit 11c4f3d into main Oct 2, 2024
1 check passed

jhugman deleted the jhugman/docs-1 branch October 2, 2024 19:55

jhugman mentioned this pull request Oct 2, 2024

Generated code is being prefixed (e.g. with "ReactNative") but some occurrences appear to be missing #109

Closed

zzorba reviewed Oct 3, 2024

View reviewed changes

Johennes mentioned this pull request Oct 4, 2024

Auto-generate AndroidManifest.xml #112

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Draft documentation #72

Draft documentation #72

jhugman commented Aug 17, 2024 •

edited

Loading

zzorba left a comment

zzorba Aug 19, 2024

zzorba Aug 19, 2024

zzorba Aug 19, 2024

zzorba Aug 19, 2024

jhugman Oct 2, 2024

zzorba Aug 19, 2024

zzorba Aug 19, 2024

zzorba Aug 19, 2024

zzorba Aug 19, 2024

jhugman Oct 2, 2024

zzorba Oct 2, 2024

zzorba left a comment

zzorba Oct 2, 2024


		## `build android`

		Build the crate for use on an Android device or emulator, using `cargo ndk`, which in turn uses Android Native Development Kit.



		## `generate bindings`
		Generate the just the bindings. In most cases, this command should not be called directly, but with the build, with `--and-generate`.


		This is to configure the build steps for the Rust, the bindings, and the turbo-module code for iOS.

		This section can be completely missed out, as sensible defaults are provided, but can also be customized:


		This list of [glob patterns](https://en.wikipedia.org/wiki/Glob_(programming)) of file that should not be generated or overwritten by the `--and-generate` flag, and the `generate turbo-module` command.

		This is useful if you want to customize one or more of the generated files, and not losen those changes.

Draft documentation #72

Draft documentation #72

Conversation

jhugman commented Aug 17, 2024 • edited Loading

zzorba left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zzorba left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jhugman commented Aug 17, 2024 •

edited

Loading